Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 5. Use custom CA certificates

If containers communicate with services secured by a private Certificate Authority (CA), you must add the root CA certificates to the container image. This ensures that the container can verify the identity of internal endpoints and establish secure, encrypted TLS connections.

In OpenSSL-based container images, such as curl and nginx, you can make your custom root Certificate Authority (CA) certificates available to the image. Your application can then establish secure TLS connections to services that use certificates signed by your company’s CA.

Use the Podman volume mount option to override the image’s Certificate Authority (CA) bundle if you require only a custom certificate bundle in an OpenSSL-based image. The application in your image then uses only the custom bundle.

Prerequisites

  • The podman package is installed.
  • You have the CA certificate bundle in PEM format.

Procedure

  • When you start the container, use a bind mount to pass the certificate bundle to the container. For example: 

    $ podman run \
    --rm \
    --volume <path_to_certificate_bundle>.pem:/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem:ro,Z \
    registry.access.redhat.com/hi/<image>
    Important

    This approach replaces the image’s built-in CA certificate bundle. If you require that your container trusts multiple CAs, ensure that all required CA certificates are part of the file that you mount to the container.

If you require only a custom certificate bundle in an OpenSSL-based image, you can use an OpenShift Container Platform ConfigMap to override the image’s Certificate Authority (CA) bundle. The application in your image then uses only the custom bundle.

Prerequisites

  • You have access to OpenShift Container Platform CLI.
  • The cluster administrator added the custom CA bundle to the cluster-wide proxy.
  • You have the permissions to create ConfigMaps and modify Pod specifications in the target namespace.

Procedure

  1. Display the name of the ConfigMap that contains the cluster-wide trusted certificates: 

    $ oc get proxy/cluster -o jsonpath='{.spec.trustedCA.name}'
     
    ca-bundle

  2. Create a YAML configuration file that both requests the cluster-wide CA bundle and defines the volume mount necessary for your application to access it: 

    apiVersion: v1
kind: ConfigMap
metadata:
  name: trusted-ca
  labels:
    config.openshift.io/inject-trusted-cabundle: "true"
---
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: app
    image: registry.access.redhat.com/hi/<image>:latest
    volumeMounts:
    - name: trusted-ca
      mountPath: /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem
      subPath: ca-bundle.crt
      readOnly: true
  volumes:
  - name: trusted-ca
    configMap:
      name: trusted-ca

    This configuration uses the config.openshift.io/inject-trusted-cabundle: "true" label to trigger the automatic injection of the cluster CA bundle into the ConfigMap. The subPath: ca-bundle.crt property mounts the certificate at the path required by OpenSSL.

  3. Apply the configuration: 

    $ oc apply -f <configuration_file>.yaml

If you require only a custom certificate bundle in an OpenSSL-based image, you can use an OpenShift Container Platform ConfigMap to override the image’s Certificate Authority (CA) bundle. The application in your image then uses only the custom bundle.

Prerequisites

  • You have access to OpenShift Container Platform CLI.
  • You have the CA certificate bundle in PEM format.
  • You have the permissions to create ConfigMaps and modify Pod specifications in the target namespace.

Procedure

  1. Create a YAML configuration file that both defines the CA bundle and the volume mount necessary for your application to access it: 

    apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-ca-bundle
data:
  tls-ca-bundle.pem: |
    -----BEGIN CERTIFICATE-----
    <certificate>
    -----END CERTIFICATE-----
    <more_certificates_if_needed>
---
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: app
    image: registry.access.redhat.com/hi/<image>:latest
    volumeMounts:
    - name: custom-ca
      mountPath: /etc/pki/ca-trust/extracted/pem
      readOnly: true
  volumes:
  - name: custom-ca
    configMap:
      name: custom-ca-bundle

  2. Apply the configuration: 

    $ oc apply -f <configuration_file>.yaml

If you require that an OpenSSL-based image trusts both your custom Certificate Authorities (CAs) and the image’s built-in default CAs, create a modified image to add the custom certificates.

Prerequisites

  • The podman package is installed.

Procedure

  1. Create a project directory. For example: 

    $ mkdir ~/project/

  2. Copy the custom CA certificate to your project directory: 

    $ cp <path>/custom-root-ca.pem ~/project/

  3. Create a file named ~/project/Containerfile, that references the Red Hat Hardened Images in the FROM instructions. For example: 

    # Build stage:
FROM registry.access.redhat.com/hi/curl:latest-builder AS builder

# Copy the certificate to the image
COPY custom-root-ca.pem /tmp/

# Temporarily switch to root to add the CA certificate to the truststore
USER root
RUN trust anchor /tmp/custom-root-ca.pem
USER ${CONTAINER_DEFAULT_USER}


