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

Migrate/Update Platform Certificates to use Cert Manager

Platform Certificates 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.

This migration script can be configured to execute on any deployment configuration <deployment-options> supported by (, standard, and distributed cloud configurations), allowing you to migrate the certificates at scale. The script will replace old certificates and a backup of the original certificates will be retained for reference. The certificates that will be migrated/updated with this playbook are:

• REST API & Web Server certificate
• Docker Registry certificate
• OIDC-Auth-Apps certificate

The against which the server certificates will be validated can be generated on-platform (self-signed) or use an external Root and . Using an external Root and is recommended. Note that this ansible-playbook will use the same cert & key to create the Issuers and/or ClusterIssuers for all controllers/subclouds.

Note

This playbook can also be used to update certificates, which is useful for situations such as approaching expiry.

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 for enhanced security. 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>
       root_ca_cert: <base64_cert>
     children:
       target_group:
         vars:
           dns_domain: xyz.com
           duration: 2160h # 90d
           renewBefore: 360h # 15d
           subject_C: Canada
           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

   You may choose to generate a certificate & key on the platform (self-signed, internal Root ) or use an external Root that would make this an Intermediate .

   root_ca_cert

   The Root that signed system_local_ca_cert. If system_local_ca_cert is a self-signed, internal Root certificate, duplicate the value of system_local_ca_cert in this field.

   ca_duration

   duration validation parameter. This will be used against system_local_ca_cert and root_ca_cert to ensure that they 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.

   dns_domain

   The DNS domain that will be used to build the 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.

   duration

   The duration of certificate validity to use in all Platform Certificates, in hours. The Platform Server Certificates will be auto-renewed by Cert-Manager.

   renewBefore

   The number of hours before certificate expiry that the Platform Certificate should be auto-renewed by Cert-Manager.

   subject_* fields

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

   • subject_C: country
   • subject_ST: State or Province
   • subject_L: Location
   • subject_O: Organization
   • subject_OU: Organization Unit
   • subject_CN: Common Name
   • subject_prefix: An optional field to add a prefix to further identify the certificate, such as 'starlingx' 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 target system'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/migrate_platform_certificates_to_certmanager.yml -i migration-inventory.yml --extra-vars "target_list=subcloud1 mode=update ignore_alarms=yes" --ask-vault-pass

   The behavior of the 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 such as replacing the or changing other parameters.
   • check: Gathers certificates from all subclouds and prints them on the system controller

   target_list

   • subcloud1, subcloud2: A comma separated list of hosts the playbook will target.
   • localhost: Will target the localhost (standalone systems or system controller)
   • 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.

   Note

   The ignore_alarms extra-var should be avoided as much as possible. Only use it after a careful analysis of the alarm in question and for specific hosts.