Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

Chapter 3. Configuring certificates


3.1. Replacing the default ingress certificate

3.1.1. Understanding the default ingress certificate

By default, OpenShift Container Platform uses the Ingress Operator to create an internal CA and issue a wildcard certificate that is valid for applications under the

.apps
sub-domain. Both the web console and CLI use this certificate as well.

The internal infrastructure CA certificates are self-signed. While this process might be perceived as bad practice by some security or PKI teams, any risk here is minimal. The only clients that implicitly trust these certificates are other components within the cluster. Replacing the default wildcard certificate with one that is issued by a public CA already included in the CA bundle as provided by the container userspace allows external clients to connect securely to applications running under the

.apps
sub-domain.

3.1.2. Replacing the default ingress certificate

You can replace the default ingress certificate for all applications under the

.apps
subdomain. After you replace the certificate, all applications, including the web console and CLI, have encryption provided by the specified certificate.

Prerequisites

  • You must have a wildcard certificate for the fully qualified
    .apps
    subdomain and its corresponding private key. Each should be in a separate PEM format file.
  • The private key must be unencrypted. If your key is encrypted, decrypt it before importing it into OpenShift Container Platform.
  • The certificate must include the
    subjectAltName
    extension showing
    *.apps.<clustername>.<domain>
    .
  • The certificate file can contain one or more certificates in a chain. The file must list the wildcard certificate as the first certificate, followed by other intermediate certificates, and then ending with the root CA certificate.
  • Copy the root CA certificate into an additional PEM format file.
  • Verify that all certificates which include
    -----END CERTIFICATE-----
    also end with one carriage return after that line.

Procedure

  1. Create a config map that includes only the root CA certificate that is used to sign the wildcard certificate:

    $ oc create configmap custom-ca \
         --from-file=ca-bundle.crt=</path/to/example-ca.crt> \
    1
    
         -n openshift-config
    1
    </path/to/example-ca.crt> is the path to the root CA certificate file on your local file system. For example, /etc/pki/ca-trust/source/anchors.
  2. Update the cluster-wide proxy configuration with the newly created config map:

    $ oc patch proxy/cluster \
         --type=merge \
         --patch='{"spec":{"trustedCA":{"name":"custom-ca"}}}'
    Note

    If you update only the trusted CA for your cluster, the MCO updates the

    /etc/pki/ca-trust/source/anchors/openshift-config-user-ca-bundle.crt
    file and the Machine Config Controller (MCC) applies the trusted CA update to each node so that a node reboot is not required. However, with these changes, the Machine Config Daemon (MCD) restarts critical services on each node, such as kubelet and CRI-O. These service restarts cause each node to briefly enter the
    NotReady
    state until the service is fully restarted.

    If you change any other parameter in the

    openshift-config-user-ca-bundle.crt
    file, such as
    noproxy
    , the MCO reboots each node in your cluster.

  3. Create a secret that contains the wildcard certificate chain and key:

    $ oc create secret tls <secret> \
    1
    
         --cert=</path/to/cert.crt> \
    2
    
         --key=</path/to/cert.key> \
    3
    
         -n openshift-ingress
    1
    <secret> is the name of the secret that will contain the certificate chain and private key.
    2
    </path/to/cert.crt> is the path to the certificate chain on your local file system.
    3
    </path/to/cert.key> is the path to the private key associated with this certificate.
  4. Update the Ingress Controller configuration with the newly created secret:

    $ oc patch ingresscontroller.operator default \
         --type=merge -p \
         '{"spec":{"defaultCertificate": {"name": "<secret>"}}}' \
    1
    
         -n openshift-ingress-operator
    1
    Replace <secret> with the name used for the secret in the previous step.
    Important

    To trigger the Ingress Operator to perform a rolling update, you must update the name of the secret. Because the kubelet automatically propagates changes to the secret in the volume mount, updating the secret contents does not trigger a rolling update. For more information, see this Red Hat Knowledgebase Solution.

