Chapter 5. Installing RHACS on Red Hat OpenShift

Procedure

1. Navigate in the web console to the Operators OperatorHub page.
2. If Red Hat Advanced Cluster Security for Kubernetes is not displayed, enter Advanced Cluster Security into the Filter by keyword box to find the Red Hat Advanced Cluster Security for Kubernetes Operator.
3. Select the Red Hat Advanced Cluster Security for Kubernetes Operator to view the details page.
4. Read the information about the Operator, and then click Install.

5. On the Install Operator page:

   • Keep the default value for Installation mode as All namespaces on the cluster.
   • Choose a specific namespace in which to install the Operator for the Installed namespace field. Install the Red Hat Advanced Cluster Security for Kubernetes Operator in the rhacs-operator namespace.

   • Select automatic or manual updates for Update approval.

     If you choose automatic updates, when a new version of the Operator is available, Operator Lifecycle Manager (OLM) automatically upgrades the running instance of your Operator.

     If you choose manual updates, when a newer version of the Operator is available, OLM creates an update request. As a cluster administrator, you must manually approve the update request to update the Operator to the latest version.

     Important

     If you choose manual updates, you must update the RHACS Operator in all secured clusters when you update the RHACS Operator in the cluster where Central is installed. The secured clusters and the cluster where Central is installed must have the same version to ensure optimal functionality.

6. Click Install.

Procedure

1. On the OpenShift Container Platform web console, navigate to the Operators Installed Operators page.
2. Select the Red Hat Advanced Cluster Security for Kubernetes Operator from the list of installed Operators.

3. If you have installed the Operator in the recommended namespace, OpenShift Container Platform lists the project as rhacs-operator. Select Project: rhacs-operator Create project.

   Warning
   • If you have installed the Operator in a different namespace, OpenShift Container Platform shows the name of that namespace rather than rhacs-operator.
   • You must install the Red Hat Advanced Cluster Security for Kubernetes Central custom resource in its own project and not in the rhacs-operator and openshift-operator projects, or in the project in which you have installed the Red Hat Advanced Cluster Security for Kubernetes Operator.
4. Enter the new project name (for example, stackrox), and click Create. Red Hat recommends that you use stackrox as the project name.
5. Under the Provided APIs section, select Central. Click Create Central.

6. Optional: If you are using declarative configuration, next to Configure via:, click YAML view and add the information for the declarative configuration, such as shown in the following example:

   ...
   spec:
     central:
       declarativeConfiguration:
         configMaps:
         - name: "<declarative-configs>" 1
         secrets:
         - name: "<sensitive-declarative-configs>" 2
   ...

   1

   Replace <declarative-configs> with the name of the config maps that you are using.

   2

   Replace <sensitive-declarative-configs> with the name of the secrets that you are using.

7. Enter a name for your Central custom resource and add any labels you want to apply. Otherwise, accept the default values for the available options.
8. Click Create.

Next Steps

1. Verify Central installation.
2. Optional: Configure Central options.
3. Generate an init bundle containing the cluster secrets that allows communication between the Central and SecuredCluster resources. You need to download this bundle, use it to generate resources on the clusters you want to secure, and securely store it.
4. Install secured cluster services on each cluster you want to monitor.

Procedure

1. On the OpenShift Container Platform web console, navigate to the Operators Installed Operators page.
2. Select the Red Hat Advanced Cluster Security for Kubernetes Operator from the list of installed Operators.

3. If you have installed the Operator in the recommended namespace, OpenShift Container Platform lists the project as rhacs-operator. Select Project: rhacs-operator Create project.

   Warning
   • If you have installed the Operator in a different namespace, OpenShift Container Platform shows the name of that namespace rather than rhacs-operator.
   • You must install the Red Hat Advanced Cluster Security for Kubernetes Central custom resource in its own project and not in the rhacs-operator and openshift-operator projects, or in the project in which you have installed the Red Hat Advanced Cluster Security for Kubernetes Operator.
4. Enter the new project name (for example, stackrox), and click Create. Red Hat recommends that you use stackrox as the project name.

5. Create a password secret in the deployed namespace by using the OpenShift Container Platform web console or the terminal.

   • On the OpenShift Container Platform web console, go to the Workloads Secrets page. Create a Key/Value secret with the key password and the value as the path of a plain text file containing the password for the superuser of the provisioned database.

   • Or, run the following command in your terminal:

     $ oc create secret generic external-db-password \ 1
       --from-file=password=<password.txt> 2

     1

     If you use Kubernetes, enter kubectl instead of oc.

     2

     Replace password.txt with the path of the file which has the plain text password.

