The legacy deploy scripts have served us well, but over time their configuration grew into a maze of environment variables scattered across many files, each subtly influencing deployment behavior. This makes them hard to maintain, hard to debug, and hard to reproduce deployment configurations easily.

roxie is the ACS/StackRox deployment tool intended to replace the deployment shell scripts entirely.

Its core idea is simple: It uses one self-contained configuration file for reproducible deployments, instead of implicitly picking up dozens of environment variables.

Installation of roxie is straightforward:

1. there are executables for released versions which can be fetched from https://github.com/stackrox/roxie/releases
2. with a properly set up Go dev environment, the roxie repo can be checked out and roxie can be built with make build or make install.
3. there is the script wrapper scripts/roxie.sh, which handles the downloading of roxie automatically under the hood.
4. there is also a containerized version of roxie living at quay.io/rhacs-eng/roxie, which can be used ad-hoc.

Furthermore, the deploy/deploy.sh shell script uses roxie under the hood. It will automatically download and run the roxie version specified in the ROXIE_VERSION file.

Any extra arguments you pass to deploy.sh are forwarded directly to roxie, so you can use roxie CLI flags even with deploy.sh, e.g.:

./deploy/deploy.sh --tag 4.11.0

The legacy deployment scripts will be removed entirely soon.

If you would like to use roxie directly, but roxie is not installed on your system, all roxie commands below can also be run via scripts/roxie.sh instead:

❯ ./scripts/roxie.sh --help

roxie is a fast, developer-friendly CLI to deploy and manage
Red Hat Advanced Cluster Security (ACS) on any Kubernetes/OpenShift cluster.