3.2. Adding API server certificates

The default API server certificate is issued by an internal OpenShift Container Platform cluster CA. Clients outside of the cluster will not be able to verify the API server’s certificate by default. This certificate can be replaced by one that is issued by a CA that clients trust.

Note

In hosted control plane clusters, you cannot replace self-signed certificates from the API.

3.2.1. Add an API server named certificate

The default API server certificate is issued by an internal OpenShift Container Platform cluster CA. You can add one or more alternative certificates that the API server will return based on the fully qualified domain name (FQDN) requested by the client, for example when a reverse proxy or load balancer is used.

Prerequisites

  • You must have a certificate for the FQDN and its corresponding private key. Each should be in a separate PEM format file.
  • The private key must be unencrypted. If your key is encrypted, decrypt it before importing it into OpenShift Container Platform.
  • The certificate must include the
    subjectAltName
    extension showing the FQDN.
  • The certificate file can contain one or more certificates in a chain. The certificate for the API server FQDN must be the first certificate in the file. It can then be followed with any intermediate certificates, and the file should end with the root CA certificate.
Warning

Do not provide a named certificate for the internal load balancer (host name

api-int.<cluster_name>.<base_domain>
). Doing so will leave your cluster in a degraded state.

Procedure

  1. Login to the new API as the

    kubeadmin
    user.

    $ oc login -u kubeadmin -p <password> https://FQDN:6443
  2. Get the

    kubeconfig
    file.

    $ oc config view --flatten > kubeconfig-newapi
  3. Create a secret that contains the certificate chain and private key in the

    openshift-config
    namespace.

    $ oc create secret tls <secret> \
    1
    
         --cert=</path/to/cert.crt> \
    2
    
         --key=</path/to/cert.key> \
    3
    
         -n openshift-config
    1
    <secret> is the name of the secret that will contain the certificate chain and private key.
    2
    </path/to/cert.crt> is the path to the certificate chain on your local file system.
    3
    </path/to/cert.key> is the path to the private key associated with this certificate.
  4. Update the API server to reference the created secret.

    $ oc patch apiserver cluster \
         --type=merge -p \
         '{"spec":{"servingCerts": {"namedCertificates":
         [{"names": ["<FQDN>"],
         "servingCertificate": {"name": "<secret>"}}]}}}'

    where:

    <FQDN>
    Replace <FQDN> with the FQDN that the API server should provide the certificate for. Do not include the port number.
    <secret>
    Replace <secret> with the name used for the secret in the previous step.
  5. Examine the

    apiserver/cluster
    object and confirm the secret is now referenced.

    $ oc get apiserver cluster -o yaml

    Example output

    ...
    spec:
      servingCerts:
        namedCertificates:
        - names:
          - <FQDN>
          servingCertificate:
            name: <secret>
    ...

  6. Check the

    kube-apiserver
    operator, and verify that a new revision of the Kubernetes API server rolls out. It may take a minute for the operator to detect the configuration change and trigger a new deployment. While the new revision is rolling out,
    PROGRESSING
    will report
    True
    .

    $ oc get clusteroperators kube-apiserver

    Do not continue to the next step until

    PROGRESSING
    is listed as
    False
    , as shown in the following output:

    Example output

    NAME             VERSION   AVAILABLE   PROGRESSING   DEGRADED   SINCE
    kube-apiserver   4.14.0     True        False         False      145m

    If

    PROGRESSING
    is showing
    True
    , wait a few minutes and try again.

    Note

    A new revision of the Kubernetes API server only rolls out if the API server named certificate is added for the first time. When the API server named certificate is renewed, a new revision of the Kubernetes API server does not roll out because the

    kube-apiserver
    pods dynamically reload the updated certificate.

3.3. Securing service traffic using service serving certificate secrets

3.3.1. Understanding service serving certificates

Service serving certificates are intended to support complex middleware applications that require encryption. These certificates are issued as TLS web server certificates.

