starlingx/docs
Code Issues Proposed changes

Configuring REST API GUI certificate

Browse Source 
Update documentation regarding the REST API / GUI certificate.
Fix link.

Story: 2009811
Task: 50152

Change-Id: Ic6b07200df9e1664b1310be9e0799a338f9ac586
Signed-off-by: Elisamara Aoki Goncalves <elisamaraaoki.goncalves@windriver.com>
This commit is contained in:
Elisamara Aoki Goncalves 2024-09-13 18:28:11 +00:00
parent 021026d26c
commit 133f037b5c
1 changed files with 16 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
doc/source/security/kubernetes/configure-rest-api-apps-and-web-admin-server-certs-after-inst-6816457ab95f.rst
View File

@ -4,110 +4,22 @@
Configure REST API Applications and Web Administration Server certificate
=========================================================================
.. rubric:: |context|
|prod| provides support for secure HTTPS external connections used for |prod|
REST API application endpoints (Keystone, Barbican and |prod|) and the |prod|
web administration server.
|prod| provides support for secure HTTPS external connections used for
StarlingX REST API application endpoints (Keystone, Barbican and StarlingX) and
the |prod| web administration server. By default, HTTPS access to StarlingX
REST and Web Server endpoints is disabled. They are accessible via HTTP only.
To enable secure HTTPS access, an x509 certificate and key must be configured.
During installation, the Platform Issuer (``system-local-ca``) will
automatically issue a certificate used to secure access to the |prod| REST API
and to the Web Server GUI. This allows the system to have HTTPS access enabled
from the bootstrap to the services. This certificate will be stored in a K8s
|TLS| secret in namespace ``deployment``, named
``system-restapi-gui-certificate``. It will be managed by cert-manager, renewed
upon expiration and the required services restarted automatically.
You can update the certificate used for HTTPS access at any time.
To configure or update the HTTPS certificate for the StarlingX REST API and Web
Server endpoints, create a certificate named ``system-restapi-gui-certificate``
in the ``deployment`` namespace. The ``secretName`` attribute of this
certificate's spec must also be named ``system-restapi-gui-certificate``.
See the example procedure below for creating the certificate for the StarlingX
REST API and Web Server endpoints.
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 for this system.
* The ``dnsNames`` with any |FQDN| names configured for this system in an
external DNS server.
.. note::
If you plan to use the container-based remote CLIs, due to a limitation in
the Python2 SSL certificate validation, the certificate used for the
``system-restapi-gui-certificate`` certificate must either have:
- CN=IPADDRESS and SANs=IPADDRESS
or
- CN=FQDN and SANs=FQDN
where IPADDRESS and FQDN are for the |OAM| Floating IP Address.
.. rubric:: |proc|
#. Create the REST API certificate yaml configuration file.
.. code-block::
~(keystone_admin)]$ cat <<EOF > restapi-certificate.yaml
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: system-restapi-gui-certificate
namespace: deployment
spec:
secretName: system-restapi-gui-certificate
issuerRef:
name: system-local-ca
kind: ClusterIssuer
duration: 2160h # 90 days
renewBefore: 360h # 15 days
commonName: < oam floating IP Address or FQDN >
subject:
organizations:
- ABC-Company
organizationalUnits:
- StarlingX-system-restapi-gui
ipAddresses:
- < oam floating IP address >
dnsNames:
- < oam floating FQDN >
EOF
#. Apply the configuration.
.. code-block::
~(keystone_admin)]$ kubectl apply -f restapi-certificate.yaml
#. Verify the configuration.
.. code-block::
~(keystone_admin)]$ kubectl get certificate system-restapi-gui-certificate -n deployment
If configuration was successful, the certificate's Ready status will be
``True``.
.. rubric:: |result|
The REST and Web Server 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
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).
The certificate will be anchored by ``system-local-ca``'s Root |CA|. For more
information, refer to
:ref:`system-local-ca-issuer-9196c5794834`.