Alauda Container Security

Alauda Security Service for StackRox Installation

This guide provides step-by-step instructions for installing the Alauda Security Service for StackRox.

TOC

Installation Requirements

  • Architecture: amd64
  • Kernel version: >=5.8
  • Resource requirements:
    • CPU: >=4
    • Memory: >=8GB
  • PostgreSQL: >=13
  • TLS Certificate

Download and Import

  1. Download the Alauda Security Service for StackRox from the Custom portal.

  2. Use the Violet tool to upload the plugin to the platform.

    violet push stackrox-operator.vx.x.x.tgz --platform-address https://192.168.0.1 --platform-username <user> --platform-password <password>

Install StackRox Operator

  1. Log in to the platform and navigate to the Administrator page.

  2. In the left navigation bar, select Marketplace -> OperatorHub to enter the OperatorHub page.

  3. Find Alauda Security Service for StackRox, click Install to access the installation page.

Configuration Parameters:

ParameterRecommended Configuration
ChannelThe default Channel is alpha.
VersionSelect the desired version to install.
Installation ModeCluster: All namespaces under the cluster share one Operator for creating and managing instances, resulting in lower resource usage.
Installation LocationChoose the Recommended: If none exists, it will be created automatically.
Upgrade StrategyManual: When a new version is available in the OperatorHub, manual confirmation is required to upgrade the Operator to the latest version.
  1. On the Install Operator page, select Default Configuration, then click Install to complete the installation of Alauda Security Service for StackRox.

Central Service Installation

INFO

Some components of the StackRox Central service are resource-intensive. We recommend running them on infra nodes and setting nodeSelector and tolerations to ensure they run only on those nodes. If you are evaluating the product and have not provisioned infra nodes, you can remove these settings so the components run on all nodes.

For guidance on planning infra nodes, see .

Pre-installation procedure

  1. Create the central-db-password secret:
    Store the password in the password data item.

    kubectl create secret generic central-db-password \
  --from-literal=password=<central db password> \
  -n stackrox-operator

  2. Enable Ingress and configure domain certificate:
    Create a TLS secret with your certificate and key.

    kubectl create secret tls central-ingress-tls \
  --cert=<path/to/tls.crt> \
  --key=<path/to/tls.key> \
  -n stackrox-operator

Install via UI

  1. Log in to the platform and navigate to the Administrator page.

  2. In the left navigation bar, select Marketplace -> OperatorHub to enter the OperatorHub page.

  3. Find Alauda Security Service for StackRox, click the card to access the Details page.

  4. Navigate to the All Instances tab, click Create and select Central to access the Create Central page.

  5. Fill in the configuration parameters as prompted.

  6. Click Create to complete the installation of Central Service.

Install via YAML

Apply the following YAML to your target cluster:

# YAML Deployment Method for StackRox Operator
# Create a StackRox Central Services instance
---
apiVersion: platform.stackrox.io/v1alpha1
kind: Central
metadata:
  name: stackrox-central-services
  namespace: stackrox-operator
  labels: {}
  annotations:
    cpaas.io/display-name: ""
spec:
  egress:
    connectivityPolicy: Online  # Supported: Online/Offline. Offline mode requires manual upload of the vulnerability database.
  central:
    exposure:
      ingress:
        enabled: true
        host: example.com
        tls:
          secretName: central-ingress-tls
      nodePort:
        enabled: true
      loadBalancer:
        enabled: false
    db:
      passwordSecret:
        name: central-db-password
      connectionString: host=central-db.stackrox port=5432 user=postgres sslmode=require  # Specify the database connection string

    # Tolerations Optional
    # If you want this component to only run on specific nodes, you can configure tolerations of tainted nodes.
    tolerations:
    - effect: NoSchedule
      key: node-role.kubernetes.io/infra
      value: reserved
      operator: Equal
    nodeSelector:
      node-role.kubernetes.io/infra: ""
  

  # scannerV4 Optional
  scannerV4:
    db:
      tolerations:
      - effect: NoSchedule
        key: node-role.kubernetes.io/infra
        value: reserved
        operator: Equal

      nodeSelector:
        node-role.kubernetes.io/infra: ""

    indexer:
      scaling:
        autoScaling: Enabled
        maxReplicas: 5
        minReplicas: 2
        replicas: 3
      tolerations:
        - effect: NoSchedule
        key: node-role.kubernetes.io/infra
        value: reserved
        operator: Equal
      nodeSelector:
        node-role.kubernetes.io/infra: ""

    matcher:
      scaling:
        autoScaling: Enabled
        maxReplicas: 5
        minReplicas: 1
        replicas: 3
      tolerations:
      - effect: NoSchedule
        key: node-role.kubernetes.io/infra
        value: reserved
        operator: Equal
      nodeSelector:
        node-role.kubernetes.io/infra: ""

  # Ingress domain certificate CA or cert. If ingress is not enabled, no configuration is needed.
  tls:
    additionalCAs:
      - content: |-
          -----BEGIN CERTIFICATE-----
          MIIB0TCCAXigAwIBAgIUXvN2ovk16V6+7jUAJpYdEXo1K4UwCgYIKoZIzj0EAwIw
          RzEnMCUGA1UEAxMeU3RhY2tSb3ggQ2VydGlmaWNhdGUgQXV0aG9yaXR5MRwwGgYD
          VQQFExM2MDYyNzAwMjg3MTkxNjM0NDY4MB4XDTI1MDkyNTA2MjQwMFoXDTMwMDky
          NDA2MjQwMFowRzEnMCUGA1UEAxMeU3RhY2tSb3ggQ2VydGlmaWNhdGUgQXV0aG9y
          aXR5MRwwGgYDVQQFExM2MDYyNzAwMjg3MTkxNjM0NDY4MFkwEwYHKoZIzj0CAQYI
          KoZIzj0DAQcDQgAE57RYqus1/v3VcJ/fP+vG4flQ8uunyx2lguQ9cT0VYOZJnKDh
          FQ/58jgEPeHGgu+wU2Mvjumc7qFe1gP/jSuW66NCMEAwDgYDVR0PAQH/BAQDAgEG
          MA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFKxLpgvy2HnDYZTQw2nIiLdR3fxh
          MAoGCCqGSM49BAMCA0cAMEQCID2uapFJnsdM4BGmnRCx7HqUrwrpBEjXZ98atcKO
          IDCXAiAwuYzXAIMLNfLRakIz+hXxvvGY3+A5ZeRARZQVPatTaQ==
          -----END CERTIFICATE-----
        name: additional-ca

