Manage SSL certificates associated with an HTTPS listener of an ALB instance - Container Compute Service

This topic describes how to manage SSL certificates for an HTTPS listener, focusing on how to replace certificates that are about to expire or have expired.

Prerequisites

You have created an ACS cluster that runs Kubernetes 1.18 or later. To learn more, see Create an ACS cluster.
The ALB Ingress Controller component is installed in the cluster. To learn more, see Manage the ALB Ingress Controller add-on.

SSL certificate management scenarios

Terms

Default Certificate: A Default Certificate can only be replaced, not added or deleted. Each listener has one Default Certificate.
Additional Certificate: Additional Certificates can be added or deleted. A listener can have multiple Additional Certificates. For information about the certificate quota, see Limitations.
Listener certificate list: The list of certificates for a listener is viewable in the Application Load Balancer (ALB) console.
New certificate: A certificate that is not in the current listener certificate list.

Manage SSL certificates

Management scenario	Certificate auto discovery	Secret certificates	AlbConfigs certificates
Set a new certificate as the Default Certificate	Log on to the ALB console to replace the Default Certificate.	Update the Secret resource that is associated with the Ingress. Log on to the ALB console to verify the updated Default Certificate. If it is incorrect, follow the procedure in the Set an Additional Certificate as the Default Certificate scenario.	Use the `kubectl edit` command to update the certificate ID.
Set an Additional Certificate as the Default Certificate	Log on to the ALB console to delete the Additional Certificate. This is a high-risk operation. Perform it during off-peak hours and follow the risk mitigation steps. Log on to the ALB console to replace the Default Certificate.	Log on to the ALB console to delete the Additional Certificate. This is a high-risk operation. Perform it during off-peak hours and follow the risk mitigation steps. Log on to the ALB console to replace the Default Certificate.	Log on to the ALB console to delete the Additional Certificate. This is a high-risk operation. Perform it during off-peak hours and follow the risk mitigation steps. Log on to the ALB console to replace the Default Certificate.
Set a new certificate as an Additional Certificate	Manually trigger a reconciliation.	Update the Secret resource associated with the Ingress.	Use the `kubectl edit` command to update the certificate ID.

The following sections provide detailed procedures for managing SSL certificates.

Replace the default certificate

Notes

To replace the Default Certificate with a new certificate that is not in the listener's certificate list, first ensure the new certificate is available in the SSL Certificates Service. If the certificate does not exist, you can purchase or upload a new SSL certificate in the SSL Certificates Service. For more information, see Purchase a commercial certificate or Upload, sync, and share SSL certificates.

Use cases

The current Default Certificate has expired. Replace the expired Default Certificate with a new one.
Replace a Default Certificate that has not yet expired.
After you remove an additional certificate in the ALB console, set it as the new Default Certificate.

Procedure

Log on to the ALB console. In the top navigation bar, select the region where the instance is deployed.
On the Instances page, find the target instance and click its Instance ID. On the Instance Details tab, click Disable Configuration Read-only Mode and confirm the action in the dialog box.
Important
Once this mode is disabled, if you modify the listener configuration in the ALB console, only the Default Certificate configuration is written back to the ACK cluster after the next reconciliation. Other configuration changes are not written back, and these changes will be overwritten by the configuration from the cluster. Therefore, avoid performing other operations.
After the next reconciliation, run the kubectl describe albconfig [$Albconfig_Name] command in the cluster and check the Status field to verify that the Default Certificate configuration was written back.
Click the Listener tab, click the ID of the target listener, then click the Certificates tab.
On the Certificates tab, click the Server Certificates tab, find the default server certificate. In the Actions column, click Replace.
In the dialog box that appears, select your new certificate and click OK.
- If you still need to use the original Default Certificate, on the current Server Certificates page, click Add Additional Certificate to add it back to the listener as an Additional Certificate.
- If you are sure that the original Default Certificate is no longer needed and is not used by other instances or listeners, on the current Server Certificates page, find the certificate and click Delete in the Actions column to remove it. If you do not remove it, the unexpired original Default Certificate is automatically associated with the current listener as an Additional Certificate during the next configuration reconciliation.
Click Enable Configuration Read-only Mode.

Delete an additional certificate

This operation requires you to delete an Additional Certificate before promoting it to the Default Certificate. During this process, which typically takes a few seconds, if no other certificate for the same domain exists on the listener, requests to that domain will fail, causing a service disruption. Therefore, perform this operation with caution and only after you confirm that it will not affect your business.

Notes

Before you delete an Additional Certificate, check your listener certificate list. If the current Default Certificate and Additional Certificate configurations already meet your expectations, you do not need to perform these operations.

Before you start, you should upload a temporary certificate with the same domain name as the Additional Certificate to be removed. On the Server Certificates tab, click Add Additional Certificate and select the temporary certificate that you uploaded. After you confirm that the status of the temporary certificate is Associated, you can remove the Additional Certificate. After you replace the Default Certificate, delete the temporary one.

Use cases

If the current Default Certificate has expired, first delete the Additional Certificate and then follow the steps in Replace the Default Certificate to set it as the new Default Certificate.
If the current Default Certificate has not expired but you want to stop using it, you can delete an Additional Certificate and then follow the steps in Replace the Default Certificate to set it as the new Default Certificate. You can decide whether to add the original Default Certificate back as an Additional Certificate.
If the Default Certificate automatically selected during reconciliation is incorrect, you can delete an Additional Certificate, follow the steps in Replace the Default Certificate to set it as the new one, and then add the original Default Certificate back as an Additional Certificate.

Procedure

