From 18e3fb7d391ec351ea023fc7bbc5b6f17c72a2b2 Mon Sep 17 00:00:00 2001 From: Rachel Lawton Date: Fri, 6 Dec 2024 14:39:13 +0000 Subject: [PATCH] update secure protect connect fixing commands (#1046) * update the docs to remove kuadrantctl Signed-off-by: R-Lawton * Updated SCP to currenrt versions and removed old and unecessary parts Signed-off-by: R-Lawton Updated SCP to currenrt versions and removed old and unecessary parts Signed-off-by: R-Lawton * add self signed cert and remove wildcard Signed-off-by: R-Lawton * adding dns health checks Signed-off-by: R-Lawton --------- Signed-off-by: R-Lawton --- .../secure-protect-connect-openshift.md | 790 +++++++----------- 1 file changed, 313 insertions(+), 477 deletions(-) diff --git a/doc/user-guides/full-walkthrough/secure-protect-connect-openshift.md b/doc/user-guides/full-walkthrough/secure-protect-connect-openshift.md index e6caca56e..08f45fcb8 100644 --- a/doc/user-guides/full-walkthrough/secure-protect-connect-openshift.md +++ b/doc/user-guides/full-walkthrough/secure-protect-connect-openshift.md @@ -1,131 +1,108 @@ -# Secure, protect, and connect APIs with Kuadrant on OpenShift +# Secure, protect, and connect APIs with Kuadrant ## Overview -This guide walks you through using Kuadrant on OpenShift to secure, protect, and connect an API exposed by a Gateway that is based on Kubernetes Gateway API. You can use this walkthrough for a Gateway deployed on a single OpenShift cluster or a Gateway distributed across multiple OpenShift clusters with a shared listener hostname. This guide shows how the platform engineer and application developer user roles can each use Kuadrant to achieve their goals. +This guide walks you through using Kuadrant to secure, protect, and connect an API exposed by a Gateway (Kubernetes Gateway API) from the personas platform engineer and application developer. For more information on the different personas please see the [Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#key-roles-and-personas) -### What Kuadrant can do for you in a multicluster environment - -You can leverage Kuadrant's capabilities in single or multiple clusters. The following features are designed to work across multiple clusters as well as in a single-cluster environment. - -- **Multicluster ingress:** Kuadrant provides multicluster ingress connectivity using DNS to bring traffic to your Gateways by using a strategy defined in a `DNSPolicy`. -- **Global rate limiting:** Kuadrant can enable global rate limiting use cases when configured to use a shared Redis store for counters based on limits defined by a `RateLimitPolicy`. -- **Global auth:** You can configure a Kuadrant `AuthPolicy` to leverage external auth providers to ensure that different clusters exposing the same API authenticate and authorize in the same way. -- **Integration with federated metrics stores:** Kuadrant has example dashboards and metrics for visualizing your Gateways and observing traffic hitting those Gateways across multiple clusters. - -### User roles - -- **Platform engineer**: This guide walks you through deploying a Gateway that provides secure communication and is protected and ready for use by application development teams to deploy an API. It then walks through using this Gateway in clusters in different geographic regions, leveraging Kuadrant to bring specific traffic to your geo-located Gateways to reduce latency and distribute load, while still being protected and secured with global rate limiting and auth. +## Prerequisites -- **Application developer**: This guide walks through how you can use the Kuadrant OpenAPI Specification (OAS) extensions and `kuadrantctl` CLI to generate an `HTTPRoute` for your API and to add specific auth and rate limiting requirements. +- Completed the steps in [Install Kuadrant on an OpenShift cluster](../../install/install-openshift.md). +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command line tool. +- AWS/Azure or GCP with DNS capabilities. -As an optional extra, this guide highlights how both user roles can observe and monitor these Gateways when the OpenShift user workload monitoring and observability stack is deployed. -### Deployment management tooling +### Set the environment variables -While this document uses `kubectl` commands for simplicity, working with multiple clusters is complex, and it is best to use a tool such as Argo CD to manage the deployment of resources to multiple clusters. +Set the following environment variables used for convenience in this guide: -## Prerequisites +```bash +export KUADRANT_GATEWAY_NS=api-gateway # Namespace for the example Gateway +export KUADRANT_GATEWAY_NAME=external # Name for the example Gateway +export KUADRANT_DEVELOPER_NS=toystore # Namespace for an example toystore app +export KUADRANT_AWS_ACCESS_KEY_ID=xxxx # AWS Key ID with access to manage the DNS Zone ID below +export KUADRANT_AWS_SECRET_ACCESS_KEY=xxxx # AWS Secret Access Key with access to manage the DNS Zone ID below +export KUADRANT_AWS_DNS_PUBLIC_ZONE_ID=xxxx # AWS Route 53 Zone ID for the Gateway +export KUADRANT_ZONE_ROOT_DOMAIN=example.com # Root domain associated with the Zone ID above +export KUADRANT_CLUSTER_ISSUER_NAME=self-signed # Name for the ClusterIssuer +``` -This guide expects that you have successfully installed Kuadrant on at least one OpenShift cluster: +### Set up a DNS Provider -- You have completed the steps in [Install Kuadrant on an OpenShift cluster](../../install/install-openshift.md) for one or more clusters. -- For multicluster scenarios, you have installed Kuadrant on at least two different OpenShift clusters, and have a shared accessible Redis store. -- You have the `kubectl` command line installed. -- Optional: User workload monitoring is configured to remote write to a central storage system such as Thanos, as described in [Install Kuadrant on an OpenShift cluster](../../install/install-openshift.md). +The DNS provider declares credentials to access the zone(s) that Kuadrant can use to set up DNS configuration. Ensure that this credential only has access to the zones you want Kuadrant to manage via `DNSPolicy` -## Platform engineer workflow +Create the namespace the Gateway will be deployed in: -NOTE: You must perform the following steps in each cluster individually, unless specifically excluded. +```bash +kubectl create ns ${KUADRANT_GATEWAY_NS} +``` -### Step 1 - Set your environment variables +Create the secret credentials in the same namespace as the Gateway - these will be used to configure DNS: -Set the following environment variables used for convenience in this guide: ```bash -export zid=change-this-to-your-zone-id -export rootDomain=example.com -export gatewayNS=api-gateway -export gatewayName=external -export devNS=toystore -export AWS_ACCESS_KEY_ID=xxxx -export AWS_SECRET_ACCESS_KEY=xxxx -export AWS_REGION=us-east-1 -export clusterIssuerName=lets-encrypt -export EMAIL=foo@example.com +kubectl -n ${KUADRANT_GATEWAY_NS} create secret generic aws-credentials \ + --type=kuadrant.io/aws \ + --from-literal=AWS_ACCESS_KEY_ID=$KUADRANT_AWS_ACCESS_KEY_ID \ + --from-literal=AWS_SECRET_ACCESS_KEY=$KUADRANT_AWS_SECRET_ACCESS_KEY ``` -### Step 2 - Set up a DNS Provider +Before adding a TLS issuer, create the secret credentials in the cert-manager namespace: -The DNS provider declares a credential to access the zone(s) that Kuadrant can use to set up DNS configuration. You should ensure that this credential only has access to the zones you want managed. +```bash +kubectl -n cert-manager create secret generic aws-credentials \ + --type=kuadrant.io/aws \ + --from-literal=AWS_ACCESS_KEY_ID=$KUADRANT_AWS_ACCESS_KEY_ID \ + --from-literal=AWS_SECRET_ACCESS_KEY=$KUADRANT_AWS_SECRET_ACCESS_KEY +``` -#### Create the DNS Provider Secret resource +### Deploy the Toystore app -Apply the following `Secret` resource to each cluster. Alternatively, if you are adding an additional cluster, add it to the new cluster: +Create the namespace for the Toystore application: ```bash -kubectl create ns ${gatewayNS} + +kubectl create ns ${KUADRANT_DEVELOPER_NS} ``` -Create the secret credentials as follows: +Deploy the Toystore app to the developer namespace: -``` -kubectl -n ${gatewayNS} create secret generic aws-credentials \ - --type=kuadrant.io/aws \ - --from-literal=AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \ - --from-literal=AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY +```bash +kubectl apply -f https://raw.githubusercontent.com/Kuadrant/Kuadrant-operator/main/examples/toystore/toystore.yaml -n ${KUADRANT_DEVELOPER_NS} ``` -### Step 3 - Add a TLS issuer -To secure communication to the Gateways, you will define a TLS issuer for TLS certificates. This example uses Let's Encrypt, but you can use any issuer supported by `cert-manager`. +### Add a TLS issuer -The following example uses Let's Encrypt staging, which you must also apply to all clusters: +To secure communication to the Gateways, define a TLS issuer for TLS certificates. + +!!! note + This example uses Let's Encrypt, but you can use any issuer supported by `cert-manager`. ```bash kubectl apply -f - <. -- You have a realm, client, and users set up. This example assumes a realm in a Keycloak instance called `toystore`. -- Copy the OAS from [sample OAS for rate-limiting and OIDC](../../../examples/oas-oidc.yaml) to a local location. - -#### Set up an OpenID AuthPolicy - -Set the following environment variables: - -```bash -export openIDHost=some.keycloak.com -export oasPath=examples/oas-oidc.yaml -``` - -NOTE: The sample OAS has some placeholders for namespaces and domains. You will inject valid values into these placeholders based on your previous environment variables. - -You can use your OAS and `kuadrantctl` to generate an `AuthPolicy` to replace the default on the Gateway as follows: - -```bash -cat $oasPath | envsubst | kuadrantctl generate kuadrant authpolicy --oas - -``` - -If you are happy with the generated resource, you can apply it to the cluster as follows: - -```bash -cat $oasPath | envsubst | kuadrantctl generate kuadrant authpolicy --oas - | kubectl apply -f - +kubectl apply -f - <