Alibaba Cloud Service Mesh:Issue certificates for ASM ingress gateways with an ACME CA

How it works

When you create an ACME Issuer resource in cert-manager, cert-manager generates a private key for secure communication with the ACME CA server. To issue a certificate, the CA must first verify that you own the domain. It does this through challenges.

cert-manager supports two challenge types:

The following steps use HTTP-01 challenges with the Ingress API. ASM also supports the Gateway API for solving challenges.

For the full ACME protocol specification, see RFC 8555.

Prerequisites

• A Container Service for Kubernetes (ACK) cluster is added to an ASM instance of V1.16 or later. For more information, see Add a cluster to an ASM instance and Update an ASM instance.

• An ingress gateway is deployed with ports 80 and 443 exposed. For more information, see Create an ingress gateway.

• An HTTPBin application is deployed in the ACK cluster added to the ASM instance. For more information, see Deploy the HTTPBin application.

• cert-manager is installed. For more information, see Install cert-manager in your cluster.

• Ingress API access is enabled for the ASM ingress gateway. For more information, see Enable Ingress on the ASM gateway.

Step 1: Prepare a public domain

Point a public domain to the IP address of your ASM ingress gateway. The Let's Encrypt CA needs to reach your domain over the public Internet to complete HTTP-01 challenges.

For DNS configuration instructions, see the documentation of your DNS provider. If you use Alibaba Cloud DNS, see Add DNS records. For more information about Let's Encrypt, see Getting Started.

Step 2: Create an Issuer resource

An Issuer tells cert-manager how to request certificates from a CA. In this step, create an Issuer that connects to the Let's Encrypt production server.

Use the kubeconfig file of the ACK cluster on the data plane and create the following Issuer resource:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt-prod-issuer
  namespace: istio-system
spec:
  acme:
    # Email for certificate-related notifications (optional but recommended)
    email: '<your-email@example.com>'
    # ACME account private key stored in this Secret
    privateKeySecretRef:
      name: letsencrypt-prod
    # Let's Encrypt production server
    server: https://acme-v02.api.letsencrypt.org/directory
    solvers:
    # Use HTTP-01 challenges routed through the Istio Ingress class
    - http01:
        ingress:
          ingressClassName: istio

This Issuer uses an HTTP-01 solver with ingressClassName: istio. When a challenge is triggered, cert-manager creates a temporary Ingress resource with this class, which routes the challenge request through the ASM ingress gateway to a cert-manager solver pod.

Verify that the Issuer is ready:

kubectl -n istio-system get issuer letsencrypt-prod-issuer

Expected output:

NAME                      READY   AGE
letsencrypt-prod-issuer   True    8m3s

If READY shows False, see Troubleshooting.

Step 3: Issue a certificate

Create a Certificate resource that references the Issuer from Step 2. cert-manager uses this resource to request a certificate from Let's Encrypt for your domain.

Use the kubeconfig file of the ACK cluster on the data plane and create the following Certificate resource:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: istio-ingressgateway-certs
  namespace: istio-system
spec:
  # Domain names to include in the certificate
  dnsNames:
  - <your-domain.com>
  issuerRef:
    group: cert-manager.io
    kind: Issuer
    name: letsencrypt-prod-issuer
  # Secret where the issued certificate and private key are stored
  secretName: istio-ingressgateway-certs

Replace <your-domain.com> with your actual domain name (for example, example.com).

Verify that the Certificate is ready:

kubectl -n istio-system get certificate istio-ingressgateway-certs

Expected output:

NAME                         READY   SECRET                       AGE
istio-ingressgateway-certs   True    istio-ingressgateway-certs   59m

If READY shows False after several minutes, see Troubleshooting.

kubectl -n istio-system logs <ingress-gateway-pod-name> | grep letsencrypt | tail -1

{
    "authority_for": "xxxxxxx",
    "bytes_received": "0",
    "bytes_sent": "87",
    "downstream_local_address": "xx.xx.xx.xx:80",
    "downstream_remote_address": "xx.xx.xx.xx:57101",
    "duration": "0",
    "istio_policy_status": "-",
    "method": "GET",
    "path": "/.well-known/acme-challenge/JfKvfdSNmkR7UqmCQU0OSkJC3EsnP4ZUiCc28OLLLxA",
    "protocol": "HTTP/1.1",
    "request_id": "e6806d08-0469-4383-be8e-4d7506b39ec5",
    "requested_server_name": "-",
    "response_code": "200",
    "response_flags": "-",
    "route_name": "-",
    "start_time": "2024-04-08T12:04:06.153Z",
    "trace_id": "-",
    "upstream_cluster": "outbound|8089||cm-acme-http-solver-c4ch9.istio-system.svc.cluster.local",
    "upstream_host": "xx.xx.xx.xx:8089",
    "upstream_local_address": "xx.xx.xx.xx:55886",
    "upstream_response_time": "0",
    "upstream_service_time": "0",
    "upstream_transport_failure_reason": "-",
    "user_agent": "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)",
    "x_forwarded_for": "xx.xx.xx.xx"
}

Step 4: Configure the ASM ingress gateway to use the certificate

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: httpbin-https
  namespace: default
spec:
  selector:
    istio: ingressgateway
  servers:
  - hosts:
    - <your-domain.com>
    port:
      name: https
      number: 443
      protocol: HTTPS
    tls:
      # Reference the Secret created by cert-manager
      credentialName: istio-ingressgateway-certs
      mode: SIMPLE

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: httpbin-vs
  namespace: default
spec:
  gateways:
    - httpbin
    - httpbin-https    # Add the HTTPS Gateway
  hosts:
    - '*'
  http:
    - name: test
      route:
        - destination:
            host: httpbin.default.svc.cluster.local
            port:
              number: 8000

Verify the certificate

Open https://<your-domain.com> in a browser. Click the lock icon in the address bar. The browser displays Connection is secure, confirming that it trusts the Let's Encrypt certificate.

To verify from the command line:

curl -v https://<your-domain.com> 2>&1 | grep -E "SSL certificate|issuer"

The output shows Let's Encrypt as the certificate issuer.

Troubleshooting

kubectl -n istio-system describe issuer letsencrypt-prod-issuer

kubectl -n istio-system describe certificate istio-ingressgateway-certs

kubectl -n istio-system get certificaterequest
kubectl -n istio-system get order
kubectl -n istio-system get challenge

What's next

• Manage Istio gateways

• Manage virtual services