Configure ACME in Kubernetes environment

Available in Classic and VPC

This guide explains how to use cert-manager to obtain certificates from the Ncloud ACME server in a Kubernetes cluster.

Before you start

After completing all the steps in ACME prerequisites, the following items must be ready.

• Issued EAB Key ID and EAB HMAC Key
• kubectl usage permissions and cluster-admin permissions
• DNS provider accounts and API permissions supported by cert-manager (see the list of supported items)
• When using an OV certificate, complete organization validation under Certificate Manager > Organization

Workflow

The certificate automation workflow using cert-manager is as follows:

  User's browser
       │ HTTPS
       ▼
  Ingress
       │ See tls.secretName
       ▼
  K8s Secret (to store certificate)
       ▲ Automatic issuance/renewal
       │
  cert-manager
       │ ACME DNS-01 challenge
       ▼
  Ncloud ACME server  ←→  DNS provider (automatic TXT record processing)

cert-manager attempts automatic renewal at two-thirds of the certificate's lifetime. To explicitly specify the renewal time, use Certificate.spec.renewBefore field.

Step 1: Install cert-manager

Run the following command to install cert-manager on the cluster.

kubectl apply -f \
  https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

After installation, wait until all Pods reach Running state.

kubectl get pods -n cert-manager

Sample output:

NAME                                       READY   STATUS    RESTARTS
cert-manager-xxxx                          1/1     Running   0
cert-manager-cainjector-xxxx               1/1     Running   0
cert-manager-webhook-xxxx                  1/1     Running   0

Step 2: Create EAB Secret

Store the EAB HMAC key to be used for ACME account registration as a Kubernetes Secret. Replace [EAB_HMAC_KEY] with the actual value you received and run.

kubectl create secret generic ncp-acme-eab \
  --from-literal secret="[EAB_HMAC_KEY]" \
  -n cert-manager

Step 3: Create ClusterIssuer

cert-manager provides two issuer resources.

This guide uses the generally recommended ClusterIssuer. Create clusterissuer.yaml file with the following content. Replace [EAB_KEY_ID], admin@example.com, solvers sections to suit your environment.

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: ncp-acme
spec:
  acme:
    server: https://acme.navercloudtrust.com/acme/directory
    email: admin@example.com
    privateKeySecretRef:
      name: ncp-acme-account-key
    externalAccountBinding:
      keyID: "[EAB_KEY_ID]"
      keySecretRef:
        name: ncp-acme-eab
        key: secret
    solvers:
    - dns01:
        # Configure based on the DNS provider in use
        # For detailed configuration, see the official cert-manager documentation.
        # https://cert-manager.io/docs/configuration/acme/dns01/

After creating the file, run the following command to create the ClusterIssuer.

kubectl apply -f clusterissuer.yaml

After creation, verify the registration status. If the status of Ready is True, it is normal.

kubectl get clusterissuer ncp-acme
kubectl describe clusterissuer ncp-acme

Step 4: Request certificate

Create a certificate resource to request a certificate. Create certificate.yaml file with the following content.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: company-tls
  namespace: default
spec:
  secretName: company-tls-secret
  issuerRef:
    name: ncp-acme
    kind: ClusterIssuer
  dnsNames:
  - www.example.com
  - api.example.com

kubectl apply -f certificate.yaml

To view the issuance status, run the following command. Wait until the Ready status changes to True. It may take a few minutes to complete the DNS-01 challenge.

# View certificate issuance status
kubectl get certificate company-tls -n default

# View event details (identify the cause of error)
kubectl describe certificate company-tls -n default
kubectl describe certificaterequest -n default

# View the secret after issuance is complete
kubectl get secret company-tls-secret -n default

To reissue a certificate, delete the certificate resource and then recreate it.

kubectl delete -f certificate.yaml
kubectl apply -f certificate.yaml

Step 5: Apply Ingress

Apply the issued certificate to Ingress. Create ingress.yaml file with the following content.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: company-ingress
  annotations:
    cert-manager.io/cluster-issuer: "ncp-acme"
spec:
  tls:
  - hosts:
    - www.example.com
    secretName: company-tls-secret
  rules:
  - host: www.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: company-service
            port:
              number: 80

kubectl apply -f ingress.yaml

Troubleshooting

Security advisory

• Configure RBAC so that ncp-acme-eab secrets that store the EAB HMAC key and the ACME account key ncp-acme-account-key secrets are accessible only within the cert-manager namespace.
• Minimize access permissions to the secret that stores the DNS provider API key.
• We recommend granting only the minimum permissions required for the DNS service to the DNS provider API key.
• Do not commit secret resources directly to the Git repository. We recommend using sealed secrets or an external secret management tool.

Reference documents

• cert-manager official documentation
• Configure cert-manager ACME DNS-01
• cert-manager External Account Binding