OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Adding custom certificates

Adding a custom security certificate

You can apply a security certificate during the installation or on an existing Red Hat Advanced Cluster Security for Kubernetes deployment.

Prerequisites for adding custom certificates

Prerequisites

  • You must already have PEM-encoded private key and certificate files.

  • The certificate file should begin and end with human-readable blocks. For example:

    -----BEGIN CERTIFICATE-----
MIICLDCCAdKgAwIBAgIBADAKBggqhkjOPQQDAjB9MQswCQYDVQQGEwJCRTEPMA0G
...
l4wOuDwKQa+upc8GftXE2C//4mKANBC6It01gUaTIpo=
-----END CERTIFICATE-----

  • The certificate file can contain either a single (leaf) certificate, or a certificate chain.

    • If the certificate is not directly signed by a trusted root, you must provide the full certificate chain, including any intermediate certificates.

    • All certificates in the chain must be in order so that the leaf certificate is the first and the root certificate is the last in the chain.

  • If you are using a custom certificate that is not globally trusted, you must also configure the Sensor to trust your custom certificate.

Adding a custom certificate during a new installation

Procedure

  • If you are installing Red Hat Advanced Cluster Security for Kubernetes using the Operator:

    1. Create a central-default-tls-cert secret that contains the appropriate TLS certificates in the namespace where the Central service will be installed by entering the following command:

      oc -n <namespace> create secret tls central-default-tls-cert --cert <tls-cert.pem> --key <tls-key.pem>

  • If you are installing Red Hat Advanced Cluster Security for Kubernetes using Helm:

    1. Add your custom certificate and its key in the values-private.yaml file:

      central:
  # Configure a default TLS certificate (public cert + private key) for central
  defaultTLS:
    cert: |
      -----BEGIN CERTIFICATE-----
      EXAMPLE!MIIMIICLDCCAdKgAwIBAgIBADAKBggqhkjOPQQDAjB9MQswCQYDVQQGEwJCRTEPMA0G
      ...
      -----END CERTIFICATE-----
    key: |
      -----BEGIN EC PRIVATE KEY-----
      EXAMPLE!MHcl4wOuDwKQa+upc8GftXE2C//4mKANBC6It01gUaTIpo=
      ...
      -----END EC PRIVATE KEY-----

    2. Provide the configuration file during the installation:

      $ helm install -n stackrox --create-namespace stackrox-central-services rhacs/central-services -f values-private.yaml

  • If you are installing Red Hat Advanced Cluster Security for Kubernetes using the roxctl CLI, provide the certificate and key files when you run the installer:

    • For the non-interactive installer, use the --default-tls-cert and --default-tls-key options:

      $ roxctl central generate --default-tls-cert "cert.pem" --default-tls-key "key.pem"

    • For the interactive installer, provide the certificate and key files when you enter answers for the prompts:

      ...
Enter PEM cert bundle file (optional): <cert.pem>
Enter PEM private key file (optional): <key.pem>
Enter administrator password (default: autogenerated):
Enter orchestrator (k8s, openshift): openshift
...

Adding a custom certificate for an existing instance

Procedure

  • If you have installed Red Hat Advanced Cluster Security for Kubernetes using the Operator:

    1. Create a central-default-tls-cert secret that contains the appropriate TLS certificates in the namespace where the Central service is installed by entering the following command:

      oc -n <namespace> create secret tls central-default-tls-cert --cert <tls-cert.pem> --key <tls-key.pem>

  • If you have installed Red Hat Advanced Cluster Security for Kubernetes using Helm:

    1. Add your custom certificate and its key in the values-private.yaml file:

      central:
  # Configure a default TLS certificate (public cert + private key) for central
  defaultTLS:
    cert: |
      -----BEGIN CERTIFICATE-----
      EXAMPLE!MIIMIICLDCCAdKgAwIBAgIBADAKBggqhkjOPQQDAjB9MQswCQYDVQQGEwJCRTEPMA0G
      ...
      -----END CERTIFICATE-----
    key: |
      -----BEGIN EC PRIVATE KEY-----
      EXAMPLE!MHcl4wOuDwKQa+upc8GftXE2C//4mKANBC6It01gUaTIpo=
      ...
      -----END EC PRIVATE KEY-----

    2. Use the helm upgrade command and provide the updated configuration file:

      $ helm upgrade -n stackrox --create-namespace stackrox-central-services rhacs/central-services -f values-private.yaml

  • If you have installed Red Hat Advanced Cluster Security for Kubernetes using the roxctl CLI:

    • Create and apply a TLS secret from the PEM-encoded key and certificate files:

      $ oc -n stackrox create secret tls central-default-tls-cert \
  --cert <server_cert.pem> \
  --key <server_key.pem> \
  --dry-run -o yaml | oc apply -f -

      After you run this command, Central automatically applies the new key and certificate without requiring the pod to be restarted. It might take up to a minute to propagate the changes.