Central Settings

ParameterDescription
central.nodeSelectorIf 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.tolerationsIf 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.exposeMonitoringSpecify true to expose Prometheus metrics endpoint for Central on port number 9090.
central.image.registryA custom registry that overrides the global image.registry parameter for the Central image.
central.image.nameThe custom image name that overrides the default Central image name (main).
central.image.tagThe custom image tag that overrides the default tag for Central image. If you specify your own image tag during a new installation, you must manually increment this tag when you upgrade to a new version by running the helm upgrade command. If you mirror Central images in your own registry, do not modify the original image tags.
central.image.fullRefFull reference including registry address, image name, and image tag for the Central image. Setting a value for this parameter overrides the central.image.registry, central.image.name, and central.image.tag parameters.
central.resources.requests.memoryThe memory request for Central.
central.resources.requests.cpuThe CPU request for Central.
central.resources.limits.memoryThe memory limit for Central.
central.resources.limits.cpuThe CPU limit for Central.
central.exposure.loadBalancer.enabledUse true to expose Central by using a load balancer.
central.exposure.loadBalancer.portThe port number on which to expose Central. The default port number is 443.
central.exposure.nodePort.enabledUse true to expose Central by using the node port service.
central.exposure.nodePort.portThe port number on which to expose Central. When you skip this parameter, Alauda Container Platform automatically assigns a port number. Red Hat recommends that you do not specify a port number if you are exposing StackRox by using a node port.
central.exposure.ingress.enabledUse true to expose Central by using an ingress. Disables all ingress settings if set to false. This parameter is only available for Alauda Container Platform clusters.
central.exposure.ingress.hostUse this parameter to specify a custom hostname to use for Central's passthrough route. Leave this unset to accept the default value that Alauda Container Platform provides. This parameter is only available for Alauda Container Platform clusters.
central.exposure.ingress.ingressClassNameSpecify a custom ingress class name for the Central ingress.
central.exposure.ingress.tls.secretNameSet up a Central ingress with TLS secret.
central.db.passwordSecret.nameSpecify a secret that contains the password in the "password" data item.
central.db.connectionStringSpecify a connection string that corresponds to a database managed elsewhere.
scannerV4.db.tolerationsIf you want this component to only run on specific nodes, you can configure tolerations of tainted nodes.
scannerV4.db.nodeSelectorIf you want this component to only run on specific nodes, you can configure a node selector here.
scannerV4.indexer.scaling.autoScalingWhen enabled, the number of component replicas is managed dynamically based on the load, within the limits specified below.
scannerV4.indexer.scaling.maxReplicas
scannerV4.indexer.scaling.minReplicas
scannerV4.indexer.scaling.replicasWhen autoscaling is disabled, the number of replicas will always be configured to match this value.
scannerV4.indexer.tolerationsIf you want this component to only run on specific nodes, you can configure tolerations of tainted nodes.
scannerV4.indexer.nodeSelectorIf you want this component to only run on specific nodes, you can configure a node selector here.
scannerV4.matcher.scaling.autoScalingWhen enabled, the number of component replicas is managed dynamically based on the load, within the limits specified below.
scannerV4.matcher.scaling.maxReplicas
scannerV4.matcher.scaling.minReplicas
scannerV4.matcher.scaling.replicasWhen autoscaling is disabled, the number of replicas will always be configured to match this value.
scannerV4.matcher.tolerationsIf you want this component to only run on specific nodes, you can configure tolerations of tainted nodes.
scannerV4.matcher.nodeSelectorIf you want this component to only run on specific nodes, you can configure a node selector here.
tls.additionalCAsAllows you to specify additional trusted Root CAs.