The

service-ca
controller uses the
x509.SHA256WithRSA
signature algorithm to generate service certificates.

The generated certificate and key are in PEM format, stored in

tls.crt
and
tls.key
respectively, within a created secret. The certificate and key are automatically replaced when they get close to expiration.

The service CA certificate, which issues the service certificates, is valid for 26 months and is automatically rotated when there is less than 13 months validity left. After rotation, the previous service CA configuration is still trusted until its expiration. This allows a grace period for all affected services to refresh their key material before the expiration. If you do not upgrade your cluster during this grace period, which restarts services and refreshes their key material, you might need to manually restart services to avoid failures after the previous service CA expires.

Note

You can use the following command to manually restart all pods in the cluster. Be aware that running this command causes a service interruption, because it deletes every running pod in every namespace. These pods will automatically restart after they are deleted.

$ for I in $(oc get ns -o jsonpath='{range .items[*]} {.metadata.name}{"\n"} {end}'); \
      do oc delete pods --all -n $I; \
      sleep 1; \
      done

3.3.2. Add a service certificate

To secure communication to your service, generate a signed serving certificate and key pair into a secret in the same namespace as the service.

The generated certificate is only valid for the internal service DNS name

<service.name>.<service.namespace>.svc
, and is only valid for internal communications. If your service is a headless service (no
clusterIP
value set), the generated certificate also contains a wildcard subject in the format of
*.<service.name>.<service.namespace>.svc
.

Important

Because the generated certificates contain wildcard subjects for headless services, you must not use the service CA if your client must differentiate between individual pods. In this case:

  • Generate individual TLS certificates by using a different CA.
  • Do not accept the service CA as a trusted CA for connections that are directed to individual pods and must not be impersonated by other pods. These connections must be configured to trust the CA that was used to generate the individual TLS certificates.

Prerequisites

  • You must have a service defined.

Procedure

  1. Annotate the service with

    service.beta.openshift.io/serving-cert-secret-name
    :

    $ oc annotate service <service_name> \
    1
    
         service.beta.openshift.io/serving-cert-secret-name=<secret_name> 
    2
    1
    Replace <service_name> with the name of the service to secure.
    2
    <secret_name> will be the name of the generated secret containing the certificate and key pair.
    Note

    For convenience, it is recommended that this value be the same as

    <service_name>
    .

    For example, use the following command to annotate the service

    test1
    :

    $ oc annotate service test1 service.beta.openshift.io/serving-cert-secret-name=test1
  2. Examine the service to confirm that the annotations are present:

    $ oc describe service <service_name>

    Example output

    ...
    Annotations:              service.beta.openshift.io/serving-cert-secret-name: <service_name>
                              service.beta.openshift.io/serving-cert-signed-by: openshift-service-serving-signer@1556850837
    ...

  3. After the cluster generates a secret for your service, your
    Pod
    spec can mount it, and the pod will run after it becomes available.

3.3.3. Add the service CA bundle to a config map

A pod can access the service Certificate Authority (CA) certificate by mounting a

ConfigMap
object that has the
service.beta.openshift.io/inject-cabundle=true
annotation. After annotating the config map, the cluster automatically injects the service CA certificate into the
service-ca.crt
key on the config map. Access to this CA certificate allows TLS clients to verify connections to services by using service serving certificates.

Important

After adding this annotation to a config map, the OpenShift Service CA Operator deletes all the data in the config map. Consider using a separate config map to contain the

service-ca.crt
, instead of using the same config map that stores your pod configuration.

