starlingx/docs
Code Issues Proposed changes

Configuring docker registry certificate

Browse Source 
Update documentation regarding the Docker Registry certificate.
Remove deprecated section Local Registry Server Certificates.
Fix ref link.

Story: 2009811
Task: 50152

Change-Id: Id6b3469419b5d1a3a195795535aa496334dec211
Signed-off-by: Elisamara Aoki Goncalves <elisamaraaoki.goncalves@windriver.com>
This commit is contained in:
Elisamara Aoki Goncalves 2024-09-13 12:51:02 +00:00
parent 021026d26c
commit 8314d46f72
6 changed files with 27 additions and 330 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/_vendor/rl-strings.txt
View File

@ -258,7 +258,6 @@
.. |pod-security-policies| replace:: :ref:`Pod Security Policies <pod-security-policies>`
.. |remove-portieris| replace:: :ref:`Remove Portieris <remove-portieris>`
.. |delete-ldap-linux-accounts-7de0782fbafd| replace:: :ref:`Delete LDAP Linux Accounts <delete-ldap-linux-accounts-7de0782fbafd>`
.. |security-install-update-the-docker-registry-certificate| replace:: :ref:`Local Registry Server Certificates <security-install-update-the-docker-registry-certificate>`
.. |security-rest-api-access| replace:: :ref:`REST API Access <security-rest-api-access>`
.. |auditd-support-339a51d8ce16| replace:: :ref:`Linux Auditing System <auditd-support-339a51d8ce16>`
.. |the-cert-manager-bootstrap-process| replace:: :ref:`Configure cert-manager at Bootstrap <the-cert-manager-bootstrap-process>`

122
doc/source/admintasks/kubernetes/installing-updating-the-docker-registry-certificate.rst
View File

@ -6,114 +6,18 @@
Install/Update Local Registry Certificates
==========================================
.. warning::
During installation, the Platform Issuer (``system-local-ca``) will
automatically issue a certificate used to secure access to the Local Docker
Registry API. After bootstrap, this certificate's fields can be updated using
the procedure
:ref:`migrate-platform-certificates-to-use-cert-manager-c0b1727e4e5d`. The
certificate will be managed by cert-manager (auto renewed upon expiration).
By default a self-signed certificate is generated at installation time for
the registry API. This applies to standalone system, central cloud and
subclouds of |DC| system. For more secure access, it is strongly recommended
to update the default self-signed certificate with an intermediate or Root
|CA|-signed certificate.
This certificate will be stored in a Kubernetes |TLS| secret in namespace
``deployment``, named ``system-registry-local-certificate``. It will be managed
by cert-manager, renewed upon expiration and the required services restarted
automatically.
The local Docker registry provides secure HTTPS access using the registry API.
.. rubric:: |context|
The intermediate or Root |CA|-signed certificate for the registry must have at
least the following |SANs|: ``DNS:registry.local``, ``DNS:registry.central``,
IP Address:<oam-floating-ip-address>, IP Address:<mgmt-floating-ip-address>.
Use the :command:`system addrpool-list` command to get the |OAM| floating IP
Address and management floating IP Address for your system. You can add any
additional |DNS| entry\(s) that you have set up for your |OAM| floating IP
Address.
.. note::
The ``DNS:registry.central`` can be omitted from |SANs| for
standalone system and subcloud of |DC| system.
The update procedure for any type of system (standalone, central cloud and
subcloud of |DC| system) is the same.
Use the following procedure to install an intermediate or Root |CA|-signed
certificate to either replace the default self-signed certificate or to replace
an expired or soon to expire certificate.
.. rubric:: |prereq|
Obtain an intermediate or Root |CA|-signed certificate and key from a trusted
intermediate or Root Certificate Authority (|CA|). Refer to the documentation
for the external Root |CA| that you are using, on how to create public
certificate and private key pairs, signed by an intermediate or Root |CA|, for
HTTPS.
.. xreflink
For lab purposes, see |sec-doc|: :ref:`Create Certificates Locally
using openssl <create-certificates-locally-using-openssl>` to create an
Intermediate or test Root |CA| certificate and key, and use it to sign test
certificates.
Put the Privacy Enhanced Mail (PEM) encoded versions of the certificate and
key in a single file, and copy the file to the controller host.
Also obtain the certificate of the intermediate or Root CA that signed the
above certificate.
Ensure all certificates are valid before starting an upgrade. Run the
:command:`show-certs.sh` script to display an overview of the various
certificates that exist in the system along with their expiry date. For more
information, see, :ref:`Display Certificates Installed on a System <utility-script-to-display-certificates>`.
.. rubric:: |proc|
.. _installing-updating-the-docker-registry-certificate-d271e71:
#. In order to enable internal use of the Docker registry certificate, update
the trusted |CA| list for this system with the Root |CA| associated with the
Docker registry certificate.
.. code-block:: none
~(keystone_admin)]$ system certificate-install --mode ssl_ca <pathTocertificate>
where:
**<pathTocertificate>**
is the path to the intermediate or Root |CA| certificate associated with the
Docker registry's intermediate or Root |CA|-signed certificate.
#. Update the Docker registry certificate using the
:command:`certificate-install` command.
Set the mode (``-m`` or ``--mode``) parameter to docker_registry.
.. code-block:: none
~(keystone_admin)]$ system certificate-install --mode docker_registry <pathTocertificateAndKey>
where:
**<pathTocertificateAndKey>**
is the path to the file containing both the Docker registry's Intermediate
or Root |CA|-signed certificate and private key to install.
In |DC| system, the server certificate of central registry and the server
certificate of subcloud’s local registry can be arranged to be generated from
the same root |CA| certificate.
In this case, the generated server certificates need to be installed on the
central cloud and each of the subclouds.
The root |CA| certificate only needs to install on central cloud, the |DC|
orchestration will sync the root |CA| certificate to all the subclouds.
---------------------------------
Renew local registry certificates
---------------------------------
The local registry certificate is not automatically renewed, user MUST renew
the certificate prior to expiry, otherwise a variety of system operations will
fail.
The certificate will be anchored by system-local-ca's Root |CA|. For more
information, refer to
:ref:`system-local-ca-issuer-9196c5794834`.

