|
| 1 | +# StackRox Kubernetes Security Platform - Central Services Helm Chart |
| 2 | + |
| 3 | +This Helm chart allows you to deploy the central services of the StackRox |
| 4 | +Kubernetes Security Platform: StackRox Central and StackRox Scanner. |
| 5 | + |
| 6 | +If you want to install Red Hat Advanced Cluster Security, refer to |
| 7 | +[Installing quickly using Helm charts](https://docs.openshift.com/acs/installing/installing_helm/install-helm-quick.html) |
| 8 | +for up to date information. |
| 9 | + |
| 10 | +## Prerequisites |
| 11 | + |
| 12 | +To deploy the central services for the StackRox Kubernetes Security platform |
| 13 | +using Helm, you must: |
| 14 | +- Have at least version 3.1 of the Helm tool installed on your machine |
| 15 | + |
| 16 | +## Add the Canonical Chart Location as a Helm Repository |
| 17 | + |
| 18 | +The canonical repository for StackRox Helm charts is https://raw.githubusercontent.com/stackrox/helm-charts/main/opensource/. |
| 19 | +To use StackRox Helm charts on your machine, run |
| 20 | +```sh |
| 21 | +helm repo add stackrox https://raw.githubusercontent.com/stackrox/helm-charts/main/opensource/ |
| 22 | +``` |
| 23 | +This command only needs to be run once on your machine. Whenever you are deploying |
| 24 | +or upgrading a chart from a remote repository, it is advisable to run |
| 25 | +```sh |
| 26 | +helm repo update |
| 27 | +``` |
| 28 | +beforehand. |
| 29 | + |
| 30 | +## Deploy Central Services Using Helm |
| 31 | + |
| 32 | +The basic command for deploying the central services is |
| 33 | +```sh |
| 34 | +helm install -n stackrox --create-namespace \ |
| 35 | + stackrox-central-services stackrox/stackrox-central-services |
| 36 | +``` |
| 37 | +If you have a copy of this chart on your machine, you can also reference the |
| 38 | +path to this copy instead of `stackrox/stackrox-central-services` above. |
| 39 | + |
| 40 | +In case you use image mirroring or otherwise access StackRox container images from non-standard location, |
| 41 | +you may also need to provide image pull credentials. |
| 42 | +There are several ways to inject the required credentials (if any) into the installation process: |
| 43 | + |
| 44 | +- **Explicitly specify username and password:** Use this if you are using a registry that supports username/password |
| 45 | + authentication. Pass the following arguments to the `helm install` command: |
| 46 | + ```sh |
| 47 | + --set imagePullSecrets.username=<registry username> --set imagePullSecrets.password=<registry password> |
| 48 | + ``` |
| 49 | +- **Use pre-existing image pull secrets:** If you already have one or several image pull secrets |
| 50 | + created in the namespace to which you are deploying, you can reference these in the following |
| 51 | + way (we assume that your secrets are called `pull-secret-1` and `pull-secret-2`): |
| 52 | + ```sh |
| 53 | + --set imagePullSecrets.useExisting="pull-secret-1;pull-secret-2" |
| 54 | + ``` |
| 55 | +- **Do not use image pull secrets:** If you are pulling your images from quay.io/stackrox-io or a registry in a private |
| 56 | + network that does not require authentication, or if the default service account in the namespace |
| 57 | + to which you are deploying is already configured with appropriate image pull secrets, you do |
| 58 | + not need to specify any additional image pull secrets. |
| 59 | + |
| 60 | +### Accessing the StackRox Portal After Deployment |
| 61 | + |
| 62 | +Once you have deployed the StackRox Kubernetes Security Platform Central Services via |
| 63 | +`helm install`, you will see an information text on the console that contains any things to |
| 64 | +note, or warnings encountered during the installation text. In particular, it instructs you |
| 65 | +how to connect to your Central deployment via port-forward (if you have not configured an |
| 66 | +exposure method, see below), and the administrator password to use for the initial login. |
| 67 | + |
| 68 | +### Applying Custom Configuration Options |
| 69 | + |
| 70 | +This Helm chart has many different configuration options. For simple use cases, these can be |
| 71 | +set directly on the `helm install` command line; however, we generally recommend that you |
| 72 | +store your configuration in a dedicated file. |
| 73 | + |
| 74 | +#### Using the `--set` family of command-line flags |
| 75 | + |
| 76 | +This approach is the quickest way to customize the deployment, but it does not work for |
| 77 | +more complex configuration settings. Via the `--set` and `--set-file` flags, which need to be |
| 78 | +appended to your `helm install` invocation, you can inject configuration values into the |
| 79 | +installation process. Here are some examples: |
| 80 | +- **Deploy StackRox in offline mode:** This configures StackRox in a way such that it will not |
| 81 | + reach out to any external endpoints. |
| 82 | + ```sh |
| 83 | + --set env.offlineMode=true |
| 84 | + ``` |
| 85 | +- **Configure a fixed administrator password:** This sets the password with which you log in to |
| 86 | + the StackRox portal as an administrator. If you do not configure a password yourself, one will |
| 87 | + be created for you and printed as part of the installation notes. |
| 88 | + ```sh |
| 89 | + --set central.adminPassword.value=mysupersecretpassword |
| 90 | + ``` |
| 91 | + |
| 92 | +#### Using configuration YAML files and the `-f` command-line flag |
| 93 | + |
| 94 | +To ensure the best possible upgrade experience, it is recommended that you store all custom |
| 95 | +configuration options in two files: `values-public.yaml` and `values-private.yaml`. The former |
| 96 | +contains all non-sensitive configuration options (such as whether to run in offline mode), and the |
| 97 | +latter contains all sensitive configuration options (such as the administrator password, or |
| 98 | +custom TLS certificates). The `values-public.yaml` file can be stored in, for example, your Git |
| 99 | +repository, while the `values-private.yaml` file should be stored in a secrets management |
| 100 | +system. |
| 101 | + |
| 102 | +There is a large number of configuration options that cannot all be discussed in minute detail |
| 103 | +in this README file. However, the Helm chart contains example configuration files |
| 104 | +`values-public.yaml.example` and `values-private.yaml.example`, that list all the available |
| 105 | +configuration options, along with documentation. The following is just a brief example of what |
| 106 | +can be configured via those files: |
| 107 | +- **`values-public.yaml`:** |
| 108 | + ```yaml |
| 109 | + env: |
| 110 | + offlineMode: true # run in offline mode |
| 111 | + |
| 112 | + central: |
| 113 | + # Use custom resource overrides for central |
| 114 | + resources: |
| 115 | + requests: |
| 116 | + cpu: 4 |
| 117 | + memory: "8Gi" |
| 118 | + limits: |
| 119 | + cpu: 8 |
| 120 | + memory: "16Gi" |
| 121 | + |
| 122 | + # Expose central via a LoadBalancer service |
| 123 | + exposure: |
| 124 | + loadBalancer: |
| 125 | + enabled: true |
| 126 | + |
| 127 | + scanner: |
| 128 | + # Run without StackRox Scanner (NOT RECOMMENDED) |
| 129 | + disable: true |
| 130 | + |
| 131 | + scannerV4: |
| 132 | + # Enable Scanner V4, which will become the default scanner for StackRox. |
| 133 | + # Note that enabling Scanner V4 while having the StackRox Scanner disabled (scanner.disable=true) |
| 134 | + # is not a supported configuration. |
| 135 | + disable: false |
| 136 | + |
| 137 | + customize: |
| 138 | + # Apply the important-service=true label for all objects managed by this chart. |
| 139 | + labels: |
| 140 | + important-service: true |
| 141 | + # Set the CLUSTER=important-cluster environment variable for all containers in the |
| 142 | + # central deployment: |
| 143 | + central: |
| 144 | + envVars: |
| 145 | + CLUSTER: important-cluster |
| 146 | + ``` |
| 147 | +- **`values-private.yaml`**: |
| 148 | + ```yaml |
| 149 | + central: |
| 150 | + # Configure a default TLS certificate (public cert + private key) for central |
| 151 | + defaultTLS: |
| 152 | + cert: | |
| 153 | + -----BEGIN CERTIFICATE----- |
| 154 | + MII... |
| 155 | + -----END CERTIFICATE----- |
| 156 | + key: | |
| 157 | + -----BEGIN EC PRIVATE KEY----- |
| 158 | + MHc... |
| 159 | + -----END EC PRIVATE KEY----- |
| 160 | + ``` |
| 161 | + |
| 162 | +After you have created these YAML files, you can inject the configuration options into the |
| 163 | +installation process via the `-f` flag, i.e., by appending the following options to the |
| 164 | +`helm install` invocation: |
| 165 | +```sh |
| 166 | +-f values-public.yaml -f values-private.yaml |
| 167 | +``` |
| 168 | + |
| 169 | +### Changing Configuration Options After Deployment |
| 170 | + |
| 171 | +If you wish to make any changes to the deployment, simply change the configuration options |
| 172 | +in your `values-public.yaml` and/or `values-private.yaml` file(s), and inject them into an |
| 173 | +`helm upgrade` invocation: |
| 174 | +```sh |
| 175 | +helm upgrade -n stackrox stackrox-central-services stackrox/stackrox-central-services \ |
| 176 | + -f values-public.yaml \ |
| 177 | + -f values-private.yaml |
| 178 | +``` |
| 179 | +Under most circumstances, you will not need to supply the `values-private.yaml` file, unless |
| 180 | +you want changes to sensitive configuration options to be applied. |
| 181 | + |
| 182 | +Alternatively, you can also use the `--reuse-values` for the `helm upgrade` command. This flag |
| 183 | +causes values which were previously passed via `--values / -f`, `--set` or `--set-file` to be |
| 184 | +automatically passed again to the Helm chart rendering. |
| 185 | + |
| 186 | +### Passing Generated Values |
| 187 | + |
| 188 | +The Helm chart can conveniently automatically generate certain sensitive data objects. This includes |
| 189 | +passwords, keys and certificates. If these data objects were generated during the installation |
| 190 | +of the Helm chart, a command is provided as part of the post-installation notes which can be used |
| 191 | +for retrieving them and storing them in a file `generated-values.yaml`. This file |
| 192 | +might contain a CA key. |
| 193 | + |
| 194 | +If, during an upgrade of the Helm release, the Helm chart needs to generate a new certificate for |
| 195 | +some component, it is required to pass in the existing CA, for example by adding |
| 196 | +`-f generated-values.yaml` to the arguments for `helm upgrade`. |
| 197 | + |
| 198 | +### Enabling Scanner V4 |
| 199 | + |
| 200 | +Beginning with StackRox 4.4, a new scanner component based on ClairCore named Scanner V4 is integrated. |
| 201 | +In a future version of StackRox, Scanner V4 will become the new default scanner and replace the existing |
| 202 | +scanner named StackRox Scanner. Currently, Scanner V4 is not installed by default, but it |
| 203 | +can be enabled alongside StackRox Scanner using the following Helm chart setting: |
| 204 | + |
| 205 | +``` |
| 206 | +scannerV4: |
| 207 | + disable: false |
| 208 | +``` |
| 209 | + |
| 210 | +To enable Scanner V4 for an existing installation of this chart, the CA certificate |
| 211 | +and its key must be provided to the `helm upgrade` command. |
| 212 | +For example, if the CA was generated ahead of time and injected into the `helm install` command, then |
| 213 | +the `--reuse-values` flag for `helm upgrade` can be used to provide the certificate and key. However, if the CA was |
| 214 | +generated by the Helm chart at installation time, you must retrieve the generated secret |
| 215 | +values from the cluster (see above) and provide those to the `helm upgrade` command. |
| 216 | + |
| 217 | +Note that because Scanner V4 currently runs simultaneously with StackRox Scanner, your |
| 218 | +cluster must have sufficient computing resources available to host both scanner components at the same time. |
| 219 | +The default resource configuration for Scanner V4 components can be found in the file |
| 220 | +internal/defaults.yaml. |
0 commit comments