Manage SSL certificates for an HTTPS listener

Prerequisites

You have created an ACS cluster.
You have installed the ALB Ingress Controller add-on in the ACS cluster.

SSL certificate management scenarios

Key concepts

default certificate: Each listener has one default certificate. You can replace it but cannot add or delete it.
additional certificate: A listener supports multiple additional certificates that you can add or delete. Certificate quotas are listed in Quotas and limits.
listener certificate list: All certificates for a listener, viewable in the 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	AlbConfig-specified certificates
Set a new certificate as the default certificate	Log on to the ALB console to replace the default certificate.	Update the Secret resource associated with the Ingress. In the ALB console, verify the updated default certificate. If adjustments are needed, follow the Set an additional certificate as the default certificate procedure.	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 mitigate the risks. 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 mitigate the risks. 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 mitigate the risks. 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 describe each certificate management operation.

Replace the default certificate

Usage notes

Before replacing the default certificate, ensure the new certificate is available in Certificate Management Service. If not, Purchase a commercial certificate or Upload, synchronize, and share SSL certificates.

Use cases

The default certificate has expired and needs replacement.
The default certificate has not expired, but you want to replace it.
After you delete an additional certificate in the ALB console, you can set it as the new default.

Procedure

Log on to the ALB console and select the region of the target instance.
On the Instances page, find the target instance and click its Instance ID. On the instance details tab, turn off Configuration Read-only Mode.

Important
After you disable Configuration Read-only Mode, only the default certificate change is synchronized back to the ACS cluster. Other manual changes in the ALB console are overwritten during the next reconciliation. To verify synchronization, run kubectl describe albconfig [$Albconfig_Name] and check the status field.
Click the Listener tab, click the target listener ID, and then click the Certificates tab.
On the Server Certificates tab, find Default Server Certificate, and in the Actions column, click Replace.
In the Change Default Server Certificate dialog box, select your new certificate and click OK.

The listener's default certificate is now updated.
- To keep using the original default certificate, click Add EV Certificate on the Server Certificates tab to re-add it as an additional certificate.
- If the original certificate is no longer needed and not used by other resources, find it on the Server Certificates tab and click Delete in the Actions column. Otherwise, the unexpired certificate is automatically re-associated as an additional certificate during the next reconciliation.
Turn on Configuration Read-only Mode.

Delete an additional certificate

Deleting an additional certificate before promoting it to default can briefly disrupt services for the associated domain if no other valid certificate covers it. Confirm this will not affect your business before proceeding.

Usage notes

Review your listener's certificate list first. If the current default and additional certificates already meet your requirements, skip this operation.

As a best practice, upload a temporary certificate with the same domain name in Certificate Management Service before you begin. Add it as an additional certificate on the Server Certificates tab and confirm its status is Associated. Then delete the target additional certificate. After replacing the default certificate, delete the temporary certificate.

Use cases

The default certificate has expired. Delete an additional certificate, then follow Replace the default certificate in the ALB console to set it as the new default.
The default certificate has not expired, but you want to replace it. Delete an additional certificate, then follow Replace the default certificate in the ALB console to set the new default. Optionally re-add the original default as an additional certificate.
The ALB Ingress Controller selected an incorrect default certificate during reconciliation. Delete an additional certificate, follow Replace the default certificate in the ALB console to set the correct one, then re-add the original default as an additional certificate.

Procedure

Log on to the ALB console and select the region of the target instance.
On the Instances page, find the target instance and click its Instance ID. On the Instance Details tab, turn off Configuration Read-only Mode.

Important
After you disable Configuration Read-only Mode, only certificate changes from Replace the default certificate in the ALB console are synchronized back to the ACS cluster. Other manual changes in the ALB console are overwritten during the next reconciliation. To verify synchronization, run kubectl describe albconfig [$Albconfig_Name] and check the status field.
Click the Listener tab, click the target listener ID, and 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 to complete the operation.
Turn on Configuration Read-only Mode.

Add an additional certificate

Manually trigger a reconciliation

Use case

With certificate auto-discovery, the ALB Ingress Controller detects new SSL certificates only during reconciliation. To apply a newly purchased or uploaded certificate immediately, manually trigger a reconciliation.

Note

With certificate auto-discovery, each spec.rules[].host value must match a corresponding domain in spec.tls[].hosts[] to ensure correct certificate association.

Procedure

Modify the ALB Ingress configuration to trigger a reconciliation. Select a configuration from the ALB Ingress configuration dictionary.

If unsure which configuration to change, add a trivial annotation such as key_test: value_test to the Ingress YAML file. Example:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-https
  namespace: default
  annotations:
    key_test: value_test    # Add a trivial annotation to trigger 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

Update the Ingress.
```
kubectl apply -f demo.yaml
```

Verify that the reconciliation succeeded.

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 Secret resource

Use cases

To update an existing Secret, edit its YAML file and apply the changes. This automatically triggers an ALB Ingress Controller reconciliation. Configure an HTTPS certificate for encrypted communication.

To add a new Secret certificate, create the Secret resource, then add its name to the secretName field in the ALB Ingress TLS configuration.

Create a Secret resource. Configure an HTTPS certificate for encrypted communication.

Add the new Secret to the ALB Ingress configuration file.

In the Ingress YAML file, add the domain and secretName for the new Secret. Example:

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  # New domain for the new Secret resource.
    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  # Add the domain for the new Secret resource.
    secretName: newsecret    # Add the secretName for the new Secret resource.

Update the Ingress.

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

Update the certificate ID

Use case

If you manage certificates in an AlbConfig, update it whenever a certificate ID changes, such as after renewal or modification.

Procedure

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

Use the kubectl edit command to perform an incremental update.

View the AlbConfig name.
```
kubectl -n kube-system get AlbConfig
```

Update the 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 # New certificate ID.
        IsDefault: false
      port: 443
      protocol: HTTPS
      #...

Additional considerations

When you modify a certificate in Certificate Management Service (renewal, domain change), check whether the certificate ID has changed. If so, trigger an ALB Ingress update using your chosen certificate management method.
If you use multiple certificate configuration methods, check compatibility before updating. Configure an HTTPS certificate for encrypted communication.

FAQ

"Too many items" reconciliation error

Certificate pagination requires ALB Ingress Controller v2.11.0-aliyun.1 or later. The "Specified parameter array contains too many items, up to 15 items, Certificates is not valid" error means your controller version does not support pagination and you are trying to associate more than 15 certificates. Upgrade the ALB Ingress Controller to the latest version. Manage ALB Ingress Controller.

Prerequisites

SSL certificate management scenarios

Key concepts

Manage SSL certificates

Replace the default certificate

Usage notes

Use cases

Procedure

Delete an additional certificate

Usage notes

Use cases

Procedure

Add an additional certificate

Manually trigger a reconciliation

Use case

Procedure

Update the Secret resource

Use cases

Update the certificate ID

Use case

Procedure

Additional considerations

FAQ

"Too many items" reconciliation error

Related documents