Updating the custom certificate for an existing instance

If you use a custom certificate for Central, you can update the certificate by performing the following procedure.

Procedure

  1. Delete the existing custom certificate’s secret:

    $ oc delete secret central-default-tls-cert

  2. Create a new secret:

    $ oc -n stackrox create secret tls central-default-tls-cert \
  --cert <server_cert.pem> \
  --key <server_key.pem> \
  --dry-run -o yaml | oc apply -f -

  3. Restart the Central container.

Restarting the Central container

You can restart the Central container by killing the Central container or by deleting the Central pod.

Procedure

  • Run the following command to kill the Central container:

    You must wait for at least 1 minute, until OpenShift Container Platform propagates your changes and restarts the Central container.

    		 
    $ oc -n stackrox exec deploy/central -c central -- kill 1

  • Or, run the following command to delete the Central pod:

    $ oc -n stackrox delete pod -lapp=central

Configuring Sensor to trust custom certificates

If you are using a custom certificate that is not trusted globally, you must configure the Sensor to trust your custom certificate. Otherwise, you might get errors. The specific type of error may vary based on your setup and the certificate you use. Usually, it is an x509 validation related error.

You do not need to configure the Sensor to trust your custom certificate if you are using a globally trusted certificate.

Downloading a Sensor bundle

The Sensor bundle includes the necessary configuration files and scripts to install Sensor. You can download the Sensor bundle from the RHACS portal.

Procedure

  1. Navigate to the RHACS portal.

  2. Go to Platform Configuration → Clusters.

  3. Click New Cluster and specify a name for the cluster.

  4. If you are deploying the Sensor in the same cluster, accept the default values for all the fields. Otherwise, if you are deploying into a different cluster, replace the address central.stackrox.svc:443 with a load balancer, node port, or other address (including the port number) that is accessible from the other cluster in which you are planning to install.

    If you are using a non-gRPC capable load balancer, such as HAProxy, AWS Application Load Balancer (ALB), or AWS Elastic Load Balancing (ELB) use the WebSocket Secure (wss) protocol. To use wss:

    1. Prefix the address with wss://, and

    2. Add the port number after the address, for example, wss://stackrox-central.example.com:443.

  5. Click Next to continue.

  6. Click Download YAML File and Keys.

Configuring Sensor to trust custom certificates when deploying a new Sensor

Prerequisites

  • You have downloaded the Sensor bundle.

Procedure

  • If you are using the sensor.sh script:

    1. Unzip the Sensor bundle:

      $ unzip -d sensor sensor-<cluster_name>.zip

    2. Run the sensor.sh script:

      $ ./sensor/sensor.sh

      The certificates are automatically applied when you run the sensor (./sensor/sensor.sh) script. You can also place additional custom certificates in the sensor/additional-cas/ directory before you run the sensor.sh script.

  • If you are not using the sensor.sh script:

    1. Unzip the Sensor bundle:

      $ unzip -d sensor sensor-<cluster_name>.zip

    2. Run the following command to create the secret:

      $ ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ (1)
      1 Use the -d option to specify a directory containing custom certificates.

      If you get the "secret already exists" error message, re-run the script with the -u option:

      $ ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ -u

    3. Continue Sensor deployment by using the YAML files.

Configuring an existing Sensor to trust custom certificates

Prerequisites

  • You have downloaded the Sensor bundle.

Procedure

  1. Unzip the Sensor bundle:

    $ unzip -d sensor sensor-<cluster_name>.zip

  2. Run the following command to create the secret:

    $ ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ (1)
    1 Use the -d option to specify a directory containing custom certificates.

    If you get the "secret already exists" error message, re-run the script with the -u option:

    $ ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ -u

  3. Continue Sensor deployment by using the YAML files.

If you added the certificates to an existing sensor, you must restart the Sensor container.

Restarting the Sensor container

You can restart the Sensor container either by killing the container or by deleting the Sensor pod.

Procedure

  • Run the following command to kill the Sensor container:

    You must wait for at least 1 minute, until OpenShift Container Platform or Kubernetes propagates your changes and restarts the Sensor container.

    • On OpenShift Container Platform:

      $ oc -n stackrox deploy/sensor -c sensor -- kill 1

    • On Kubernetes:

      $ kubectl -n stackrox deploy/sensor -c sensor -- kill 1

  • Or, run the following command to delete the Sensor pod:

    • On OpenShift Container Platform:

      $ oc -n stackrox delete pod -lapp=sensor

    • On Kubernetes:

      $ kubectl -n stackrox delete pod -lapp=sensor