starlingx/docs
Code Issues Proposed changes

Playbook to migrate platform certificates to use cert-manager for auto-renewals

Browse Source 
Initial draft content for migration playbook usage.
Incorporate patchset 1 review comments.
Incorporate patchset 2 review comments.
Incorporate patchset 3 review comments.

Story: 2007361
Task: 44350

Signed-off-by: Ron Stone <ronald.stone@windriver.com>
Change-Id: I3617ce10b6416eb8cd714a97cb6411900d7240d2
This commit is contained in:
Ron Stone 2022-03-01 09:53:19 -05:00
parent 86e221b10f
commit 403e986ed3
3 changed files with 217 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/security/kubernetes/index-security-kub-81153c1254c3.rst
View File

@ -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

1
doc/source/security/kubernetes/kubernetes-certificates-f4196d7cae9c.rst
View File

@ -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

216
doc/source/security/kubernetes/migrate-platform-certificates-to-use-cert-manager-c0b1727e4e5d.rst Normal file
View File

@ -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 <deployment-options>` 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: <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 |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.<dns_domain> 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: <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:
#. 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.