Skip to content

Commit b62504a

Browse files
dlanovdlanov
authored
docs: improve custom certificate installation guide (#9650)
Signed-off-by: Dennis Lanov <dennis.lanov@gmail.com>
1 parent 422ca9c commit b62504a

1 file changed

Lines changed: 104 additions & 14 deletions

File tree

‎site/content/en/latest/install/custom-cert.md‎

Lines changed: 104 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,29 @@
11
---
2-
title: Control Plane Authentication using custom certs
2+
title: Control Plane Authentication Using Custom Certificates
33
weight: -70
44
---
55

6-
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.
6+
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.
77

8-
This task will walk you through configuring custom certs for control plane auth.
8+
This guide shows how to create and manage these certificates with cert-manager before installing Envoy Gateway.
99

1010
## Before you begin
1111

12-
We use Cert-Manager to manage the certificates. You can install it by following the [official guide](https://cert-manager.io/docs/installation/kubernetes/).
12+
Install [cert-manager](https://cert-manager.io/docs/installation/kubectl/) and [Helm](https://helm.sh/docs/intro/install/) before continuing.
1313

14-
## Configure custom certs for control plane
14+
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.
1515

16-
1. First you need to set up the CA issuer, in this task, we use the `selfsigned-issuer` as an example.
16+
## Configure custom certificates for the control plane
1717

18-
*You should not use the self-signed issuer in production, you should use a real CA issuer.*
18+
1. Create the namespace where Envoy Gateway and the certificate resources will be installed.
19+
20+
```shell
21+
kubectl create namespace envoy-gateway-system
22+
```
23+
24+
2. Set up the CA issuer. This example uses a self-signed issuer to create the root CA.
25+
26+
**Warning:** Do not use the self-signed issuer in production. Use an issuer backed by a trusted certificate authority.
1927

2028
```shell
2129
cat <<EOF | kubectl apply -f -
@@ -59,10 +67,24 @@ We use Cert-Manager to manage the certificates. You can install it by following
5967
EOF
6068
```
6169
62-
2. Create a cert for envoy gateway controller, the cert will be stored in secret `envoy-gatewy`.
70+
3. Wait for the CA certificate and CA issuer to become ready.
71+
72+
```shell
73+
kubectl wait --for=condition=Ready \
74+
certificate/envoy-gateway-ca \
75+
--namespace envoy-gateway-system \
76+
--timeout=5m
77+
78+
kubectl wait --for=condition=Ready \
79+
issuer/eg-issuer \
80+
--namespace envoy-gateway-system \
81+
--timeout=5m
82+
```
83+
84+
4. Create the certificate for the Envoy Gateway controller. cert-manager stores it in the `envoy-gateway` Secret.
6385
6486
```shell
65-
cat<<EOF | kubectl apply -f -
87+
cat <<EOF | kubectl apply -f -
6688
apiVersion: cert-manager.io/v1
6789
kind: Certificate
6890
metadata:
@@ -89,10 +111,10 @@ We use Cert-Manager to manage the certificates. You can install it by following
89111
EOF
90112
```
91113
92-
3. Create a cert for envoy proxy, the cert will be stored in secret `envoy`.
114+
5. Create the certificate for Envoy Proxy. cert-manager stores it in the `envoy` Secret.
93115
94116
```shell
95-
cat<<EOF | kubectl apply -f -
117+
cat <<EOF | kubectl apply -f -
96118
apiVersion: cert-manager.io/v1
97119
kind: Certificate
98120
metadata:
@@ -116,10 +138,10 @@ We use Cert-Manager to manage the certificates. You can install it by following
116138
EOF
117139
```
118140
119-
4. Create a cert for rate limit, the cert will be stored in secret `envoy-rate-limit`.
141+
6. Create the certificate for the rate-limit service. cert-manager stores it in the `envoy-rate-limit` Secret.
120142
121143
```shell
122-
cat<<EOF | kubectl apply -f -
144+
cat <<EOF | kubectl apply -f -
123145
apiVersion: cert-manager.io/v1
124146
kind: Certificate
125147
metadata:
@@ -143,4 +165,72 @@ We use Cert-Manager to manage the certificates. You can install it by following
143165
EOF
144166
```
145167
146-
5. Now you can follow the helm chart [installation guide](../install-helm) to install envoy gateway with custom certs.
168+
7. Wait for the certificates to become ready.
169+
170+
```shell
171+
kubectl wait --for=condition=Ready \
172+
certificate/envoy-gateway \
173+
certificate/envoy \
174+
certificate/envoy-rate-limit \
175+
--namespace envoy-gateway-system \
176+
--timeout=5m
177+
```
178+
179+
Verify the certificate resources and the expected TLS Secrets.
180+
181+
```shell
182+
kubectl get certificates \
183+
--namespace envoy-gateway-system
184+
185+
kubectl get secrets \
186+
envoy-gateway \
187+
envoy \
188+
envoy-rate-limit \
189+
--namespace envoy-gateway-system \
190+
--output=custom-columns=NAME:.metadata.name,TYPE:.type
191+
```
192+
193+
8. Create a Helm values file that specifies the Kubernetes cluster domain used in the controller certificate DNS names.
194+
195+
```shell
196+
cat > custom-cert-values.yaml <<'EOF'
197+
# Keep this value aligned with the cluster domain used in the
198+
# envoy-gateway Certificate DNS names.
199+
kubernetesClusterDomain: cluster.local
200+
EOF
201+
```
202+
203+
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`.
204+
205+
Keep the certgen job enabled. It leaves existing certificate Secrets unchanged and creates any additional Secrets required by Envoy Gateway.
206+
207+
9. Install Envoy Gateway using the custom values file.
208+
209+
```shell
210+
helm install eg oci://docker.io/envoyproxy/gateway-helm \
211+
--version {{< helm-version >}} \
212+
--namespace envoy-gateway-system \
213+
--values custom-cert-values.yaml
214+
```
215+
216+
10. Wait for Envoy Gateway to become available.
217+
218+
```shell
219+
kubectl wait --for=condition=Available \
220+
deployment/envoy-gateway \
221+
--namespace envoy-gateway-system \
222+
--timeout=5m
223+
```
224+
225+
Verify the deployment, pods, and Helm release.
226+
227+
```shell
228+
kubectl get deployment/envoy-gateway \
229+
--namespace envoy-gateway-system
230+
231+
kubectl get pods \
232+
--namespace envoy-gateway-system
233+
234+
helm status eg \
235+
--namespace envoy-gateway-system
236+
```

0 commit comments

Comments
 (0)