From cc1784cce9aca53008bfc39d84bd033b3370b79d Mon Sep 17 00:00:00 2001 From: Sascha Spreitzer Date: Mon, 23 Jun 2025 12:46:52 +0200 Subject: [PATCH] feat(tutorials): Add Gateway API Signed-off-by: Sascha Spreitzer --- content/docs/manifest.json | 4 + content/docs/tutorials/README.md | 8 ++ .../docs/tutorials/acme/cilium-gateway-api.md | 119 ++++++++++++++++++ 3 files changed, 131 insertions(+) create mode 100644 content/docs/tutorials/acme/cilium-gateway-api.md diff --git a/content/docs/manifest.json b/content/docs/manifest.json index 1142c56e5f8..2fa0f0fe4d6 100644 --- a/content/docs/manifest.json +++ b/content/docs/manifest.json @@ -607,6 +607,10 @@ "title": "Introduction", "path": "/docs/tutorials/README.md" }, + { + "title": "Securing Cilium Gateway API", + "path": "/docs/tutorials/acme/cilium-gateway-api.md" + }, { "title": "Securing NGINX-ingress", "path": "/docs/tutorials/acme/nginx-ingress.md" diff --git a/content/docs/tutorials/README.md b/content/docs/tutorials/README.md index a2efe63d06e..6dc05d569ba 100644 --- a/content/docs/tutorials/README.md +++ b/content/docs/tutorials/README.md @@ -6,6 +6,14 @@ description: 'cert-manager tutorials: Overview' Step-by-step tutorials are a great way to get started with cert-manager, and we provide a few for you to learn from. Take a look! +### Gateway API Tutorials + +- [Securing Cilium Gateway API](./acme/cilium-gateway-api.md): A tutorial for deploying Kubernetes Gateway API in combination with Cilium and securing ingress traffic with certificates from `Let's Encrypt` with the Automatic Certificate Management Environment (ACME) mechanism. + +### Ingress Tutorials + +Kubernetes Ingress is in a feature freeze state in favor of the Kubernetes Gateway API. See the [Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) and [Kubernetes Gateway API](https://kubernetes.io/docs/concepts/services-networking/gateway/) documentation. + - [Securing Ingresses with NGINX-Ingress and cert-manager](./acme/nginx-ingress.md): Tutorial for deploying NGINX into your cluster and securing incoming connections with a certificate from Let's Encrypt. - [GKE + Ingress + Let's Encrypt](./getting-started-with-cert-manager-on-google-kubernetes-engine-using-lets-encrypt-for-ingress-ssl/README.md): diff --git a/content/docs/tutorials/acme/cilium-gateway-api.md b/content/docs/tutorials/acme/cilium-gateway-api.md new file mode 100644 index 00000000000..33e777d0b42 --- /dev/null +++ b/content/docs/tutorials/acme/cilium-gateway-api.md @@ -0,0 +1,119 @@ +--- +title: Securing Cilium Gateway API +description: 'cert-manager tutorials: Using Cilium Gateway API to solve Automatic Certificate Management Environment (ACME) challenges' +--- + +This tutorial will specify how to automate ingress traffic encryption to your Kubernetes cluster with `Kubernetes Gateway API`, `Cilium` and `cert-manager`. + +## Steps + +* [Step 1 - Install Helm](#step-1---install-helm) +* [Step 2 - Deploy Kubernetes Gateway API](#step-2---deploy-kubernetes-gateway-api) +* [Step 3 - Deploy Cilium](#step-3---deploy-cilium) +* [Step 4 - Deploy cert-manager and Configure an Issuer](#step-4---deploy-cert-manager-and-configure-an-issuer) +* [Step 5 - Configure a Gateway and HTTPRoute](#step-5---configure-a-gateway-and-httproute) + +## Step 1 - Install Helm + +> *Skip this step if you have helm already installed on your client.* + +The easiest way to install and manage `cert-manager` and `Cilium` is to use [`Helm`](https://helm.sh), a templating and deployment tool for Kubernetes resources. + +First, ensure the Helm client is installed on your client by following the [Helm installation instructions](https://helm.sh/docs/intro/install/). + +For example, on MacOS: + +```shell +$ brew install helm +``` + +For a detailed description read the documentation provided at: https://helm.sh/docs/intro/install/ + +## Step 2 - Deploy Kubernetes Gateway API + +> *In this tutorial we are focusing on Cilium version `1.17.5`, which supports Gateway API version `1.2.0`.* + +Install the Gateway API Custom Resource Definitions (CRDs): + +```shell +$ kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.2.0/config/crd/standard/gateway.networking.k8s.io_gatewayclasses.yaml +$ kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.2.0/config/crd/standard/gateway.networking.k8s.io_gateways.yaml +$ kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.2.0/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml +$ kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.2.0/config/crd/standard/gateway.networking.k8s.io_referencegrants.yaml +$ kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.2.0/config/crd/standard/gateway.networking.k8s.io_grpcroutes.yaml +``` + +Optionally the *experimental* TLSRoute CRD: + +```shell +$ kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.2.0/config/crd/experimental/gateway.networking.k8s.io_tlsroutes.yaml +``` + +This is also described in the [cilium docs](https://docs.cilium.io/en/stable/network/servicemesh/gateway-api/gateway-api/#prerequisites). + +## Step 3 - Deploy Cilium + +Install the cilium cli either via your package manager or GitHub releases. For example: + +```shell + $ brew install cilium-cli +``` + +Install cilium on a newly deployed Kubernetes cluster with the Gateway API integration enabled: + +```shell +$ cilium install \ + --set kubeProxyReplacement=true \ + --set gatewayAPI.enabled=true + +$ cilium status --wait +``` + +There is a detailed description in the [cilium docs](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-default/). + +## Step 4 - Deploy cert-manager and Configure an Issuer + +Install the Helm repository: + +```shell +$ helm repo add jetstack https://charts.jetstack.io --force-update +``` + +Install cert-manager: + +```shell +$ helm install \ + cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --create-namespace \ + --set crds.enabled=true +``` + +There is also a detailed installation documentation with [Helm](/docs/installation/helm/). + +Defining a letsencrypt ACME HTTP01 cluster issuer: + +`custerissuer-letsencrypt.yaml` +```yaml +apiVersion: cert-manager.io/v1 +kind: ClusterIssuer +metadata: + name: letsencrypt +spec: + acme: + email: noreply@example.com + privateKeySecretRef: + name: letsencrypt-clusterissuer + server: https://acme-v02.api.letsencrypt.org/directory + solvers: + - http01: + ingress: {} +``` + +Apply it to the cluster: +```shell +$ kubectl apply -f clusterissuer-letsencrypt.yaml +``` + +## Step 5 - Configure a Gateway and HTTPRoute +