6. Return to the Red Hat Advanced Cluster Security for Kubernetes operator page in the OpenShift Container Platform web console. Under the Provided APIs section, select Central. Click Create Central.
7. Optional: If you are using declarative configuration, next to Configure via:, click YAML view.

8. Add the information for the declarative configuration, such as shown in the following example:

   ...
   spec:
     central:
       declarativeConfiguration:
         configMaps:
         - name: <declarative-configs> 1
         secrets:
         - name: <sensitive-declarative-configs> 2
   ...

   1

   Replace <declarative-configs> with the name of the config maps that you are using.

   2

   Replace <sensitive-declarative-configs> with the name of the secrets that you are using.

9. Enter a name for your Central custom resource and add any labels you want to apply.
10. Navigate to Central Component Settings Central DB Settings.
11. For Administrator Password specify the referenced secret as external-db-password (or the secret name of the password created previously).
12. For Connection String (Technology Preview) specify the connection string in keyword=value format, for example, host=<host> port=5432 user=postgres sslmode=verify-ca
13. For Persistence PersistentVolumeClaim Claim Name, remove central-db.

14. If necessary, you can specify a Certificate Authority so that there is trust between the data base certificate and Central. To add this, go to the YAML view and add a TLS block under the top-level spec, as shown in the following example:

    spec:
      tls:
        additionalCAs:
        - name: db-ca
          content: |
            <certificate>

15. Click Create.

Next Steps

1. Verify Central installation.
2. Optional: Configure Central options.
3. Generate an init bundle containing the cluster secrets that allows communication between the Central and SecuredCluster resources. You need to download this bundle, use it to generate resources on the clusters you want to secure, and securely store it.
4. Install secured cluster services on each cluster you want to monitor.

Procedure

1. On the OpenShift Container Platform web console, navigate to the Operators Installed Operators page.
2. Select the Red Hat Advanced Cluster Security for Kubernetes Operator from the list of installed Operators.
3. Select the Central tab.
4. From the Centrals list, select stackrox-central-services to view its details.

5. To get the password for the admin user, you can either:

   • Click the link under Admin Password Secret Reference.

   • Use the Red Hat OpenShift CLI to enter the command listed under Admin Credentials Info:

     $ oc -n stackrox get secret central-htpasswd -o go-template='{{index .data "password" | base64decode}}'

6. Find the link to the RHACS portal by using the Red Hat OpenShift CLI command:

   $ oc -n stackrox get route central -o jsonpath="{.status.ingress[0].host}"

   Alternatively, you can use the Red Hat Advanced Cluster Security for Kubernetes web console to find the link to the RHACS portal by performing the following commands:

   1. Navigate to Networking Routes.
   2. Find the central Route and click on the RHACS portal link under the Location column.
7. Log in to the RHACS portal using the username admin and the password that you retrieved in a previous step. Until RHACS is completely configured (for example, you have the Central resource and at least one SecuredCluster resource installed and configured), no data is available in the dashboard. The SecuredCluster resource can be installed and configured on the same cluster as the Central resource. Clusters with the SecuredCluster resource are similar to managed clusters in Red Hat Advanced Cluster Management (RHACM).

Next Steps

1. Optional: Configure central settings.
2. Generate an init bundle containing the cluster secrets that allows communication between the Central and SecuredCluster resources. You need to download this bundle, use it to generate resources on the clusters you want to secure, and securely store it.
3. Install secured cluster services on each cluster you want to monitor.

Procedure

1. Update the values-public.yaml and values-private.yaml configuration files with new values.

2. Run the helm upgrade command and specify the configuration files using the -f option:

   $ helm upgrade -n stackrox \
     stackrox-central-services rhacs/central-services \
     -f <path_to_values_public.yaml> \
     -f <path_to_values_private.yaml>

   Note

   You can also specify configuration values using the --set or --set-file parameters. However, these options are not saved, and it requires you to manually specify all the options again whenever you make changes.

Procedure

1. Run the interactive install command:

   $ roxctl central generate interactive

   Important

   Installing RHACS using the roxctl CLI creates PodSecurityPolicy (PSP) objects by default for backward compatibility. If you install RHACS on Kubernetes versions 1.25 and newer or OpenShift Container Platform version 4.12 and newer, you must disable the PSP object creation. To do this, specify --enable-pod-security-policies option as false for the roxctl central generate and roxctl sensor generate commands.

