Using TLS certificates

Deckhouse Virtualization Platform (DVP) provides built-in tools for managing TLS certificates, simplifying setup and management of traffic encryption for applications running in the cluster.

This page covers the following aspects of certificate usage in DVP:

• Manually requesting TLS certificates using the Certificate and ClusterIssuer resources.
• Securely storing and using credentials for accessing certificate authorities (CAs).
• Automatically obtaining certificates using the tls-acme annotation in Ingress resources.

Working with certificates

Viewing certificate details

• To list all certificates in the cluster, use the following command:

  d8 k get certificate --all-namespaces
  

• To check the status of a specific certificate, run:

  d8 k -n <NAMESPACE> describe certificate <CERTIFICATE-NAME>
  

Automatic certificate requesting

To request a letsencrypt certificate, follow these steps:

1. Create a Certificate resource as described in the cert-manager documentation. Use the following example as a reference:

   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: example-com            # Certificate name.
     namespace: default
   spec:
     secretName: example-com-tls  # Name of the Secret that will store the private key and the certificate.
     issuerRef:
       kind: ClusterIssuer        # Certificate issuer details.
       name: letsencrypt
     commonName: example.com      # Certificate main domain.
     dnsNames:                    # Optional additional certificate domains (at least one DNS name or IP address).
     - www.example.com
     - admin.example.com
   

2. The cert-manager module will automatically run a domain ownership challenge using the method defined in the ClusterIssuer resource (for example, HTTP-01 or DNS-01).
3. The cert-manager module will automatically create a temporary Ingress resource for the challenge. This temporary Ingress will not affect your existing Ingress configuration.
4. Once validated, the issued certificate will be stored in the Secret specified in the secretName field.

Requesting a wildcard certificate using DNS in Cloudflare

1. Obtain your GlobalAPIKey and Email:
   • Go to dash.cloudflare.com/profile.
   • Your email is shown at the top under Email Address.
   • To view the key, click View next to Global API Key at the bottom.

2. Edit the cert-manager module settings, adding the following section:

   settings:
     cloudflareGlobalAPIKey: APIkey
     cloudflareEmail: some@mail.somedomain
   

   Or, use an API token instead (recommended):

   settings:
     cloudflareAPIToken: some-token
     cloudflareEmail: some@mail.somedomain
   

   DVP will automatically create a ClusterIssuer and Secret for Cloudflare in the d8-cert-manager namespace.

3. Create a Certificate resource using Cloudflare for DNS validation. This option becomes available only after the cloudflareGlobalAPIKey and cloudflareEmail parameters are configured:

   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: domain-wildcard
     namespace: app-namespace
   spec:
     secretName: tls-wildcard
     issuerRef:
       name: cloudflare
       kind: ClusterIssuer
     commonName: "*.domain.com"
     dnsNames:
     - "*.domain.com"
   

4. Create the Ingress resource:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: domain-wildcard
     namespace: app-namespace
   spec:
     ingressClassName: nginx
     rules:
     - host: "*.domain.com"
       http:
         paths:
         - backend:
             service:
               name: svc-web
               port:
                 number: 80
           path: /
     tls:
     - hosts:
       - "*.domain.com"
       secretName: tls-wildcard
   

Requesting a wildcard certificate using DNS in AWS Route53

1. Create a user with the required permissions:

   • On the policy management page, create a policy with the following permissions:

     {
         "Version": "2012-10-17",
         "Statement": [
             {
                 "Effect": "Allow",
                 "Action": "route53:GetChange",
                 "Resource": "arn:aws:route53:::change/*"
             },
             {
                 "Effect": "Allow",
                 "Action": "route53:ChangeResourceRecordSets",
                 "Resource": "arn:aws:route53:::hostedzone/*"
             },
             {
                 "Effect": "Allow",
                 "Action": "route53:ListHostedZonesByName",
                 "Resource": "*"
             }
         ]
     }
     

   • Open the user management page and create a user with the above policy.