115
doc/source/security/kubernetes/configure-docker-registry-certificate-after-installation-c519edbfe90a.rst
View File

@ -4,107 +4,18 @@
Configure Docker Registry Certificate
=====================================
The local Docker registry provides secure HTTPS access using the registry API.
During installation, the Platform Issuer (``system-local-ca``) will
automatically issue a certificate used to secure access to the Local Docker
Registry API. After bootstrap, this certificate's fields can be updated using
the procedure
:ref:`migrate-platform-certificates-to-use-cert-manager-c0b1727e4e5d`. The
certificate will be managed by cert-manager (auto renewed upon expiration).
.. rubric:: |context|
This certificate will be stored in a Kubernetes |TLS| secret in namespace
``deployment``, named ``system-registry-local-certificate``. It will be managed
by cert-manager, renewed upon expiration and the required services restarted
automatically.
By default, a self-signed server certificate is generated at installation time
for the registry API. For more secure access, an intermediate or Root CA-signed
server certificate is strongly recommended.
To configure or update the HTTPS certificate for the local Docker registry,
create a certificate named ``system-registry-local-certificate`` in the
``deployment`` namespace. The ``secretName`` attribute of this certificate's
spec must also be named ``system-registry-local-certificate``.
See the example procedure below for creating the certificate for the local
Docker registry.
Update the following fields:
* The ``duration`` and ``renewBefore`` dates for the expiry and renewal times
you desire. The system will automatically renew and re-install the
certificate.
.. include:: /shared/_includes/recommended-renewbefore-value-for-certificates-c929cf42b03b.rest
* The ``subject`` fields to identify your particular system.
* The ``ipAddresses`` with the |OAM| Floating IP Address and the MGMT Floating
IP address for this system which MUST be specified for this certificate. Use
the :command:`system addrpool-list` command to get the |OAM| floating IP
Address and MGMT floating IP Address for your system.
* The ``dnsNames`` with ``registry.local``, ``registry.central`` and any |FQDN|
names configured for this system's |OAM| Floating IP Address in an external
DNS server.
.. rubric:: |proc|
#. Create the Docker certificate yaml configuration file.
.. code-block::
~(keystone_admin)]$ cat <<EOF > docker-certificate.yaml
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: system-registry-local-certificate
namespace: deployment
spec:
secretName: system-registry-local-certificate
issuerRef:
name: system-local-ca
kind: ClusterIssuer
duration: 2160h # 90d
renewBefore: 360h # 15d
subject:
organizationalUnits:
- StarlingX-system-registry-local
ipAddresses:
- <OAM_FLOATING_IP>
- <MGMT_FLOATING_IP>
dnsNames:
- registry.local
- registry.central
- <external-FQDN-for-OAM-Floating-IP-Address, if applicable>
#. Apply the configuration.
.. code-block::
~(keystone_admin)]$ kubectl apply -f docker-certificate.yaml
#. Verify the configuration.
.. code-block::
~(keystone_admin)]$ kubectl get certificate system-registry-local-certificate -n deployment
If configuration was successful, the certificate's Ready status will be
``True``.
#. Update the platform's trusted certificates (i.e. ``ssl_ca``) with the Root
|CA| associated with ``system-registry-local-certificate``.
See the example below where a Root |CA| ``system-local-ca`` was used to sign
the ``system-registry-local-certificate``, the ``ca.crt`` of the
``system-local-ca`` SECRET is extracted and added as a trusted |CA| for
|prod| (i.e. ``system ca-certificate-install``).
.. code-block:: none
~(keystone_admin)]$ kubectl -n cert-manager get secret system-local-ca -o yaml | fgrep tls.crt | awk '{print $2}' | base64 --decode >> system-local-ca.pem
~(keystone_admin)]$ system ca-certificate-install system-local-ca.pem
.. rubric:: |result|
The Docker registry certificate installation is now complete, and Cert-Manager
will handle the lifecycle management of the certificate.
---------------------------------------------------------------------------
Limitations for using IPv6 addresses related to management and OAM networks
---------------------------------------------------------------------------
.. include:: /shared/_includes/cert-mgmt-ipv6-address-limitation-1a4504370674.rest
The certificate will be anchored by system-local-ca's Root |CA|. For more
information, refer to
:ref:`system-local-ca-issuer-9196c5794834`.

