Kubernetes Root CA Certificate Update Cloud Orchestration

About this task

You can update Kubernetes Root CA certificate on a running system, with either an uploaded certificate or an auto generated certificate.

Warning

Do not let the Kubernetes Root CA certificate expire on your system and ensure that certificates with valid/adequate expiry dates are used during renewal as there is no easy way to recover a system if the Kubernetes Root CA certificate expires.

Special care should be taken when updating the Root CA certificate.

Warning

During the Kubernetes Root CA update, deployments, daemonsets, and statefulsets present in the cluster are rolling restarted. This impacts services provided by the application. It is highly recommended to schedule a Kubernetes Root CA update during planned maintenance windows.

Prerequisites

  • The system is clear of alarms (with the exception of alarms for locked hosts, stopped instances, certificate expiring soon, certificate expired, and Kubernetes root ca update in progress).

  • All hosts must be unlocked, enabled and available.

  • All Kubernetes pods must be ready.

  • Cert-manager app is applied.

  • A file containing a self-signed certificate and corresponding private key if choose to upload a new Root CA certificate.

Procedure

Before starting the update, it is highly recommended to backup the existing Kubernetes Root CA certificate and key, i.e. /etc/kubernetes/pki/ca.crt and /etc/kubernetes/pki/ca.key.

  1. Create the strategy.

    ~(keystone_admin)$ sw-manager kube-rootca-update-strategy create --subject "C=CA ST=ON L=OTT O=WR OU=STX CN=STX" --expiry-date YYYY-MM-DD
    
    Strategy Kubernetes RootCA Update Strategy:
    strategy-uuid: 47163c5b-44ac-432a-bd25-6e5c353046e9
    controller-apply-type: serial
    storage-apply-type: serial
    worker-apply-type: serial
    default-instance-action: stop-start
    alarm-restrictions: strict
    current-phase: build
    current-phase-completion: 0%
    state: building
    inprogress: true
    
    ~(keystone_admin)$ sw-manager kube-rootca-update-strategy create --cert-file some_cert.pem
    
    strategy-uuid: 9575f1ea-4d66-4f13-8013-b04c2f420eff
    controller-apply-type: serial
    storage-apply-type: serial
    worker-apply-type: serial
    default-instance-action: stop-start
    alarm-restrictions: strict
    current-phase: build
    current-phase-completion: 0%
    state: building
    inprogress: true
    

    --expiry-date

    Optional argument to specify the expiry date of the new certificate. It has to be in the “YYYY-MM-DD” format. If not specified, the new certificate will have the same valid period as the existing one (normally 10 years).

    --subject

    Optional argument to specify the distinguished name of the new certificate. It has to be in the format C=<Country> ST=<State/Province> L=<Locality> O=<Organization> OU=<OrganizationUnit> CN=<commonName>. If not specified, the new certificate will have “Kubernetes” as default.

    --cert-file

    Optional argument to upload a self-signed certificate as the new Root CA certificate.

    Note

    Passing --cert-file uses an existing certificate, but --expiry-date and --subject generate a certificate. Using an existing certificate will ignore any arguments to generate a certificate.

    Note

    Ensure the certificates have RSA key length >= 2048 bits. The StarlingX Release r9.0 provides a new version of openssl which requires a minimum of 2048-bit keys for RSA for better security / encryption strength.

    You can check the key length by running openssl x509 -in <the certificate file> -noout -text and looking for the “Public-Key” in the output. For more information see Create Certificates Locally using openssl.

  2. Apply the strategy.

    sw-manager kube-rootca-update-strategy apply
    
  3. Show the status of the update strategy.

    ~(keystone_admin)$ sw-manager kube-rootca-update-strategy show
    
    Strategy Kubernetes RootCA Update Strategy:
    strategy-uuid: 47163c5b-44ac-432a-bd25-6e5c353046e9
    controller-apply-type: serial
    storage-apply-type: serial
    worker-apply-type: serial
    default-instance-action: stop-start
    alarm-restrictions: strict
    current-phase: build
    current-phase-completion: 100%
    state: ready-to-apply
    build-result: success
    build-reason:
    

    Note

    Passing --details will show all the internal steps and stages for the orchestration strategy.

    Passing --active will show which step is currently running for the orchestration strategy.

  4. If you want to delete the strategy.

    ~(keystone_admin)$ sw-manager kube-rootca-update-strategy delete
    
    Strategy deleted