how to use an ALB Ingress to configure certificates for an HTTPS listener - Container Service for Kubernetes

When an HTTPS listener forwards HTTPS requests, the listener needs to create a TLS connection by using a certificate. Application Load Balancer (ALB) Ingresses support automatic certificate discovery, certificates stored as Secrets, and HTTPS listener certificate configuration by using an AlbConfig. This topic describes how to use an ALB Ingress to configure certificates for an HTTPS listener.

Prerequisites

Certificate configuration method comparison

Compatibility of certificates configured by using different methods

Configure automatic certificate discovery

Manage certificates by using Kubernetes Secrets

Specify certificates in AlbConfigs

Prerequisites

ALB Ingress controller 2.5.0 or later is installed. For more information, see Manage components.
A trusted certificate is obtained. You can obtain a trusted certificate by using one of the following methods:
- Purchase a certificate in the Certificate Management Service console. For more information, see Purchase an SSL certificate.
- Purchase a certificate that is issued by another certificate authority (CA) or create a self-signed certificate.
- Create a certificate that is stored as a Kubernetes Secret.

Certificate configuration method comparison

ALB Ingresses allow you to configure automatic certificate discovery, manage certificates as Kubernetes Secrets, and specify certificates in AlbConfigs. The following table compares the preceding methods.

Note

ALB Ingresses do not affect persistent connections.

Item	Use automatic certificate discovery	Manage certificates as Kubernetes Secrets	Specify certificates in AlbConfigs
Scenarios	This feature is suitable for certificates that are purchased in the Certificate Management Service console or certificates that are uploaded to the Certificate Management Service console.	This feature is suitable for certificates managed in the cluster. For example, if you use cert-manager to manage certificates, the certificates for ALB instances are automatically updated together with the corresponding Secrets.	To use this feature, you must upload the certificate that you want to use to the Certificate Management Service console. This feature is suitable for scenarios where the certificate that you want to use shares the same domain name with other certificates.
Automatically renew certificates for relevant ALB instances	Not supported. You must manually renew certificates for ALB instances.	Supported	Not supported. You must manually renew certificates for ALB instances.
Priority	Low	Medium	High
Use certificates across namespaces	Supported	Not supported. A certificate stored as a Secret can be used only within the namespace of the Secret.	Supported. AlbConfigs are cluster-scoped resources and take effect within all namespaces in a cluster.
How to renew certificates	You must upload a new certificate to the Certificate Management Service console or renew the original certificate in the Certificate Management Service console. Then, you need to manually modify Ingress configurations, such as the Ingress name and annotations, so that the new certificate can be automatically discovered.	You must update the Secret that is associated with the Ingress.	You must upload a new certificate to the Certificate Management Service console or renew the original certificate in the Certificate Management Service console. Then, you need to manually update the AlbConfig to specify the new certificate ID.
References	Configure automatic certificate discovery	Manage certificates by using Kubernetes Secrets	Specify certificates in AlbConfigs

Compatibility of certificates configured by using different methods

The following table describes the compatibility of different certificate configuration methods.

How certificates are configured	Description
A certificate is configured by using automatic certificate discovery and a certificate is configured by using a Kubernetes Secret.	If both certificates are associated with the same domain name, the certificate that is configured by using a Secret is preferably used. If the certificates are associated with different domain names, the ALB Ingress controller use the certificates for the corresponding domain names.
A certificate is configured by using automatic certificate discovery and a certificate is specified in an AlbConfig. Both certificates are associated with the same listener.	The listener uses only the certificate specified in the AlbConfig. If no certificate is specified in the AlbConfig, the listener uses the certificate configured by using automatic certificate discovery.
A certificate is configured by using a Kubernetes Secret and a certificate is specified in an AlbConfig.	Both certificates are used.

Configure automatic certificate discovery

This section describes how to configure automatic certificate discovery for self-signed certificates.

Note

An ALB instance supports a maximum of 25 additional certificates, including certificates that share the same domain name.

Run the following OpenSSL commands to create a self-signed certificate:

openssl genrsa -out albtop-key.pem 4096
openssl req -subj "/CN=demo.alb.ingress.top" -sha256  -new -key albtop-key.pem -out albtop.csr
echo subjectAltName = DNS:demo.alb.ingress.top > extfile.cnf
openssl x509 -req -days 3650 -sha256 -in albtop.csr -signkey albtop-key.pem -out albtop-cert.pem -extfile extfile.cnf