Log on to the ALB console. In the top navigation bar, select the region where the instance is deployed.
On the Instances page, find the target instance and click its Instance ID. On the Instance Details tab, click Disable Configuration Read-only Mode.
Important
Once this mode is disabled, if you modify the listener configuration in the ALB console, only the certificate configuration updated by following the steps in Replace the Default Certificate is written back to the ACK cluster after the next reconciliation. Other configuration changes are not written back. This means that during the next reconciliation, these changes will be overwritten by the configuration from the cluster. Therefore, avoid performing other operations.
After the next reconciliation, run the kubectl describe albconfig [$Albconfig_Name] command in the cluster and check the Status field to verify that the certificate configuration was written back.
Click the Listener tab, click the ID of the target listener, then click the Certificates tab.
On the Server Certificates tab, find the Additional Certificate that you want to delete. In the Actions column, click Delete and follow the on-screen instructions.
Click Enable Configuration Read-only Mode.

Add a new additional certificate

Manually trigger a reconciliation

Use case

If you use certificate auto-discovery, the ALB Ingress Controller does not immediately detect new SSL certificates that you purchase or upload. The ALB Ingress Controller queries and retrieves certificates only during a reconciliation. To apply the new certificate immediately, you must manually trigger a reconciliation.

Note

If you use certificate auto-discovery, make sure that the value of the spec.rules[ ].host field in the Ingress configuration file corresponds to the domain names listed in the spec.tls[ ].hosts[ ] field. This allows each domain name to be associated with its corresponding certificate.

Procedure

To trigger a reconciliation and update the certificate, modify the ALB Ingress configuration. Select a configuration to modify from the ALB Ingress GlobalConfiguration dictionary based on your business needs.

If you are unsure of the specific configuration requirements, you can add a non-critical annotation to the Ingress YAML file, such as key_test: value_test, to trigger a reconciliation. An example is shown below.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-https
  namespace: default
  annotations:
    key_test: value_test # Add a meaningless annotation to trigger a reconciliation. 
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 update the Ingress:
```
kubectl apply -f demo.yaml
```
Run the following command to verify that the reconciliation is successful:
```
kubectl describe ingress demo-https -n default
```
(Optional) Delete the trivial annotation from the Ingress YAML file and run the command in Step 2 to update the Ingress.

Update the Ingress Secret resource

Use cases

If you need to update a Secret resource that is used by an ALB Ingress, you can edit the Secret resource's YAML file and apply the updated file to the Kubernetes cluster. This operation automatically triggers a reconciliation by the ALB Ingress Controller. For more information, see Configure certificates for encrypted communication over HTTPS.

If you need to add a new Secret certificate to an ALB Ingress, you must first create a new Secret resource. Then, modify the ALB Ingress resource's configuration file to add the new Secret resource name to the secretName field in the tls section.

Create a new Secret resource. For more information, see Configure certificates for encrypted communication over HTTPS.
Add the new Secret resource to the ALB Ingress resource's configuration file.

In the Ingress YAML file, add the domain name and secretName for the new Secret resource. The following is a code sample.

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
  - host: newsecret.alb.ingress.top  # The domain name that is associated with the Secret. 
    http:
      paths:
      - backend:
          service:
            name: demo-service-https
            port:
              number: 443
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - demo.alb.ingress.top
    secretName: secret-tls
  - hosts:    
    - newsecret.alb.ingress.top  # The domain name that is associated with the Secret. 
    secretName: newsecret    # The name of the Secret.

Run the following command to update the Ingress:

kubectl apply -f demo.yaml # Replace demo.yaml with the name of your YAML file.

Update certificate IDs by using kubectl edit

Use case

If you specify certificates in AlbConfig, update the AlbConfig whenever a certificate's ID changes (for example, after a purchase, upload, or modification).

Procedure

Obtain the Certificate ID.
- Log on to the Certificate Management Service console.
- In the left navigation pane, choose SSL Certificate Management.
- Click the Uploaded Certificates tab. In the Actions column of the target certificate, click More. In the certificate details panel, obtain the Certificate ID.

Run the kubectl edit command to update the AlbConfig.

Run the following command to view the AlbConfig name:
```
kubectl -n kube-system get AlbConfig
```

Run the following command to update the corresponding AlbConfig:

kubectl -n <NameSpace> edit AlbConfig <AlbConfig_Name>

Update the certificate ID in the YAML file.

  #...
  spec:
    config:
      #...
    listeners:
    - caEnabled: false
      certificates:
      #...
      - CertificateId: 756****-cn-hangzhou # The certificate ID. 
        IsDefault: false
      port: 443
      protocol: HTTPS
      #...

Additional information

When you modify a certificate (for example, by renewing it or changing its domain), check if the Certificate ID has changed. If the Certificate ID changes, you must trigger an update in ALB Ingress based on your certificate management method.

FAQ

What should I do if reconciliation fails with a "too many items" error?

Starting from version v2.11.0-aliyun.1, the ALB Ingress Controller supports certificate pagination. If you receive the error message "Specified parameter array contains too many items, up to 15 items, Certificates is not valid" during reconciliation, it means that the version of the ALB Ingress Controller that you are using does not support certificate pagination, and you are trying to associate more than 15 certificates in a single reconciliation.

To resolve this issue, upgrade the ALB Ingress Controller to the latest version. See Manage the ALB Ingress Controller.

Container Compute Service:Manage SSL certificates for an HTTPS listener

Prerequisites

SSL certificate management scenarios

Terms

Manage SSL certificates

Replace the default certificate

Notes

Use cases

Procedure

Delete an additional certificate

Notes

Use cases

Procedure

Add a new additional certificate

Manually trigger a reconciliation

Use case

Procedure

Update the Ingress Secret resource

Use cases

Update certificate IDs by using kubectl edit

Use case

Procedure

Additional information

FAQ

What should I do if reconciliation fails with a "too many items" error?

Related documentation