This topic describes how to manage the SSL certificates that are associated with an HTTPS listener to ensure that the certificates can be smoothly replaced, especially when the certificates are about to expire or have expired.
SSL certificate management scenarios
Terms
default certificate: You can only replace a default certificate. You cannot add or remove a default certificate. The default certificate that is associated with each HTTPS listener is unique.
additional certificate: You can add or remove additional certificates. Each HTTPS listener can be associated with multiple additional certificates. For more information about the maximum number of additional certificates that can be added to an ALB instance, see Limits.
certificate list: You can log on to the ALB console to view the certificates that are associated with each HTTPS listener.
new certificate: A new certificate is not included in the certificate list of an HTTPS listener.
Manage SSL certificates
Scenario | Use automatic certificate discovery | Manage certificates as Secrets | Specify certificates in AlbConfigs |
Replace the default certificate with a new certificate | Log on to the ALB console to replace the default certificate. | Update the Secret that is associated with an ALB Ingress. Log on to the ALB console to check whether the replaced default certificate meets your expectations. You can also replace the default certificate with an additional certificate.
| Update the certificate ID by running the kubectl edit command. |
Replace the default certificate with an additional certificate | Log on to the ALB console to remove an additional certificate. Risks may occur when you remove the additional certificate. We recommend that you perform this operation during off-peak hours to prevent risks. Log on to the ALB console to replace the default certificate.
| Log on to the ALB console to remove an additional certificate. Risks may occur when you remove the additional certificate. We recommend that you perform this operation during off-peak hours to prevent risks. Log on to the ALB console to replace the default certificate.
| Log on to the ALB console to remove an additional certificate. Risks may occur when you remove the additional certificate. We recommend that you perform this operation during off-peak hours to prevent risks. Log on to the ALB console to replace the default certificate.
|
Update a new certificate to an additional certificate | Trigger a reconciliation. | Update the Secret that is associated with an ALB Ingress. | Update the certificate ID by running the kubectl edit command. |
For more information about how to manage SSL certificates, see the following sections of this topic.
Replace the default certificate in the ALB console
Usage notes
If you want to use a new certificate to replace the default certificate that is associated with an HTTPS listener, check whether the new certificate is available in Certificate Management Service. If the new certificate does not exist, you can purchase or upload a new SSL certificate in the Certificate Management Service console. For more information, see Purchase an official certificate or Upload and share an SSL certificate.
Typical scenarios
The current default certificate has expired. You need to replace the expired default certificate with a new certificate.
The current default certificate is valid, but you want to replace the current default certificate. In this case, you can replace the default certificate with a new certificate.
After you remove an additional certificate in the ALB console, you want to configure the additional certificate as the default certificate.
Procedure
Log on to the ALB console. In the top navigation bar, select the region in which the ALB instance that you want to manage resides.
In the left-side navigation pane, choose ALB > Instances. On the Instances page, find the ALB instance and click the instance ID. On the Instance Details tab, disable the configuration read-only mode.
Important
After the configuration read-only mode is disabled, you can modify the configurations of an HTTPS listener in the ALB console. If you replace the default certificate that is associated with the HTTPS listener, the configurations of the default certificate are written back to the ACK cluster during the next reconciliation. Except for the configurations of the default certificate, other modified configurations are not written back to the cluster. This indicates that the configurations that are not written back to the cluster are at the risk of being overwritten during the next reconciliation. Therefore, you must proceed with caution. After the next reconciliation is complete, you can run the kubectl describe albconfig [$Albconfig_Name] command in the cluster and view the value of the status parameter to verify whether the configurations of the default certificate are written back.
Click the Listener tab. On the Listener tab, find the HTTPS listener that you want to manage and click the listener ID. On the page that appears, click the Certificates tab.
On the Certificates tab, click the Server Certificates tab, find the default server certificate, and then click Replace in the Actions column.
In the dialog box that appears, select a new certificate and click OK.
After this operation is complete, the default certificate that is associated with the current listener is replaced with the new certificate.
If you want to retain the original default certificate, click Add EV Certificate on the Server Certificates tab to add the original default certificate as an additional certificate to the listener.
If you no longer require the original default certificate and do not want the certificate to be used by other instances or listeners, find the certificate on the Server Certificates tab and click Delete in the Actions column to remove the certificate. If you do not remove the original default certificate, the original default certificate that is still valid will be automatically associated with the current listener as an additional certificate during the next reconciliation.
Enable the configuration read-only mode.
Remove an additional certificate in the ALB console
When you perform this operation, you need to remove an additional certificate and then configure the additional certificate as the default certificate. During this process that lasts several seconds, if the certificate list of an HTTPS listener does not include another certificate that is associated with the same domain name as the additional certificate to be removed, the forwarding policy that matches the domain name cannot use an appropriate certificate. This may affect the normal operation of related services. Therefore, we recommend that you perform related operations with caution after you make sure that your services are not affected.
Usage notes
Before you remove an additional certificate, view the certificate list of your HTTPS listener. If the configurations of the default certificate and the additional certificate meet your expectations, you do not need to remove the additional certificate or replace the default certificate.
Before you remove an additional certificate, we recommend that you upload a temporary certificate that is associated with the same domain name as the additional certificate to be removed in the Certificate Management Service console. Then, go to the ALB console and click Add EV Certificate on the Server Certificates tab. In the dialog box that appears, select the temporary certificate that you uploaded. Confirm that the temporary certificate is in the Associated state, and then remove the additional certificate. Remove the temporary certificate after you replace the default certificate.
Typical scenarios
Procedure
Log on to the ALB console. In the top navigation bar, select the region in which the ALB instance that you want to manage resides.
In the left-side navigation pane, choose ALB > Instances. On the Instances page, find the ALB instance and click the instance ID. On the Instance Details tab, disable the configuration read-only mode.
Important
After the configuration read-only mode is disabled, you can modify the configurations of an HTTPS listener in the ALB console. If you replace the default certificate that is associated with the HTTPS listener, the configurations of the default certificate are written back to the ACK cluster during the next reconciliation. Except for the configurations of the default certificate, other modified configurations are not written back to the cluster. This indicates that the configurations that are not written back to the cluster are at the risk of being overwritten during the next reconciliation. Therefore, you must proceed with caution. After the next reconciliation is complete, you can run the kubectl describe albconfig [$Albconfig_Name] command in the cluster and view the value of the status parameter to verify whether the configurations of the default certificate are written back.
Click the Listener tab. On the Listener tab, find the HTTPS listener that you want to manage and click the listener ID. On the page that appears, click the Certificates tab.
On the Server Certificates tab, find the additional certificate that you want to remove and click Delete in the Actions column. In the message that appears, click OK.
Enable the configuration read-only mode.
Update a new certificate to an additional certificate
Trigger a reconciliation
Typical scenarios
If you manage SSL certificates by using the automatic certificate discovery method, when you purchase or upload a new SSL certificate in the Certificate Management Service console, the ALB Ingress controller cannot immediately detect the new SSL certificate. The ALB Ingress controller queries and obtains certificates from Certificate Management Service only when a reconciliation is performed. In this case, the ALB Ingress controller can detect the new SSL certificate. If you want the new SSL certificate to immediately take effect in your ALB Ingress, you must trigger a reconciliation.
Note
If you manage SSL certificates by using the automatic certificate discovery method, the value of the spec.rules[].host parameter in the YAML file of your ALB Ingress must be consistent with one of the domain names that are specified by the spec.tls[].hosts[] parameter. This way, each domain name can be associated with the corresponding certificate.
Procedure
To trigger a reconciliation and update a new certificate, you can modify the configurations of your ALB Ingress. Modify the configurations in the ALB Ingress configuration with annotations based on your business requirements.
If you cannot determine the specific configuration requirements of your business, we recommend that you add a non-critical annotation, such as key_test: value_test, to the YAML file of the ALB Ingress to enable the ALB Ingress controller to perform a reconciliation. Sample code:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: demo-https
namespace: default
annotations:
key_test: value_test
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 ALB Ingress:
kubectl apply -f demo.yaml
Run the following command to check whether the reconciliation is successful:
kubectl describe ingress demo-https -n default
Optional. Remove the meaningless annotation from the YAML file of the ALB Ingress and run the command that is used in Step 2 to update the ALB Ingress.
Update the Secret that is associated with an ALB Ingress
Typical scenarios
If you want to update the Secret that is associated with an ALB Ingress, you can directly modify the YAML file of the Secret and apply the updated YAML file to your Kubernetes cluster. This operation automatically triggers the ALB Ingress controller to perform a reconciliation without manual operations. For more information, see Configure HTTPS Certificates for Encrypted Communication.
If you want to store a certificate as a Secret and associate the Secret with an ALB Ingress, you must create a Secret and modify the YAML file of the ALB Ingress to specify the Secret name as the value of the secretName parameter.
Create a Secret. For more information, see Configure HTTPS Certificates for Encrypted Communication.
Add the Secret to the YAML file of the ALB Ingress.
In the YAML file of the ALB Ingress, add the domain name that is associated with the Secret and specify the secretName parameter. Sample code:
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
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
secretName: newsecret
Run the following command to update the ALB Ingress:
kubectl apply -f demo.yaml
Update the certificate ID by running the kubectl edit command
Typical scenarios
If you manage SSL certificates by specifying certificates in AlbConfigs, certificate IDs will be changed after you purchase or upload a new SSL certificate or modify an existing certificate in the Certificate Management Service console. In this case, you can update AlbConfigs.
Procedure
Obtain the certificate ID.
Log on to the Certificate Management Service console.
In the left-side navigation pane, choose Certificate Management > SSL Certificate Management.
On the SSL Certificate Management page, click the Manage Uploaded Certificates tab. On the Manage Uploaded Certificates tab, find the certificate that you want to manage and choose 
> Details in the Actions column. In the certificate details panel, obtain the certificate ID.
Run the kubectl edit command to perform an incremental update on an existing AlbConfig.
Run the following command to query the name of the AlbConfig:
kubectl -n kube-system get AlbConfig
Run the following command to update the AlbConfig:
kubectl -n <NameSpace> edit AlbConfig <AlbConfig_Name>
Add the obtained certificate ID to the YAML file.
spec:
config:
listeners:
- caEnabled: false
certificates:
- CertificateId: 756****-cn-hangzhou
IsDefault: false
port: 443
protocol: HTTPS
Additional notes
After you modify a certificate in the Certificate Management Service console such as renewing a certificate, associating a domain name, or changing a domain name, check whether the certificate ID changes. If the certificate ID changes, you must update the certificate ID in your ALB Ingress based on the certificate management method that you use.
If you use multiple methods to configure certificates, pay attention to the compatibility of certificates configured by using different methods when you update the certificates. For more information, see the Compatibility of certificates configured by using different methods section of the "Configure HTTPS Certificates for Encrypted Communication" topic.
FAQ
What do I do if the error "Specified parameter array contains too many items, up to 15 items, Certificates is not valid" occurs during a reconciliation?
In v2.11.0-aliyun.1 and later, the ALB Ingress controller allows you to query certificates by page. If the error "Specified parameter array contains too many items, up to 15 items, Certificates is not valid" occurs during a reconciliation, the ALB Ingress controller of the version that you use does not support the paged query of certificates, and the number of certificates that you want to associate exceeds the upper limit of 15 during the reconciliation. To resolve this issue, we recommend that you update the ALB Ingress controller to the latest version. For more information about the versions of the ALB Ingress controller, see ALB Ingress controller. For more information about how to update the ALB Ingress controller, see the Update the ALB Ingress controller section of the "Manage the ALB Ingress controller" topic.
Elastic Compute Service (ECS)
Lingma