Upload the self-signed certificate to the Certificate Management Service console. For more information, see Upload and share SSL certificates.

Create an Ingress, a Service, and an application.

Create a file named demo.yaml and copy the following content to the file.

Add the following setting to the YAML template of the Ingress to specify the domain name in the created certificate:

tls:
  - hosts:
    - demo.alb.ingress.top

Show sample code

apiVersion: v1
kind: Service
metadata:
  name: demo-service-https
  namespace: default
spec:
  ports:
    - name: port1
      port: 443
      protocol: TCP
      targetPort: 8080
  selector:
    app: demo-cafe
  sessionAffinity: None
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-cafe
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demo-cafe
  template:
    metadata:
      labels:
        app: demo-cafe
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/alb-sample/cafe:v1
          imagePullPolicy: IfNotPresent
          name: demo-cafe
          ports:
            - containerPort: 8080
              protocol: TCP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-https
  namespace: default
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - backend:
          service:
            name: demo-service-https
            port:
              number: 443
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - demo.alb.ingress.top

Run the following command to create an Ingress, a Service, and an application:
```
kubectl apply -f demo.yaml
```

Run the following command to check whether the certificate is configured:
```
curl https://demo.alb.ingress.top/tea
```
Expected output:
```
{"hello":"tee"}
```
If the preceding output is returned, the certificate is configured.

Manage certificates by using Kubernetes Secrets

This section describes how to manage a self-signed certificate by using a Kubernetes Secret.

Note

You can store a certificate in multiple Secrets. You can associate multiple certificates with an ALB instance. However, an ALB instance supports a maximum of 25 additional certificates.

Run the following OpenSSL commands to create a self-signed certificate:

openssl genrsa -out albtop-key.pem 4096
openssl req -subj "/CN=demo.alb.ingress.top" -sha256  -new -key albtop-key.pem -out albtop.csr
echo subjectAltName = DNS:demo.alb.ingress.top > extfile.cnf
openssl x509 -req -days 3650 -sha256 -in albtop.csr -signkey albtop-key.pem -out albtop-cert.pem -extfile extfile.cnf

Encode the content in the albtop-key.pem and albtop-cert.pem files that are generated in Step 1 by using Base64.
```
echo -n <albtop-key.pem> | base64
```
```
echo -n <albtop-cert.pem> | base64
```

Create a Secret.

Create a file named secret.yaml and copy the following content to the file:

apiVersion: v1
kind: Secret
metadata:
  name: secret-tls
type: kubernetes.io/tls
data:
  # the data is abbreviated in this example
  tls.crt: |
    {base64 albtop-cert.pem} # Base64-encoded content of the albtop-cert.pem file. 
  tls.key: |
    {base64 albtop-key.pem}  # Base64-encoded content of the albtop-key.pem file.

Run the following command to create a Secret:
```
kubectl apply -f secret.yaml
```

Create an Ingress, a Service, and an application.

Create a file named demo.yaml and copy the following content to the file.

Add the following setting to the YAML template of the Ingress to specify the domain name in the created certificate:

tls:
  - hosts:
    - demo.alb.ingress.top
    secretName: secret-tls

Show sample code

apiVersion: v1
kind: Service
metadata:
  name: demo-service-https
  namespace: default
spec:
  ports:
    - name: port1
      port: 443
      protocol: TCP
      targetPort: 8080
  selector:
    app: demo-cafe
  sessionAffinity: None
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-cafe
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demo-cafe
  template:
    metadata:
      labels:
        app: demo-cafe
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/alb-sample/cafe:v1
          imagePullPolicy: IfNotPresent
          name: demo-cafe
          ports:
            - containerPort: 8080
              protocol: TCP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-https
  namespace: default
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - backend:
          service:
            name: demo-service-https
            port:
              number: 443
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - demo.alb.ingress.top
    secretName: secret-tls

Run the following command to create an Ingress, a Service, and an application:
```
kubectl apply -f demo.yaml
```

Run the following command to check whether the certificate is configured:
```
curl https://demo.alb.ingress.top/tea
```
Expected output:
```
{"hello":"tee"}
```
If the preceding output is returned, the certificate is configured.

Specify certificates in AlbConfigs

This section describes how to specify a self-signed certificate in an AlbConfig.

Note

If a listener is configured with a certificate ID, the domain names associated with the listener no longer use certificates stored as Secrets or the automatic certificate discovery feature.

