diff --git a/doc/source/_vendor/rl-strings.txt b/doc/source/_vendor/rl-strings.txt index 6b38b91be..ffd7d0751 100644 --- a/doc/source/_vendor/rl-strings.txt +++ b/doc/source/_vendor/rl-strings.txt @@ -258,7 +258,6 @@ .. |pod-security-policies| replace:: :ref:`Pod Security Policies ` .. |remove-portieris| replace:: :ref:`Remove Portieris ` .. |delete-ldap-linux-accounts-7de0782fbafd| replace:: :ref:`Delete LDAP Linux Accounts ` -.. |security-install-update-the-docker-registry-certificate| replace:: :ref:`Local Registry Server Certificates ` .. |security-rest-api-access| replace:: :ref:`REST API Access ` .. |auditd-support-339a51d8ce16| replace:: :ref:`Linux Auditing System ` .. |the-cert-manager-bootstrap-process| replace:: :ref:`Configure cert-manager at Bootstrap ` diff --git a/doc/source/admintasks/kubernetes/installing-updating-the-docker-registry-certificate.rst b/doc/source/admintasks/kubernetes/installing-updating-the-docker-registry-certificate.rst index ea6be19c4..ed6877d8a 100644 --- a/doc/source/admintasks/kubernetes/installing-updating-the-docker-registry-certificate.rst +++ b/doc/source/admintasks/kubernetes/installing-updating-the-docker-registry-certificate.rst @@ -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:, 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 ` 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 `. - -.. 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 - - where: - - **** - - 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 - - where: - - **** - - 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. \ No newline at end of file +The certificate will be anchored by system-local-ca's Root |CA|. For more +information, refer to +:ref:`system-local-ca-issuer-9196c5794834`. \ No newline at end of file diff --git a/doc/source/security/kubernetes/configure-docker-registry-certificate-after-installation-c519edbfe90a.rst b/doc/source/security/kubernetes/configure-docker-registry-certificate-after-installation-c519edbfe90a.rst index 6bcac793b..bda2bc024 100644 --- a/doc/source/security/kubernetes/configure-docker-registry-certificate-after-installation-c519edbfe90a.rst +++ b/doc/source/security/kubernetes/configure-docker-registry-certificate-after-installation-c519edbfe90a.rst @@ -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 < 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: - - - - - dnsNames: - - registry.local - - registry.central - - - -#. 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`. \ No newline at end of file diff --git a/doc/source/security/kubernetes/https-access-overview.rst b/doc/source/security/kubernetes/https-access-overview.rst index 8293315ad..e07fd877e 100644 --- a/doc/source/security/kubernetes/https-access-overview.rst +++ b/doc/source/security/kubernetes/https-access-overview.rst @@ -143,7 +143,7 @@ The following sections provide details on managing these certificates: - :ref:`Kubernetes Certificates ` -- :ref:`Local Registry Server Certificates ` +- :ref:`configure-docker-registry-certificate-after-installation-c519edbfe90a` - :ref:`System Trusted CA Certificates ` diff --git a/doc/source/security/kubernetes/index-security-kub-81153c1254c3.rst b/doc/source/security/kubernetes/index-security-kub-81153c1254c3.rst index 4cb7fb956..afb906ded 100644 --- a/doc/source/security/kubernetes/index-security-kub-81153c1254c3.rst +++ b/doc/source/security/kubernetes/index-security-kub-81153c1254c3.rst @@ -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 *************************************** diff --git a/doc/source/security/kubernetes/security-install-update-the-docker-registry-certificate-deprecated.rst b/doc/source/security/kubernetes/security-install-update-the-docker-registry-certificate-deprecated.rst deleted file mode 100644 index f2ca1cb9c..000000000 --- a/doc/source/security/kubernetes/security-install-update-the-docker-registry-certificate-deprecated.rst +++ /dev/null @@ -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:, 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 -` 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 - - - where: - - ```` - 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 - - - where: - - ```` - 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 -noout -text`` - and looking for the "Public-Key" in the output. For more information see - :ref:`Create Certificates Locally using openssl `. - -Refer to :ref:`Install/Update Local Registry Certificates -` on how to install/update -and renew local registry certificates.