Usage:
  roxie [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  deploy      Deploy ACS components
  help        Help about any command
  logs        View logs for ACS components
  shell       Open a subshell for an existing ACS Central deployment
  teardown    Teardown ACS components
  version     Print version information

Flags:
      --dry-run   Do not actually modify cluster
  -h, --help      help for roxie
  -v, --verbose   Enable verbose output (show CRs)

Use "roxie [command] --help" for more information about a command.

roxie is designed as a standard CLI tool built around the notion of sub-commands. The following focuses on the most important commands and flags, for a complete description of roxies command line interface, please use roxie --help.

The old scripts picked up configuration from the shell environment -- feature flags, image tags, storage settings, and more. This is convenient at first, but becomes a maintenance burden: it's unclear which variables are active, what their defaults are, and whether your colleague's deployment matches yours.

With roxie, we intentionally do not inherit environment variables (apart from one: MAIN_IMAGE_TAG). Instead, all configuration lives in a YAML config file that you pass explicitly. This makes deployments self-documenting and reproducible.

Before (environment variables):

ROX_NETWORK_GRAPH_EXTERNAL_IPS=true ./deploy/deploy.sh

After (roxie CLI):

roxie deploy --features ROX_NETWORK_GRAPH_EXTERNAL_IPS

The --features flag accepts a comma-separated list. Prefix with - to disable:

roxie deploy --features ROX_NETWORK_GRAPH_EXTERNAL_IPS,-ROX_CISA_KEV

Via deploy.sh with roxie under the hood:

./deploy/deploy.sh --features ROX_NETWORK_GRAPH_EXTERNAL_IPS

One of the most important commands is roxie deploy <component>, where component can be one of

1. central
2. securedcluster
3. both

Note that specifying "both" is optional -- leaving it out does the same thing.

For example, to deploy the whole stack to your current cluster context use

roxie deploy [ <roxie args> ... ] --tag <main tag>

or alternatively

MAIN_IMAGE_TAG=<main tag> ./deploy/deploy.sh [ <roxie args> ... ]

roxie supports two distinct modes of operation:

1. Interactive mode: after deployment a sub-shell is spawned in which the environment is set up automatically for interacting with central (most importantly endpoint and authentication information).
2. Non-interactive mode: after the deployment the environmental information for communicating with central is written into an envrc-style file which can then be used by the user as desired -- sourced, propagated, etc.

There exist several flags for influencing the deployment behavior. With the exception of very few special flags, there exist corresponding fields in a "roxie config YAML file", which can be passed with --config. The config file has this structure:

roxie:
  version: "<a main image tag>" # The same as `MAIN_IMAGE_TAG` used in other places in this repo.
  konfluxImages: <bool> # Only use this if you need to deploy downstream images
                        # (Konflux building pipelines must have passed for this to work).
  featureFlags:
    ROX_FEATURE_FLAG_A: "true"
    ROX_FEATURE_FLAG_B: "false"
  clusterType: "<string representation of the cluster type>" # Usually not needed, since this is auto-detected.

operator:
  skipDeployment: <bool> # Useful when running the operator using `make -C operator run` locally
                         # and roxie shouldn't interfere with that.
  deployViaOlm: <bool> # By default roxie deploys without olm.
  version: "<string representation of the operator tag>" # This is usually derived from roxie.version.
  envVars:
    ENV_VAR_A: "Value for ENV_VAR_A"
    ENV_VAR_B: "Value for ENV_VAR_B"
    # Prominent use-case: Setting the RELATED_IMAGE_... variables within the operator to
    # overwrite specific image references. Can be used, for example, to test an updated main image while
    # using the other images corresponding to some other tag.

central:
  namespace: "<namespace>" # By default this is "acs-central". A different popular choice is "stackrox".
  resourceProfile: "<profile name>" # Leave empty for using ACS default settings for resources.
                                    # Often a good idea to use "auto".
                                    # Important to keep in mind that even on some standard infra cluster flavors
                                    # (e.g. openshift-4), the "medium" resourceProfile might lead to some
                                    # resource shortage.
  pauseReconciliation: <bool> # By default this is false. In case the operand resources shall be modifiable without
                              # the operator's reconciler kicking in, set this to true.
  exposure: "<exposure type>" # Usually this can be unset, letting roxie pick a reasonable default.
                              # Only "lb" is currently supported.
  deployTimeout: "<duration string>" # Unless earlyReadiness is disabled, this can usually be left unset.
  portForwarding: <bool> # Can be usually left unset, a sensible default will be selected.
  earlyReadiness: <bool> # Defaults to true, meaning that roxie only waits for the central deployment.
                         # If disabled, roxie will wait for all operand workloads to be ready.
                         # Usually requires a longer `deployTimeout` to be configured, depending on several
                         # environment properties (e.g. speed of the node disk type, influencing the DB
                         # initialization for scanner).
  spec: <map> # This is a verbatim overlay for the Central CR spec and allows arbitrary customization of the CR.

securedCluster:
  namespace: "<namespace>" # By default this is "acs-sensor". A different popular choice is "stackrox".
  resourceProfile: "<profile name>" # Leave empty for using ACS default settings for resources.
                                    # Often a good idea to use "auto".
                                    # Important to keep in mind that even on some standard infra cluster flavors
                                    # (e.g. openshift-4), the "medium" resourceProfile might lead to some
                                    # resource shortage.
  pauseReconciliation: <bool> # By default this is false. In case the operand resources shall be modifiable without
                              # the operator's reconciler kicking in, set this to true.
  deployTimeout: "<duration string>" # Unless earlyReadiness is disabled, this can usually be left unset.
  earlyReadiness: <bool> # Defaults to true, meaning that roxie only waits for the sensor deployment.
                         # If disabled, roxie will wait for all operand workloads to be ready.
                         # Usually requires a longer `deployTimeout` to be configured, depending on several
                         # environment properties (e.g. speed of the node disk type, influencing the DB
                         # initialization for scanner).
  spec: <map> # This is a verbatim overlay for the SecuredCluster CR spec and allows arbitrary customization of the CR.

Note that roxie also supports "user config", which is automatically loaded by the deploy command and contains overwritable defaults. On Linux systems the path of this user config file is usually ~/.config/roxie/config.yaml (or $XDG_CONFIG_HOME/roxie/config.yaml, if that environment variable is set). On darwin the path of the file is ~/Library/Application Support/roxie/config.yaml.

Most CLI flags of roxie implement short-cuts for certain patches of the in-memory representation of this deployment config. For example, for the roxie deploy command:

1. --tag/-t corresponds to roxie.version
2. --central-wait/--secured-cluster-wait corresponds to central.deployTimeout/securedCluster.deployTimeout.
3. --deploy-operator corresponds to operator.skipDeployment (negated).
4. --early-readiness corresponds to central.earlyReadiness/securedCluster.earlyReadiness.
5. --exposure corresponds to central.exposure.
6. --features corresponds to roxie.featureFlags.
7. --konflux corresponds to roxie.konfluxImages.
8. --olm corresponds to operator.deployViaOlm.
9. --pause-reconciliation corresponds to central.pauseReconciliation/securedCluster.pauseReconciliation.
10. --port-forwarding corresponds to central.portForwarding.
11. --resources corresponds to central.resourceProfile/securedCluster.resourceProfile.
12. --single-namespace sets central.namespace and securedCluster.namespace to stackrox.
13. --operator-env corresponds to operator.envVars.

These CLI flags are special in the sense that they do not correspond to a specific fields in the config file:

1. --set <YAML path>=<val> can be used for arbitrary patches to the in-memory deployment config.
2. --config/-c <file path> can be used for specifying a roxie config file for the deployment.
3. --envrc <path> enables non-interactive mode, writing post-deployment information into the specified envrc file instead of spawning a sub-shell.
4. --skip-user-config disables automatic loading of the user config file.
5. --image-preload-command <command> can be used for configuring an "image preloading command" for deploying only locally existing images onto a local cluster. Preloading support for kind and minikube clusters is already built in. For other local cluster solutions it might be necessary to specify a preloading command. The provided command string will be executed in a shell where $IMAGE is bound to the value of the image which needs to be sent to the local cluster.

For debugging purposes these flags might be helpful:

1. --dry-run do not actually deploy.
2. --verbose dump verbose information during operation, including final custom resources.

Another important roxie command is roxie teardown <component>, where component is one of

1. central
2. securedcluster
3. both (meaning central + securedcluster)
4. all (meaning both + operator)
5. operator (just operator)

We're actively improving roxie and would love your feedback! If you run into issues, have feature requests, or just want to share your experience, please reach out to the ACS Install team.