2. Edit the cert-manager module settings to add the following section:

   settings:
     route53AccessKeyID: AKIABROTAITAJMPASA4A
     route53SecretAccessKey: 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
   

   DVP will automatically create a ClusterIssuer and Secret for Route53 in the d8-cert-manager namespace.

3. Create a Certificate resource for validation with Route53. This option becomes available only after the route53AccessKeyID and route53SecretAccessKey parameters are configured:

   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: domain-wildcard
     namespace: app-namespace
   spec:
     secretName: tls-wildcard
     issuerRef:
       name: route53
       kind: ClusterIssuer
     commonName: "*.domain.com"
     dnsNames:
     - "*.domain.com"
   

Requesting a wildcard certificate using DNS in Google

1. Create a ServiceAccount with the required role:

   • Open the policy management page.
   • Choose the target project and create a ServiceAccount under any name (for example, dns01-solver).
   • In the created account, create a key by clicking Add key. A JSON file with the key data will be downloaded.

   • Encode the JSON file as a Base64 string:

     base64 project-209317-556c656b81c4.json
     

2. Save the Base64 string in the cloudDNSServiceAccount parameter.

   DVP will automatically create a ClusterIssuer and Secret for CloudDNS in the d8-cert-manager namespace.

3. Create a Certificate resource using CloudDNS for validation:

   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: domain-wildcard
     namespace: app-namespace
   spec:
     secretName: tls-wildcard
     issuerRef:
       name: clouddns
       kind: ClusterIssuer
     dnsNames:
     - "*.domain.com"
   

Requesting a self-signed certificate

To issue a self-signed certificate, specify selfsigned as the value for issuerRef.name:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com            # Certificate name.
  namespace: default
spec:
  secretName: example-com-tls  # Name of the Secret that will store the private key and the certificate.
  issuerRef:
    kind: ClusterIssuer        # Certificate issuer details.
    name: selfsigned
  commonName: example.com      # Certificate main domain.
  dnsNames:                    # Optional additional certificate domains (at least one DNS name or IP address).
  - www.example.com
  - admin.example.com

Generating a self-signed certificate

When generating certificates manually, it is important to fill out all fields of the certificate request correctly to ensure that the final certificate is issued properly and can be validated across various services.

It is important to follow these guidelines:

1. Specify domain names in the SAN (Subject Alternative Name) field.

   The SAN field is a more modern and commonly used method for specifying the domain names covered by the certificate. Some services no longer consider the CN (Common Name) field as the source for domain names.

2. Correctly fill out the keyUsage, basicConstraints, extendedKeyUsage fields, specifically:

   • basicConstraints = CA:FALSE

     This field determines whether the certificate is an end-entity certificate or a certification authority (CA) certificate. CA certificates cannot be used as service certificates.

   • keyUsage = digitalSignature, keyEncipherment

     The keyUsage field limits the permissible usage scenarios of this key:

     • digitalSignature: Allows the key to be used for signing digital messages and ensuring data integrity.
     • keyEncipherment: Allows the key to be used for encrypting other keys, which is necessary for secure data exchange using TLS (Transport Layer Security).

   • extendedKeyUsage = serverAuth

     The extendedKeyUsage field specifies additional key usage scenarios required by specific protocols or applications:

     • serverAuth: Indicates that the certificate is intended for server use, authenticating the server to the client during the establishment of a secure connection.

It is also recommended to:

1. Issue the certificate for no more than 1 year (365 days).

   The validity period of the certificate affects its security. A one-year validity ensures the cryptographic methods remain current and allows for timely certificate updates in case of threats. Furthermore, some modern browsers now reject certificates with a validity period longer than 1 year.

2. Use robust cryptographic algorithms, such as elliptic curve algorithms (including prime256v1).

   Elliptic curve algorithms (ECC) provide a high level of security with a smaller key size compared to traditional methods like RSA. This makes the certificates more efficient in terms of performance and secure in the long term.

