diff --git a/doc/source/security/kubernetes/index-security-kub-81153c1254c3.rst b/doc/source/security/kubernetes/index-security-kub-81153c1254c3.rst index cb5c0d290..224422e82 100644 --- a/doc/source/security/kubernetes/index-security-kub-81153c1254c3.rst +++ b/doc/source/security/kubernetes/index-security-kub-81153c1254c3.rst @@ -109,6 +109,7 @@ HTTPS Certificate Management configure-rest-api-applications-and-web-administration-server-certificates-after-installation-6816457ab95f configure-docker-registry-certificate-after-installation-c519edbfe90a oidc-client-dex-server-certificates-dc174462d51a + migrate-platform-certificates-to-use-cert-manager-c0b1727e4e5d portieris-server-certificate-a0c7054844bd vault-server-certificate-8573125eeea6 dc-admin-endpoint-certificates-8fe7adf3f932 diff --git a/doc/source/security/kubernetes/kubernetes-certificates-f4196d7cae9c.rst b/doc/source/security/kubernetes/kubernetes-certificates-f4196d7cae9c.rst index 47ab8355f..6627fb1bf 100644 --- a/doc/source/security/kubernetes/kubernetes-certificates-f4196d7cae9c.rst +++ b/doc/source/security/kubernetes/kubernetes-certificates-f4196d7cae9c.rst @@ -126,7 +126,6 @@ This certificate is configured to auto renew. .. toctree:: :maxdepth: 1 - kubernetes-root-ca-certificate update-renew-kubernetes-certificates-52b00bd0bdae manual-kubernetes-root-ca-certificate-update-8e9df2cd7fb9 kubernetes-root-ca-certificate-update-cloud-orchestration-a627f9d02d6d diff --git a/doc/source/security/kubernetes/migrate-platform-certificates-to-use-cert-manager-c0b1727e4e5d.rst b/doc/source/security/kubernetes/migrate-platform-certificates-to-use-cert-manager-c0b1727e4e5d.rst new file mode 100644 index 000000000..7283bf618 --- /dev/null +++ b/doc/source/security/kubernetes/migrate-platform-certificates-to-use-cert-manager-c0b1727e4e5d.rst @@ -0,0 +1,216 @@ +.. _migrate-platform-certificates-to-use-cert-manager-c0b1727e4e5d: + +======================================================== +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. + +.. rubric:: |context| + +This migration script can be configured to execute on any +:ref:`deployment configuration ` supported by |prod| +(|AIO|, 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 |CA| against which the server certificates will be validated can be generated +on-platform (self-signed) or use an external Root |CA| and |ICA|. Using an external +Root |CA| and |ICA| is recommended. Note that this ansible-playbook will use the same +|ICA| 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 |ICA| approaching expiry. + +.. rubric:: |proc| + +#. 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: + + .. code-block:: none + + ~(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: + + .. code-block:: none + + all: + vars: + system_local_ca_cert: + system_local_ca_key: + root_ca_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: + # Sudo password + ansible_become_pass: + + 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 |CA|) or use an external Root + |CA| that would make this an Intermediate |CA|. + + ``root_ca_cert`` + The Root |CA| that signed ``system_local_ca_cert``. If + ``system_local_ca_cert`` is a self-signed, internal Root |CA| + certificate, duplicate the value of ``system_local_ca_cert`` + in this field. + + ``ca_duration`` + |ICA| 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 |CA| 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 |SANs| List of the Platform Certificates. E.g. + starlingx-restapi-gui. would appear in the |SANs| 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. + + .. code-block:: none + + all: + vars: + ... + children: + target_group: + vars: + ... + children: + different_password_group: + vars: + ansible_ssh_user: sysadmin + ansible_ssh_pass: + ansible_become_pass: + hosts: + subcloud1: + subcloud2: + different_password_group2: + vars: + ansible_ssh_user: sysadmin + ansible_ssh_pass: + ansible_become_pass: + hosts: + subcloud3: + +#. 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: + + .. code-block:: none + + ~(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 |ICA| 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.