2
doc/source/security/kubernetes/https-access-overview.rst
View File

@ -143,7 +143,7 @@ The following sections provide details on managing these certificates:
- :ref:`Kubernetes Certificates <kubernetes-certificates-f4196d7cae9c>`
- :ref:`Local Registry Server Certificates <security-install-update-the-docker-registry-certificate>`
- :ref:`configure-docker-registry-certificate-after-installation-c519edbfe90a`
- :ref:`System Trusted CA Certificates <add-a-trusted-ca>`

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

@ -275,7 +275,6 @@ Deprecated Functionality
:maxdepth: 1
starlingx-rest-api-applications-and-the-web-administration-server-deprecated
security-install-update-the-docker-registry-certificate-deprecated
***************************************

116
doc/source/security/kubernetes/security-install-update-the-docker-registry-certificate-deprecated.rst
View File

@ -1,116 +0,0 @@
.. vri1561486014514
.. _security-install-update-the-docker-registry-certificate:
==================================
Local Registry Server Certificates
==================================
.. note::
This procedure is deprecated. For up-to-date information, refer to:
:ref:`configure-docker-registry-certificate-after-installation-c519edbfe90a`.
For the Local Docker Registry, HTTPS is always enabled. By default, a
self-signed server certificate and key is generated and installed for this
endpoint. However, it is strongly recommended that you update the server
certificate used after installation with an Intermediate or Root |CA|-signed
server certificate and key. Refer to the documentation for the external
Intermediate or Root |CA| that you are using, on how to create public
certificate and private key pairs, signed by a Root |CA|, for HTTPS.
The local Docker registry provides Docker image service that can be accessed
using the registry API by secure HTTPS. Standalone system, central cloud and
every subcloud of |DC| system has their own Docker registry called
`registry.local`.
The Docker registry on the central cloud of |DC| system has an
alias of `registry.central`, which is used by subcloud to remotely login or
pull images from this central Docker registry.
.. rubric:: |context|
By default a self-signed certificate is generated at installation time for the
registry API. For more secure access, an Intermediate or Root |CA|-signed
certificate is strongly recommended.
The Intermediate or Root |CA|-signed certificate for the registry must have at
least the following |SANs|: ``DNS:registry.local``, ``DNS:registry.central``, IP
Address:<oam-floating-ip-address>, IP Address:<mgmt-floating-ip-address>. Use
the :command:`system addrpool-list` command to get the |OAM| floating IP
Address and management floating IP Address for your system. You can add any
additional DNS entry\(s) that you have set up for your |OAM| floating IP
Address.
Use the following procedure to install an intermediate or Root |CA|-signed
certificate to either replace the default self-signed certificate or to replace
an expired or soon to expire certificate.
.. rubric:: |prereq|
Obtain an intermediate or Root |CA|-signed certificate and key from a trusted
Intermediate or Root |CA|. Refer to the documentation for the external Root
|CA| that you are using, on how to create public certificate and private key
pairs, signed by an Intermediate or Root |CA|, for HTTPS.
For lab purposes, see :ref:`Create Certificates Locally using openssl
<create-certificates-locally-using-openssl>` for how to create a test
Intermediate or Root |CA| certificate and key, and use it to sign test
certificates.
Put the |PEM| encoded versions of the certificate and key in a single file,
and copy the file to the controller host.
Also, obtain the certificate of the Intermediate or Root |CA| that signed the
above certificate.
.. rubric:: |proc|
.. _security-install-update-the-docker-registry-certificate-d527e71:
#. In order to enable internal use of the Docker registry certificate,
update the trusted |CA| list for this system with the Root |CA| associated
with the Docker registry certificate.
.. code-block:: none
~(keystone_admin)]$ system certificate-install --mode ssl_ca
<pathTocertificate>
where:
``<pathTocertificate>``
is the path to the intermediate or Root |CA| certificate associated
with the Docker registry's Intermediate or Root |CA|-signed
certificate.
#. Update the Docker registry certificate using the
:command:`certificate-install` command.
Set the ``mode (-m or --mode)`` parameter to ``docker_registry``.
.. code-block:: none
~(keystone_admin)]$ system certificate-install --mode docker_registry
<pathTocertificateAndKey>
where:
``<pathTocertificateAndKey>``
is the path to the file containing both the Docker registry's
Intermediate or Root CA-signed certificate and private key to install.
.. note::
Ensure the certificates have RSA key length >= 2048 bits. The
|prod-long| Release |this-ver| 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
:ref:`Create Certificates Locally using openssl <create-certificates-locally-using-openssl>`.
Refer to :ref:`Install/Update Local Registry Certificates
<installing-updating-the-docker-registry-certificate>` on how to install/update
and renew local registry certificates.