Quick Start (Helm)

Install the StackRox Kubernetes Security Platform by using Helm.

This guide describes step-by-step instructions for installing the StackRox Kubernetes Security Platform by using Helm and conducting simple tests using sample container images.

StackRox installs as a set of services in your Kubernetes cluster. You can use the same central installation to secure multiple clusters.

If you want to upgrade from an existing version to a newer version, see Upgrade StackRox.

Prerequisites

To install the StackRox Kubernetes Security Platform, you need:

  • A Kubernetes or OpenShift cluster.

    See the supported platforms topic to learn more about the operating systems, container platforms, and managed Kubernetes services that we support.

    We don’t support:

    • installing the StackRox Kubernetes Security Platform on Minikube and other similar single-node clusters.
    • Amazon Elastic File System (Amazon EFS), use the Amazon Elastic Block Store (Amazon EBS) with the default gp2 volume type instead.
    • older CPUs that don’t have the Streaming SIMD Extensions (SSE) 4.2 instruction set, for example Intel processors older than Sandy Bridge and AMD processors older than Bulldozer. (Both of these processors were released in 2011.)
  • Cluster nodes with:

    • Operating system: Amazon Linux, CentOS, Container-Optimized OS from Google, CoreOS, Debian, Red Hat Enterprise Linux, or Ubuntu.

    • Processor and memory: 2 CPU cores and at least 3GiB of RAM.

      For deploying Central, we recommend that you use a machine type with 4 or more cores and apply scheduling policies to launch Central on such nodes.

  • Persistent storage by using PersistentVolumeClaim (pvc) or hostPath.

    • Use the host-mounted storage only if all your hosts (or a group of hosts) mount a shared filesystem, such as an NFS share or a storage appliance. Otherwise, your data is only saved on a single node.

    • We recommend using Solid-State Drives (SSDs) for best performance. However, you can use another storage type if you don’t have SSDs available.

    • To use an SSD on Google Kubernetes Engine (GKE), you must use an SSD StorageClass. You can use an existing StorageClass, or you can create a new StorageClass before running the installer.

      For example, to create a StorageClass, run the following command:

      Copy
      kubectl apply -f - <<EOF
      apiVersion: storage.k8s.io/v1
      kind: StorageClass
      metadata:
        name: ssd
      provisioner: kubernetes.io/gce-pd
      parameters:
        type: pd-ssd
      EOF

      Once done, you can specify the StorageClass name as ssd while answering the installer prompts.

  • A system with the kubectl (Kubernetes) command-line tool.

  • Helm command-line interface (CLI) v3.2 or newer. Use the helm version command to verify the version of Helm you have installed.

For detailed system-level requirements, see Resource requirements.

Permissions
  1. You must have the required permissions to configure Deployments in the central cluster.
  2. To secure a cluster, you must have permissions to configure Deployments, DaemonSets, ClusterRoleBindings, RoleBindings, and ServiceAccounts in that cluster.

Install the StackRox Kubernetes Security Platform

The StackRox Kubernetes Security Platform installs as a set of containers in your Kubernetes or OpenShift cluster and includes the multiple components. The main software component of the StackRox Kubernetes Security Platform is called Central. To learn about the components that make up the StackRox Kubernetes Security Platform, see StackRox architecture.

Install Central with Helm

Get the Helm chart

If you haven’t done so yet:

  1. Add the StackRox Kubernetes Security Platform charts repository.

    Copy
    helm repo add rhacs https://mirror.openshift.com/pub/rhacs/charts/
  2. Run the following command to verify the added chart repository:

    Copy
    helm search repo -l rhacs/

    Otherwise, make sure you have the latest version of the charts repository on your local machine.

    Copy
    helm repo update

StackRox charts are also available at https://charts.stackrox.io/.

Install the chart

The following instructions assume that you want to deploy StackRox without any customizations applied.

For customizing your deployment:

You can install using several exposure methods:

  1. To expose using port forwarding run the following command:

    Copy
    helm install -n stackrox --create-namespace stackrox-central-services rhacs/central-services --set imagePullSecrets.allowNone=true
  2. To expose using an OpenShift route run the following command:

    Copy
    helm install -n stackrox --create-namespace stackrox-central-services rhacs/central-services --set imagePullSecrets.allowNone=true --set central.exposure.route.enabled=true
  3. To expose using a load balancer run the following command:

    Copy
    helm install -n stackrox --create-namespace stackrox-central-services rhacs/central-services --set imagePullSecrets.allowNone=true --set central.exposure.loadBalancer.enabled=true

After a short waiting period, you should see a message appear on your screen informing you of any warnings encountered or things to note. It will also contain the generated administrator password and instructions on storing all the configuration values that Helm has generated automatically.

  1. To access central using the load balancer use the external IP address from the following command:

    Copy
    kubectl get service central-loadbalancer -n stackrox
  2. To access central using port forwarding run the following command and navigate to https://localhost:18443:

    Copy
    kubectl -n stackrox port-forward svc/central 18443:443
  3. To access central using an OpenShift route find the route using the following command:

    Copy
    oc get route central -n stackrox

Log in by using the generated password displayed in the terminal after running the helm install command and the default username admin.

