diff --git a/_topic_map.yml b/_topic_map.yml index c1fd9c2f0e..2b1844f1e9 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -336,6 +336,9 @@ Topics: - Name: Understanding identity provider configuration File: dedicated-understanding-authentication Distros: openshift-dedicated +- Name: Certificate types and descriptions + File: certificate-types-descriptions + Distros: openshift-enterprise,openshift-webscale,openshift-origin - Name: Configuring the internal OAuth server File: configuring-internal-oauth Distros: openshift-enterprise,openshift-webscale,openshift-origin @@ -816,7 +819,7 @@ Topics: File: images-other-jenkins-agent - Name: Building and deploying a DPDK payload using the s2i image File: cnf-building-and-deploying-a-dpdk-payload - Distros: openshift-webscale + Distros: openshift-webscale --- Name: Applications Dir: applications diff --git a/authentication/certificate-types-descriptions.adoc b/authentication/certificate-types-descriptions.adoc new file mode 100644 index 0000000000..7f4c9ba85a --- /dev/null +++ b/authentication/certificate-types-descriptions.adoc @@ -0,0 +1,166 @@ +[id="ocp-certificates"] += Certificate types and descriptions +include::modules/common-attributes.adoc[] +:context: ocp-certificates + +toc::[] + +== Certificate validation + +{product-title} monitors certificates for proper validity, for the cluster +certificates it issues and manages. The {product-title} alerting framework has +rules to help identify when a certificate issue is about to occur. These rules +consist of the following checks: + +* API server client certificate expiration is less than five minutes. + +include::modules/user-provided-certificates-for-api-server.adoc[leveloffset=+1] +include::modules/proxy-certificates.adoc[leveloffset=+1] +include::modules/service-ca-certificates.adoc[leveloffset=+1] +include::modules/node-certificates.adoc[leveloffset=+1] +include::modules/bootstrap-certificates.adoc[leveloffset=+1] +include::modules/etcd-certificates.adoc[leveloffset=+1] +include::modules/olm-certificates.adoc[leveloffset=+1] +include::modules/user-provided-certificates-for-default-ingress.adoc[leveloffset=+1] + +== Ingress certificates + +[discrete] +== Purpose + +The Ingress Operator uses certificates for: + +* Securing access to metrics for Prometheus. +* Securing access to routes. + +[discrete] +== Location + +To secure access to Ingress Operator and Ingress Controller metrics, the Ingress +Operator uses service serving certificates. The Operator requests a certificate +from the `service-ca` controller for its own metrics, and the `service-ca` +controller puts the certificate in a secret named `metrics-tls` in the +`openshift-ingress-operator` namespace. Additionally, the Ingress Operator +requests a certificate for each Ingress Controller, and the `service-ca` +controller puts the certificate in a secret named `router-metrics-certs-`, +where `` is the name of the Ingress Controller, in the +`openshift-ingress` namespace. + +Each Ingress Controller has a default certificate that it uses for secured +routes that do not specify their own certificates. Unless you specify a custom +certificate, the Operator uses a self-signed certificate by default. The +Operator uses its own self-signed signing certificate to sign any default +certificate that it generates. The Operator generates this signing certificate +and puts it in a secret named `router-ca` in the `openshift-ingress-operator` +namespace. When the Operator generates a default certificate, it puts the default +certificate in a secret named `router-certs-` (where `` is the name +of the Ingress Controller) in the `openshift-ingress` namespace. + +[WARNING] +==== +The Ingress Operator generates a default certificate for an Ingress Controller +to serve as a placeholder until you configure a custom default certificate. Do +not use Operator-generated default certificates in production clusters. +==== + +[discrete] +== Expiration + +The expiration terms for the Ingress Operator's certificates are as follows: + +* The expiration date for metrics certificates that the `service-ca` controller +creates is two years after the date of creation. +* The expiration date for the Operator's signing certificate is two years after +the date of creation. +* The expiration date for default certificates that the Operator generates is two +years after the date of creation. + +You cannot specify custom expiration terms on certificates that the Ingress +Operator or `service-ca` controller creates. + +You cannot specify expiration terms when installing {product-title} for +certificates that the Ingress Operator or `service-ca` controller creates. + +[discrete] +== Services + +Prometheus uses the certificates that secure metrics. + +The Ingress Operator uses its signing certificate to sign default certificates +that it generates for Ingress Controllers for which you do not set custom +default certificates. + +Cluster components that use secured routes may use the default Ingress +Controller's default certificate. + +Ingress to the cluster via a secured route uses the default certificate of the +Ingress Controller by which the route is accessed unless the route specifies +its own certificate. + +[discrete] +== Management + +Ingress certificates are managed by the user. See +xref:../authentication/certificates/replacing-default-ingress-certificate.adoc#replacing-default-ingress[Replacing +the default ingress certificate] for more information. + +[discrete] +== Renewal + +The `service-ca` controller automatically rotates the certificates that it +issues. However, it is possible to use `oc delete secret ` to +manually rotate service serving certificates. + +The Ingress Operator does not rotate its own signing certificate or the default +certificates that it generates. Operator-generated default certificates are +intended as placeholders for custom default certificates that you configure. + += Monitoring and cluster logging Operator component certificates + +Monitoring components secure their traffic with service CA certificates. These +certificates are valid for 2 years and are replaced automatically on rotation of +the service CA, which is every 13 months. + + +If the certificate lives in the `openshift-monitoring` or `openshift-logging` +namespace, it is system managed and rotated automatically. + +[discrete] +== Management + +These certificates are managed by the system and not the user. + += Control plane certificates + +[discrete] +== Location + +Control plane certificates are included in these namespaces: + +* openshift-config-managed +* openshift-kube-apiserver +* openshift-kube-apiserver-operator +* openshift-kube-controller-manager +* openshift-kube-controller-manager-operator +* openshift-kube-scheduler + +[discrete] +== Management + +Control plane certificates are managed by the system and rotated automatically. + +In the rare case that your control plane certificates expired, see +xref:../backup_and_restore/disaster_recovery/scenario-3-expired-certs.adoc#dr-recovering-expired-certs[Recovering +from expired control plane certificates] + +.Additional resources + +* xref:../authentication/certificates/service-serving-certificate.adoc#add-service-serving[Manually rotate service serving certificates] +* xref:../authentication/certificates/service-serving-certificate.adoc#add-service-serving[Securing service traffic using service serving certificate secrets] +* xref:../backup_and_restore/disaster_recovery/scenario-3-expired-certs.adoc#dr-recovering-expired-certs[Recovering +from expired control plane certificates] +* xref:../networking/enable-cluster-wide-proxy.adoc#enable-cluster-wide-proxy[Configuring the cluster-wide proxy] +* xref:../authentication/certificates/api-server.adoc#api-server-certificates[Adding API server certificates] +* xref:../authentication/certificates/replacing-default-ingress-certificate.adoc#replacing-default-ingress[Replacing the default ingress certificate] +* xref:../nodes/nodes/nodes-nodes-working.adoc#nodes-nodes-working[Working with nodes] +* xref:../backup_and_restore/disaster_recovery/scenario-1-infra-recovery.adoc#dr-scenario-1-recover-master-hosts_dr-infrastructure-recovery[Recovering from lost master hosts] diff --git a/authentication/understanding-certificates.adoc b/authentication/understanding-certificates.adoc new file mode 100644 index 0000000000..e69de29bb2 diff --git a/images/darkcircle-0.png b/images/darkcircle-0.png new file mode 100644 index 0000000000..5ab465076d Binary files /dev/null and b/images/darkcircle-0.png differ diff --git a/images/darkcircle-10.png b/images/darkcircle-10.png new file mode 100644 index 0000000000..dfdc4f8d4e Binary files /dev/null and b/images/darkcircle-10.png differ diff --git a/images/darkcircle-9.png b/images/darkcircle-9.png new file mode 100644 index 0000000000..5cc237f705 Binary files /dev/null and b/images/darkcircle-9.png differ diff --git a/images/ingress-certificates-workflow.png b/images/ingress-certificates-workflow.png new file mode 100644 index 0000000000..77edf2652a Binary files /dev/null and b/images/ingress-certificates-workflow.png differ diff --git a/modules/bootstrap-certificates.adoc b/modules/bootstrap-certificates.adoc new file mode 100644 index 0000000000..c281abfaf6 --- /dev/null +++ b/modules/bootstrap-certificates.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * authentication/certificate-types-descriptions.adoc + +[id="bootstrap-certificates_{context}"] += Bootstrap certificates + +[discrete] +== Purpose + +The kubelet, in {product-title} 4 and later, uses the bootstrap certificate +located in `/etc/kubernetes/kubeconfig` to initially bootstrap. This is followed +by the +link:https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/#bootstrap-initialization[bootstrap +initialization process] and +link:https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/#authorize-kubelet-to-create-csr[authorization +of the kubelet to create a CSR]. + +In that process, the kubelet generates a CSR while communicating over the +bootstrap channel. The controller manager signs the CSR, resulting in a +certificate that the kubelet manages. + +[discrete] +== Management + +These certificates are managed by the system and not the user. + +[discrete] +== Expiration +This bootstrap CA is valid for 10 years. + +The kubelet-managed certificate is valid for one year and rotates automatically at +around the 80 percent mark of that one year. + +[discrete] +== Customization + +You cannot customize the bootstrap certificates. diff --git a/modules/etcd-certificates.adoc b/modules/etcd-certificates.adoc new file mode 100644 index 0000000000..ac3bcd166d --- /dev/null +++ b/modules/etcd-certificates.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * authentication/certificate-types-descriptions.adoc + +[id="etcd-certificates_{context}"] += etcd certificates + +[discrete] +== Purpose + +etcd certificates are signed by the etcd-signer; they come from a certificate +authority (CA) that is generated by the bootstrap process. + +[discrete] +== Expiration + +The CA certificates are valid for 10 years. The peer, client, and server +certificates are valid for three years. + +[discrete] +== Management + +These certificates are managed by the system and not the user. + +[discrete] +== Services + +etcd certificates are used for encrypted communication between etcd member +peers, as well as encrypted client traffic. The following certificates are +generated and used by etcd and other processes that communicate with etcd: + +* Peer certificates: Used for communication between etcd members. +* Client certificates: Used for encrypted server-client communication. Client +certificates are currently used by the API server only, and no other service +should connect to etcd directly except for the proxy. Client secrets +(`etcd-client`, `etcd-metric-client`, `etcd-metric-signer`, and `etcd-signer`) +are added to the `openshift-config`, `openshift-monitoring`, and +`openshift-kube-apiserver` namespaces. +* Server certificates: Used by the etcd server for authenticating client requests. +* Metric certificates: All metric consumers connect to proxy with metric-client +certificates. diff --git a/modules/node-certificates.adoc b/modules/node-certificates.adoc new file mode 100644 index 0000000000..90b8df5ad3 --- /dev/null +++ b/modules/node-certificates.adoc @@ -0,0 +1,19 @@ + +// Module included in the following assemblies: +// +// * authentication/certificates/certificate-reference.adoc + +[id="node-certificates_{context}"] += Node certificates + +[discrete] +== Purpose + +Node certificates are signed by the cluster; they come from a certificate +authority (CA) that is generated by the bootstrap process. Once the cluster is +installed, the node certificates are auto-rotated. + +[discrete] +== Management + +These certificates are managed by the system and not the user. diff --git a/modules/olm-certificates.adoc b/modules/olm-certificates.adoc new file mode 100644 index 0000000000..f7da52c4c3 --- /dev/null +++ b/modules/olm-certificates.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * authentication/certificate-types-descriptions.adoc + +[id="olm-certificates_{context}"] += OLM certificates + +[discrete] +== Management + +All certificates for OpenShift Lifecycle Manager (OLM) components +(`olm-operator`, `catalog-operator`, `packageserver`, and +`marketplace-operator`) are managed by the system. + +Operators installed via OLM can have certificates generated for them if they are +providing API services. `packageserver` is one example. + +Certificates in the `openshift-operator-lifecycle-manager` namespace are managed +by OLM with the exception of certificates used by Operators that require a +validating or mutating webhook. + +Operators that install validating or mutating webhooks must currently manage +those certificates themselves. They do not require the user to manage the +certificates. + +OLM will not update the certificates of Operators that it manages in proxy +environments. These certificates must be managed by the user via the +subscription config. diff --git a/modules/proxy-certificates.adoc b/modules/proxy-certificates.adoc new file mode 100644 index 0000000000..85852960ed --- /dev/null +++ b/modules/proxy-certificates.adoc @@ -0,0 +1,169 @@ + +// Module included in the following assemblies: +// +// * authentication/certificate-types-descriptions.adoc + +[id="proxy-certificates_{context}"] += Proxy certificates + +[discrete] +== Purpose + +Proxy certificates allow users to specify one or more custom certificate +authority (CA) certificates used by platform components when making egress +connections. + +The `trustedCA` field of the Proxy object is a reference to a ConfigMap that +contains a user-provided trusted certificate authority (CA) bundle. This bundle +is merged with the {op-system-first} trust bundle and injected into the trust +store of platform components that make egress HTTPS calls. For example, +`image-registry-operator` calls an external image registry to download images. +If `trustedCA` is not specified, only the {op-system} trust bundle is used for proxied +HTTPS connections. Provide custom CA certificates to the {op-system} trust bundle if +you want to use your own certificate infrastructure. + +The `trustedCA` field should only be consumed by a proxy validator. The +validator is responsible for reading the certificate bundle from required key +`ca-bundle.crt` and copying it to a ConfigMap named `trusted-ca-bundle` in the +`openshift-config-managed` namespace. The namespace for the ConfigMap referenced +by `trustedCA` is `openshift-config`: + +[source,yaml] +---- +apiVersion: v1 + kind: ConfigMap + metadata: + name: user-ca-bundle + namespace: openshift-config + data: + ca-bundle.crt: | + -----BEGIN CERTIFICATE----- + Custom CA certificate bundle. + -----END CERTIFICATE----- +---- + +[discrete] +== Managing proxy certificates during installation + +The `additionalTrustBundle` value of the installer configuration is used to +specify any proxy-trusted CA certificates during installation. For example: + +---- +$ cat install-config.yaml +. . . +proxy: + httpProxy: http:// + httpsProxy: https:// +additionalTrustBundle: | + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- +. . . +---- + +[discrete] +== Location + +The user-provided trust bundle is represented as a ConfigMap. The ConfigMap is +mounted into the file system of platform components that make egress HTTPS +calls. Typically, Operators mount the ConfigMap to +`/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem`, but this is not required by +the proxy. A proxy can modify or inspect the HTTPS connection. In either case, +the proxy must generate and sign a new certificate for the connection. + +Complete proxy support means connecting to the specified proxy and trusting any +signatures it has generated. Therefore, it is necessary to let the user specify +a trusted root, such that any certificate chain connected to that trusted root +is also trusted. + +If using the RHCOS trust bundle, place CA certificates in +`/etc/pki/ca-trust/source/anchors`. + +See +link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/using-shared-system-certificates_security-hardening[Using +shared system certificates] in the Red Hat Enterprise Linux documentation for +more information. + +[discrete] +== Expiration + +The user sets the expiration term of the user-provided trust bundle. + +The default expiration term is defined by the CA certificate itself. It is up to +the CA administrator to configure this for the certificate before it can be used +by {product-title} or {op-system}. + +[NOTE] +==== +Red Hat does not monitor for when CAs expire. However, due to the long life of +CAs, this is generally not an issue. However, you might need to periodically +update the trust bundle. +==== + +[discrete] +== Services + +By default, all platform components that make egress HTTPS calls will use the +{op-system} trust bundle. If `trustedCA` is defined, it will also be used. + +Any service that is running on the {op-system} node is able to use the trust bundle of +the node. + +[discrete] +== Management + +These certificates are managed by the system and not the user. + +[discrete] +== Customization + +Updating the user-provided trust bundle consists of either: + +* updating the PEM-encoded certificates in the ConfigMap referenced by +`trustedCA,` or +* creating a ConfigMap in the namespace `openshift-config` that contains the new +trust bundle and updating `trustedCA` to reference the name of the new +ConfigMap. + +The mechanism for writing CA certificates to the {op-system} trust bundle is exactly +the same as writing any other file to {op-system}, which is done through the use of +MachineConfigs. When the Machine Config Operator (MCO) applies the new +MachineConfig that contains the new CA certificates, the node is rebooted. +During the next boot, the service `coreos-update-ca-trust.service` runs on the +{op-system} nodes, which automatically update the trust bundle with the new CA +certificates. For example: + +[source,yaml] +---- +apiVersion: machineconfiguration.openshift.io/v1 +kind: MachineConfig +metadata: + labels: + machineconfiguration.openshift.io/role: worker + name: 50-examplecorp-ca-cert +spec: + config: + ignition: + version: 2.2.0 + storage: + files: + - contents: + source: data:text/plain;charset=utf-8;base64,LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVORENDQXh5Z0F3SUJBZ0lKQU51bkkwRDY2MmNuTUEwR0NTcUdTSWIzRFFFQkN3VUFNSUdsTVFzd0NRWUQKV1FRR0V3SlZVekVYTUJVR0ExVUVDQXdPVG05eWRHZ2dRMkZ5YjJ4cGJtRXhFREFPQmdOVkJBY01CMUpoYkdWcApBMmd4RmpBVUJnTlZCQW9NRFZKbFpDQklZWFFzSUVsdVl5NHhFekFSQmdOVkJBc01DbEpsWkNCSVlYUWdTVlF4Ckh6QVpCZ05WQkFNTUVsSmxaQ0JJWVhRZ1NWUWdVbTl2ZENCRFFURWhNQjhHQ1NxR1NJYjNEUUVKQVJZU2FXNW0KWGpDQnBURUxNQWtHQTFVRUJoTUNWVk14RnpBVkJnTlZCQWdNRGs1dmNuUm9JRU5oY205c2FXNWhNUkF3RGdZRApXUVFIREFkU1lXeGxhV2RvTVJZd0ZBWURWUVFLREExU1pXUWdTR0YwTENCSmJtTXVNUk13RVFZRFZRUUxEQXBTCkFXUWdTR0YwSUVsVU1Sc3dHUVlEVlFRRERCSlNaV1FnU0dGMElFbFVJRkp2YjNRZ1EwRXhJVEFmQmdrcWhraUcKMHcwQkNRRVdFbWx1Wm05elpXTkFjbVZrYUdGMExtTnZiVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUApCRENDQVFvQ2dnRUJBTFF0OU9KUWg2R0M1TFQxZzgwcU5oMHU1MEJRNHNaL3laOGFFVHh0KzVsblBWWDZNSEt6CmQvaTdsRHFUZlRjZkxMMm55VUJkMmZRRGsxQjBmeHJza2hHSUlaM2lmUDFQczRsdFRrdjhoUlNvYjNWdE5xU28KSHhrS2Z2RDJQS2pUUHhEUFdZeXJ1eTlpckxaaW9NZmZpM2kvZ0N1dDBaV3RBeU8zTVZINXFXRi9lbkt3Z1BFUwpZOXBvK1RkQ3ZSQi9SVU9iQmFNNzYxRWNyTFNNMUdxSE51ZVNmcW5obzNBakxRNmRCblBXbG82MzhabTFWZWJLCkNFTHloa0xXTVNGa0t3RG1uZTBqUTAyWTRnMDc1dkNLdkNzQ0F3RUFBYU5qTUdFd0hRWURWUjBPQkJZRUZIN1IKNXlDK1VlaElJUGV1TDhacXczUHpiZ2NaTUI4R0ExVWRJd1FZTUJhQUZIN1I0eUMrVWVoSUlQZXVMOFpxdzNQegpjZ2NaTUE4R0ExVWRFd0VCL3dRRk1BTUJBZjh3RGdZRFZSMFBBUUgvQkFRREFnR0dNQTBHQ1NxR1NJYjNEUUVCCkR3VUFBNElCQVFCRE52RDJWbTlzQTVBOUFsT0pSOCtlbjVYejloWGN4SkI1cGh4Y1pROGpGb0cwNFZzaHZkMGUKTUVuVXJNY2ZGZ0laNG5qTUtUUUNNNFpGVVBBaWV5THg0ZjUySHVEb3BwM2U1SnlJTWZXK0tGY05JcEt3Q3NhawpwU29LdElVT3NVSks3cUJWWnhjckl5ZVFWMnFjWU9lWmh0UzV3QnFJd09BaEZ3bENFVDdaZTU4UUhtUzQ4c2xqCjVlVGtSaml2QWxFeHJGektjbGpDNGF4S1Fsbk92VkF6eitHbTMyVTB4UEJGNEJ5ZVBWeENKVUh3MVRzeVRtZWwKU3hORXA3eUhvWGN3bitmWG5hK3Q1SldoMWd4VVp0eTMKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo= + filesystem: root + mode: 0644 + path: /etc/pki/ca-trust/source/anchors/examplecorp-ca.crt +---- + +The trust store of machines must also support updating the trust store of nodes. + +[discrete] +== Renewal + +There are no Operators that can auto-renew certificates on the {op-system} nodes. + +[NOTE] +==== +Red Hat does not monitor for when CAs expire. However, due to the long life of +CAs, this is generally not an issue. However, you might need to periodically +update the trust bundle. +==== diff --git a/modules/service-ca-certificates.adoc b/modules/service-ca-certificates.adoc new file mode 100644 index 0000000000..4033712698 --- /dev/null +++ b/modules/service-ca-certificates.adoc @@ -0,0 +1,83 @@ +// Module included in the following assemblies: +// +// * authentication/certificate-types-descriptions.adoc + +[id="service-ca-certificates_{context}"] += Service CA certificates + +[discrete] +== Purpose + +`service-ca` is an Operator that creates a self-signed CA when an +{product-title} cluster is deployed. + +[discrete] +== Expiration + +A custom expiration term is not supported. The self-signed CA is stored in a +secret with qualified name `service-ca/signing-key` in fields `tls.crt` +(certificate(s)), `tls.key` (private key), and `ca-bundle.crt` (CA bundle). + +Other services can request a service serving certificate by annotating a +service resource with `service.beta.openshift.io/serving-cert-secret-name: +`. In response, the Operator generates a new certificate, as +`tls.crt`, and private key, as `tls.key` to the named secret. The certificate +is valid for two years. + +Other services can request that the CA bundle for the service CA be injected +into APIService or ConfigMap resources by annotating with +`service.beta.openshift.io/inject-cabundle: true` to support validating +certificates generated from the service CA. In response, the Operator writes its +current CA bundle to the `CABundle` field of APIService or as `service-ca.crt` +to a ConfigMap. + +As of {product-title} 4.3.5, automated rotation is supported and is backported +to some 4.2.z and 4.3.z releases. For any release supporting automated rotation, +the service CA is valid for 26 months and is automatically refreshed when there +is less than 13 months validity left. If necessary, you can manually refresh +the service CA. + +The service CA expiration of 26 months is longer than the expected upgrade +interval for a supported {product-title} cluster, such that non-control plane +consumers of service CA certificates will be refreshed after CA rotation and +prior to the expiration of the pre-rotation CA. + +[WARNING] +==== +A manually-rotated service CA does not maintain trust with the previous service +CA. You might experience a temporary service disruption until the Pods in the +cluster are restarted, which ensures that Pods are using service serving +certificates issued by the new service CA. +==== + +[discrete] +== Management + +These certificates are managed by the system and not the user. + +[discrete] +== Services + +Services that use service CA certificates include: + +* cluster-autoscaler-operator +* cluster-monitoring-operator +* cluster-authentication-operator +* cluster-image-registry-operator +* cluster-ingress-operator +* cluster-kube-apiserver-operator +* cluster-kube-controller-manager-operator +* cluster-kube-scheduler-operator +* cluster-networking-operator +* cluster-openshift-apiserver-operator +* cluster-openshift-controller-manager-operator +* cluster-samples-operator +* cluster-svcat-apiserver-operator +* cluster-svcat-controller-manager-operator +* machine-config-operator +* console-operator +* insights-operator +* machine-api-operator +* operator-lifecycle-manager + +This is not a comprehensive list. diff --git a/modules/user-provided-certificates-for-api-server.adoc b/modules/user-provided-certificates-for-api-server.adoc new file mode 100644 index 0000000000..f8cfacdf95 --- /dev/null +++ b/modules/user-provided-certificates-for-api-server.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// *authentication/certificate-types-descriptions.adoc + +[id="user-provided-certificates-for-the-api-server_{context}"] += User-provided certificates for the API server + +[discrete] +== Purpose + +The API server is accessible by clients external to the cluster at +`api..`. You might want clients to access the API +server at a different host name or without the need to distribute the +cluster-managed certificate authority (CA) certificates to the clients. The +administrator must set a custom default certificate to be used by the API server +when serving content. + +[discrete] +== Location + +The user-provided certificates must be provided in a `kubernetes.io/tls` type +`Secret` in the `openshift-config` namespace. Update the API server cluster +configuration, the `apiserver/cluster` resource, to enable the use of the +user-provided certificate. + +[discrete] +== Management + +User-provided certificates are managed by the user. + +[discrete] +== Expiration + +User-provided certificates are managed by the user. + +[discrete] +== Customization + +Update the secret containing the user-managed certificate as needed. diff --git a/modules/user-provided-certificates-for-default-ingress.adoc b/modules/user-provided-certificates-for-default-ingress.adoc new file mode 100644 index 0000000000..67cf1c82fa --- /dev/null +++ b/modules/user-provided-certificates-for-default-ingress.adoc @@ -0,0 +1,53 @@ +// Module included in the following assemblies: +// +// * authentication/certificate-types-descriptions.adoc + +[id="user-provided-certificates-for-default-ingress_{context}"] += User-provided certificates for default ingress + +[discrete] +== Purpose + +Applications are usually exposed at +`.apps..`. For example, +`myapp.apps.mycluster.example.com`. You might want clients to access the +applications without the need to distribute the cluster-managed CA certificates +to the clients. The administrator must set a custom default certificate when +serving application content. + +[WARNING] +==== +The Ingress Operator generates a default certificate for an Ingress Controller +to serve as a placeholder until you configure a custom default certificate. Do +not use operator-generated default certificates in production clusters. +==== + +[discrete] +== Location + +The user-provided certificates must be provided in a `kubernetes.io/tls` type +`Secret` in the `openshift-config` namespace. Update the +`ingresscontroller.operator/default` resource in the +`openshift-ingress-operator` namespace to enable the use of the user-provided +certificate. + +[discrete] +== Management + +User-provided certificates are managed by the user. + +[discrete] +== Expiration + +User-provided certificates are managed by the user. + +[discrete] +== Services + +Applications deployed on the cluster use user-provided certificates for default +ingress. + +[discrete] +== Customization + +Update the secret containing the user-managed certificate as needed.