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
×

Installing by using the roxctl CLI

Red Hat Advanced Cluster Security for Kubernetes installs a set of services on your OpenShift Container Platform cluster. This topic describes the installation procedure for installing Red Hat Advanced Cluster Security for Kubernetes on your OpenShift Container Platform cluster by using the roxctl CLI.

For production environments, Red Hat recommends Installing Red Hat Advanced Cluster Security for Kubernetes by using Helm charts. Do not use the roxctl install method unless you have a specific installation need that requires using this method.

High-level installation flow:

  1. Install the roxctl CLI.

  2. Use the roxctl CLI interactive installer to install the centralized components (Central and Scanner).

  3. Install Sensor to monitor your cluster.

Before you install:

Installing the roxctl CLI

To install Red Hat Advanced Cluster Security for Kubernetes you must install the roxctl CLI by downloading the binary. You can install roxctl on Linux, Windows, or macOS.

Installing the roxctl CLI on Linux

You can install the roxctl CLI binary on Linux by using the following procedure.

Procedure

  1. Download the latest version of the roxctl CLI:

    $ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.72.3/bin/Linux/roxctl

  2. Make the roxctl binary executable:

    $ chmod +x roxctl

  3. Place the roxctl binary in a directory that is on your PATH:

    To check your PATH, execute the following command:

    $ echo $PATH
Verification

  • Verify the roxctl version you have installed:

    $ roxctl version

Installing the roxctl CLI on macOS

You can install the roxctl CLI binary on macOS by using the following procedure.

Procedure

  1. Download the latest version of the roxctl CLI:

    $ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.72.3/bin/Darwin/roxctl

  2. Remove all extended attributes from the binary:

    $ xattr -c roxctl

  3. Make the roxctl binary executable:

    $ chmod +x roxctl

  4. Place the roxctl binary in a directory that is on your PATH:

    To check your PATH, execute the following command:

    $ echo $PATH
Verification

  • Verify the roxctl version you have installed:

    $ roxctl version

Installing the roxctl CLI on Windows

You can install the roxctl CLI binary on Windows by using the following procedure.

Procedure

  • Download the latest version of the roxctl CLI:

    $ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.72.3/bin/Windows/roxctl.exe
Verification

  • Verify the roxctl version you have installed:

    $ roxctl version

Installing Central

The main component of Red Hat Advanced Cluster Security for Kubernetes is called Central. You can install Central on OpenShift Container Platform by using the interactive installer. You deploy Central only once and you can monitor multiple separate clusters by using the same installation.

Using the interactive installer

Use the interactive installer to generate the required secrets, deployment configurations, and deployment scripts for your environment.

Procedure

  1. Run the interactive install command:

    $ roxctl central generate interactive

    Installing Red Hat Advanced Cluster Security for Kubernetes using 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.

    Enter path to the backup bundle from which to restore keys and certificates (optional):
Enter PEM cert bundle file (optional): (1)
Enter administrator password (default: autogenerated):
Enter orchestrator (k8s, openshift): openshift
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"): 4
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"): route (2)
Enter main image to use (default: "stackrox.io/main:3.0.61.1"):
Enter whether to run StackRox in offline mode, which avoids reaching out to the Internet (default: "false"):
Enter whether to enable telemetry (default: "true"):
Enter the deployment tool to use (kubectl, helm, helm-values) (default: "kubectl"):
Enter Scanner DB image to use (default: "stackrox.io/scanner-db:2.15.2"):
Enter Scanner image to use (default: "stackrox.io/scanner:2.15.2"):
Enter Central volume type (hostpath, pvc): pvc (3)
Enter external volume name (default: "stackrox-db"):
Enter external volume size in Gi (default: "100"):
Enter storage class name (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 To use the RHACS portal, you must expose Central by using a route, a load balancer or a node port.
    3 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.

    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.

On completion, the installer creates a folder named central-bundle, which contains the necessary YAML manifests and scripts to deploy Central. In addition, it shows on-screen instructions for the scripts you need to run to deploy additional trusted certificate authorities, Central and Scanner, and the authentication instructions for logging into the RHACS portal along with the autogenerated password if you did not provide one when answering the prompts.

Running the Central installation scripts

After you run the interactive installer, you can run the setup.sh script to install Central.

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

If you have selected autogenerated password during the interactive install, you can run the following command to see it for logging into Central:

$ cat central-bundle/password

Installing Scanner

You can configure Red Hat Advanced Cluster Security for Kubernetes to obtain image data from a variety of open-source and commercial image scanners.

However, Red Hat Advanced Cluster Security for Kubernetes also provides an image vulnerability scanner component, called Scanner. It enriches deployments with image vulnerability information.

Red Hat recommends deploying Scanner so that it can scan all images, including the images from public registries, for vulnerabilities. You can deploy the Scanner in the same cluster with Central.

Prerequisites

  • You must configure your image registry to allow Scanner to download and scan images. Usually, image registry integrations are created automatically by Red Hat Advanced Cluster Security for Kubernetes.

Procedure

  1. Run the following command to configure image registry access:

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

  2. After the script finishes, run the following command to create the scanner service:

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

Installing Sensor

To monitor a cluster, you must deploy Sensor. You must deploy Sensor into each cluster that you want to monitor. The following steps describe adding Sensor by using the RHACS portal.

Prerequisites

  • You must have already installed Central services.

Procedure

  1. On 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).

    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.

After Sensor is deployed, it contacts Central and provides cluster information.

Verification

  1. Return to the RHACS portal and check if the deployment is successful. If it is successful, a green checkmark appears under section #2. If you do not see a green checkmark, use the following command to check for problems:

    • On OpenShift Container Platform:

      $ oc get pod -n stackrox -w

    • On Kubernetes:

      $ kubectl get pod -n stackrox -w

  2. Click Finish to close the window.

After installation, Sensor starts reporting security information to Red Hat Advanced Cluster Security for Kubernetes and the RHACS portal dashboard begins showing deployments, images, and policy violations from the cluster on which you have installed the Sensor.

Verifying installation

After you complete the installation, run a few vulnerable applications and navigate to the RHACS portal to evaluate the results of security assessments and policy violations.

The sample applications listed in the following section contain critical vulnerabilities and they are specifically designed to verify the build and deploy-time assessment features of Red Hat Advanced Cluster Security for Kubernetes.

To verify installation:

  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. Using the OpenShift Container Platform CLI, create a new project:

    $ oc new-project test

  3. Start some applications with critical vulnerabilities:

    $ oc run shell --labels=app=shellshock,team=test-team \
  --image=vulnerables/cve-2014-6271 -n test
$ oc run samba --labels=app=rce \
  --image=vulnerables/cve-2017-7494 -n test

Red Hat Advanced Cluster Security for Kubernetes automatically scans these deployments for security risk and policy violations as soon as they are submitted to the cluster. Navigate to the RHACS portal to view the violations. You can log in to the RHACS portal by using the default username admin and the generated password.

Additional resources