This is a cache of https://docs.openshift.com/acs/3.68/installing/install-ocp-operator.html. It is a snapshot of the page at 2024-11-29T17:25:15.089+0000.
Installing by using an Operator | Installing | Red Hat Advanced Cluster Security for Kubernetes 3.68
    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 an Operator

Red Hat Advanced Cluster Security for Kubernetes (RHACS) installs a set of services on your OpenShift Container Platform cluster. This section describes the installation procedure for installing Red Hat Advanced Cluster Security for Kubernetes on your OpenShift Container Platform cluster by using an Operator.

Before you install:

The Red Hat Advanced Cluster Security for Kubernetes Operator includes the following two custom resources:

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

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

  1. Install the Red Hat Advanced Cluster Security for Kubernetes Operator from OperatorHub in the cluster where you want to install Central.

  2. Configure and deploy the Central custom resource.

  3. Generate and apply an init bundle.

  4. Install the Red Hat Advanced Cluster Security for Kubernetes Operator in all clusters that you want to monitor.

  5. Configure and deploy the SecuredCluster custom resource in all clusters that you want to monitor.

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

  1. Navigate in the web console to the Operators → OperatorHub page.

  2. 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 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. 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.

  6. 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.

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

  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.

    • 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 Create instance on the Central API.

  6. 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.

  7. 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.
Additional resources

Verifying Central installation

After Central finishes installing, log in to the RHACS portal to verify the successful installation of Central.

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. The Admin Credentials Info section lists the command you need to run to get the autogenerated password. Run the command to get your admin password.

  6. Navigate to Networking → Routes.

  7. Find the central Route and click on the RHACS portal link under the Location column.

  8. Log in to the RHACS portal using the username admin and the autogenerated password.

Central configuration options

When you create a Central instance, the Operator lists the following configuration options for the Central custom resource.

Central settings

Parameter Description

central.adminPasswordSecret

Specify a secret that contains the administrator password in the password data item. If omitted, the operator autogenerates a password and store it in the password item in the central-htpasswd secret.

central.defaultTLSSecret

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.

central.adminPasswordGenerationDisabled

Set this parameter to true to disable the automatic administrator password generation. Use this only after you perform the first-time setup of alternative authentication methods. Do not use this for initial installation. Otherwise, you must reinstall the custom resource to log back in.

central.tolerations

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.

central.exposure.loadBalancer.enabled

Set this to true to expose Central through a load balancer.

central.exposure.loadBalancer.port

Use this parameter to specify a custom port for your load balancer.

central.exposure.loadBalancer.ip

Use this parameter to specify a static IP address reserved for your load balancer.

central.exposure.route.enabled

Set this to true to expose Central through an OpenShift route. The default value is false.

central.exposure.nodeport.enabled

Set this to true to expose Central through a node port. The default value is false.

central.exposure.nodeport.port

Use this to specify an explicit node port.

central.nodeSelector

If you want this component to only run on specific nodes, you can configure a node selector by using this parameter.

central.persistence.hostPath.path

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.

