You are viewing documentation for a release that is no longer maintained. To view the documentation for the most recent version, see the latest RHACS docs.
Chapter 3. Installing by using an Operator
Red Hat Advanced Cluster Security for Kubernetes (RHACS) installs a set of services on your OpenShift Container Platform or Kubernetes cluster. This section describes the installation procedure for installing Red Hat Advanced Cluster Security for Kubernetes on your OpenShift Container Platform or Kubernetes cluster by using an Operator.
Before you install:
The Red Hat Advanced Cluster Security for Kubernetes Operator includes the following two custom resources:
Central
- The central resource is a logical grouping of the following services:- Central: Central is the Red Hat Advanced Cluster Security for Kubernetes application management interface and services. It handles data persistence, API interactions, and user interface (RHACS Portal) access. You can use the same Central instance to secure multiple OpenShift Container Platform or Kubernetes clusters.
- Scanner: Scanner is a Red Hat-developed and certified vulnerability scanner for scanning container images and their associated database. It analyzes all image layers to check known vulnerabilities from the Common Vulnerabilities and Exposures (CVEs) list. Scanner also identifies vulnerabilities in packages installed by package managers and in dependencies for multiple programming languages.
SecuredCluster
- The secured cluster resource is a logical grouping of the following services:- Sensor: Sensor is the service responsible for analyzing and monitoring the cluster. It handles interactions with the OpenShift Container Platform or Kubernetes API server for policy detection and enforcement, and it coordinates with Collector.
- Collector: Collector analyzes and monitors container activity on cluster nodes. It collects information about container runtime and network activity. It then sends the collected data to Sensor.
- Admission Control: The admission controller prevents users from creating workloads that violate security policies in Red Hat Advanced Cluster Security for Kubernetes.
The following steps represent a high-level workflow for installing Red Hat Advanced Cluster Security for Kubernetes by using an Operator:
- Install the Red Hat Advanced Cluster Security for Kubernetes Operator from OperatorHub in the cluster where you want to install Central.
-
Configure and deploy the
Central
custom resource. - Generate and apply an init bundle. The init bundle contains the secrets that provide linking between Central and the secured clusters.
- Install the Red Hat Advanced Cluster Security for Kubernetes Operator in all clusters that you want to monitor.
-
Configure and deploy the
SecuredCluster
custom resource in each individual cluster that you want to monitor.
3.1. Installing the Red Hat Advanced Cluster Security for Kubernetes Operator
Using the OperatorHub provided with OpenShift Container Platform is the easiest way to install Red Hat Advanced Cluster Security for Kubernetes.
Prerequisites
- You have access to an OpenShift Container Platform cluster using an account with Operator installation permissions.
- You must be using OpenShift Container Platform 4.6 or later.
Procedure
-
Navigate in the web console to the Operators
OperatorHub page. - 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.
- Select the Red Hat Advanced Cluster Security for Kubernetes Operator to view the details page.
- Read the information about the Operator and click Install.
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. Red Hat recommends installing 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 then manually approve that update request to update the Operator to the new version.
ImportantIf you choose manual updates, you should 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 should have the same version to ensure optimal functionality.
- Click Install.
Verification
-
After the installation completes, navigate to Operators
Installed Operators to verify that the Red Hat Advanced Cluster Security for Kubernetes Operator is listed with the status of Succeeded.
Next Step
-
Install, configure, and deploy the
Central
custom resource.
3.2. 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 Central
custom resource. You deploy Central only once, and you can monitor multiple separate clusters by using the same Central installation.
When you install Red Hat Advanced Cluster Security for Kubernetes for the first time, you must first install the Central
custom resource because the SecuredCluster
custom resource installation is dependent on certificates that Central generates.
Prerequisites
- You must be using OpenShift Container Platform 4.6 or later.
Procedure
-
On the OpenShift Container Platform web console, navigate to the Operators
Installed Operators page. - Select the Red Hat Advanced Cluster Security for Kubernetes Operator from the list of installed Operators.
If you have installed the Operator in the recommended namespace, OpenShift Container Platform lists the project as
rhacs-operator
. Select Project: rhacs-operatorCreate 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 therhacs-operator
andopenshift-operator
projects, or in the project in which you have installed the Red Hat Advanced Cluster Security for Kubernetes Operator.
-
If you have installed the Operator in a different namespace, OpenShift Container Platform shows the name of that namespace rather than
-
Enter the new project name (for example,
stackrox
), and click Create. Red Hat recommends that you usestackrox
as the project name. - Under the Provided APIs section, select Central. Click Create Central.
-
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. - Click Create.
If you are using the cluster-wide proxy, Red Hat Advanced Cluster Security for Kubernetes uses that proxy configuration to connect to the external services.
Next Steps
- Verify Central installation.
- Optional: Configure Central options.
- Generate an init bundle.
Additional resources
3.3. Verifying Central installation
After Central finishes installing, log in to the RHACS portal to verify the successful installation of Central.
Procedure
-
On the OpenShift Container Platform web console, navigate to the Operators
Installed Operators page. - Select the Red Hat Advanced Cluster Security for Kubernetes Operator from the list of installed Operators.
- Select the Central tab.
-
From the Centrals list, select
stackrox-central-services
to view its details. To get the password for the
admin
user, you can either:- Click the link under Admin Password Secret Reference.
Use the OpenShift Container Platform CLI to enter the command listed under Admin Credentials Info:
$ oc -n stackrox get secret central-htpasswd -o go-template='{{index .data "password" | base64decode}}'
Find the link to the RHACS portal by using the OpenShift Container Platform 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:
-
Navigate to Networking
Routes. - Find the central Route and click on the RHACS portal link under the Location column.
-
Navigate to Networking
-
Log in to the RHACS portal using the username admin and the password that you retrieved in a previous step. Until Red Hat Advanced Cluster Security for Kubernetes is completely configured (for example, you have the
Central
resource and at least oneSecuredCluster
resource installed and configured), no data is available in the dashboard. TheSecuredCluster
resource can be installed and configured on the same cluster as theCentral
resource. Clusters with theSecuredCluster
resource are similar to managed clusters in Red Hat Advanced Cluster Management (RHACM).
Next Steps
- Optional: Configure central settings.
-
Generate an init bundle containing the cluster secrets that allows communication between the
Central
andSecuredCluster
resources. You need to download this bundle, use it to generate resources on the clusters you want to secure, and securely store it.
3.4. Central configuration options
When you create a Central instance, the Operator lists the following configuration options for the Central
custom resource.
3.4.1. Central settings
Parameter | Description |
---|---|
|
Specify a secret that contains the administrator password in the |
| By default, Central only serves an internal TLS certificate, which means that you need to handle TLS termination at the ingress or load balancer level. If you want to terminate TLS in Central and serve a custom server certificate, you can specify a secret containing the certificate and private key. |
|
Set this parameter to |
| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Central. This parameter is mainly used for infrastructure nodes. |
|
Set this to |
| Use this parameter to specify a custom port for your load balancer. |
| Use this parameter to specify a static IP address reserved for your load balancer. |
|
Set this to |
|
Set this to |
| Use this to specify an explicit node port. |
| If you want this component to only run on specific nodes, you can configure a node selector by using this parameter. |
| Specify a host path to store persistent data in a directory on the host. Red Hat does not recommend using this. If you need to use host path, you must use it with a node selector. |
|
The name of the PVC to manage persistent data. If no PVC with the given name exists, it will be created. The default value is |
| The size of the persistent volume when created through the claim. This is automatically generated by default. |
| The name of the storage class to use for the PVC. If your cluster is not configured with a default storage class, you must provide a value for this parameter. |
| Use this parameter to override the default resource limits for the Central. |
| Use this parameter to override the default resource requests for the Central. |
| Use this parameter to specify the image pull secrets for the Central image. |
3.4.2. Scanner settings
Parameter | Description |
---|---|
| If you want this scanner to only run on specific nodes, you can configure a node selector by using this parameter. |
| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Scanner. This parameter is mainly used for infrastructure nodes. |
| Use this parameter to override the default resource limits for the scanner. |
| Use this parameter to override the default resource requests for the scanner. |
| When enabled, the number of analyzer replicas is managed dynamically based on the load, within the limits specified. |
| Specifies the maximum replicas to be used the analyzer autoscaling configuration |
| Specifies the minimum replicas to be used the analyzer autoscaling configuration |
| When autoscaling is disabled, the number of replicas will always be configured to match this value. |
| If you want this component to only run on specific nodes, you can configure a node selector by using this parameter. |
| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Scanner DB. This parameter is mainly used for infrastructure nodes. |
| Use this parameter to override the default resource limits for the scanner. |
| Use this parameter to override the default resource requests for the scanner. |
| If you do not want to deploy Scanner, you can disable it by using this parameter. If you disable Scanner, all other settings in this section have no effect. Red Hat does not recommend disabling Red Hat Advanced Cluster Security for Kubernetes Scanner. |
3.4.3. General and miscellaneous settings
Parameter | Description |
---|---|
| Additional Trusted CA certificates for the secured cluster to trust. This is typically used when integrating with services using a private certificate authority. |
|
Specify |
3.5. Generating an init bundle
Before you install the SecuredCluster
resource on a cluster, you must create an init bundle. The cluster that has SecuredCluster
installed and configured then uses this bundle to authenticate with Central.
You can create an init bundle by using the RHACS portal (recommended) or by using the roxctl CLI.
3.5.1. Generating an init bundle by using the RHACS portal
You can create an init bundle containing secrets by using the RHACS portal.
Procedure
Find the address of the RHACS portal based on your exposure method:
For a route:
$ oc get route central -n stackrox
For a load balancer:
$ oc get service central-loadbalancer -n stackrox
For port forward:
Run the following command:
$ oc port-forward svc/central 18443:443 -n stackrox
-
Navigate to
https://localhost:18443/
.
-
On the RHACS portal, navigate to Platform Configuration
Integrations. - Navigate to the Authentication Tokens section and click on Cluster Init Bundle.
- Click Generate bundle.
- Enter a name for the cluster init bundle and click Generate.
- Click Download Kubernetes Secret File to download the generated bundle.
Store this bundle securely because it contains secrets. You can use the same bundle to create multiple secured clusters.
Next Step
- Use the OpenShift Container Platform CLI to create resources using the init bundle.
- Install Red Hat Advanced Cluster Security for Kubernetes in all clusters that you want to monitor.
3.5.2. Generating an init bundle by using the roxctl CLI
You can create an init bundle with secrets by using the roxctl
CLI.
Prerequisites
You have configured the ROX_API_TOKEN
and the ROX_CENTRAL_ADDRESS
environment variables.
Set the
ROX_API_TOKEN
and theROX_CENTRAL_ADDRESS
environment variables:$ export ROX_API_TOKEN=<api_token>
$ export ROX_CENTRAL_ADDRESS=<address>:<port_number>
Procedure
Run the following command to generate a cluster init bundle containing secrets:
$ roxctl -e "$ROX_CENTRAL_ADDRESS" \ central init-bundles generate <cluster_init_bundle_name> \ --output-secrets cluster_init_bundle.yaml
Make sure that you store this bundle securely because it contains secrets. You can use the same bundle to set up multiple secured clusters.
3.5.3. Additional resources
3.6. Creating resources by using the init bundle
Before you install secured clusters, you must use the init bundle to create the required resources on the cluster that will allow the services on the secured clusters to communicate with Central.
Prerequisites
- You must have generated an init bundle containing secrets.
Procedure
Using the OpenShift Container Platform CLI, run the following command to create the resources:
$ oc create -f <init_bundle>.yaml \ 1 -n <stackrox> 2
Next Step
- Install Red Hat Advanced Cluster Security for Kubernetes in all clusters that you want to monitor.
3.7. Installing secured cluster services
You can install secured cluster services on your clusters by using the SecuredCluster
custom resource. You must install the secured cluster services on every cluster in your environment that you want to monitor.
To install Collector on systems that have Unified Extensible Firmware Interface (UEFI) and that have Secure Boot enabled, you must use eBPF probes because kernel modules are unsigned, and the UEFI firmware cannot load unsigned packages. Collector identifies Secure Boot status at the start and switches to eBPF probes if required.
Prerequisites
- You must be using OpenShift Container Platform 4.6 or later.
- You must have generated an init bundle and already created the required resources by using the init bundle.
Procedure
-
On the OpenShift Container Platform web console, navigate to the Operators
Installed Operators page. - Select the Red Hat Advanced Cluster Security for Kubernetes Operator from the list of installed operators.
By default, OpenShift Container Platform lists the project as
rhacs-operator
. Select Project: rhacs-operatorCreate project. WarningYou must install Red Hat Advanced Cluster Security for Kubernetes
SecuredCluster
resource in its own project and not the defaultopenshift-operators
project.- Enter the new project name as stackrox or some other name, and click Create.
- Under the Provided APIs section, select Secured Cluster.
- Choose Create SecuredCluster.
-
Enter a name for your
SecuredCluster
custom resource. -
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 ascentral.example.com:443
. The default value ofcentral.stackrox.svc:443
only works when you install secured cluster services and Central in the same cluster. - Accept the default values or configure custom values for the available options.
- Click Create.
Next step
- Optional: Configure additional secured cluster settings.
- Verify Red Hat Advanced Cluster Security for Kubernetes installation.
3.8. Secured cluster configuration options
When you create a Central instance, the Operator lists the following configuration options for the Central
custom resource.
3.8.1. Required Configuration Settings
Parameter | Description |
---|---|
|
The endpoint of Central instance to connect to, including the port number. If using a non-gRPC capable load balancer, use the WebSocket protocol by prefixing the endpoint address with |
| The unique name of this cluster, which shows up in the RHACS portal. After the name is set by using this parameter, you cannot change it again. To change the name, you must delete and recreate the object. |
3.8.2. Admission controller settings
Parameter | Description |
---|---|
|
Specify |
|
Specify |
|
Specify |
| If you want this component to only run on specific nodes, you can configure a node selector using this parameter. |
| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Admission Control. This parameter is mainly used for infrastructure nodes. |
| Use this parameter to override the default resource limits for the admission controller. |
| Use this parameter to override the default resource requests for the admission controller. |
| Use one of the following values to configure the bypassing of admission controller enforcement:
The default value is |
| Use one of the following values to specify if the admission controller must connect to the image scanner:
The default value is |
| Use this parameter to specify the maximum number of seconds Red Hat Advanced Cluster Security for Kubernetes must wait for an admission review before marking it as fail open. |
3.8.3. Scanner configuration
Use Scanner configuration settings to modify the local cluster scanner for the OpenShift Container Registry (OCR).
Parameter | Description |
---|---|
|
Specify a node selector label as |
| The memory request for the Scanner container. Use this parameter to override the default value. |
| The CPU request for the Scanner container. Use this parameter to override the default value. |
| The memory limit for the Scanner container. Use this parameter to override the default value. |
| The CPU limit for the Scanner container. Use this parameter to override the default value. |
|
If you set this option to |
|
The minimum number of replicas for autoscaling. The default value is |
|
The maximum number of replicas for autoscaling. The default value is |
|
The default number of replicas. The default value is |
| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Scanner. |
|
Specify a node selector label as |
| The memory request for the Scanner DB container. Use this parameter to override the default value. |
| The CPU request for the Scanner DB container. Use this parameter to override the default value. |
| The memory limit for the Scanner DB container. Use this parameter to override the default value. |
| The CPU limit for the Scanner DB container. Use this parameter to override the default value. |
| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Scanner DB. |
|
If you set this option to |
3.8.4. Image configuration
Use image configuration settings when you are using a custom registry.
Parameter | Description |
---|---|
| Additional image pull secrets to be taken into account for pulling images. |
3.8.5. Per node settings
Per node settings define the configuration settings for components that run on each node in a cluster to secure the cluster. These components are Collector and Compliance.
Parameter | Description |
---|---|
|
The method for system-level data collection. The default value is |
|
The image type to use for Collector. You can specify it as |
| Use this parameter to override the default resource limits for Collector. |
| Use this parameter to override the default resource requests for Collector. |
| Use this parameter to override the default resource requests for Compliance. |
| Use this parameter to override the default resource limits for Compliance. |
3.8.6. Taint Tolerations settings
Parameter | Description |
---|---|
|
To ensure comprehensive monitoring of your cluster activity, Red Hat Advanced Cluster Security for Kubernetes runs services on every node in the cluster, including tainted nodes by default. If you do not want this behavior, specify |
3.8.7. Sensor configuration
This configuration defines the settings of the Sensor components, which runs on one node in a cluster.
Parameter | Description |
---|---|
| If you want Sensor to only run on specific nodes, you can configure a node selector. |
| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Sensor. This parameter is mainly used for infrastructure nodes. |
| Use this parameter to override the default resource limits for Sensor. |
| Use this parameter to override the default resource requests for Sensor. |
3.8.8. General and miscellaneous settings
Parameter | Description |
---|---|
| Additional trusted CA certificates for the secured cluster. These certificates are used when integrating with services using a private certificate authority. |
|
Set this to |
| Allows specifying custom annotations for the Central deployment. |
| Advanced settings to configure environment variables. |
| Configures whether Red Hat Advanced Cluster Security for Kubernetes should run in online or offline mode. In offline mode, automatic updates of vulnerability definitions and kernel modules are disabled. |
3.9. 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:
Find the address of the RHACS portal based on your exposure method:
For a route:
$ oc get route central -n stackrox
For a load balancer:
$ oc get service central-loadbalancer -n stackrox
For port forward:
Run the following command:
$ oc port-forward svc/central 18443:443 -n stackrox
-
Navigate to
https://localhost:18443/
.
Using the OpenShift Container Platform CLI, create a new project:
$ oc new-project test
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.
3.10. Adding a new cluster to RHACS
To add more clusters to Red Hat Advanced Cluster Security for Kubernetes, you must install the Red Hat Advanced Cluster Security for Kubernetes Operator in every cluster that you want to add.
The following steps represent the high-level flow for adding additional clusters to Red Hat Advanced Cluster Security for Kubernetes:
- Install the Red Hat Advanced Cluster Security for Kubernetes Operator in your cluster.
- Use an existing init bundle or generate a new init bundle.
- Create resources in your cluster by using the init bundle.
- Install secured cluster services on your cluster.