# Runtime stage:
# Copy the truststore from the builder image to the runtime image
FROM registry.access.redhat.com/hi/curl:latest
COPY --from=builder /etc/pki/ca-trust/extracted /etc/pki/ca-trust/extracted

  4. Build the custom image: 

    $ podman build -t <image_name> ~/project/

    The -t <image_name> option specifies the name of the image after the build process.

  5. Optional: Display the list of images: 

    $ podman image list
     
    REPOSITORY             TAG     IMAGE ID      CREATED        SIZE
localhost/<image_name> latest  2cd25ce7a7ef  2 minutes ago  51 MB

  6. Create a container that uses the image. For example: 

    $ podman run --rm <image_name>:latest https://intranet.example.com

5.2. Use Python images with custom CA certificates
Copy link

You can make your custom root Certificate Authority (CA) certificates available to Python images. Your application can then establish secure TLS connections to services that use certificates signed by your company’s CA.

Python libraries search for trusted certificates in different locations:

  • The built-in urllib library reads the CAs from the following locations:

    • /etc/pki/tls/cert.pem - the main CA bundle file
    • /etc/pki/tls/certs/ - a directory with hashed certificate symbolic links

  • The third-party requests library only uses the path defined in the REQUESTS_CA_BUNDLE environment variable.

    The requests library is not included in the standard Python image. If you want to use it, you must create a custom image.

Use the Podman volume mount option to override the image’s Certificate Authority (CA) bundle if you require only a custom certificate bundle in a Python image. The application in your image then uses only the custom bundle.

Prerequisites

  • The podman package is installed.
  • You have the CA certificate bundle in PEM format.

Procedure

  • When you start the container, use a bind mount to pass the certificate bundle to the container. For example: 

    $ podman run \
    --rm \
    --volume <path_to_certificate_bundle>.pem:/etc/pki/tls/cert.pem:ro,Z \
    --tmpfs /etc/pki/tls/certs:notmpcopyup \
    --env REQUESTS_CA_BUNDLE=/etc/pki/tls/cert.pem \
    registry.access.redhat.com/hi/python

    This command mounts your CA bundle to the /etc/pki/tls/cert.pem file, sets the $REQUESTS_CA_BUNDLE environment variable to it, and blocks the directory with the hashes by overriding it with an empty tmpfs overlay.

    Important

    This approach replaces the image’s built-in CA certificate bundle. If you require that your container trusts multiple CAs, ensure that all required CA certificates are part of the file that you mount to the container.

If you require only a custom certificate bundle in a Python image, you can use an OpenShift Container Platform ConfigMap to override the image’s Certificate Authority (CA) bundle. The application in your image then uses only the custom bundle.

Prerequisites

  • You have access to OpenShift Container Platform CLI.
  • The cluster administrator added the custom CA bundle to the cluster-wide proxy.
  • You have the permissions to create ConfigMaps and modify Pod specifications in the target namespace.

Procedure

  1. Display the name of the ConfigMap that contains the cluster-wide trusted certificates: 

    $ oc get proxy/cluster -o jsonpath='{.spec.trustedCA.name}'
     
    ca-bundle

  2. Create a YAML configuration file that both defines the CA bundle and the volume mount necessary for your application to access it: 

    apiVersion: v1
kind: ConfigMap
metadata:
  name: trusted-ca
  labels:
    config.openshift.io/inject-trusted-cabundle: "true"
---
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: app
    # Use registry.access.redhat.com/hi/python if you require only urllib
    # Use your custom image with the requests library installed for both libraries
    image: registry.access.redhat.com/hi/python
    env:
    - name: REQUESTS_CA_BUNDLE
      value: /etc/pki/tls/cert.pem
    volumeMounts:
    - name: trusted-ca
      mountPath: /etc/pki/tls/cert.pem
      subPath: ca-bundle.crt
      readOnly: true
    - name: empty-certs
      mountPath: /etc/pki/tls/certs
      readOnly: true
  volumes:
  - name: trusted-ca
    configMap:
      name: trusted-ca
  - name: empty-certs
    emptyDir: {}

  3. Apply the configuration: 

    $ oc apply -f <configuration_file>.yaml

If you require only a custom certificate bundle in a Python image, you can use an OpenShift Container Platform ConfigMap to override the image’s Certificate Authority (CA) bundle. The application in your image then uses only the custom bundle.

Prerequisites

  • You have access to OpenShift Container Platform CLI.
  • You have the CA certificate bundle in PEM format.
  • You have the permissions to create ConfigMaps and modify Pod specifications in the target namespace.

Procedure

  1. Create a YAML configuration file that both defines the CA bundle and the volume mount necessary for your application to access it: 

    apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-ca-bundle
data:
  cert.pem: |
    -----BEGIN CERTIFICATE-----
    <certificate>
    -----END CERTIFICATE-----
    <more_certificates_if_needed>