2. Press Enter to accept the default value for a prompt or enter custom values as required. The following example shows the interactive installer prompts:

   Enter path to the backup bundle from which to restore keys and certificates (optional):
   Enter read templates from local filesystem (default: "false"):
   Enter path to helm templates on your local filesystem (default: "/path"):
   Enter PEM cert bundle file (optional): 1
   Enter Create PodSecurityPolicy resources (for pre-v1.25 Kubernetes) (default: "true"): 2
   Enter administrator password (default: autogenerated):
   Enter orchestrator (k8s, openshift):
   Enter default container images settings (development_build, stackrox.io, rhacs, opensource); it controls repositories from where to download the images, image names and tags format (default: "development_build"):
   Enter the directory to output the deployment bundle to (default: "central-bundle"):
   Enter the OpenShift major version (3 or 4) to deploy on (default: "0"):
   Enter whether to enable telemetry (default: "false"):
   Enter central-db image to use (if unset, a default will be used according to --image-defaults):
   Enter Istio version when deploying into an Istio-enabled cluster (leave empty when not running Istio) (optional):
   Enter the method of exposing Central (route, lb, np, none) (default: "none"): 3
   Enter main image to use (if unset, a default will be used according to --image-defaults):
   Enter whether to run StackRox in offline mode, which avoids reaching out to the Internet (default: "false"):
   Enter list of secrets to add as declarative configuration mounts in central (default: "[]"): 4
   Enter list of config maps to add as declarative configuration mounts in central (default: "[]"): 5
   Enter the deployment tool to use (kubectl, helm, helm-values) (default: "kubectl"):
   Enter scanner-db image to use (if unset, a default will be used according to --image-defaults):
   Enter scanner image to use (if unset, a default will be used according to --image-defaults):
   Enter Central volume type (hostpath, pvc): 6
   Enter external volume name for Central (default: "stackrox-db"):
   Enter external volume size in Gi for Central (default: "100"):
   Enter storage class name for Central (optional if you have a default StorageClass configured):
   Enter external volume name for Central DB (default: "central-db"):
   Enter external volume size in Gi for Central DB (default: "100"):
   Enter storage class name for Central DB (optional if you have a default StorageClass configured):

   1

   If you want to add a custom TLS certificate, provide the file path for the PEM-encoded certificate. When you specify a custom certificate the interactive installer also prompts you to provide a PEM private key for the custom certificate you are using.

   2

   If you are running Kubernetes version 1.25 or later, set this value to false.

   3

   To use the RHACS portal, you must expose Central by using a route, a load balancer or a node port.

   4

   For more information on using declarative configurations for authentication and authorization, see "Declarative configuration for authentication and authorization resources" in "Managing RBAC in Red Hat Advanced Cluster Security for Kubernetes".

   5

   For more information on using declarative configurations for authentication and authorization, see "Declarative configuration for authentication and authorization resources" in "Managing RBAC in Red Hat Advanced Cluster Security for Kubernetes".

   6

   If you plan to install Red Hat Advanced Cluster Security for Kubernetes on OpenShift Container Platform with a hostPath volume, you must modify the SELinux policy.

   Warning

   On OpenShift Container Platform, for using a hostPath volume, you must modify the SELinux policy to allow access to the directory, which the host and the container share. It is because SELinux blocks directory sharing by default. To modify the SELinux policy, run the following command:

   $ sudo chcon -Rt svirt_sandbox_file_t <full_volume_path>

   However, Red Hat does not recommend modifying the SELinux policy, instead use PVC when installing on OpenShift Container Platform.

Procedure

1. Run the setup.sh script to configure image registry access:

   $ ./central-bundle/central/scripts/setup.sh

2. Create the necessary resources:

   $ oc create -R -f central-bundle/central

3. Check the deployment progress:

   $ oc get pod -n stackrox -w

4. After Central is running, find the RHACS portal IP address and open it in your browser. Depending on the exposure method you selected when answering the prompts, use one of the following methods to get the IP address.

   Exposure method	Command	Address	Example
   Route	oc -n stackrox get route central	The address under the HOST/PORT column in the output	https://central-stackrox.example.route
   Node Port	oc get node -owide && oc -n stackrox get svc central-loadbalancer	IP or hostname of any node, on the port shown for the service	https://198.51.100.0:31489
   Load Balancer	oc -n stackrox get svc central-loadbalancer	EXTERNAL-IP or hostname shown for the service, on port 443	https://192.0.2.0
   None	central-bundle/central/scripts/port-forward.sh 8443	https://localhost:8443	https://localhost:8443

