openshift-docs/authentication/certificate-types-descriptions.adoc

[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]
== Workflow

.Custom certificate workflow

image::custom_4.5.png[custom ingress certificate workflow]


.Default certificate workflow

image::default_4.5.png[default ingress certificate workflow]

image:darkcircle-0.png[20,20] An empty `defaultCertificate` field causes the Ingress Operator to use its self-signed CA to generate a serving certificate for the specified domain.

image:darkcircle-1.png[20,20] The default CA certificate and key generated by the Ingress Operator. Used to sign Operator-generated default serving certificates.

image:darkcircle-2.png[20,20] In the default workflow, the wildcard default serving certificate, created by the Ingress Operator and signed using the generated default CA certificate. In the custom workflow, this is the user-provided certificate.

image:darkcircle-3.png[20,20] The router deployment. Uses the certificate in `secrets/router-certs-default` as its default front-end server certificate.

image:darkcircle-4.png[20,20] In the default workflow, the contents of the wildcard default serving certificate (public and private parts) are copied here to enable OAuth integration. In the custom workflow, this is the user-provided certificate.

image:darkcircle-5.png[20,20] The public (certificate) part of the default serving certificate. Replaces the `configmaps/router-ca` resource.

image:darkcircle-6.png[20,20] The user updates the cluster proxy configuration with the CA certificate that signed the `ingresscontroller` serving certificate. This enables components like `auth`, `console`, and the registry to trust the serving certificate.

image:darkcircle-7.png[20,20] The cluster-wide trusted CA bundle containing the combined {op-system-first} and user-provided CA bundles or an {op-system}-only bundle if a user bundle is not provided.

image:darkcircle-8.png[20,20] The custom CA certificate bundle, which instructs other components (for example, `auth` and `console`) to trust an `ingresscontroller` configured with a custom certificate.

image:darkcircle-9.png[20,20] The `trustedCA` field is used to reference the user-provided CA bundle.

image:darkcircle-10.png[20,20] The Cluster Network Operator injects the trusted CA bundle into the `proxy-ca` ConfigMap.

image:darkcircle-11.png[20,20] {product-title} {product-version} and newer use `default-ingress-cert`.

[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]