---
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: app
    # Use registry.access.redhat.com/hi/python if you require only urllib
    # Use your custom image with the requests library installed for both libraries
    image: registry.access.redhat.com/hi/python
    env:
    - name: REQUESTS_CA_BUNDLE
      value: /etc/pki/tls/cert.pem
    volumeMounts:
    - name: custom-ca
      mountPath: /etc/pki/tls/cert.pem
      subPath: cert.pem
      readOnly: true
    - name: empty-certs
      mountPath: /etc/pki/tls/certs
      readOnly: true
  volumes:
  - name: custom-ca
    configMap:
      name: custom-ca-bundle
  - name: empty-certs
    emptyDir: {}

  2. Apply the configuration: 

    $ oc apply -f <configuration_file>.yaml

If you require that a Python image trusts both your custom Certificate Authorities (CAs) and the image’s built-in default CAs, use the Podman volume mount option to mount the custom certificate to the image. The application in your image can then use all these certificates.

Prerequisites

  • The podman package is installed.
  • You have the CA certificate bundle in PEM format.

Procedure

  1. Store the hash of the certificate’s subject name in a temporary environment variable: 

    $ CA_HASH=$(openssl x509 -noout -subject_hash -in <path_to_certificate>.pem)

  2. When you start the container, use a bind mount to pass the certificate to the container. For example: 

    $ podman run \
    --rm \
    --volume <path_to_certificate>.pem:/etc/pki/tls/certs/${CA_HASH}.0:ro,Z \
    --env REQUESTS_CA_BUNDLE=/etc/pki/tls/certs/ \
    registry.access.redhat.com/hi/python

    This command uses the hash in the CA_HASH environment variable to define the destination of the bind mount. Additionally, it sets the REQUESTS_CA_BUNDLE environment variable in the image to the /etc/pki/tls/certs/ directory.

If you require that a Python image trusts both your custom Certificate Authorities (CAs) and the image’s built-in default CAs, use an OpenShift Container Platform ConfigMap to mount the custom certificate to the image. The application in your image can then use all these certificates.

Prerequisites

  • You have access to OpenShift Container Platform CLI.
  • You have the CA certificate bundle in PEM format.
  • You have the permissions to create ConfigMaps and modify Pod specifications in the target namespace.

Procedure

  1. Display the hash of the certificate’s subject name: 

    $ openssl x509 -noout -subject_hash -in <path_to_certificate>.pem
     
    12abc456

    You require the hash when you mount the ConfigMap into the Pod specification.

  2. Create a YAML configuration file that both defines the CA bundle and the volume mount necessary for your application to access it: 

    apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-ca
data:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    <certificate>
    -----END CERTIFICATE-----
    <more_certificates_if_needed>
---
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: app
    # Use registry.access.redhat.com/hi/python if you require only urllib
    # Use your custom image with the requests library installed for both libraries
    image: registry.access.redhat.com/hi/python
    env:
    - name: REQUESTS_CA_BUNDLE
      value: /etc/pki/tls/certs/
    volumeMounts:
    - name: custom-ca
      # Append .0 to the hash
      mountPath: /etc/pki/tls/certs/<hash>.0
      subPath: ca.crt
      readOnly: true
  volumes:
  - name: custom-ca
    configMap:
      name: custom-ca

  3. Apply the configuration: 

    $ oc apply -f <configuration_file>.yaml

5.3. Use Java images with custom CA certificates
Copy link

You can make your custom root Certificate Authority (CA) certificates available to Java images. Your application can then establish secure TLS connections to services that use certificates signed by your company’s CA.

Java uses the Java KeyStore (JKS) or Public-Key Cryptography Standards #12 (PKCS12) formats for key storage. However, you can import certificates in PEM files.

The key stores require a password for integrity checking. For the system truststore, the default password is changeit. This simple default password is intended for tamper detection and integrity verification rather than cryptographic confidentiality.

To add a custom Certificate Authority (CA) bundle to a Java image, you can use an OpenShift Container Platform ConfigMap. You can select whether you want to add your custom CA bundle to the existing truststore or create a new truststore that contains only your CA bundle.