Procedure

1. Find the address of the RHACS portal based on your exposure method:

   1. For a route:

      $ oc get route central -n stackrox

   2. For a load balancer:

      $ oc get service central-loadbalancer -n stackrox

   3. For port forward:

      1. Run the following command:

         $ oc port-forward svc/central 18443:443 -n stackrox

      2. Navigate to https://localhost:18443/.
2. On the RHACS portal, navigate to Platform Configuration Integrations.
3. Navigate to the Authentication Tokens section and click on Cluster Init Bundle.
4. Click Generate bundle.

5. Enter a name for the cluster init bundle and click Generate.

   1. If you are installing using Helm charts, click Download Helm Values File to download the generated bundle.
   2. If you are installing using the Operator, click Download Kubernetes Secret File to download the generated bundle.

Next steps

1. Apply the init bundle by creating a resource on the secured cluster.
2. Install secured cluster services on each cluster.

Procedure

1. On the OpenShift Container Platform web console, navigate to the Operators Installed Operators page.
2. Click the RHACS Operator.
3. Click Secured Cluster from the central navigation menu in the Operator details page.
4. Click Create SecuredCluster.

5. Select one of the following options in the Configure via field:

   • Form view: Use this option if you want to use the on-screen fields to configure the secured cluster and do not need to change any other fields.
   • YAML view: Use this view to set up the secured cluster using the YAML file. The YAML file is displayed in the window and you can edit fields in it. If you select this option, when you are finished editing the file, click Create.
6. If you are using Form view, enter the new project name by accepting or editing the default name. The default value is stackrox-secured-cluster-services.
7. Optional: Add any labels for the cluster.
8. Enter a unique name for your SecuredCluster custom resource.

9. For Central Endpoint, enter the address and port number of your Central instance. For example, if Central is available at https://central.example.com, then specify the central endpoint as central.example.com:443. The default value of central.stackrox.svc:443 only works when you install secured cluster services and Central in the same cluster. Do not use the default value when you are configuring multiple clusters. Instead, use the hostname when configuring the Central Endpoint value for each cluster.

   • Only if you are installing secured cluster services and Central in the same cluster, use central.stackrox.svc:443.
10. Accept the default values or configure custom values if needed. For example, you may need to configure TLS if you are using custom certificates or untrusted CAs.
11. Click Create.

Next step

1. Optional: Configure additional secured cluster settings.
2. Verify installation.

Procedure

1. Update the values-public.yaml and values-private.yaml configuration files with new values.

2. Run the helm upgrade command and specify the configuration files using the -f option:

   $ helm upgrade -n stackrox \
     stackrox-secured-cluster-services rhacs/secured-cluster-services \
     --reuse-values \ 1
     -f <path_to_values_public.yaml> \
     -f <path_to_values_private.yaml>

   1

   You must specify the --reuse-values parameter, otherwise the Helm upgrade command resets all previously configured settings.

   Note

   You can also specify configuration values using the --set or --set-file parameters. However, these options are not saved, and it requires you to manually specify all the options again whenever you make changes.

Procedure

1. On your secured cluster, in the RHACS portal, navigate to Platform Configuration Clusters.
2. Select + New Cluster.
3. Specify a name for the cluster.

4. Provide appropriate values for the fields based on where you are deploying the Sensor.

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

   • 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://.
     • Add the port number after the address, for example, wss://stackrox-central.example.com:443.
5. Click Next to continue with the Sensor setup.

6. Click Download YAML File and Keys to download the cluster bundle (zip archive).

   Important

   The cluster bundle zip archive includes unique configurations and keys for each cluster. Do not reuse the same files in another cluster.

7. From a system that has access to the monitored cluster, unzip and run the sensor script from the cluster bundle:

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

   $ ./sensor/sensor.sh

   If you get a warning that you do not have the required permissions to deploy Sensor, follow the on-screen instructions, or contact your cluster administrator for assistance.

Verification

1. Return to the RHACS portal and check if the deployment is successful. If successful, when viewing your list of clusters in Platform Configuration Clusters, the cluster status displays a green checkmark and a Healthy status. If you do not see a green checkmark, use the following command to check for problems:

   • On OpenShift Container Platform, enter the following command:

     $ oc get pod -n stackrox -w

   • On Kubernetes, enter the following command:

     $ kubectl get pod -n stackrox -w

2. Click Finish to close the window.