Chapter 1. Adding custom certificates
Chapter 1. Adding custom certificates Learn how to use a custom TLS certificate with Red Hat Advanced Cluster Security for Kubernetes. After you set up a certificate, users and API clients do not have to bypass the certificate security warnings when connecting to Central. 1.1. 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. 1.1.1. 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. Warning 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. 1.1.2. Adding a custom certificate during a new installation Procedure If you are installing Red Hat Advanced Cluster Security for Kubernetes using the Operator: 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: 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----- Provide the configuration file during the installation: USD 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: USD 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 ... 1.1.3. Adding a custom certificate for an existing instance Procedure If you have installed Red Hat Advanced Cluster Security for Kubernetes using the Operator: 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: 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----- Use the helm upgrade command and provide the updated configuration file: USD helm upgrade -n stackrox --create-namespace stackrox-central-services \ rhacs/central-services --reuse-values \ 1 -f values-private.yaml 1 You must use this parameter because the values-private.yaml file does not contain all of the required configuration values. 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: USD 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. 1.1.4. 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 Delete the existing custom certificate's secret: USD oc delete secret central-default-tls-cert Create a new secret: USD 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 - Restart the Central container. 1.1.4.1. 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: Note You must wait for at least 1 minute, until OpenShift Container Platform propagates your changes and restarts the Central container. USD oc -n stackrox exec deploy/central -c central -- kill 1 Or, run the following command to delete the Central pod: USD oc -n stackrox delete pod -lapp=central 1.2. 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. Note You do not need to configure the Sensor to trust your custom certificate if you are using a globally trusted certificate. 1.2.1. 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 In the RHACS portal, go to Platform Configuration Clusters . Click New Cluster and specify a name for the cluster. 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. Note 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 : Prefix the address with wss:// , and Add the port number after the address, for example, wss://stackrox-central.example.com:443 . Click to continue. Click Download YAML File and Keys . 1.2.2. 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: Unzip the Sensor bundle: USD unzip -d sensor sensor-<cluster_name>.zip Run the sensor.sh script: USD ./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: Unzip the Sensor bundle: USD unzip -d sensor sensor-<cluster_name>.zip Run the following command to create the secret: USD ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ 1 1 Use the -d option to specify a directory containing custom certificates. Note If you get the "secret already exists" error message, re-run the script with the -u option: USD ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ -u Continue Sensor deployment by using the YAML files. 1.2.3. Configuring an existing Sensor to trust custom certificates Prerequisites You have downloaded the Sensor bundle. Procedure Unzip the Sensor bundle: USD unzip -d sensor sensor-<cluster_name>.zip Run the following command to create the secret: USD ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ 1 1 Use the -d option to specify a directory containing custom certificates. Note If you get the "secret already exists" error message, re-run the script with the -u option: USD ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ -u Continue Sensor deployment by using the YAML files. If you added the certificates to an existing sensor, you must restart the Sensor container. 1.2.3.1. 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: Note 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: USD oc -n stackrox deploy/sensor -c sensor -- kill 1 On Kubernetes: USD kubectl -n stackrox deploy/sensor -c sensor -- kill 1 Or, run the following command to delete the Sensor pod: On OpenShift Container Platform: USD oc -n stackrox delete pod -lapp=sensor On Kubernetes: USD kubectl -n stackrox delete pod -lapp=sensor
-----BEGIN CERTIFICATE----- MIICLDCCAdKgAwIBAgIBADAKBggqhkjOPQQDAjB9MQswCQYDVQQGEwJCRTEPMA0G l4wOuDwKQa+upc8GftXE2C//4mKANBC6It01gUaTIpo= -----END CERTIFICATE----- -n <namespace> create secret tls central-default-tls-cert --cert <tls-cert.pem> --key <tls-key.pem> 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----- helm install -n stackrox --create-namespace stackrox-central-services rhacs/central-services -f values-private.yaml roxctl central generate --default-tls-cert "cert.pem" --default-tls-key "key.pem" 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 -n <namespace> create secret tls central-default-tls-cert --cert <tls-cert.pem> --key <tls-key.pem> 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----- helm upgrade -n stackrox --create-namespace stackrox-central-services rhacs/central-services --reuse-values \ 1 -f values-private.yaml 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 - oc delete secret central-default-tls-cert 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 - oc -n stackrox exec deploy/central -c central -- kill 1 oc -n stackrox delete pod -lapp=central unzip -d sensor sensor-<cluster_name>.zip ./sensor/sensor.sh unzip -d sensor sensor-<cluster_name>.zip ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ 1 ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ -u unzip -d sensor sensor-<cluster_name>.zip ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ 1 ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ -u oc -n stackrox deploy/sensor -c sensor -- kill 1 kubectl -n stackrox deploy/sensor -c sensor -- kill 1 oc -n stackrox delete pod -lapp=sensor kubectl -n stackrox delete pod -lapp=sensor