Procedure

  1. Create a storage volume: 

    $ podman volume create <volume_name>

  2. Enter the Podman user namespace shell: 

    $ podman unshare

  3. Mount the volume: 

    $ podman volume mount <volume_name>
     
    /home/<user>/.local/share/containers/storage/volumes/<volume_name>/_data

  4. Copy your custom certificate to the volume: 

    # cp <path_to_certificate>.pem \
     /home/<user>/.local/share/containers/storage/volumes/<volume_name>/_data/

  5. Exit the user namespace shell: 

    # exit

  6. If you want to add your custom CA bundle to the existing truststore, you must first export it: 

    $ podman run \
    --rm \
    --volume <volume_name>:/work/:Z \
    --user 0 registry.access.redhat.com/hi/openjdk:latest \
      cp /etc/pki/ca-trust/extracted/java/cacerts /work/cacerts

    The command extracts the CA certificates from the Java truststore and stores it in the cacerts file on the storage volume.

    Skip this step if you want to trust only your custom CAs.

  7. Import the custom CA certificate into the Java truststore: 

    $ podman run \
    --rm \
    --volume <volume_name>:/work:Z \
    registry.access.redhat.com/hi/openjdk:latest \
    keytool \
      -import \
      -noprompt \
      -trustcacerts \
      -alias <unique_name> \
      -file /work/<certificate_file_name>.pem \
      -keystore /work/cacerts \
      -storepass changeit \
      -storetype JKS

    The default password of the system truststore is changeit. The -alias <unique_name> option sets the name for the certificate in the truststore. It can be any value.

Verification

  • Start an OpenJDK container and mount the storage volume with the truststore to the /etc/pki/ca-trust/extracted/java/cacerts file: 

    # podman run --rm \
    --volume <volume_name>/cacerts:/etc/pki/ca-trust/extracted/java/cacerts:ro,Z \
    registry.access.redhat.com/hi/openjdk:latest \
      java -jar <application>.jar

Use an OpenShift Container Platform ConfigMap to add a custom Certificate Authority (CA) bundle to a Java image. You can select whether you want to add your custom CA bundle to the existing truststore or if you want to create a new truststore that contains only your CA bundle.

Prerequisites

  • You have access to OpenShift Container Platform CLI.
  • You have the CA certificate bundle in PEM format.
  • You have the permissions to create ConfigMaps and modify Pod specifications in the target namespace.

Procedure

  1. Create a YAML configuration file that both defines the CA bundle and the volume mount necessary for your application to access it: 

    apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-ca
data:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    <certificate>
    -----END CERTIFICATE-----
    <more_certificates_if_needed>
---
apiVersion: v1
kind: Pod
spec:
  initContainers:
  - name: prepare-truststore
    image: quay.io/hummingbird/openjdk:latest
    command: ["sh", "-c"]
    args:
    - |
      # 1. Copy the default Java truststore to a writable location
      # Skip this step if you want to trust only your custom CAs
      cp /etc/pki/ca-trust/extracted/java/cacerts /truststore/cacerts

      chmod 666 /truststore/cacerts

      # 2. Import your file into the truststore (default password: changeit)
      keytool -import -noprompt -trustcacerts -alias custom-ca \
        -file /ca/ca.crt -keystore /truststore/cacerts \
        -storepass changeit -storetype JKS
    volumeMounts:
    - name: custom-ca
      mountPath: /ca
    - name: truststore
      mountPath: /truststore
  containers:
  - name: app
    image: registry.access.redhat.com/hi/openjdk:latest
    volumeMounts:
    - name: truststore
      mountPath: /etc/pki/ca-trust/extracted/java
      readOnly: true
  volumes:
  - name: custom-ca
    configMap:
      name: custom-ca
  - name: truststore
    emptyDir: {}

  2. Apply the configuration: 

    $ oc apply -f <configuration_file>.yaml

If you require that a Java image trusts both your custom Certificate Authorities (CAs) and the image’s built-in default CAs, create a modified image to add the custom certificates. This avoids the need to generate the truststore on each container startup.

Prerequisites

  • The podman package is installed.

Procedure

  1. Create a project directory. For example: 

    $ mkdir ~/project/

  2. Copy the custom CA certificate to your project directory: 

    $ cp <path>/custom-root-ca.pem ~/project/

  3. Create a file named ~/project/Containerfile, that references the Red Hat Hardened Images in the FROM instructions. For example: 

    # Build stage:
FROM registry.access.redhat.com/hi/openjdk:latest-builder AS builder

# Copy the certificate to the image
COPY custom-root-ca.pem /tmp/

# Temporarily switch to root to add the CA certificate to the truststore
USER root
RUN trust anchor /tmp/custom-root-ca.pem
USER ${CONTAINER_DEFAULT_USER}


# Runtime stage:
# Copy the truststore from the builder image to the runtime image
FROM registry.access.redhat.com/hi/openjdk:latest
COPY --from=builder /etc/pki/ca-trust/extracted /etc/pki/ca-trust/extracted

  4. Build the custom image: 

    $ podman build -t <image_name> ~/project/

    The -t <image_name> option specifies the name of the image after the build process.

  5. Optional: Display the list of images: 

    $ podman image list
     
    REPOSITORY             TAG     IMAGE ID      CREATED        SIZE
localhost/<image_name>  latest  03ca4c30326a  4 seconds ago  343 MB

  6. Create a container that uses the image. For example: 

    $ podman run --rm <image_name>:latest ...
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top