Installing an NGINX Ingress controller with a Let's Encrypt® certificate manager

To use Kubernetes to create an NGINX Ingress controller and protect it with a certificate, follow these steps:

1. Install the NGINX Ingress controller
2. Configure a DNS record for the Ingress controller
3. Install the certificate manager
4. Create a ClusterIssuer
5. Create objects to test cert-manager
6. Test how TLS works

If you no longer need the resources you created, delete them.

Getting startedGetting started

1. Create a service account with the editor, container-registry.images.puller, and load-balancer.admin roles for the folder. The load-balancer.admin role is required to create a network load balancer.

2. Create security groups for the Managed Service for Kubernetes cluster and its node groups.

   Warning

   The configuration of security groups determines the performance and availability of the cluster and the services and applications running in it.

3. Create a Managed Service for Kubernetes cluster and a node group in any suitable configuration. In the cluster settings, specify the service account and the security groups created earlier.

4. Install kubectl and configure it to work with the created cluster.

5. Register a public domain zone and delegate your domain.

6. (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 the NGINX Ingress controllerInstall the NGINX Ingress controller

For specific port forwarding at NGINX Ingress controller installation, follow this guide.

Configure a DNS record for the Ingress controllerConfigure 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:

1. 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
   ...
   

2. 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>
   

Install the certificate managerInstall the certificate manager

You can install the certificate manager in one of the following ways:

• Using Yandex Cloud Marketplace: To install cert-manager integrated with Cloud DNS.

  This will create a ClusterIssuer object configured to pass the DNS-01 challenge using Cloud DNS in the cluster.

  If required, you can manually create and configure other objects: Issuer or ClusterIssuer. For more information about these objects, see the cert-manager documentation.

• Manually: To install cert-manager with no additional integrations.

  You will need to create and configure any Issuer and ClusterIssuer objects manually.

Create a ClusterIssuerCreate a ClusterIssuer

Create a ClusterIssuer object you can use to issue Let's Encrypt® certificates.

Certificates will be issued after you pass the HTTP-01 challenge using the Ingress controller you installed previously.

Create an object with the required parameters:

1. Create the http01-clusterissuer.yaml file with the object manifest:

   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: http01-clusterissuer
   spec:
     acme:
       server: https://acme-v02.api.letsencrypt.org/directory
       email: <your_email>
       privateKeySecretRef:
         name: http01-clusterissuer-secret
       solvers:
       - http01:
           ingress:
             class: nginx
   

2. Create an object in the Managed Service for Kubernetes cluster:

   kubectl apply -f http01-clusterissuer.yaml
   

Create objects to test cert-managerCreate objects to test cert-manager

To test the certificate manager, create the Ingress, Service, and Deployment objects:

1. Create the app.yaml YAML file with the Ingress, Service, and Deployment object manifests:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: minimal-ingress
     annotations:
       cert-manager.io/cluster-issuer: "http01-clusterissuer"
   spec:
     ingressClassName: nginx
     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
   

2. Create objects in a Managed Service for Kubernetes cluster:

   kubectl apply -f app.yaml
   

Test how TLS worksTest how TLS works

1. 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.

2. 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>
   

   Note

   If the resource is unavailable at the specified URL, make sure that the security groups for the Managed Service for Kubernetes cluster and its node groups are configured correctly. If any rule is missing, add it.

Delete the resources you createdDelete the resources you created

Some resources are not free of charge. To avoid paying for them, delete the resources you no longer need:

1. Delete the Managed Service for Kubernetes cluster.
2. Delete the public domain zone.