central.persistence.persistentVolumeClaim.claimName

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 stackrox-db if not set. To prevent data losses the PVC is not removed automatically with Central`s deletion.

central.persistence.persistentVolumeClaim.size

The size of the persistent volume when created through the claim. This is automatically generated by default.

central.persistence.persistentVolumeClaim.storageClassName

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.

central.resources.limits

Use this paramter to override the default resource limits for the Central.

central.resources.requests

Use this parameter to override the default resource requests for the Central.

central.imagePullSecrets

Use this parameter to specify the image pull secrets for the Central image.

Scanner settings

Parameter Description

scanner.analyzer.nodeSelector

If you want this scanner to only run on specific nodes, you can configure a node selector by using this parameter.

scanner.analyzer.tolerations

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.

scanner.analyzer.resources.limits

Use this parameter to override the default resource limits for the scanner.

scanner.analyzer.resources.requests

Use this parameter to override the default resource requests for the scanner.

scanner.analyzer.scaling.autoScaling

When enabled, the number of analyzer replicas is managed dynamically based on the load, within the limits specified.

scanner.analyzer.scaling.maxReplicas

Specifies the maximum replicas to be used the analyzer autoscaling configuration

scanner.analyzer.scaling.minReplicas

Specifies the minimum replicas to be used the analyzer autoscaling configuration

scanner.analyzer.scaling.replicas

When autoscaling is disabled, the number of replicas will always be configured to match this value.

scanner.db.nodeSelector

If you want this component to only run on specific nodes, you can configure a node selector by using this parameter.

scanner.db.tolerations

If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for ScannerDB. This parameter is mainly used for infrastructure nodes.

scanner.db.resources.limits

Use this parameter to override the default resource limits for the scanner.

scanner.db.resources.requests

Use this parameter to override the default resource requests for the scanner.

scanner.scannerComponent

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.

General and miscellaneous settings

Parameter Description

tls.additionalCAs

Additional Trusted CA certificates for the secured cluster to trust. This is typically used when integrating with services using a private certificate authority.

misc.createSCCs

Specify true to create SCCs for Central. It might cause issues in some environments.

Generating an init bundle

To create a secured cluster, you must create an init bundle. The secured cluster uses this bundle to authenticate with Central.

You can create an init bundle by using the the roxctl CLI or from the RHACS portal.

Generating an init bundle by using the RHACS portal

You can create an init bundle by using the RHACS portal.

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. Under the Authentication Tokens section, click on Cluster Init Bundle.

  4. Click Generate bundle.

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

  6. 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.

Generating an init bundle by using the roxctl CLI

You can create an init bundle by using the the roxctl CLI.

Prerequisites

  • You have configured the ROX_API_TOKEN and the ROX_CENTRAL_ADDRESS environment variables.

Procedure

  • Run the following command to generate a cluster init bundle:

    $ 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.

Additional resources

Creating resources by using the init bundle

Before you install secured clusters, you must create the required resources.

Prerequisities

  • You must have generated an init bundle.

Procedure

  • Run the following command to create the resources:

    $ oc create -f <init_bundle>.yaml \ (1)
  -n <stackrox> (2)
    1 Specify the init bundle file name.
    2 Specify the name of the project where you installed Central.

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 configured with Unified Extensible Firmware Interface (UEFI) boot, you must use eBPF probes because kernel modules are unsigned, and the UEFI firmware cannot load unsigned packages.
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

  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 form the list of installed operators.

  3. By default, OpenShift Container Platform lists the project as openshift-operator. Select Project: openshift-operator → Create project.

    You must install Red Hat Advanced Cluster Security for Kubernetes SecuredCluster resource in its own project and not the default openshift-operators project.

  4. Enter the new project name as stackrox or some other name, and click Create.

  5. Under the Provided APIs section, select Create instance on the Secured Cluster API.

  6. Enter a name for your SecuredCluster custom resource.

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

  8. Accept the default values or configure custom values for the avilable options.

  9. Click Create.

Secured cluster configuration options

When you create a Central instance, the Operator lists the following configuration options for the Central custom resource.

Required Configuration Settings

Parameter Description

centralEndpoint

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 wss://. If you do not specify a value for this paramter, Sensor attempts to connect to a Central instance running in the same namespace.

clusterName

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.

Admission controller settings

Parameter Description

admissionControl.listenOnCreates

Specify true to enable preventive policy enforcement for object creations. The default value is false.

admissionControl.listenOnEvents

Specify true to enable monitoring and enforcement for Kubernetes events, such as port-forward and exec events. It is used to control access to resources through the Kubernetes API. The default value is true.

admissionControl.listenOnUpdates

Specify true to enable preventive policy enforcement for object updates. It will not have any effect unless Listen On Creates is set to true as well. The default value is false.

admissionControl.nodeSelector

If you want this component to only run on specific nodes, you can configure a node selector using this parameter.

admissionControl.tolerations

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.

admissionControl.resources.limits

Use this parameter to override the default resource limits for the admission controller.

admissionControl.resources.requests

Use this parameter to override the default resource requests for the admission controller.

admissionControl.bypass

Use one of the following values to configure the bypassing of admission controller enforcement:

  • BreakGlassAnnotation to enable bypassing the admission controller via the admission.stackrox.io/break-glass annotation.

  • Disabled to disable the ability to bypass admission controller enforcement for the secured cluster.

The default value is BreakGlassAnnotation.

admissionControl.contactImageScanners

Use one of the following values to specify if the admission controller must connect to the image scanner:

  • ScanIfMissing if the scan results for the image are missing.

  • DoNotScanInline to skip scanning the image when processing the admission request.

The default value is DoNotScanInline.

admissionControl.timeoutSeconds

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.

Image configuration

Use image configuration settings when you are using a custom registry.

Parameter Description

imagePullSecrets.name

Additional image pull secrets to be taken into account for pulling images.

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

perNode.collector.collection

The method for system-level data collection. The default value is KernelModule. Red Hat recommend using KernelModule as the value for this parameter. If you select NoCollection, you will not be able to see any information about network activity and process executions. Options include NoCollection, EBPF, and KernelModule.

perNode.collector.imageFlavor

The image type to use for Collector. You can specify it as Regular or Slim. Regular images are bigger in size, but contain kernel modules for most kernels. If you use the Slim image type, you must ensure that your Central instance is connected to the internet, or regularly receives Collector support package updates. The default value is Slim.

perNode.collector.resources.limits

Use this parameter to override the default resource limits for Collector.

perNode.collector.resources.requests

Use this parameter to override the default resource requests for Collector.

perNode.compliance.resources.requests

Use this parameter to override the default resource requests for Compliance.

perNode.compliance.resources.limits

Use this parameter to override the default resource limits for Compliance.

Taint Tolerations settings

Parameter Description

taintToleration

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 AvoidTaints for this parameter.

Sensor configuration

This configuration defines the settings of the Sensor components, which runs on one node in a cluster.

Parameter Description

sensor.nodeSelector

If you want Sensor to only run on specific nodes, you can configure a node selector.

sensor.tolerations

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.

sensor.resources.limits

Use this parameter to override the default resource limits for Sensor.

sensor.resources.requests

Use this parameter to override the default resource requests for Sensor.

General and miscellaneous settings

Parameter Description

tls.additionalCAs

Additional trusted CA certificates for the secured cluster. These certificates are used when integrating with services using a private certificate authority.

misc.createSCCs

Set this to true to create SCCs for Central. It may cause issues in some environments.

customize.annotations

Allows specifying custom annotations for the Central deployment.

customize.envVars

Advanced settings to configure environment variables.

egress.connectivityPolicy

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.

Verifying installation

After you complete the installation, navigate to the RHACS portal and run a few vulnerable applications 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.

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

  4. 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.

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:

  1. Install the Red Hat Advanced Cluster Security for Kubernetes Operator in your cluster.

  2. Use an existing init bundle or generate a new init bundle.

  3. Create resources in your cluster by using the init bundle.

  4. Install secured cluster services on your cluster.