Run the following OpenSSL commands to create a self-signed certificate:

openssl genrsa -out albtop-key.pem 4096
openssl req -subj "/CN=demo.alb.ingress.top" -sha256  -new -key albtop-key.pem -out albtop.csr
echo subjectAltName = DNS:demo.alb.ingress.top > extfile.cnf
openssl x509 -req -days 3650 -sha256 -in albtop.csr -signkey albtop-key.pem -out albtop-cert.pem -extfile extfile.cnf

Upload the self-signed certificate to the Certificate Management Service console. For more information, see Upload and share SSL certificates.
Obtain the certificate ID.
1. Log on to the Certificate Management Service console.
2. In the left-side navigation pane, click SSL Certificates.
3. On the SSL Certificates page, click the Manage Uploaded Certificates tab. Find the certificate that you want to view and choose > Details in the Actions column.
  In the Certificate Details panel, you can view the certificate ID.

Specify the certificate in an AlbConfig.

Create an AlbConfig and specify the certificate

Create a file named albconfig.yaml and copy the following content to the file:

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: alb-demo
spec:
  config:
    #...
  listeners:
  - caEnabled: false
    certificates:
    - CertificateId: 756****-cn-hangzhou # Set the value to the certificate ID that you obtained.
      IsDefault: true
    port: 443
    protocol: HTTPS
  #...

Parameter	Description
CertificateId	The certificate ID. In this example, 756-cn-hangzhou is specified. Specify the value of CertificateId based on the following description: If the certificate is created in a region in China, set the value to 756-cn-hangzhou. -cn-hangzhou is fixed content. You need to only replace 756**. If the certificate is created in a region outside China, set the value to 756**-ap-southeast-1. -ap-southeast-1 is fixed content. You need to only replace 756****.
IsDefault	Specifies whether to set the certificate as the default certificate. In this example, true is specified. The certificate is set as the default certificate.
protocol	The protocol used by listeners. In this example, HTTPS is specified. The HTTPS protocol is used by listeners.

Run the following command to create an AlbConfig:
```
kubectl apply -f albconfig.yaml
```

Specify the certificate in an existing AlbConfig

You can run the kubectl edit command to perform an incremental update on an existing AlbConfig.

Run the following command to query the AlbConfig that you want to use:
```
kubectl -n kube-system get AlbConfig
```
Expected output:
```
NAME AGE
alb-demo 87m
```

Run the following command to update the AlbConfig:

kubectl -n kube-system edit AlbConfig alb-demo
  #...
  spec:
    config:
      #...
    listeners:
    - caEnabled: false
      certificates:
      - CertificateId: 756****-cn-hangzhou # Set the value to the certificate ID that you obtained.
        IsDefault: true
      port: 443
      protocol: HTTPS
      #...

For more information about how to update an AlbConfig, see Update an AlbConfig.

Create an Ingress, a Service, and an application.

Create a file named demo.yaml and copy the following content to the file.

Note

In this example, the tls parameter is used only as the identifier for associating with listening port 443. The parameter is not used to configure automatic certificate discovery.

Show sample code

apiVersion: v1
kind: Service
metadata:
  name: demo-service-https
  namespace: default
spec:
  ports:
    - name: port1
      port: 443
      protocol: TCP
      targetPort: 8080
  selector:
    app: demo-cafe
  sessionAffinity: None
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-cafe
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demo-cafe
  template:
    metadata:
      labels:
        app: demo-cafe
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/alb-sample/cafe:v1
          imagePullPolicy: IfNotPresent
          name: demo-cafe
          ports:
            - containerPort: 8080
              protocol: TCP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-https
  namespace: default
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - backend:
          service:
            name: demo-service-https
            port:
              number: 443
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - demo.alb.ingress.top

Run the following command to create an Ingress, a Service, and an application:
```
kubectl apply -f demo.yaml
```

Run the following command to check whether the certificate is configured:
```
curl https://demo.alb.ingress.top/tea
```
Expected output:
```
{"hello":"tee"}
```

Container Service for Kubernetes:Use an ALB Ingress to configure certificates for an HTTPS listener

Table of contents

Prerequisites

Certificate configuration method comparison

Compatibility of certificates configured by using different methods

Configure automatic certificate discovery

Manage certificates by using Kubernetes Secrets

Specify certificates in AlbConfigs

Create an AlbConfig and specify the certificate

Specify the certificate in an existing AlbConfig