diff --git a/site/content/en/latest/install/custom-cert.md b/site/content/en/latest/install/custom-cert.md index 4aa0d9687c..19ace73074 100644 --- a/site/content/en/latest/install/custom-cert.md +++ b/site/content/en/latest/install/custom-cert.md @@ -1,21 +1,29 @@ --- -title: Control Plane Authentication using custom certs +title: Control Plane Authentication Using Custom Certificates weight: -70 --- -Envoy Gateway establishes a secure TLS connection for control plane communication between Envoy Gateway pods and the Envoy Proxy fleet. The TLS Certificates used here are self signed and generated using a job that runs before envoy gateway is created, and these certs and mounted on to the envoy gateway and envoy proxy pods. +Envoy Gateway establishes secure TLS connections for control plane communication between the Envoy Gateway deployment and the Envoy Proxy fleet. By default, the Helm chart generates the required certificates before Envoy Gateway starts. -This task will walk you through configuring custom certs for control plane auth. +This guide shows how to create and manage these certificates with cert-manager before installing Envoy Gateway. ## Before you begin -We use Cert-Manager to manage the certificates. You can install it by following the [official guide](https://cert-manager.io/docs/installation/kubernetes/). +Install [cert-manager](https://cert-manager.io/docs/installation/kubectl/) and [Helm](https://helm.sh/docs/intro/install/) before continuing. -## Configure custom certs for control plane +The examples below use the default Kubernetes cluster domain, `cluster.local`. If your cluster uses a different domain, update both the `kubernetesClusterDomain` Helm value and the controller certificate DNS names. -1. First you need to set up the CA issuer, in this task, we use the `selfsigned-issuer` as an example. +## Configure custom certificates for the control plane - *You should not use the self-signed issuer in production, you should use a real CA issuer.* +1. Create the namespace where Envoy Gateway and the certificate resources will be installed. + + ```shell + kubectl create namespace envoy-gateway-system + ``` + +2. Set up the CA issuer. This example uses a self-signed issuer to create the root CA. + + **Warning:** Do not use the self-signed issuer in production. Use an issuer backed by a trusted certificate authority. ```shell cat < custom-cert-values.yaml <<'EOF' + # Keep this value aligned with the cluster domain used in the + # envoy-gateway Certificate DNS names. + kubernetesClusterDomain: cluster.local + EOF + ``` + + The certificate Secret names are fixed, so no certificate-specific Helm override is required. The chart uses the pre-created Secrets named `envoy-gateway`, `envoy`, and `envoy-rate-limit`. + + Keep the certgen job enabled. It leaves existing certificate Secrets unchanged and creates any additional Secrets required by Envoy Gateway. + +9. Install Envoy Gateway using the custom values file. + + ```shell + helm install eg oci://docker.io/envoyproxy/gateway-helm \ + --version {{< helm-version >}} \ + --namespace envoy-gateway-system \ + --values custom-cert-values.yaml + ``` + +10. Wait for Envoy Gateway to become available. + + ```shell + kubectl wait --for=condition=Available \ + deployment/envoy-gateway \ + --namespace envoy-gateway-system \ + --timeout=5m + ``` + + Verify the deployment, pods, and Helm release. + + ```shell + kubectl get deployment/envoy-gateway \ + --namespace envoy-gateway-system + + kubectl get pods \ + --namespace envoy-gateway-system + + helm status eg \ + --namespace envoy-gateway-system + ```