Procedure

  1. Annotate the config map with the

    service.beta.openshift.io/inject-cabundle=true
    annotation by entering the following command:

    $ oc annotate configmap <config_map_name> \
    1
    
         service.beta.openshift.io/inject-cabundle=true
    1
    Replace <config_map_name> with the name of the config map to annotate.
    Note

    Explicitly referencing the

    service-ca.crt
    key in a volume mount prevents a pod from starting until the config map has been injected with the CA bundle. You can override this behavior by setting the
    optional
    parameter to
    true
    in the serving certificate configuration of the volume.

  2. View the config map to ensure that the service CA bundle has been injected:

    $ oc get configmap <config_map_name> -o yaml

    The CA bundle is displayed as the value of the

    service-ca.crt
    key in the YAML output:

    apiVersion: v1
    data:
      service-ca.crt: |
        -----BEGIN CERTIFICATE-----
    ...
  3. Mount the config map as a volume to each container that exists in a pod by configuring your

    Deployment
    object.

    Example Deployment object that defines the volume for the mounted config map

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: my-example-custom-ca-deployment
      namespace: my-example-custom-ca-ns
    spec:
      ...
        spec:
          ...
          containers:
            - name: my-container-that-needs-custom-ca
              volumeMounts:
              - name: trusted-ca
                mountPath: /etc/pki/ca-trust/extracted/pem
                readOnly: true
          volumes:
          - name: trusted-ca
            configMap:
              name: <config_map_name> 
    1
    
              items:
                - key: ca-bundle.crt 
    2
    
                  path: tls-ca-bundle.pem 
    3
    
    # ...

    1
    Specify the name of the config map that you annotated in an earlier step of the procedure.
    2
    ca-bundle.crt is required as the ConfigMap key.
    3
    tls-ca-bundle.pem is required as the ConfigMap path.

3.3.4. Add the service CA bundle to an API service

You can annotate an

APIService
object with
service.beta.openshift.io/inject-cabundle=true
to have its
spec.caBundle
field populated with the service CA bundle. This allows the Kubernetes API server to validate the service CA certificate used to secure the targeted endpoint.

Procedure

  1. Annotate the API service with

    service.beta.openshift.io/inject-cabundle=true
    :

    $ oc annotate apiservice <api_service_name> \
    1
    
         service.beta.openshift.io/inject-cabundle=true
    1
    Replace <api_service_name> with the name of the API service to annotate.

    For example, use the following command to annotate the API service

    test1
    :

    $ oc annotate apiservice test1 service.beta.openshift.io/inject-cabundle=true
  2. View the API service to ensure that the service CA bundle has been injected:

    $ oc get apiservice <api_service_name> -o yaml

    The CA bundle is displayed in the

    spec.caBundle
    field in the YAML output:

    apiVersion: apiregistration.k8s.io/v1
    kind: APIService
    metadata:
      annotations:
        service.beta.openshift.io/inject-cabundle: "true"
    ...
    spec:
      caBundle: <CA_BUNDLE>
    ...

3.3.5. Add the service CA bundle to a custom resource definition

You can annotate a

CustomResourceDefinition
(CRD) object with
service.beta.openshift.io/inject-cabundle=true
to have its
spec.conversion.webhook.clientConfig.caBundle
field populated with the service CA bundle. This allows the Kubernetes API server to validate the service CA certificate used to secure the targeted endpoint.

Note

The service CA bundle will only be injected into the CRD if the CRD is configured to use a webhook for conversion. It is only useful to inject the service CA bundle if a CRD’s webhook is secured with a service CA certificate.

Procedure

  1. Annotate the CRD with

    service.beta.openshift.io/inject-cabundle=true
    :

    $ oc annotate crd <crd_name> \
    1
    
         service.beta.openshift.io/inject-cabundle=true
    1
    Replace <crd_name> with the name of the CRD to annotate.

    For example, use the following command to annotate the CRD

    test1
    :

    $ oc annotate crd test1 service.beta.openshift.io/inject-cabundle=true
  2. View the CRD to ensure that the service CA bundle has been injected:

    $ oc get crd <crd_name> -o yaml

    The CA bundle is displayed in the

    spec.conversion.webhook.clientConfig.caBundle
    field in the YAML output:

    apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    metadata:
      annotations:
        service.beta.openshift.io/inject-cabundle: "true"
    ...
    spec:
      conversion:
        strategy: Webhook
        webhook:
          clientConfig:
            caBundle: <CA_BUNDLE>
    ...

3.3.6. Add the service CA bundle to a mutating webhook configuration

You can annotate a

MutatingWebhookConfiguration
object with
service.beta.openshift.io/inject-cabundle=true
to have the
clientConfig.caBundle
field of each webhook populated with the service CA bundle. This allows the Kubernetes API server to validate the service CA certificate used to secure the targeted endpoint.

Note

Do not set this annotation for admission webhook configurations that need to specify different CA bundles for different webhooks. If you do, then the service CA bundle will be injected for all webhooks.

Procedure

  1. Annotate the mutating webhook configuration with

    service.beta.openshift.io/inject-cabundle=true
    :

    $ oc annotate mutatingwebhookconfigurations <mutating_webhook_name> \
    1
    
         service.beta.openshift.io/inject-cabundle=true
    1
    Replace <mutating_webhook_name> with the name of the mutating webhook configuration to annotate.

    For example, use the following command to annotate the mutating webhook configuration

    test1
    :

    $ oc annotate mutatingwebhookconfigurations test1 service.beta.openshift.io/inject-cabundle=true
  2. View the mutating webhook configuration to ensure that the service CA bundle has been injected:

    $ oc get mutatingwebhookconfigurations <mutating_webhook_name> -o yaml

    The CA bundle is displayed in the

    clientConfig.caBundle
    field of all webhooks in the YAML output:

    apiVersion: admissionregistration.k8s.io/v1
    kind: MutatingWebhookConfiguration
    metadata:
      annotations:
        service.beta.openshift.io/inject-cabundle: "true"
    ...
    webhooks:
    - myWebhook:
      - v1beta1
      clientConfig:
        caBundle: <CA_BUNDLE>
    ...

3.3.7. Add the service CA bundle to a validating webhook configuration

You can annotate a

ValidatingWebhookConfiguration
object with
service.beta.openshift.io/inject-cabundle=true
to have the
clientConfig.caBundle
field of each webhook populated with the service CA bundle. This allows the Kubernetes API server to validate the service CA certificate used to secure the targeted endpoint.

Note

Do not set this annotation for admission webhook configurations that need to specify different CA bundles for different webhooks. If you do, then the service CA bundle will be injected for all webhooks.

Procedure

  1. Annotate the validating webhook configuration with

    service.beta.openshift.io/inject-cabundle=true
    :

    $ oc annotate validatingwebhookconfigurations <validating_webhook_name> \
    1
    
         service.beta.openshift.io/inject-cabundle=true
    1
    Replace <validating_webhook_name> with the name of the validating webhook configuration to annotate.

    For example, use the following command to annotate the validating webhook configuration

    test1
    :

    $ oc annotate validatingwebhookconfigurations test1 service.beta.openshift.io/inject-cabundle=true
  2. View the validating webhook configuration to ensure that the service CA bundle has been injected:

    $ oc get validatingwebhookconfigurations <validating_webhook_name> -o yaml

    The CA bundle is displayed in the

    clientConfig.caBundle
    field of all webhooks in the YAML output:

    apiVersion: admissionregistration.k8s.io/v1
    kind: ValidatingWebhookConfiguration
    metadata:
      annotations:
        service.beta.openshift.io/inject-cabundle: "true"
    ...
    webhooks:
    - myWebhook:
      - v1beta1
      clientConfig:
        caBundle: <CA_BUNDLE>
    ...

3.3.8. Manually rotate the generated service certificate

You can rotate the service certificate by deleting the associated secret. Deleting the secret results in a new one being automatically created, resulting in a new certificate.

Prerequisites

  • A secret containing the certificate and key pair must have been generated for the service.

