mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
143 lines
5.5 KiB
Plaintext
143 lines
5.5 KiB
Plaintext
// Module included in the following assemblies:
|
|
//
|
|
// * microshift_security_compliance/microshift-custom-ca.adoc
|
|
|
|
:_mod-docs-content-type: PROCEDURE
|
|
[id="microshift-custom-cas-configuring_{context}"]
|
|
= Configuring custom certificate authorities
|
|
|
|
To configure externally generated certificates and domain names by using custom certificate authorities (CAs), add them to the {microshift-short} `/etc/microshift/config.yaml` configuration file. You must also configure the host operating system trust root.
|
|
|
|
[NOTE]
|
|
====
|
|
Externally generated `kubeconfig` files are created in the `/var/lib/microshift/resources/kubeadmin/<hostname>/kubeconfig` directory. If you need to use `localhost` in addition to externally generated configurations, retain the original `kubeconfig` file in its default location. The `localhost` `kubeconfig` file uses the self-signed certificate authority.
|
|
====
|
|
|
|
.Prerequisites
|
|
|
|
* The {oc-first} is installed.
|
|
* You have root access to the node.
|
|
* The certificate authority has issued the custom certificates.
|
|
* A {microshift-short} `/etc/microshift/config.yaml` configuration file exists.
|
|
|
|
.Procedure
|
|
|
|
. Copy the custom certificates you want to add to the trust root of the {microshift-short} host. Ensure that the
|
|
certificate and private keys are only accessible to {microshift-short}.
|
|
|
|
. For each custom CA that you need, add an `apiServer` section called `namedCertificates` to the `/etc/microshift/config.yaml` {microshift-short} configuration file by using the following example:
|
|
+
|
|
[source,yaml]
|
|
----
|
|
apiServer:
|
|
namedCertificates:
|
|
- certPath: ~/certs/api_fqdn_1.crt <1>
|
|
keyPath: ~/certs/api_fqdn_1.key <2>
|
|
- certPath: ~/certs/api_fqdn_2.crt
|
|
keyPath: ~/certs/api_fqdn_2.key
|
|
names: <3>
|
|
- api_fqdn_1
|
|
- *.apps.external.com
|
|
----
|
|
<1> Add the full path to the certificate.
|
|
<2> Add the full path to the certificate key.
|
|
<3> Optional. Add a list of explicit DNS names. Leading wildcards are allowed. If no names are listed, the implicit names are extracted from the certificates.
|
|
|
|
. Restart the {microshift-short} to apply the certificates by running the following command:
|
|
+
|
|
[source,terminal]
|
|
----
|
|
$ systemctl microshift restart
|
|
----
|
|
|
|
. Wait a few minutes for the system to restart and apply the custom server. New `kubeconfig` files are generated in the `/var/lib/microshift/resources/kubeadmin/` directory.
|
|
|
|
. Copy the `kubeconfig` files to the client. If you specified wildcards for the IP address, update the `kubeconfig` to remove the public IP address of the server and replace that IP address with the specific wildcard range you want to use.
|
|
|
|
. From the client, use the following steps:
|
|
|
|
.. Specify the `kubeconfig` to use by running the following command:
|
|
+
|
|
[source,terminal]
|
|
----
|
|
$ export KUBECONFIG=~/custom-kubeconfigs/kubeconfig <1>
|
|
----
|
|
<1> Use the location of the copied `kubeconfig` file as the path.
|
|
|
|
.. Check that the certificates are applied by using the following command:
|
|
+
|
|
[source,terminal]
|
|
----
|
|
$ oc --certificate-authority ~/certs/ca.ca get node
|
|
----
|
|
+
|
|
.Example output
|
|
[source,terminal]
|
|
----
|
|
oc get node
|
|
NAME STATUS ROLES AGE VERSION
|
|
dhcp-1-235-195.arm.example.com Ready control-plane,master,worker 76m v1.34.2
|
|
----
|
|
|
|
.. Add the new CA file to the $KUBECONFIG environment variable by running the following command:
|
|
+
|
|
[source,terminal]
|
|
----
|
|
$ oc config set clusters.microshift.certificate-authority /tmp/certificate-authority-data-new.crt
|
|
----
|
|
|
|
.. Verify that the new `kubeconfig` file contains the new CA by running the following command:
|
|
+
|
|
[source,terminal]
|
|
----
|
|
$ oc config view --flatten
|
|
----
|
|
+
|
|
.Example externally generated `kubeconfig` file
|
|
+
|
|
[source,yaml]
|
|
----
|
|
apiVersion: v1
|
|
clusters:
|
|
- cluster:
|
|
certificate-authority: /tmp/certificate-authority-data-new.crt <1>
|
|
server: https://api.ci-ln-k0gim2b-76ef8.aws-2.ci.openshift.org:6443
|
|
name: ci-ln-k0gim2b-76ef8
|
|
contexts:
|
|
- context:
|
|
cluster: ci-ln-k0gim2b-76ef8
|
|
user:
|
|
name:
|
|
current-context:
|
|
kind: Config
|
|
preferences: {}
|
|
----
|
|
<1> The `certificate-authority-data` section is not present in externally generated `kubeconfig` files. It is added with the `oc config set` command used previously.
|
|
|
|
.. Verify the `subject` and `issuer` of your customized API server certificate authority by running the following command:
|
|
+
|
|
[source,terminal]
|
|
----
|
|
$ curl --cacert /tmp/caCert.pem https://${fqdn_name}:6443/healthz -v
|
|
----
|
|
+
|
|
.Example output
|
|
----
|
|
Server certificate:
|
|
subject: CN=kas-test-cert_server
|
|
start date: Mar 12 11:39:46 2024 GMT
|
|
expire date: Mar 12 11:39:46 2025 GMT
|
|
subjectAltName: host "dhcp-1-235-3.arm.eng.rdu2.redhat.com" matched cert's "dhcp-1-235-3.arm.eng.rdu2.redhat.com"
|
|
issuer: CN=kas-test-cert_ca
|
|
SSL certificate verify ok.
|
|
----
|
|
+
|
|
[IMPORTANT]
|
|
====
|
|
Either replace the `certificate-authority-data` in the generated `kubeconfig` file with the new `rootCA` or add the `certificate-authority-data` to the trust root of the operating system. Do not use both methods.
|
|
====
|
|
|
|
.. Configure additional CAs in the trust root of the operating system. For example, in the RHEL Client truststore on the client system. link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/securing_networks/using-shared-system-certificates_securing-networks#the-system-wide-trust-store_using-shared-system-certificates[The system-wide truststore].
|
|
** Updating the certificate bundle with the configuration that contains the CA is recommended.
|
|
** If you do not want to configure your certificate bundles, you can alternately use the `oc login localhost:8443 --certificate-authority=/path/to/cert.crt` command, but this method is not preferred.
|