Access Central Console

  • Address: https://example.com (The address of the central ingress host)

  • Initial account: admin

  • Initial password: The initial password is in the stackrox central-htpasswd secret.

    kubectl -n stackrox-operator get secret central-htpasswd -o go-template='{{index .data "password" | base64decode}}'

Cluster Service Installation

Cluster Pre-installation procedure

  1. Download the CLI tool following the guide Download CLI from the platform.

  2. Run the following command to generate the cluster access certificate:

    roxctl central crs generate <cluster name> --output crs.yaml --endpoint <stackrox central address> --password <central admin password>

    The password can be obtained from the central-htpasswd secret.

  3. Create Secured Cluster CRs YAML

    kubectl apply -f crs.yaml -n stackrox-operator

Cluster Install via UI

  1. Log in to the platform and navigate to the Administrator page.

  2. In the left navigation bar, select Marketplace -> OperatorHub to enter the OperatorHub page.

  3. Find Alauda Security Service for StackRox, click the card to access the Details page.

  4. Navigate to the All Instances tab, click Create and select Central to access the Create Cluster Service page.

  5. Fill in the configuration parameters as prompted.

  6. Click Create to complete the installation of Cluster Service.

Cluster Install via YAML

Apply the following YAML to your target cluster:

---
# Create a StackRox Secured Cluster Services instance
---
apiVersion: platform.stackrox.io/v1alpha1
kind: SecuredCluster
metadata:
  name: stackrox-secured-cluster-services
  namespace: stackrox-operator
  labels: {}
  annotations:
    cpaas.io/display-name: ""
spec:
  clusterName: business-1
  centralEndpoint: wss://example.com:443  # Specify the address of StackRox Central Services. If it is in the same cluster as Central, configuration may not be necessary.

  # AdmissionControl Optional
  admissionControl:
    replicas: 3
    tolerations:
      - effect: NoSchedule
        key: node-role.kubernetes.io/infra
        value: reserved
        operator: Equal
    nodeSelector:
      node-role.kubernetes.io/infra: ""

  # Sensor Optional
  sensor:
    tolerations:
      - effect: NoSchedule
        key: node-role.kubernetes.io/infra
        value: reserved
        operator: Equal
    nodeSelector:
      node-role.kubernetes.io/infra: ""

  # Ingress domain certificate CA or cert. If ingress is not enabled, no configuration is needed.
  tls: 
    additionalCAs:
      content: |-
        -----BEGIN CERTIFICATE-----
        MIIB0TCCAXigAwIBAgIUXvN2ovk16V6+7jUAJpYdEXo1K4UwCgYIKoZIzj0EAwIw
        RzEnMCUGA1UEAxMeU3RhY2tSb3ggQ2VydGlmaWNhdGUgQXV0aG9yaXR5MRwwGgYD
        VQQFExM2MDYyNzAwMjg3MTkxNjM0NDY4MB4XDTI1MDkyNTA2MjQwMFoXDTMwMDky
        NDA2MjQwMFowRzEnMCUGA1UEAxMeU3RhY2tSb3ggQ2VydGlmaWNhdGUgQXV0aG9y
        aXR5MRwwGgYDVQQFExM2MDYyNzAwMjg3MTkxNjM0NDY4MFkwEwYHKoZIzj0CAQYI
        KoZIzj0DAQcDQgAE57RYqus1/v3VcJ/fP+vG4flQ8uunyx2lguQ9cT0VYOZJnKDh
        FQ/58jgEPeHGgu+wU2Mvjumc7qFe1gP/jSuW66NCMEAwDgYDVR0PAQH/BAQDAgEG
        MA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFKxLpgvy2HnDYZTQw2nIiLdR3fxh
        MAoGCCqGSM49BAMCA0cAMEQCID2uapFJnsdM4BGmnRCx7HqUrwrpBEjXZ98atcKO
        IDCXAiAwuYzXAIMLNfLRakIz+hXxvvGY3+A5ZeRARZQVPatTaQ==
        -----END CERTIFICATE-----
      name: additional-ca

Secured Cluster Settings

ParameterDescription
clusterNameThe unique name of this cluster, as it will be shown in the StackRox UI. Note: Once a name is set here, you will not be able to change it again. You will need to delete and re-create this object in order to register a cluster with a new name.
centralEndpointThe endpoint of the StackRox Central instance to connect to, including the port number. If no port is specified and the endpoint contains an https:// protocol specification, then the port 443 is implicitly assumed. If using a non-gRPC capable load balancer, use the WebSocket protocol by prefixing the endpoint address with wss://. Note: when leaving this blank, Sensor will attempt to connect to a Central instance running in the same namespace.
admissionControl.replicasThe number of replicas of the admission control pod.
admissionControl.tolerationsIf you want this component to only run on specific nodes, you can configure tolerations of tainted nodes.
admissionControl.nodeSelectorIf you want this component to only run on specific nodes, you can configure a node selector here.
sensor.tolerationsIf you want this component to only run on specific nodes, you can configure tolerations of tainted nodes.
sensor.nodeSelectorIf you want this component to only run on specific nodes, you can configure a node selector here.
tls.additionalCAsAllows you to specify additional trusted Root CAs.