mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
osdocs15216 contentx improvements for custom PKI doc
This commit is contained in:
Daniel Chadwick
committed by
openshift-cherrypick-robot
openshift-cherrypick-robot
parent
339704a33c
commit
1e42b05eab
41
modules/adding-a-custom-CA-during-cluster-installation.adoc
Normal file
41
modules/adding-a-custom-CA-during-cluster-installation.adoc
Normal file
@@ -0,0 +1,41 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * networking/configuring-a-custom-pki.adoc
|
||||
|
||||
:_mod-docs-content-type: PROCEDURE
|
||||
[id="adding-a-custom-CA-during-cluster-installation_{context}"]
|
||||
= Adding a custom CA during cluster installation
|
||||
|
||||
You can add a custom CA to the cluster-wide truststore during installation by providing the certificate in your `install-config.yaml` file.
|
||||
|
||||
This procedure uses the `additionalTrustBundle` parameter. If you are also configuring an egress proxy, you can add this parameter to your `install-config.yaml` file along with your proxy configuration. For more information on the available proxy settings, see the "Configuring the cluster-wide proxy" chapter.
|
||||
|
||||
.Prerequisites
|
||||
|
||||
* You have access to the `install-config.yaml` file for your cluster installation.
|
||||
|
||||
* You have your custom CA certificate avalable in PEM-encoded format.
|
||||
|
||||
.Procedure
|
||||
|
||||
. Open your `install-config.yaml` file.
|
||||
|
||||
. Add the `additionalTrustBundle` parameter with your PEM-encoded CA certificate:
|
||||
+
|
||||
[source,yaml]
|
||||
----
|
||||
apiVersion: v1
|
||||
baseDomain: my.domain.com
|
||||
metadata:
|
||||
name: my-cluster
|
||||
additionalTrustBundle: | <1>
|
||||
-----BEGIN CERTIFICATE-----
|
||||
<MY_PEM_ENCODED_CA_CERT>
|
||||
-----END CERTIFICATE-----
|
||||
----
|
||||
+
|
||||
<1> The `additionalTrustBundle` parameter contains the custom CA certificate that you want the cluster to trust. The installation program uses the certificate to generate a `user-ca-bundle` `ConfigMap` object in the `openshift-config` namespace.
|
||||
|
||||
. Save the `install-config.yaml` file and continue with your cluster installation.
|
||||
|
||||
During installation, the Cluster Network Operator (CNO) merges the certificate you provided with the system's default trust bundle. This process makes your custom CA trusted across the entire cluster.
|
||||
70
modules/adding-a-custom-CA-to-a-running-cluster.adoc
Normal file
70
modules/adding-a-custom-CA-to-a-running-cluster.adoc
Normal file
@@ -0,0 +1,70 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * networking/configuring-a-custom-pki.adoc
|
||||
|
||||
:_mod-docs-content-type: PROCEDURE
|
||||
[id="adding-a-custom-CA-to-a-running-cluster_{context}"]
|
||||
= Adding a custom CA to a running cluster
|
||||
|
||||
For a running cluster, you can add a custom CA by creating a `ConfigMap` object that contains your certificate and then referencing that `ConfigMap` object in the cluster `Proxy` object.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
When you modify the cluster `Proxy` object, the Machine Config Operator (MCO) initiates a rolling reboot of all nodes to apply the change. This is expected behavior and does not require manual intervention.
|
||||
====
|
||||
|
||||
This procedure uses the `trustedCA` field in the `Proxy` object. If you also need to configure or modify egress proxy settings at the same time, see the "Configuring the cluster-wide proxy" chapter for detailed instructions.
|
||||
|
||||
.Prerequisites
|
||||
|
||||
* You have cluster-admin privileges.
|
||||
|
||||
* You have the {oc-first} installed.
|
||||
|
||||
* You have your custom CA certificate available in PEM-encoded format.
|
||||
|
||||
.Procedure
|
||||
|
||||
The procedure involves two stages: creating a `ConfigMap` object with your certificate and then updating the cluster to trust it.
|
||||
|
||||
. Create a `ConfigMap` object with your CA certificate.
|
||||
|
||||
.. Create a YAML file named `custom-ca.yaml` to define the `ConfigMap` object.
|
||||
|
||||
.. Add the following content to the file:
|
||||
+
|
||||
[source,yaml]
|
||||
----
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: custom-ca-bundle <1>
|
||||
namespace: openshift-config <2>
|
||||
data:
|
||||
ca-bundle.crt: | <3>
|
||||
-----BEGIN CERTIFICATE-----
|
||||
<MY_PEM_ENCODED_CA_CERT>
|
||||
-----END CERTIFICATE-----
|
||||
----
|
||||
+
|
||||
<1> The name of the `ConfigMap` object that you will reference from the `Proxy` object.
|
||||
<2> The `ConfigMap` object must be created in the `openshift-config` namespace.
|
||||
<3> The data key for the certificate bundle must be `ca-bundle.crt`.
|
||||
|
||||
. Apply the manifest to create the `ConfigMap` object in the cluster:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ oc apply -f custom-ca.yaml
|
||||
----
|
||||
|
||||
. Reference the `ConfigMap` object in the cluster `Proxy` object.
|
||||
|
||||
.. Run the following `oc patch` command to update the cluster `Proxy` object to reference the `ConfigMap` object you just created.
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ oc patch proxy/cluster --type=merge --patch='{"spec":{"trustedCA":{"name":"custom-ca-bundle"}}}'
|
||||
----
|
||||
|
||||
After you run this command, the Machine Config Operator (MCO) detects the change and begins distributing the new trusted CA to all nodes in the cluster.
|
||||
48
modules/verifying-the-custom-ca-configuration.adoc
Normal file
48
modules/verifying-the-custom-ca-configuration.adoc
Normal file
@@ -0,0 +1,48 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * networking/configuring-a-custom-pki.adoc
|
||||
|
||||
:_mod-docs-content-type: PROCEDURE
|
||||
[id="verifying-the-custom-ca-configuration_{context}"]
|
||||
= Verifying the custom CA configuration
|
||||
|
||||
After you add your custom CA certificate, you can verify that it has been successfully added to the cluster-wide trust bundle.
|
||||
|
||||
.Prerequisites
|
||||
|
||||
* You have permissions to view `ConfigMap` objects in the openshift-config namespace.
|
||||
|
||||
* You have the {oc-first} installed.
|
||||
|
||||
.Procedure
|
||||
|
||||
. Run the following command to view the contents of the cluster-wide CA trust bundle:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ oc get configmap trusted-ca-bundle -n openshift-config -o yaml
|
||||
----
|
||||
|
||||
. In the YAML output, inspect the `data.ca-bundle.crt` field. This field contains all the trusted certificates for the cluster.
|
||||
|
||||
. Verify that the PEM-encoded certificate you added is included in the list of certificates. The output will resemble the following structure:
|
||||
+
|
||||
[source,yaml]
|
||||
----
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: trusted-ca-bundle
|
||||
namespace: openshift-config
|
||||
data:
|
||||
ca-bundle.crt: |
|
||||
-----BEGIN CERTIFICATE-----
|
||||
<A_SYSTEM_CA_CERTIFICATE>
|
||||
-----END CERTIFICATE-----
|
||||
-----BEGIN CERTIFICATE-----
|
||||
<ANOTHER_SYSTEM_CA_CERTIFICATE>
|
||||
-----END CERTIFICATE-----
|
||||
-----BEGIN CERTIFICATE-----
|
||||
<YOUR_CUSTOM_CA_CERTIFICATE_SHOULD_BE_HERE>
|
||||
-----END CERTIFICATE-----
|
||||
----
|
||||
If your certificate is present in the output, the cluster now trusts your custom PKI.
|
||||
@@ -6,42 +6,20 @@ include::_attributes/common-attributes.adoc[]
|
||||
|
||||
toc::[]
|
||||
|
||||
Some platform components, such as the web console, use Routes for communication and
|
||||
must trust other components' certificates to interact with them. If
|
||||
you are using a custom public key infrastructure (PKI), you must configure it so
|
||||
its privately signed CA certificates are recognized across the cluster.
|
||||
To ensure secure communication between internal components, your {product-title} cluster uses a shared set of trusted Certificate Authorities (CAs). If your organization uses its own private certificates (a custom PKI), you must add your CA to the cluster so that all components trust it.
|
||||
|
||||
You can leverage the Proxy API to add cluster-wide trusted CA certificates. You
|
||||
must do this either during installation or at runtime.
|
||||
You can add your custom CA certificates to the cluster-wide truststore in one of two ways:
|
||||
|
||||
* During _installation_, xref:../networking/configuring_network_settings/configuring-a-custom-pki.adoc#installation-configure-proxy_{context}[configure the cluster-wide proxy]. You must define your
|
||||
privately signed CA certificates in the `install-config.yaml` file's
|
||||
`additionalTrustBundle` setting.
|
||||
+
|
||||
The installation program generates a ConfigMap that is named `user-ca-bundle`
|
||||
that contains the additional CA certificates you defined. The Cluster Network
|
||||
Operator then creates a `trusted-ca-bundle` ConfigMap that merges these CA
|
||||
certificates with the {op-system-first} trust bundle; this ConfigMap is
|
||||
referenced in the Proxy object's `trustedCA` field.
|
||||
* During cluster installation, by adding your CA certificate to the `install-config.yaml` file.
|
||||
|
||||
* At _runtime_, xref:../networking/configuring_network_settings/configuring-a-custom-pki.adoc#nw-proxy-configure-object_{context}[modify the default Proxy object to include your privately signed CA certificates] (part of cluster's proxy enablement workflow). This involves
|
||||
creating a ConfigMap that contains the privately signed CA certificates that
|
||||
should be trusted by the cluster, and then modifying the proxy resource with the
|
||||
`trustedCA` referencing the privately signed certificates' ConfigMap.
|
||||
* On a running cluster, by creating a `ConfigMap` object that contains your CA certificate and referencing it in the cluster `Proxy` object.
|
||||
|
||||
[NOTE]
|
||||
[IMPORTANT]
|
||||
====
|
||||
The installer configuration's `additionalTrustBundle` field and the proxy
|
||||
resource's `trustedCA` field are used to manage the cluster-wide trust bundle;
|
||||
`additionalTrustBundle` is used at install time and the proxy's `trustedCA` is
|
||||
used at runtime.
|
||||
|
||||
The `trustedCA` field is a reference to a `ConfigMap` containing the custom
|
||||
certificate and key pair used by the cluster component.
|
||||
The cluster Proxy object is the mechanism for managing the cluster-wide truststore. This guide focuses only on the task of adding a CA. If you also need to configure an egress proxy, refer to the "Configuring the cluster-wide proxy" chapter for detailed instructions.
|
||||
====
|
||||
|
||||
include::modules/installation-configure-proxy.adoc[leveloffset=+1]
|
||||
|
||||
include::modules/nw-proxy-configure-object.adoc[leveloffset=+1]
|
||||
|
||||
include::modules/adding-a-custom-CA-during-cluster-installation.adoc[leveloffset=+1]
|
||||
include::modules/adding-a-custom-CA-to-a-running-cluster.adoc[leveloffset=+1]
|
||||
include::modules/verifying-the-custom-ca-configuration.adoc[leveloffset=+1]
|
||||
include::modules/certificate-injection-using-operators.adoc[leveloffset=+1]
|
||||
|
||||
Reference in New Issue
Block a user