Installing an NGINX Ingress controller with a Let's Encrypt® certificate manager
To use Kubernetes
- Install an NGINX Ingress controller using a Helm chart
- Install the certificate manager
- Create objects
- Configure a DNS record for the Ingress controller
- Test how TLS works
If you no longer need the resources you created, delete them.
Getting started
- Create a service account with the
editor
,container-registry.images.puller
, andload-balancer.admin
roles for the folder. Theload-balancer.admin
role is required to create a network load balancer. - Create a Managed Service for Kubernetes cluster and a node group in any suitable configuration. In the cluster settings, specify the service account you created earlier.
- Configure Managed Service for Kubernetes cluster security groups and node groups.
-
Install kubectl
and configure it to work with the created cluster. - Register a public domain zone and delegate your domain.
- If you already have a certificate for the domain zone, add its details to the Yandex Certificate Manager service. Alternatively, you can add a new Let's Encrypt® certificate.
-
(Optional) Install ExternalDNS with the plugin for Yandex Cloud DNS to automatically create a DNS record in Yandex Cloud DNS when creating an Ingress controller.
Install an NGINX Ingress controller using a Helm chart
-
To install a Helm chart
with the NGINX Ingress controller, run this command:helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx && \ helm repo update && \ helm install ingress-nginx ingress-nginx/ingress-nginx
The created controller will be installed behind Yandex Network Load Balancer.
To set up the controller configuration yourself, follow the guidelines provided in the Helm documentation
For specific port forwarding at NGINX Ingress controller installation, follow this guide.
Install the certificate manager
Install the cert-manager app with the Yandex Cloud DNS ACME webhook plugin according to the guide.
-
Install the latest version
of the certificate manager configured to issue Let's Encrypt® certificates. For example, run the following command for version 1.21.1:kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.12.1/cert-manager.yaml
-
Make sure that the
cert-manager
namespace has three pods, all of them being1/1
ready and with theRunning
status:kubectl get pods -n cert-manager --watch
Result:
NAME READY STATUS RESTARTS AGE cert-manager-69********-ghw6s 1/1 Running 0 54s cert-manager-cainjector-76********-gnrzz 1/1 Running 0 55s cert-manager-webhook-77********-wz9bh 1/1 Running 0 54s
-
Create the
acme-issuer.yaml
YAML file with theClusterIssuer
object manifest:apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: yc-clusterissuer namespace: cert-manager spec: acme: server: https://acme-v02.api.letsencrypt.org/directory email: <your email address> privateKeySecretRef: name: domain-name-secret solvers: - http01: ingress: class: nginx
-
Create an object in the Managed Service for Kubernetes cluster:
kubectl apply -f acme-issuer.yaml
Create objects
To test the certificate manager, create the Ingress
, Service
, and Deployment
objects.
-
Create the
app.yaml
YAML file with theIngress
,Service
, andDeployment
object manifests:apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: minimal-ingress annotations: kubernetes.io/ingress.class: "nginx" cert-manager.io/cluster-issuer: "yc-clusterissuer" spec: tls: - hosts: - <your_domain_URL> secretName: domain-name-secret rules: - host: <your_domain_URL> http: paths: - path: / pathType: Prefix backend: service: name: app port: number: 80 --- apiVersion: v1 kind: Service metadata: name: app spec: selector: app: app ports: - protocol: TCP port: 80 targetPort: 80 --- apiVersion: apps/v1 kind: Deployment metadata: name: app-deployment labels: app: app spec: replicas: 1 selector: matchLabels: app: app template: metadata: labels: app: app spec: containers: - name: app image: nginx:latest ports: - containerPort: 80
-
Create objects in a Managed Service for Kubernetes cluster:
kubectl apply -f app.yaml
Configure a DNS record for the Ingress controller
If you are using ExternalDNS with a plugin for Cloud DNS, you do not need to configure a DNS record: it is created automatically. Otherwise:
-
Find out the IP address of the Ingress controller (the value in the
EXTERNAL-IP
column):kubectl get svc
Result:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ... ingress-nginx-controller LoadBalancer 10.96.164.252 84.201.153.122 80:31248/TCP,443:31151/TCP 2m19s ...
-
Add an A record pointing to the Ingress controller's public IP to your DNS provider or to your own DNS server:
<your_domain> IN A <Ingress_controller_IP_address>
Test how TLS works
-
If you used a Let's Encrypt® certificate, make sure the domain rights verification was successful and the certificate got the
Issued
status.kubectl describe certificate domain-name-secret
The command output will contain similar events:
Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal Issuing ... cert-manager-certificates-trigger Issuing certificate as Secret does not exist Normal Generated ... cert-manager-certificates-key-manager Stored new private key in temporary Secret resource...
Certificates are used bundled with related Kubernetes secrets
, which store key pairs and service information. If there is no secret, the certificate is reissued automatically and a new secret is created – with a notification in the events. For more information on what can cause the reissue of a certificate, see the cert-manager documentation .As the certificate is being issued for the first time, it has no such related secret so far. The presence of notification events about the fact should not be considered an error.
Note
The verification of domain rights for a Let's Encrypt® certificate may take several hours.
-
Run this command:
curl https://<your_domain>
Result:
<!DOCTYPE html> <html> <head> <title>Welcome to nginx!</title> <style> html { color-scheme: light dark; } body { width: 35em; margin: 0 auto; font-family: Tahoma, Verdana, Arial, sans-serif; } </style> </head> <body> <h1>Welcome to nginx!</h1> <p>If you see this page, the nginx web server is successfully installed and working. Further configuration is required.</p> <p>For online documentation and support please refer to <a href="http://nginx.org/">nginx.org</a>.<br/> Commercial support is available at <a href="http://nginx.com/">nginx.com</a>.</p> <p><em>Thank you for using nginx.</em></p> </body> </html>
Delete the resources you created
Some resources are not free of charge. To avoid paying for them, delete the resources you no longer need: