Manage SSL certificates for HTTPS listeners on ALB - Container Service for Kubernetes

This topic describes how to manage SSL certificates for HTTPS listeners. It focuses on how to smoothly replace certificates that are about to expire or have already expired.

Prerequisites

An ACK managed cluster, ACK dedicated cluster, or ACK Serverless cluster is created. The Kubernetes version must be 1.18 or later. For more information, see Create an ACK managed cluster, Create an ACK dedicated cluster (new creation has been stopped), Create an ACK Serverless cluster, or Manually upgrade a cluster.
The ALB Ingress Controller component is installed for the cluster. For more information, see Manage the ALB Ingress Controller component.
Note
To access Services through an ALB Ingress in an ACK dedicated cluster, you must grant access permissions to the ALB Ingress Controller before you deploy the Services. For more information, see Grant the ALB Ingress Controller access permissions to an ACK dedicated cluster.
You have obtained the KubeConfig file of the cluster and used kubectl to connect to the cluster.

SSL certificate management scenarios

Terms

Default certificate: You can only replace the default certificate. You cannot add or delete it. Each listener has a unique default certificate.
Extension certificate: You can add and delete extension certificates. Each listener can have multiple extension certificates. For more information about certificate quotas, see Limits.
Listener certificate list: You can log on to the Application Load Balancer (ALB) console to view the certificates of a listener.
New certificate: A certificate that is not in the certificate list of the current listener.

Manage SSL certificates

Note

Starting from ALB Ingress Controller v2.18.0-aliyun.1, you can specify the default certificate using the defaultCertificate field in the AlbConfig. For more information, see ALB Ingress Controller release notes.

Certificate management scenario	Auto-discovered certificate	Secret certificate	Certificate specified in AlbConfig
Set a new certificate as the default certificate	Method 1 (Recommended) Specify the default certificate using defaultCertificate	Method 1 (Recommended) Specify the default certificate using defaultCertificate	Update the certificate ID using the `kubectl edit` command.
Set a new certificate as the default certificate	Method 2 Log on to the ALB console to replace the default certificate.	Method 2 Update the Secret resource associated with the Ingress. Log on to the ALB console to confirm that the default certificate is updated as expected. To make adjustments, perform the operations described in the "Set an extension certificate as the default certificate" scenario.	Update the certificate ID using the `kubectl edit` command.
Set an extension certificate as the default certificate	Method 1 (Recommended) Specify the default certificate using defaultCertificate	Method 1 (Recommended) Specify the default certificate using defaultCertificate	Method 1 (Recommended) Specify the default certificate using defaultCertificate
Set an extension certificate as the default certificate	Method 2 Log on to the ALB console Delete the extension certificate. This is a high-risk operation. Perform this operation during off-peak hours and take note of how to avoid risks. Replace the default certificate.	Method 2 Log on to the ALB console Delete the extension certificate. This is a high-risk operation. Perform this operation during off-peak hours and take note of how to avoid risks. Replace the default certificate.	Method 2 Log on to the ALB console Delete the extension certificate. This is a high-risk operation. Perform this operation during off-peak hours and take note of how to avoid risks. Replace the default certificate.
Set a new certificate as an extension certificate	Manually trigger a reconciliation.	Update the Secret resource associated with the Ingress.	Update the certificate ID using the `kubectl edit` command.

For more information about auto-discovered certificates, Secret certificates, and certificates specified in AlbConfig, see Configure an HTTPS certificate for encrypted communication.

Replace the default certificate in the ALB console

Notes

If you want to replace the default certificate with a new certificate that is not in the certificate list of the current listener, first check whether the new certificate is available in Alibaba Cloud Digital Certificate Management Service. If the certificate does not exist, you can purchase or upload a new SSL Certificate in the Digital Certificate Management Service console. For more information, see Purchase a commercial certificate and Upload, synchronize, and share SSL certificates.

Scenarios

The current default certificate has expired. You need to replace the expired default certificate with a new one.
The current default certificate has not expired, but you decide to stop using it. You can replace the unexpired default certificate with a new one.
After you delete an extension certificate in the ALB console, set that certificate as the new default certificate.

Procedure

Log on to the ALB console. In the top menu bar, select the region where the instance is deployed.
On the Instances page, find the target instance and click the instance ID. On the instance details tab, click Disable Configuration Read-only Mode.
Important
After you disable configuration read-only mode, if you change listener configurations 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 to the cluster. This means that during the next reconciliation, these configurations may be overwritten by the configurations from the cluster. Therefore, perform other operations with caution. After the next reconciliation, you can run the kubectl describe albconfig [$Albconfig_Name] command in the cluster and check the content of the status field to verify that the default certificate configuration was successfully written back.
Click the Listener tab. Click the ID of the target listener to go to the listener details page. Then, click the Certificates tab.
On the Server Certificates tab, find the default server certificate for the listener. In the Actions column, click Replace.
In the dialog box that appears, select your new certificate and click OK.
After you perform this operation, the default certificate of the listener is updated to the new certificate.
- If the original default certificate is still required, click Add EV Certificate on the Server Certificates tab to add it back to the listener configuration as an extension certificate.
- If you are sure that the original default certificate is no longer needed and is not referenced by other instances or listeners, click Delete in the Actions column of the target certificate on the Server Certificates tab to remove it. If you do not remove the certificate, the unexpired original default certificate is automatically associated with the listener as an extension certificate during the next configuration reconciliation.
Enable configuration read-only mode.

Delete an extension certificate in the ALB console

This operation involves deleting an extension certificate before you set it as the default certificate. This process usually takes a few seconds. During this process, if no other certificates for the same domain name as the extension certificate exist in the certificate list of the listener, the forwarding rule for that domain name temporarily fails to find a suitable certificate. This may affect your Services. Therefore, perform this operation with caution after you confirm that it does not affect your Services.

Notes

Before you delete an extension certificate, check the certificate list of the listener. If the current configuration of the default and extension certificates meets your requirements, you do not need to delete the extension certificate or replace the default certificate.

Before you perform the operation, we recommend that you upload a temporary certificate for the same domain name as the extension certificate to be removed. Before you delete the extension certificate, click Add Extension Certificate on the Server Certificate tab. In the dialog box that appears, select the temporary certificate you uploaded. After you confirm that the status of the temporary certificate is Associated, remove the extension certificate. After you replace the default certificate, delete the temporary certificate.

Scenarios

If the current default certificate has expired, you can first delete the extension certificate. Then, follow the steps in Replace the default certificate in the ALB console to set this certificate as the default certificate.
If the current default certificate has not expired but you decide to stop using it, you can delete the extension certificate. Then, follow the steps in Replace the default certificate in the ALB console to set this certificate as the default certificate. You can decide whether to add the original default certificate back as an extension certificate as needed.
If the default certificate that is automatically selected by the ALB Ingress Controller during reconciliation is not the one you want, you can delete the extension certificate. Then, follow the steps in Replace the default certificate in the ALB console to set this certificate as the default certificate. Then, add the original default certificate back as an extension certificate.

Procedure

Log on to the ALB console. In the top menu bar, select the region where the instance is deployed.
On the Instances page, find the target instance and click the instance ID. On the Instance Details tab, click Disable Configuration Read-only Mode.
Important
After you disable configuration read-only mode, if you change listener configurations in the ALB console, only the certificate configuration is written back to the ACK cluster after the next reconciliation when you update the default certificate by following the steps in Replace the default certificate in the ALB console. Other configuration changes are not written back to the cluster. This means that during the next reconciliation, these unwritten configurations may be overwritten by the configurations from the cluster. Therefore, perform other operations with caution. After the next reconciliation, you can run the kubectl describe albconfig [$Albconfig_Name] command in the cluster and check the content of the status field to verify that the certificate configuration was successfully written back.
Click the Listener tab. Click the ID of the target listener to go to the listener details page. Then, click the Certificates tab.
On the Server Certificates tab, find the extension certificate that you want to delete. In the Actions column, click Delete, and then complete the operation as prompted.
Enable configuration read-only mode.

Update a new certificate to an extension certificate

Manually trigger a reconciliation

Scenario

If you use the auto-discovery method to manage certificates, the ALB Ingress Controller component does not immediately detect new SSL certificates that you purchase or upload in the Digital Certificate Management Service console. The ALB Ingress Controller queries for and obtains certificates from the Digital Certificate Management Service console only during a reconciliation operation. Therefore, if you want a newly updated certificate to take effect in the ALB Ingress, you must manually trigger the reconciliation process.

Note

When you use the auto-discovery method to manage certificates, note that the value of the spec.rules[].host field in the Ingress configuration file must correspond to the domain names listed in the spec.tls[].hosts[] field. This ensures that each domain name is associated with the correct certificate.

Procedure

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

If you are unsure about your current business configuration needs, we recommend that you add a non-critical annotation, such as key_test: value_test, to the Ingress YAML file to trigger a reconciliation by the ALB Ingress Controller. The following code provides an example.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-https
  namespace: default
  annotations:
    key_test: value_test    # Add a non-critical 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 was successful.
```
kubectl describe ingress demo-https -n default
```
(Optional) Delete the non-critical annotation from the Ingress YAML file and run the command in Step 2 to update the Ingress.

Update the Secret resource associated with the Ingress

Scenarios

To update a Secret resource that is already in effect in the current ALB Ingress, you can directly edit the YAML configuration file of the existing Secret resource. Then, apply the updated YAML file to the Kubernetes cluster. This action automatically triggers a reconciliation by the ALB Ingress Controller. No manual intervention is required. For more information, see Configure an HTTPS certificate for encrypted communication.

To add a new Secret certificate to the current ALB Ingress, you must first create a new Secret resource. Then, modify the configuration file of the ALB Ingress resource to add the name of the new Secret resource to the secretName field under TLS.

Create a new Secret resource. For more information, see Configure an HTTPS certificate for encrypted communication.

Add the newly created Secret resource to the configuration file of the ALB Ingress resource.

In the Ingress YAML file, add the domain name and secretName corresponding to the new Secret resource. The following code provides an 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  # The new domain name corresponds to 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 name corresponding to the new Secret resource.
    secretName: newsecret    # Add the secretName corresponding to the new Secret resource.

Run the following command to update the Ingress.

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

Use the kubectl edit command to update the certificate ID

Scenario

When you use the method of specifying certificates in an AlbConfig, if you purchase or upload a new SSL certificate in the Digital Certificate Management Service console, or if the certificate ID changes after you modify an old certificate, you can update the AlbConfig as follows.

Procedure

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

Perform an incremental update using the kubectl edit command.

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 YAML file with the obtained certificate ID.

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

Manually specify the default certificate in AlbConfig using `defaultCertificate`

Notes

IsDefault field: You can specify the default certificate only during creation. The system does not automatically change it later unless necessary. To manually replace the default certificate, use the defaultCertificate field.
```
listeners:
  - port: 443
    protocol: HTTPS
    certificates:
      - CertificateId: abcdefg-hangzhou
        IsDefault: true
```

defaultCertificate priority: The defaultCertificate field has a higher priority than certificates.IsDefault. This means that if you configure defaultCertificate, certificates.IsDefault automatically becomes invalid.

... ...
listeners:
  - port: 443
    protocol: HTTPS
    defaultCertificate:
      kind: CertIdentifier
      certificateId: 75****-hangzhou
    certificates:
      - CertificateId: 75****-hangzhou
        IsDefault: true

Certificate matching priority: When both an extension certificate and a default certificate are configured for the same listener port, the extension certificate is matched first. If there is no match, the default certificate is used as a fallback.
The ALB Ingress Controller must be upgraded to v2.18.0-aliyun.1 or a later version. For more information, see Upgrade the ALB Ingress Controller component.

Procedure

Note

The defaultCertificate.kind field supports only CertIdentifier and Secret as values.

Use a certificate ID (CertIdentifier)

When defaultCertificate.kind is set to CertIdentifier, you must specify the corresponding certificate ID (certificateId). The following code provides an example:

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: alb
spec:
  config:
    addressType: Intranet
    name: alb-test
  listeners:
    - port: 80
      protocol: HTTP
    - port: 443
      protocol: HTTPS     
      defaultCertificate: 
        kind: CertIdentifier
        certificateId: 123****-cn-hangzhou    ## Specify the target certificate ID.

Use a Secret

When defaultCertificate.kind is set to Secret, you must specify the corresponding secretName and secretNamespace to reference a Secret as the default certificate. The following code provides an example:

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: alb
spec:
  config:
    addressType: Intranet
    name: xiaosha-alb-test
  listeners:
  - port: 80
    protocol: HTTP
  - port: 443
    protocol: HTTPS                 
    defaultCertificate:
      kind: Secret
      secretName: test-secret       ## Specify the target secretName.
      secretNamespace: test         ## Specify the target secretNamespace.

Additional information

After you modify a certificate in the Digital Certificate Management Service console, such as after a certificate renewal, domain name addition, or domain name replacement, check whether the certificate ID has changed. If the certificate ID has changed, you need to trigger an update in the ALB Ingress based on your chosen certificate management method.
If you use multiple certificate configuration methods at the same time, note the compatibility of the methods when you update certificates. For more information, see Compatibility of certificate management methods.

FAQ

Why do I receive the error message "Specified parameter array contains too many items, up to 15 items, Certificates is not valid" during reconciliation?

Starting from v2.11.0-aliyun.1, the ALB Ingress Controller component supports certificate paging. If you receive the error message "Specified parameter array contains too many items, up to 15 items, Certificates is not valid" during reconciliation, it indicates that the version of the ALB Ingress Controller component you are using does not support certificate paging, and you are trying to associate more than 15 certificates in a single reconciliation. To resolve this issue, we recommend that you upgrade the ALB Ingress Controller component to the latest version. For more information about component versions, see ALB Ingress Controller. For more information about how to upgrade the component, see Manage the ALB Ingress Controller component.

References

For more information about how to configure a certificate for an HTTPS listener for the first time using an ALB Ingress, see Compatibility of certificate management methods.
For more information about how to implement HTTPS mutual authentication by configuring an ALB Ingress, see Use HTTPS mutual authentication to improve service security.
If you encounter errors or issues when you use ALB, refer to the following topics for troubleshooting: Troubleshoot ALB Ingress issues and ALB Ingress FAQ.

Prerequisites

SSL certificate management scenarios

Terms

Manage SSL certificates

Replace the default certificate in the ALB console

Notes

Scenarios

Procedure

Delete an extension certificate in the ALB console

Notes

Scenarios

Procedure

Update a new certificate to an extension certificate

Manually trigger a reconciliation

Scenario

Procedure

Update the Secret resource associated with the Ingress

Scenarios

Use the kubectl edit command to update the certificate ID

Scenario

Procedure

Manually specify the default certificate in AlbConfig using defaultCertificate

Notes

Procedure

Use a certificate ID (CertIdentifier)

Use a Secret

Additional information

FAQ

Why do I receive the error message "Specified parameter array contains too many items, up to 15 items, Certificates is not valid" during reconciliation?

References

Manually specify the default certificate in AlbConfig using `defaultCertificate`