Basic Configuration

The following are examples of a few more configurable parameters you can use. To view all available configurable parameters, see the Helm chart configuration topic.

  1. Offline mode: Specify true for the env.offlineMode parameter if you want to use the StackRox Kubernetes Security Platform in offline mode.

  2. Online telemetry: To disable online telemetry data collection, set the central.disableTelemetry parameter to true.

  3. Exposure: To expose StackRox Central via a Kubernetes load balancer service, set the central.exposure.loadBalancer.enabled parameter to true.

  4. Custom TLS certificate: To use custom TLS certificate with the StackRox Kubernetes Security Platform, use the central.defaultTLS.cert and central.defaultTLS.key parameters.

For example, to deploy StackRox Central exposed via a load balancer service, and using the TLS certificate and private key stored in the files /path/to/tls-cert.pem and /path/to/tls-key.pem, respectively, run the following command:

Copy
helm install -n stackrox --create-namespace \
  stackrox-central-services rhacs/central-services \
  --set imagePullSecrets.allowNone=true \
  --set central.exposure.loadBalancer.enabled=true \
  --set-file central.defaultTLS.cert=/path/to/tls-cert.pem \
  --set-file central.defaultTLS.key=/path/to/tls-key.pem

As you can see, helm install command line invocations can get long if you need to customize your configuration. For this reason, we recommend storing your configuration in Helm chart configuration files instead.

Making changes to an existing deployment

If you want to make a modification to your existing StackRox Central deployment, such as enabling offline mode, run the following command:

Copy
helm upgrade -n stackrox --create-namespace \
  stackrox-central-services stackrox/central-services \
  --reuse-values \
  --set env.offlineMode=true

Pay close attention to include the --reuse-values parameter. If you omit it, all the previously configured settings will be reset.

Install Secured Cluster Services

To monitor a cluster, you must deploy the secured cluster services.

To install Sensor by using Helm charts for the StackRox Kubernetes Security Platform:

Before you begin if you haven’t already, add the StackRox helm chart repository.

  1. Add the StackRox Helm chart repository:
    Copy
    helm repo add rhacs https://mirror.openshift.com/pub/rhacs/charts/
  2. Run the helm repository update command:
    Copy
    helm repo update
  1. Generate an authentication token and create the following environment variables:

    Copy
    export ROX_API_TOKEN=<api-token>
    export ROX_CENTRAL_ADDRESS=<address>:<port-number>
  2. Generate a cluster init bundle.

    • Using the roxctl CLI:

      Copy
      roxctl -e "$ROX_CENTRAL_ADDRESS" central init-bundles generate <cluster-init-bundle-name> --output cluster-init-bundle.yaml
      • Running this command creates a cluster init bundle called cluster-init-bundle.yaml.
      • Make sure that you store this bundle securely as it contains secrets. You can use the same bundle to set up multiple StackRox secured clusters.
    • Using the StackRox portal:

    1. Navigate to Platform Configuration > Integrations.

    2. Under the Authentication Tokens section, select Cluster Init Bundle.

    3. Select Generate Bundle (add icon +) on the top right.

    4. Enter a name for the cluster init bundle and select Generate.

    5. Select Download Helm Values File to download the generated bundle.

    6. Navigate to Platform Configuration > Clusters.

    7. Select New Cluster on the top right.

    8. Enter a name for the cluster init bundle and select Generate.

    9. Select Download Helm Values File to download the generated bundle.

  3. Run the following command to deploy a sensor:

    Copy
     helm install -n stackrox --create-namespace stackrox-secured-cluster-services rhacs/secured-cluster-services \
      -f <name-of-cluster-init-bundle.yaml> \
      --set centralEndpoint=<endpoint-of-Central-service> \
      --set clusterName=<name-of-the-secured-cluster> \
      --set imagePullSecrets.allowNone=true

To view all available configurable parameters, see the Helm chart configuration topic.

If you want to deploy secured cluster services by using a continuous integration (CI) system. You can pass the init bundle YAML file as an environment variable to the helm install command as follows:

Copy
helm install ... -f <(echo "$INIT_BUNDLE_YAML_SECRET")

or, if variable contents are Base64 encoded

Copy
helm install ... -f <(echo "$INIT_BUNDLE_YAML_SECRET" | base64 --decode)

For more details about the --set parameter and other configuration options, see the StackRox Helm chart repository.

Your cluster is now reporting security information to the StackRox Kubernetes Security Platform.

Your Dashboard will begin to show deployments, images, and policy violations from the cluster.

Verify installation

After you complete the installation and configure necessary integrations, run sample applications to evaluate the results of security assessments and policy violations.

The sample applications described below are specifically designed to verify the build and deploy-time assessment features of the StackRox Kubernetes Security Platform.

To run the sample application:

  1. Create a new namespace (or project).

    Copy
    kubectl create ns test
  2. Start a few workloads with critical vulnerabilities:

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

    The StackRox Kubernetes Security Platform automatically scans these deployments for security risk and policy violations as soon as they’re submitted to the cluster.

Questions?

We're happy to help! Reach out to us to discuss questions, issues, or feature requests.

© 2021 StackRox Inc. All rights reserved.