diff --git a/docs/how-to/api-walkthrough.md b/docs/how-to/api-walkthrough.md index 34988d83..56a5dbd2 100644 --- a/docs/how-to/api-walkthrough.md +++ b/docs/how-to/api-walkthrough.md @@ -2,7 +2,155 @@ ## Introduction -This document will detail the setup of a reference architecture to support a number of API management use-cases connecting Kuadrant with other projects the wider API management on Kubernetes ecosystem. +This document will detail the setup of a reference architecture to support a number of API management use-cases connecting Kuadrant with other projects in the wider API management on Kubernetes ecosystem. -## Petstore App Deployment +## Platform Engineer Steps (Part 1) + + + +Export the following env vars: + +``` +export KUADRANT_AWS_ACCESS_KEY_ID= +export KUADRANT_AWS_SECRET_ACCESS_KEY= +export KUADRANT_AWS_REGION= +export KUADRANT_AWS_DNS_PUBLIC_ZONE_ID= +export KUADRANT_ZONE_ROOT_DOMAIN= +``` + +Run the following command, choosing `aws` as the dns provider: + + + +```bash +MGC_LOCAL_QUICKSTART_SCRIPTS_MODE=true MGC_BRANCH=api-upstream ./hack/quickstart-setup-api.sh +``` + +### Create a gateway + + + + +View the ManagedZone, Gateway and TLSPolicy: + +```bash +kubectl --context kind-mgc-control-plane describe managedzone mgc-dev-mz -n multi-cluster-gateways +kubectl --context kind-mgc-control-plane describe gateway -n multi-cluster-gateways +kubectl --context kind-mgc-control-plane describe tlspolicy -n multi-cluster-gateways +``` + +### Guard Rails: Show Constraint warnings about missing policies ( DNS, AuthPolicy, RLP) + + + +### Create missing Policies + + + +Create a DNSPolicy: + + + +```bash +envsubst < ./resources/dnspolicy.yaml | kubectl --context kind-mgc-control-plane apply -f - +kubectl --context kind-mgc-control-plane describe dnspolicy prod-web -n multi-cluster-gateways +``` + +View ns entries in Route 53 DNS Zone + + + +Create and configure a Gateway-wide RateLimitPolicy + + + +```bash +kubectl --context kind-mgc-control-plane apply -f ./resources/ratelimitpolicy.yaml +kubectl --context kind-mgc-control-plane describe ratelimitpolicy prod-web -n multi-cluster-gateways +``` + +Create and configure a Gateway-wide AuthPolicy + + + +```bash +kubectl --context kind-mgc-control-plane apply -f ./resources/authpolicy.yaml +kubectl --context kind-mgc-control-plane describe authpolicy gw-auth -n multi-cluster-gateways +``` + +### Platform Overview + +Open Platform Engineer Dashboard in Grafana to see: + + + +* Gateways & Policies - Gateway Policies created +* No Route Policies yet (as no APIs/Apps deployed yet) - Can see a TLSPolicy, DNSPolicy, AuthPolicy and RateLimitPolicy +* Constraints & Violations - Highlight no more violations +* APIs Summary - Highlight there are no APIs yet + +## App Developer Steps + +### API Setup + +TODO + +* Deploy the petstore app to 1 cluster +* Open api spec in apicurio studio, showing x-kuadrant extensions & making requests (with swagger) to the show rate limit policy +* Modify x-kuadrant extension to change rate limit +* Export spec and generate resources with kuadrantctl +* Apply generated resources to petstore app in cluster +* Back in apicurio studio, modify x-kuadrant extension to add auth to /store/inventory endpoint +* Export spec, generate resources and reapply to cluster +* Verify auth policy via swagger + +### Multicluster Bonanza + +TODO + +* Deploy the petstore to 2nd cluster (assuming deployed via manifestwork or argocd, can update a placement) + +e.g. + +```bash +kubectl --context kind-mgc-control-plane patch placement petstore -n argocd --type='json' -p='[{"op": "add", "path": "/spec/clusterSets/-", "value": "petstore-region-us"}, {"op": "replace", "path": "/spec/numberOfClusters", "value": 2}]' +``` + +Describe the DNSPolicy + +```bash +kubectl --context kind-mgc-control-plane describe dnspolicy prod-web -n multi-cluster-gateways +``` + +Show ManagedCluster labelling + +```bash +kubectl --context kind-mgc-control-plane get managedcluster -A -o custom-columns="NAME:metadata.name,URL:spec.managedClusterClientConfigs[0].url,REGION:metadata.labels.kuadrant\.io/lb-attribute-geo-code" +``` + +Show DNS resolution per geo region + +TODO + +Show rate limiting working on both clusters/apps. + +### App Developer Overview: Show API traffic & impact of AuthPolicy & Rate Limit Policy + +Open the App Developer Dashboard + + + +* List of APIs, corresponding to our HTTPRoute coming from our OAS spec + +## Platform Engineer Steps (Part 2) + +### Platform Overview + +Open Platform Engineer Dashboard in Grafana to see: + + + +* Gateways & Policies - new resources created by App Developer shown +* Constraints & Violations - no violations +* APIs Summary - API created by App Developer shown, including summary traffic diff --git a/hack/.deployUtils b/hack/.deployUtils index a90428ef..d403a132 100755 --- a/hack/.deployUtils +++ b/hack/.deployUtils @@ -321,13 +321,28 @@ deployPrometheusForFederation() { } installAPIDashboards() { + local PROMETHEUS_FOR_FEDERATION_API_DASHBOARDS_KUSTOMIZATION_DIR="$2" + local PROMETHEUS_FOR_FEDERATION_API_DASHBOARDS_GRAFANA_PATCH="$3" + if [ -z "$2" ]; then + PROMETHEUS_FOR_FEDERATION_API_DASHBOARDS_KUSTOMIZATION_DIR=${LOCAL_SETUP_DIR}/../config/prometheus-for-federation/api-dashboards + fi + if [ -z "$3" ]; then + PROMETHEUS_FOR_FEDERATION_API_DASHBOARDS_GRAFANA_PATCH=${PROMETHEUS_FOR_FEDERATION_API_DASHBOARDS_KUSTOMIZATION_DIR}/grafana_deployment_patch.yaml + fi clusterName=${1} if [[ -n "${METRICS_FEDERATION}" ]]; then echo "Deploying API Dashboards in ${clusterName}" kubectl config use-context kind-${clusterName} - ${KUSTOMIZE_BIN} build ${PROMETHEUS_FOR_FEDERATION_KUSTOMIZATION_DIR}/api-dashboards | kubectl apply -f - - - kubectl patch deployment grafana -n monitoring --type=json -p "$(cat ${PROMETHEUS_FOR_FEDERATION_KUSTOMIZATION_DIR}/api-dashboards/grafana_deployment_patch.yaml)" + ${KUSTOMIZE_BIN} build ${PROMETHEUS_FOR_FEDERATION_API_DASHBOARDS_KUSTOMIZATION_DIR} | kubectl apply -f - + + if [[ ${PROMETHEUS_FOR_FEDERATION_API_DASHBOARDS_GRAFANA_PATCH} == https* ]]; then + echo "Fetching patch file from ${PROMETHEUS_FOR_FEDERATION_API_DASHBOARDS_GRAFANA_PATCH}" + curl -L -o ${TMP_DIR}/patch.yaml ${PROMETHEUS_FOR_FEDERATION_API_DASHBOARDS_GRAFANA_PATCH} + kubectl patch deployment grafana -n monitoring --type=json -p "$(cat ${TMP_DIR}/patch.yaml)" + else + echo "Using local file at ${PROMETHEUS_FOR_FEDERATION_API_DASHBOARDS_GRAFANA_PATCH}" + kubectl patch deployment grafana -n monitoring --type=json -p "$(cat ${PROMETHEUS_FOR_FEDERATION_API_DASHBOARDS_GRAFANA_PATCH})" + fi kubectl rollout restart deployment/grafana -n monitoring fi } diff --git a/hack/quickstart-setup-api.sh b/hack/quickstart-setup-api.sh new file mode 100755 index 00000000..c3057a0e --- /dev/null +++ b/hack/quickstart-setup-api.sh @@ -0,0 +1,132 @@ +#!/bin/bash + +# +# Copyright 2024 Red Hat, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +export KFILT="docker run --rm -i ryane/kfilt" + +METRICS_FEDERATION=true + +if [ -z $MGC_BRANCH ]; then + MGC_BRANCH=${MGC_BRANCH:="main"} +fi +if [ -z $MGC_ACCOUNT ]; then +MGC_ACCOUNT=${MGC_ACCOUNT:="kuadrant"} +fi + +if [ -n "$MGC_LOCAL_QUICKSTART_SCRIPTS_MODE" ]; then + echo "Loading quickstart scripts locally" + SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" + source "${SCRIPT_DIR}/.quickstartEnv" + source "${SCRIPT_DIR}/.kindUtils" + source "${SCRIPT_DIR}/.cleanupUtils" + source "${SCRIPT_DIR}/.deployUtils" + source "${SCRIPT_DIR}/.startUtils" + source "${SCRIPT_DIR}/.setupEnv" + else + echo "Loading quickstart scripts from GitHub" + source /dev/stdin <<< "$(curl -s https://raw.githubusercontent.com/${MGC_ACCOUNT}/multicluster-gateway-controller/${MGC_BRANCH}/hack/.quickstartEnv)" + source /dev/stdin <<< "$(curl -s https://raw.githubusercontent.com/${MGC_ACCOUNT}/multicluster-gateway-controller/${MGC_BRANCH}/hack/.kindUtils)" + source /dev/stdin <<< "$(curl -s https://raw.githubusercontent.com/${MGC_ACCOUNT}/multicluster-gateway-controller/${MGC_BRANCH}/hack/.cleanupUtils)" + source /dev/stdin <<< "$(curl -s https://raw.githubusercontent.com/${MGC_ACCOUNT}/multicluster-gateway-controller/${MGC_BRANCH}/hack/.deployUtils)" + source /dev/stdin <<< "$(curl -s https://raw.githubusercontent.com/${MGC_ACCOUNT}/multicluster-gateway-controller/${MGC_BRANCH}/hack/.startUtils)" + source /dev/stdin <<< "$(curl -s https://raw.githubusercontent.com/${MGC_ACCOUNT}/multicluster-gateway-controller/${MGC_BRANCH}/hack/.setupEnv)" +fi + +export OPERATOR_SDK_BIN=$(dockerBinCmd "operator-sdk") +export YQ_BIN=$(dockerBinCmd "yq") +export CLUSTERADM_BIN=$(dockerBinCmd "clusteradm") + +MGC_REPO=${MGC_REPO:="github.com/${MGC_ACCOUNT}/multicluster-gateway-controller.git"} +PROMETHEUS_DIR=${MGC_REPO}/config/prometheus +INGRESS_NGINX_DIR=${MGC_REPO}/config/ingress-nginx +PROMETHEUS_FOR_FEDERATION_DIR=${MGC_REPO}/config/prometheus-for-federation +PROMETHEUS_FOR_FEDERATION_API_DASHBOARDS_KUSTOMIZATION_DIR=${PROMETHEUS_FOR_FEDERATION_DIR}/api-dashboards +PROMETHEUS_FOR_FEDERATION_API_DASHBOARDS_GRAFANA_PATCH=https://raw.githubusercontent.com/${MGC_ACCOUNT}/multicluster-gateway-controller/${MGC_BRANCH}/config/prometheus-for-federation/api-dashboards/grafana_deployment_patch.yaml +THANOS_DIR=${MGC_REPO}/config/thanos +QUICK_START_HUB_KUSTOMIZATION=${MGC_REPO}/config/quick-start/control-cluster +QUICK_START_SPOKE_KUSTOMIZATION=${MGC_REPO}/config/quick-start/workload-cluster + +set -e pipefail + +if [[ "${MGC_BRANCH}" != "main" ]]; then + echo "setting MGC_REPO to use branch ${MGC_BRANCH}" + QUICK_START_HUB_KUSTOMIZATION=${QUICK_START_HUB_KUSTOMIZATION}?ref=${MGC_BRANCH} + QUICK_START_SPOKE_KUSTOMIZATION=${QUICK_START_SPOKE_KUSTOMIZATION}?ref=${MGC_BRANCH} + echo "set QUICK_START_HUB_KUSTOMIZATION to ${QUICK_START_HUB_KUSTOMIZATION}" + echo "set QUICK_START_SPOKE_KUSTOMIZATION to ${QUICK_START_SPOKE_KUSTOMIZATION}" + +fi + + +# Prompt user for any required env vars that have not been set +requiredENV + +# Default config +if [[ -z "${LOG_LEVEL}" ]]; then + LOG_LEVEL=1 +fi +if [[ -z "${MGC_WORKLOAD_CLUSTERS_COUNT}" ]]; then + MGC_WORKLOAD_CLUSTERS_COUNT=2 +fi + +# Make temporary directory for kubeconfig +mkdir -p ${TMP_DIR} + +cleanupKind + +kindSetupMGCClusters ${KIND_CLUSTER_CONTROL_PLANE} ${KIND_CLUSTER_WORKLOAD} ${port80} ${port443} ${MGC_WORKLOAD_CLUSTERS_COUNT} + +# Apply Cluster Configurations to Control cluster +# Deploy OCM hub +deployOCMHub ${KIND_CLUSTER_CONTROL_PLANE} "minimal" +# Deploy Quick start kustomize +deployQuickStartControl ${KIND_CLUSTER_CONTROL_PLANE} +# Initialize local dev setup for the controller on the control-plane cluster +configureController ${KIND_CLUSTER_CONTROL_PLANE} +# Deploy MetalLb +configureMetalLB ${KIND_CLUSTER_CONTROL_PLANE} ${metalLBSubnetStart} +# Deploy Prometheus in the hub too +deployPrometheusForFederation ${KIND_CLUSTER_CONTROL_PLANE} ${PROMETHEUS_FOR_FEDERATION_DIR}?ref=${MGC_BRANCH} +# Deploy Thanos components in the hub +deployThanos ${KIND_CLUSTER_CONTROL_PLANE} ${THANOS_DIR} +# Deploy Prometheus components in the hub +deployPrometheus ${KIND_CLUSTER_CONTROL_PLANE} +# Deploy API Dashboards in hub +installAPIDashboards ${KIND_CLUSTER_CONTROL_PLANE} ${PROMETHEUS_FOR_FEDERATION_API_DASHBOARDS_KUSTOMIZATION_DIR}?ref=${MGC_BRANCH} ${PROMETHEUS_FOR_FEDERATION_API_DASHBOARDS_GRAFANA_PATCH} + + +# Apply Cluster Configurations to Workload clusters +if [[ -n "${MGC_WORKLOAD_CLUSTERS_COUNT}" ]]; then + for ((i = 1; i <= ${MGC_WORKLOAD_CLUSTERS_COUNT}; i++)); do + deployQuickStartWorkload ${KIND_CLUSTER_WORKLOAD}-${i} + configureMetalLB ${KIND_CLUSTER_WORKLOAD}-${i} $((${metalLBSubnetStart} + ${i})) + deployOLM ${KIND_CLUSTER_WORKLOAD}-${i} + deployOCMSpoke ${KIND_CLUSTER_WORKLOAD}-${i} + configureManagedAddon ${KIND_CLUSTER_CONTROL_PLANE} ${KIND_CLUSTER_WORKLOAD}-${i} + configureClusterAsIngress ${KIND_CLUSTER_CONTROL_PLANE} ${KIND_CLUSTER_WORKLOAD}-${i} + deployPrometheusForFederation ${KIND_CLUSTER_WORKLOAD}-${i} ${PROMETHEUS_FOR_FEDERATION_DIR}?ref=${MGC_BRANCH} + done +fi + +kubectl config use-context kind-${KIND_CLUSTER_CONTROL_PLANE} + + +echo "" +echo "What's next... + + Now that you have 2 kind clusters configured and with multicluster-gateway-controller installed you are ready to begin creating gateways + Visit https://docs.kuadrant.io/multicluster-gateway-controller/docs/how-to/multicluster-gateways-walkthrough/ for next steps" \ No newline at end of file