Adding certificate docs

_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

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-<name>`,
+where `<name>` 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-<name>` (where `<name>` 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 <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]

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.

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.

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.

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.