docs/doc/source/security/kubernetes/migrate-platform-certificates-to-use-cert-manager-c0b1727e4e5d.rst

Update system-local-ca or Migrate Platform Certificates to use Cert Manager

The playbook described in this section can be used to either update system-local-ca or migrate platform Certificates to use Cert Manager. For updating system-local-ca, this playbook will update the system-local-ca Secret and Issuer, re-sign all the Platform certificates using this issuer, and in a Distributed Cloud environment, iterate thru all of the subclouds and do the same updates and re-signing on each Subcloud. In the migration use case, this playbook can be used to switch from using Platform certificates generated from the legacy certificate management APIs/CLIs, which will be deprecated in a future release, to the new method of configuring Platform certificates using Cert-Manager which enables auto-renewals of Platform certificates. And again in a Distributed Cloud environment will iterate thru all of the Subclouds.

This playbook can be configured to execute on any deployment configuration <deployment-options> supported by (, standard, and distributed cloud configurations), allowing you to update system-local-ca and re-sign certificates or migrate certificates at scale.

The certificates (if they exist) that will be updated / migrated with this playbook are:

• system-local-ca
• system-openldap-local-certificate
• REST API & Web Server certificate ( system-restapi-gui-certificate signed by system-local-ca)
• Docker Registry certificate (system-registry-local-certificate signed by system-local-ca)
• OIDC-Auth-Apps certificate (<user-specified> signed by system-local-ca)

1. Create an inventory file using Ansible-Vault.

   You must create an inventory file to specify the playbook parameters. Using ansible-vault is highly recommended in order to securely store the contents of the inventory file which includes the system-local-ca public certificate and private key, and the Root public certificate for system-local-ca. Ansible vault will ask for a password in this step, which is used for subsequent ansible-vault access and ansible-playbook commands.

   For example:

   ~(keystone_admin)]$ ansible-vault create migration-inventory.yml

   This will open up an editor in which you need to manually add or paste your inventory parameters, as specified in the example below.

   An example migration-inventory.yaml file is shown below:

   all:
     vars:
       system_local_ca_cert: <base64_cert>
       system_local_ca_key: <base64_key>
       system_root_ca_cert: <base64_cert>
     children:
       target_group:
         vars:
           system_platform_certificate:
             dns_domain: xyz.com
             duration: 2160h # 90d
             renewBefore: 360h # 15d
             subject_C: CA
             subject_ST: Ontario
             subject_L: Ottawa
             subject_O: myorganization
             subject_OU: engineering
             subject_CN: myorganization.com
             subject_prefix: starlingx2`
           # SSH password to connect to all subclouds
           ansible_ssh_user: sysadmin
           ansible_ssh_pass: <sysadmin-passwd>
           # Sudo password
           ansible_become_pass: <sysadmin-passwd>

   The inventory parameters have the following meanings:

   system_local_ca_cert and system_local_ca_key

   Both values being the single-line base64 encoding of the corresponding pem file; i.e. the output of base64 -w0 <pem-file>.

   It is highly recommended that you use an Intermediate system-local-ca, where the system-local-ca's certificate and key are generated and signed by an external trusted Root . Refer to the documentation for the external trusted Root that you are using, on how to create a public certificate and private key pair, for use in an Intermediate .

   The duration of the Intermediate CA public certificate and private key pair should be at least 3 years. See rca_duration/ica_duration to modify this semantic check.

   system_root_ca_cert

   The public certificate of the Root that signed system_local_ca_cert.

   rca_duration

   duration validation parameter. This will be used against system_root_ca_cert to ensure that it have sufficient duration remaining. It defaults to 3 years, as this is typical for certificates and this certificate must be renewed manually. Only override if necessary.

   ica_duration

   duration validation parameter. This will be used against system_local_ca_cert to ensure that it have sufficient duration remaining. It defaults to 3 years, as this is typical for certificates and this certificate must be renewed manually. Only override if necessary.

   system_platform_certificate.dns_domain

   The domain that will be used to build a full DNS name for the List of the Platform Certificates. E.g. starlingx-restapi-gui.<dns_domain> would appear in the list of the REST API & Web Server certificate. in the server certificates.

   system_platform_certificate.duration

   The duration of certificate validity to use in all Platform Certificates, in hours; defaults to 2160h (or 90 days). The Platform Server Certificates will be auto-renewed by Cert-Manager.

   system_platform_certificate.renewBefore

   The number of hours before certificate expiry that the Platform Certificate should be auto-renewed by Cert-Manager; defaults to 360h (or 15 days).

   system_platform_certificate.subject_*fields

   Subject related fields that will be added to all platform certificates:

   • system_platform_certificate.subject_C: country
   • system_platform_certificate.subject_ST: State or Province
   • system_platform_certificate.subject_L: Location
   • system_platform_certificate.subject_O: Organization
   • system_platform_certificate.subject_OU: Organization Unit
   • system_platform_certificate.subject_CN: Common Name
   • system_platform_certificate.subject_prefix: An optional field to add a prefix to further identify the certificate, such as for instance.

   ansible_ssh_user

   The username to use to connect to the target system using ssh.

   ansible_ssh_pass

   The password to use to connect to the target system using ssh.

   ansible_become_pass

   The ansible_ssh_user's sudo password.

   If a separate set of overrides are required for a group of hosts, children groups can be added under target_group.

   The following example illustrates using one set of ssh/sudo passwords for subcloud1 and subcloud2 and another set of ssh/sudo passwords for subcloud3.

   all:
     vars:
       ...
     children:
       target_group:
         vars:
           ...
         children:
           different_password_group:
             vars:
               ansible_ssh_user: sysadmin
               ansible_ssh_pass: <sysadmin-passwd>
               ansible_become_pass: <sysadmin-passwd>
             hosts:
               subcloud1:
               subcloud2:
           different_password_group2:
             vars:
               ansible_ssh_user: sysadmin
               ansible_ssh_pass: <different-sysadmin-passwd>
               ansible_become_pass: <different-sysadmin-passwd>
             hosts:
               subcloud3:

2. Run the playbook.

   Execute the Ansible playbook to start the migration process. You will be prompted for the vault password created in the previous step.

   For example:

   ~(keystone_admin)]$ ansible-playbook /usr/share/ansible/stx-ansible/playbooks/update_platform_certificates.yml -i migration-inventory.yml --extra-vars "target_list=localhost,subcloud1 mode=update ignore_alarms=yes" --ask-vault-pass

   Note

   • In systems, the playbook must be run from the System Controller, and the target_list parameter should be used to target the desired subclouds.
   • The target_list parameter should include localhost within the targeted subcloud, to keep the certificates consistent with the SystemController.

   The behavior of the update/migration can be customized using the following --extra-vars parameter options:

   mode

   • update: Creates or updates platform certificates. Also supports ongoing updates, which is useful for operations such as replacing the or changing other parameters.
   • check: Gathers certificates from all subclouds and prints them on the system controller

   target_list

   • localhost: Will target the localhost (standalone systems or system controller). The target_list parameter should include this value to keep consistency with the SystemController.
   • subcloud1, subcloud2: A comma separated list of hosts the playbook will target.
   • all_online_subclouds: Will query dcmanager subcloud list and retrieve a list of online subclouds to target.

   ignore_alarms

   yes/no: When not specified defaults to no. Using ignore_alarms=yes should be avoided as much as possible. Only use it after a careful analysis of the alarm in question and for specific hosts.