|
| 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. |
| 221 | + |
| 222 | +### Multiple Installations of Central |
| 223 | + |
| 224 | +Because the StackRox Central installation includes a `SecurityPolicy` custom resource definition (CRD) in its template, |
| 225 | +only one installation can "own" the CRD. This means that any other installation on the same cluster will fail to install if it tries to install the CRD with an error like: |
| 226 | + |
| 227 | + Error: INSTALLATION FAILED: Unable to continue with install: |
| 228 | + CustomResourceDefinition "securitypolicies.config.stackrox.io" in namespace "" exists and cannot be imported into the current release: |
| 229 | + invalid ownership metadata; annotation validation error: key "meta.helm.sh/release-name" must equal "my-release-name": |
| 230 | + current value is "stackrox-central-services"; annotation validation error: |
| 231 | + key "meta.helm.sh/release-namespace" must equal "my-namespace": |
| 232 | + current value is "stackrox" |
| 233 | + |
| 234 | +There is an option to exclude the CRD from the template, but there are a few other concerns to be aware of when managing multiple Central installations on one cluster: |
| 235 | + |
| 236 | +1. Upgrades to the first installation will also upgrade the CRD used by any other installation, introducing the potential for versioning mismatches. |
| 237 | +2. Uninstallation of the first installation will remove the CRD, thus removing all custom `SecurityPolicy` resources from ALL Central installations. |
| 238 | +3. Downgrading of the first installation could remove the CRD as well. |
| 239 | +4. These concerns are the responsiblity of the user to handle. Thus, multi-tenant CRD management issues are considered unsupported! |
| 240 | + |
| 241 | +If, after understanding these risks, you still want to install multiple Central installations on the same cluster using Helm, it can be done with the following flag: |
| 242 | + |
| 243 | + --set allowUnsupportedMultipleCentrals=documentationWasReadAndUnderstood |
| 244 | + |
| 245 | +Note that installing multiple Centrals is fully supported by default using the ACS operator. |
0 commit comments