Procedure

  1. Examine the service to determine the secret containing the certificate. This is found in the

    serving-cert-secret-name
    annotation, as seen below.

    $ oc describe service <service_name>

    Example output

    ...
    service.beta.openshift.io/serving-cert-secret-name: <secret>
    ...

  2. Delete the generated secret for the service. This process will automatically recreate the secret.

    $ oc delete secret <secret> 
    1
    1
    Replace <secret> with the name of the secret from the previous step.
  3. Confirm that the certificate has been recreated by obtaining the new secret and examining the

    AGE
    .

    $ oc get secret <service_name>

    Example output

    NAME              TYPE                DATA   AGE
    <service.name>    kubernetes.io/tls   2      1s

3.3.9. Manually rotate the service CA certificate

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 by using the following procedure.

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.

Prerequisites

  • You must be logged in as a cluster admin.

Procedure

  1. View the expiration date of the current service CA certificate by using the following command.

    $ oc get secrets/signing-key -n openshift-service-ca \
         -o template='{{index .data "tls.crt"}}' \
         | base64 --decode \
         | openssl x509 -noout -enddate
  2. Manually rotate the service CA. This process generates a new service CA which will be used to sign the new service certificates.

    $ oc delete secret/signing-key -n openshift-service-ca
  3. To apply the new certificates to all services, restart all the pods in your cluster. This command ensures that all services use the updated certificates.

    $ for I in $(oc get ns -o jsonpath='{range .items[*]} {.metadata.name}{"\n"} {end}'); \
          do oc delete pods --all -n $I; \
          sleep 1; \
          done
    Warning

    This command will cause a service interruption, as it goes through and deletes every running pod in every namespace. These pods will automatically restart after they are deleted.

3.4. Updating the CA bundle

3.4.1. Understanding the CA Bundle certificate

Proxy certificates allow users to specify one or more custom certificate authority (CA) used by platform components when making egress connections.

The

trustedCA
field of the Proxy object is a reference to a config map that contains a user-provided trusted certificate authority (CA) bundle. This bundle is merged with the Red Hat Enterprise Linux CoreOS (RHCOS) 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 RHCOS trust bundle is used for proxied HTTPS connections. Provide custom CA certificates to the RHCOS 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 config map named
trusted-ca-bundle
in the
openshift-config-managed
namespace. The namespace for the config map referenced by
trustedCA
is
openshift-config
:

apiVersion: v1
kind: ConfigMap
metadata:
  name: user-ca-bundle
  namespace: openshift-config
data:
  ca-bundle.crt: |
    -----BEGIN CERTIFICATE-----
    Custom CA certificate bundle.
    -----END CERTIFICATE-----

3.4.2. Replacing the CA Bundle certificate

Procedure

  1. Create a config map that includes the root CA certificate used to sign the wildcard certificate:

    $ oc create configmap custom-ca \
         --from-file=ca-bundle.crt=</path/to/example-ca.crt> \
    1
    
         -n openshift-config
    1
    </path/to/example-ca.crt> is the path to the CA certificate bundle on your local file system.
  2. Update the cluster-wide proxy configuration with the newly created config map:

    $ oc patch proxy/cluster \
         --type=merge \
         --patch='{"spec":{"trustedCA":{"name":"custom-ca"}}}'
Red Hat logoGithubredditYoutubeTwitter

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Wir helfen Red Hat Benutzern, mit unseren Produkten und Diensten innovativ zu sein und ihre Ziele zu erreichen – mit Inhalten, denen sie vertrauen können. Entdecken Sie unsere neuesten Updates.

Mehr Inklusion in Open Source

Red Hat hat sich verpflichtet, problematische Sprache in unserem Code, unserer Dokumentation und unseren Web-Eigenschaften zu ersetzen. Weitere Einzelheiten finden Sie in Red Hat Blog.

Über Red Hat

Wir liefern gehärtete Lösungen, die es Unternehmen leichter machen, plattform- und umgebungsübergreifend zu arbeiten, vom zentralen Rechenzentrum bis zum Netzwerkrand.

Theme

© 2026 Red Hat
Nach oben