3. Do not specify domains in the CN (Common Name) field.

   Historically, the CN field was used to specify the primary domain name for which the certificate was issued. However, modern standards, such as RFC 2818, recommend using the SAN (Subject Alternative Name) field for this purpose. If the certificate is intended for multiple domain names listed in the SAN field, specifying one of the domains additionally in CN can cause a validation error in some services when accessing domains not listed in CN. If non-domain-related information is specified in CN (for example, an identifier or service name), the certificate will also extend to these names, which could be exploited for malicious purposes.

Certificate generation example

To generate a certificate, we’ll use the openssl utility.

1. Fill in the cert.cnf configuration file:

   [ req ]
   default_bits       = 2048
   default_md         = sha256
   prompt             = no
   distinguished_name = dn
   req_extensions     = req_ext
   [ dn ]
   C = GB
   ST = London
   L = London
   O = Example Company
   OU = IT Department
   # CN = Do not specify the CN field.
   [ req_ext ]
   subjectAltName = @alt_names
   [ alt_names ]
   # Specify all domain names.
   DNS.1 = example.co.uk
   DNS.2 = www.example.co.uk
   DNS.3 = api.example.co.uk
   # Specify IP addresses (if required).
   IP.1 = 192.0.2.1
   IP.2 = 192.0.4.1
   [ v3_ca ]
   basicConstraints = CA:FALSE
   keyUsage = digitalSignature, keyEncipherment
   extendedKeyUsage = serverAuth
   [ v3_req ]
   basicConstraints = CA:FALSE
   keyUsage = digitalSignature, keyEncipherment
   extendedKeyUsage = serverAuth
   subjectAltName = @alt_names
   # Elliptic curve parameters.
   [ ec_params ]
   name = prime256v1
   

2. Generate an elliptic curve key:

   openssl ecparam -genkey -name prime256v1 -noout -out ec_private_key.pem
   

3. Create a certificate signing request:

   openssl req -new -key ec_private_key.pem -out example.csr -config cert.cnf
   

4. Generate a self-signed certificate:

   openssl x509 -req -in example.csr -signkey ec_private_key.pem -out example.crt -days 365 -extensions v3_req -extfile cert.cnf
   

Protecting credentials

If you prefer not to store credentials in the DVP configuration, you can create a separate Secret and reference it in the ClusterIssuer resource.

To do this, follow these steps:

1. Create a Secret with the access key:

   d8 k apply -f - <<EOF
   apiVersion: v1
   kind: Secret
   type: Opaque
   metadata:
     name: route53
     namespace: default
   data:
     secret-access-key: MY-AWS-ACCESS-KEY-TOKEN
   EOF
   

2. Create a ClusterIssuer that references the Secret:

   d8 k apply -f - <<EOF
   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: route53
     namespace: default
   spec:
     acme:
       server: https://acme-v02.api.letsencrypt.org/directory
       privateKeySecretRef:
         name: route53-tls-key
       solvers:
       - dns01:
           route53:
             region: us-east-1
             accessKeyID: MY-AWS-ACCESS-KEY-ID
             secretAccessKeySecretRef:
               name: route53
               key: secret-access-key
   EOF
   

3. Request certificates as usual, using the created ClusterIssuer:

   d8 k apply -f - <<EOF
   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: example-com
     namespace: default
   spec:
     secretName: example-com-tls
     issuerRef:
       name: route53
     commonName: www.example.com 
     dnsNames:
     - www.example.com
   EOF
   

Support for tls-acme annotation

DVP supports the annotation kubernetes.io/tls-acme: "true" in Ingress resources. The cert-manager-ingress-shim component watches for this annotation and automatically creates Certificate resources in the same namespace as the Ingress.

Example Ingress configuration with the annotation:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/tls-acme: "true"           # Annotation.
  name: example-com
  namespace: default
spec:
  ingressClassName: nginx
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: site
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
  - host: www.example.com                    # Additional domain.
    http:
      paths:
      - backend:
          service:
            name: site
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
  - host: admin.example.com                  # Another additional domain.
    http:
      paths:
      - backend:
          service:
            name: site
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
  tls:
  - hosts:
    - example.com
    - www.example.com                        # Additional domain.
    - admin.example.com                      # Another additional domain.
    secretName: example-com-tls              # Name of the Certificate and Secret.