Configure custom certificates

Learn how to use a custom TLS certificate with the StackRox Kubernetes Security Platform.

In the StackRox Kubernetes Security Platform, you can set a custom certificate on the StackRox Central server. After you set up a certificate, users and API clients won’t have to bypass certificate security warnings when connecting to the StackRox Central server.

Configuring custom certificates requires version 2.4.21 or newer. If you are on an older version, see the Upgrade StackRox page for upgrade instructions.

Add a custom security certificate

You can apply a security certificate during the installation or on an existing StackRox deployment.

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:
      Copy
      -----BEGIN CERTIFICATE-----
      MIICLDCCAdKgAwIBAgIBADAKBggqhkjOPQQDAjB9MQswCQYDVQQGEwJCRTEPMA0G
      ...
      l4wOuDwKQa+upc8GftXE2C//4mKANBC6It01gUaTIpo=
      -----END CERTIFICATE-----
  • The certificate file may contain either a single (leaf) certificate, or a certificate chain.

    If the certificate isn’t 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’s not globally trusted, you must also configure the Sensor to trust your custom certificate.

During a new installation

To add a custom TLS security certificate:

  1. 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:

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

    For the interactive installer, just provide the certificate and key files when answering the prompts:

    Copy
    Enter PEM cert bundle file (optional): cert.pem
    Enter PEM private key file (optional): key.pem
    Enter license data or filename (`-` for multiline input) (optional):
    Enter administrator password (default: autogenerated):
    Enter orchestrator (k8s, openshift): k8s
    ...

On an existing StackRox deployment

Before you add a custom TLS security certificate for the first time, you must configure StackRox Central to mount the central-default-tls-cert Kubernetes secret.

  1. If you have upgraded from version 2.4.20 or earlier, run the following patch command, skip this step if you have upgraded from version 2.4.21 or later.

    Copy
    central_cert_patch='{ "spec": { "template": { "spec": { "containers": [ { "name": "central", "volumeMounts": [ { "mountPath": "/run/secrets/stackrox.io/default-tls-cert/", "name": "central-default-tls-cert-volume", "readOnly": true } ] } ], "volumes": [ { "name": "central-default-tls-cert-volume", "secret": { "defaultMode": 420, "optional": true, "secretName": "central-default-tls-cert" } } ] } } } }'
    kubectl -n stackrox patch deploy/central -p "$central_cert_patch"
    Copy
    central_cert_patch='{ "spec": { "template": { "spec": { "containers": [ { "name": "central", "volumeMounts": [ { "mountPath": "/run/secrets/stackrox.io/default-tls-cert/", "name": "central-default-tls-cert-volume", "readOnly": true } ] } ], "volumes": [ { "name": "central-default-tls-cert-volume", "secret": { "defaultMode": 420, "optional": true, "secretName": "central-default-tls-cert" } } ] } } } }'
    oc -n stackrox patch deploy/central -p "$central_cert_patch"

To configure a custom certificate:

  1. Create and apply a Kubernetes TLS secret from the PEM-encoded key and certificate files:

    Copy
    kubectl -n stackrox create secret tls central-default-tls-cert --cert <server-cert.pem> --key <server-key.pem> --dry-run -o yaml | kubectl apply -f -
    Copy
    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 -
  2. Beginning from version 2.5.31, Central automatically applies the new key and certificate without requiring the pod to be restarted. Kubernetes may take up to a minute to propagate any updates you make.

    In earlier versions, you must restart Central to apply the change.

    Copy
    kubectl -n stackrox exec "$(kubectl -n stackrox -l app=central get po -o jsonpath='{.items[0].metadata.name}')" -c central -- kill 1
    Copy
    oc -n stackrox exec "$(oc -n stackrox -l app=central get po -o jsonpath='{.items[0].metadata.name}')" -c central -- kill 1

Configure Sensor to trust custom certificates

If you are using a custom certificate that isn’t trusted globally, you must configure the Sensor to trust your custom certificate. The specific type of error may vary based on your setup and the certificate you use. Usually, it’s an x509 validation related error.

You don’t need to configure the Sensor to trust your custom certificate if you are using a globally trusted certificate.

Version 3.0.40 or newer

If you are using the StackRox Kubernetes Security Platform version 3.0.40 or newer, and you’ve already added a custom security certificate, when you download the sensor bundle, the certificates are already in the sensor/additional-cas/ folder.

When deploying a new sensor

With sensor.sh script
  1. Download the sensor bundle.
  2. Unzip the sensor bundle:
    Copy
    unzip -d sensor sensor-[cluster-name].zip
  3. Run the sensor.sh script:
    Copy
    ./sensor/sensor.sh
    The certificates are automatically applied when you run the sensor (./sensor/sensor.sh) script. You can also place any additional custom certificates in the sensor/additional-cas/ folder before you run the sensor script.
Without sensor.sh script
  1. Download the sensor bundle.
  2. Unzip the sensor bundle:
    Copy
    unzip -d sensor sensor-[cluster-name].zip
  3. Run the following command to create the secret:
    Copy
    ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/
  4. If you get the “secret already exists” error message, re-run the script with the -u flag:
    Copy
    ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ -u
  5. Continue Sensor deployment by using the YAML files.

When applying to an existing sensor

  1. Follow the steps in the section Without sensor.sh script.
  2. Restart the Sensor container

Version 3.0.39 or older

If you are using the StackRox Kubernetes Security Platform version 3.0.39 or older:

  1. Download the sensor bundle.

  2. Unzip the sensor bundle:

    Copy
    unzip -d sensor sensor-[cluster-name].zip
  3. Run the following command:

    Copy
    openssl s_client -connect <central-host:port> -showcerts </dev/null 2>/dev/null \
    | sed '1!G;h;$!d' \
    | sed -n '/^-----END CERT/,/^-----BEGIN CERT/p; /^-----BEGIN CERT/q' \
    | sed '1!G;h;$!d' > sensor/additional-cas/default-central-ca.crt

    This command gets the topmost certificate in the chain of certificates served by central, and store it in a default-central-ca.crt file in the sensor/additional-cas/ directory of the extracted bundle.

When deploying a new sensor

  1. Run the sensor script:
    Copy
    ./sensor/sensor.sh

When applying to an existing sensor

  1. Run the sensor script:

    Copy
    ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ -u
    • Use the -d option to specify a folder containing custom certificates.
    • use the -u option to update any existing secrets.
  2. Restart the Sensor container

Restart the Sensor container

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

Use one of the following commands to restart the Sensor container:

  • You must wait for at least 1 minute, till Kubernetes propagate your changes, before you run the following command to restart the container:

    Copy
    kubectl -n stackrox deploy/sensor -c sensor -- kill 1
    Copy
    oc -n stackrox deploy/sensor -c sensor -- kill 1
  • Or, if you don’t want to wait, run the following command to delete the pod:

    Copy
    kubectl -n stackrox delete po -lapp=sensor
    Copy
    oc -n stackrox delete po -lapp=sensor

Questions?

We're happy to help! Reach out to us to discuss questions, issues, or feature requests.

© 2021 StackRox Inc. All rights reserved.