Upgrading

Procedure

1. In the OpenShift Container Platform web console, go to the RHACS Operator page.
2. In the top navigation menu, select Secured Cluster.
3. Click the instance name, for example, stackrox-secured-cluster-services.

4. Use one of the following methods to change the setting:

   • In the Form view, under Per Node Settings → Collector Settings → Collection, select CORE_BPF.
   • Click YAML to open the YAML editor and locate the spec.perNode.collector.collection attribute. If the value is KernelModule or EBPF, then change it to CORE_BPF.
5. Click Save.

Procedure

1. Delete the OLM subscription by running the following command:

   • For OpenShift Container Platform, run the following command:

     $ oc -n rhacs-operator delete subscription rhacs-operator

     Copy to Clipboard

   • For Kubernetes, run the following command:

     $ kubectl -n rhacs-operator delete subscription rhacs-operator

     Copy to Clipboard

2. Delete the cluster service version (CSV) by running the following command:

   • For OpenShift Container Platform, run the following command:

     $ oc -n rhacs-operator delete csv -l operators.coreos.com/rhacs-operator.rhacs-operator

     Copy to Clipboard

   • For Kubernetes, run the following command:

     $ kubectl -n rhacs-operator delete csv -l operators.coreos.com/rhacs-operator.rhacs-operator

     Copy to Clipboard

3. Determine the previous version you want to roll back to by choosing one of the following options:

   • If the current Central instance is running, query the RHACS API to get the rollback version by running the following command:

     $ curl -k -s -u <user>:<password> https://<central hostname>/v1/centralhealth/upgradestatus | jq -r .upgradeStatus.forceRollbackTo

     Copy to Clipboard

   • If the current Central instance is not running, perform the following steps:

     Note

     This procedure can only be used for RHACS release 3.74 and earlier when the rocksdb database is installed.

     1. Ensure the Central deployment is scaled down by running the following command:

        • For OpenShift Container Platform, run the following command:

          $ oc scale -n <central namespace> –replicas=0 deploy/central

          Copy to Clipboard

        • For Kubernetes, run the following command:

          $ kubectl scale -n <central namespace> –replicas=0 deploy/central

          Copy to Clipboard

     2. Save the following pod spec as a YAML file:

        apiVersion: v1
        kind: Pod
        metadata:
          name: get-previous-db-version
        spec:
          containers:
          - name: get-previous-db-version
            image: registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:<rollback version>
            command:
            - sh
            args:
            - '-c'
            - "cat /var/lib/stackrox/.previous/migration_version.yaml | grep '^image:' | cut -f 2 -d : | tr -d ' '"
            volumeMounts:
            - name: stackrox-db
              mountPath: /var/lib/stackrox
          volumes:
          - name: stackrox-db
            persistentVolumeClaim:
              claimName: stackrox-db

        Copy to Clipboard

     3. Create a pod in your Central namespace by running the following command using the YAML file that you saved:

        • For OpenShift Container Platform, run the following command:

          $ oc create -n <central namespace> -f pod.yaml

          Copy to Clipboard

        • For Kubernetes, run the following command:

          $ kubectl create -n <central namespace> -f pod.yaml

          Copy to Clipboard

     4. After pod creation is complete, get the version by running the following command:

        • For OpenShift Container Platform, run the following command:

          $ oc logs -n <central namespace> get-previous-db-version

          Copy to Clipboard

        • For Kubernetes, run the following command:

          $ kubectl logs -n <central namespace> get-previous-db-version

          Copy to Clipboard

4. Edit the central-config.yaml ConfigMap to set the maintenance.forceRollBackVersion:<version> parameter by running the following command:

   • For OpenShift Container Platform, run the following command:

     $ oc get configmap -n <central namespace> central-config -o yaml | sed -e "s/forceRollbackVersion: none/forceRollbackVersion: <version>/" | oc -n <central namespace> apply -f -

     Copy to Clipboard

   • For Kubernetes, run the following command:

     $ kubectl get configmap -n <central namespace> central-config -o yaml | sed -e "s/forceRollbackVersion: none/forceRollbackVersion: <version>/" | kubectl -n <central namespace> apply -f -

     Copy to Clipboard

5. Set the image for the Central deployment using the version string shown in Step 3 as the image tag. For example, run the following command:

   • For OpenShift Container Platform, run the following command:

     $ oc set image -n <central namespace> deploy/central central=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:<version>

     Copy to Clipboard

   • For Kubernetes, run the following command:

     $ kubectl set image -n <central namespace> deploy/central central=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:<version>

     Copy to Clipboard

Verification

1. Ensure that the Central pod starts and has a ready status. If the pod crashes, check the logs to see if the backup was restored. A successful log message appears similar to the following example:

   Clone to Migrate ".previous", ""

   Copy to Clipboard
2. Reinstall the Operator on the rolled back channel. For example, 3.74.2 is installed on the rhacs-3.74 channel.

Procedure

1. Go to the Operators → Installed Operators page.
2. Click the RHACS Operator.
3. On the Operator Details page, select Uninstall Operator from the Actions list. Following this action, the Operator stops running and no longer receives updates.

4. Determine the previous version you want to roll back to by choosing one of the following options:

   • If the current Central instance is running, you can query the RHACS API to get the rollback version by running the following command from a terminal window:

     $ curl -k -s -u <user>:<password> https://<central hostname>/v1/centralhealth/upgradestatus | jq -r .upgradeStatus.forceRollbackTo

     Copy to Clipboard

   • You can create a pod and extract the previous version by performing the following steps:

     Note

     This procedure can only be used for RHACS release 3.74 and earlier when the rocksdb database is installed.

     1. Go to Workloads → Deployments → central.
     2. Under Deployment details, click the down arrow next to the pod count to scale down the pod.

     3. Go to Workloads → Pods → Create Pod and paste the contents of the pod spec as shown in the following example into the editor:

        apiVersion: v1
        kind: Pod
        metadata:
          name: get-previous-db-version
        spec:
          containers:
          - name: get-previous-db-version
            image: registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:<rollback version>
            command:
            - sh
            args:
            - '-c'
            - "cat /var/lib/stackrox/.previous/migration_version.yaml | grep '^image:' | cut -f 2 -d : | tr -d ' '"
            volumeMounts:
            - name: stackrox-db
              mountPath: /var/lib/stackrox
          volumes:
          - name: stackrox-db
            persistentVolumeClaim:
              claimName: stackrox-db

        Copy to Clipboard
     4. Click Create.
     5. After the pod is created, click the Logs tab to get the version string.

5. Update the rollback configuration by performing the following steps:

   1. Go to Workloads → ConfigMaps → central-config and select Edit ConfigMap from the Actions list.
   2. Find the forceRollbackVersion line in the value of the central-config.yaml key.
   3. Replace none with 3.73.3, and then save the file.

6. Update Central to the earlier version by performing the following steps:

   1. Go to Workloads → Deployments → central and select Edit Deployment from the Actions list.
   2. Update the image name, and then save the changes.

Verification

1. Ensure that the Central pod starts and has a ready status. If the pod crashes, check the logs to see if the backup was restored. A successful log message appears similar to the following example:

   Clone to Migrate ".previous", ""

   Copy to Clipboard
2. Reinstall the Operator on the rolled back channel. For example, 3.74.2 is installed on the rhacs-3.74 channel.

1. Check the status of the central-db pod:

   $ oc -n <namespace> get pod -l app=central-db 

   1

   Copy to Clipboard

   1

   If you use Kubernetes, enter kubectl instead of oc.

2. If the status of the pod is Pending, use the describe command to get more details:

   $ oc -n <namespace> describe po/<central-db-pod-name> 

   1

   Copy to Clipboard

   1

   If you use Kubernetes, enter kubectl instead of oc.

3. You might see the FailedScheduling warning message:

   Type     Reason            Age   From               Message
   ----     ------            ----  ----               -------
   Warning  FailedScheduling  54s   default-scheduler  0/7 nodes are available: 1 Insufficient memory, 3 node(s) had untolerated taint {node-role.kubernetes.io/master: }, 4 Insufficient cpu. preemption: 0/7 nodes are available: 3 Preemption is not helpful for scheduling, 4 No preemption victims found for incoming pod.

   Copy to Clipboard

4. This warning message suggests that the scheduled node had insufficient memory to accommodate the pod’s resource requirements. If you have a small environment, consider increasing resources on the nodes or adding a larger node that can support the database.

   Otherwise, consider decreasing the resource requirements for the central-db pod in the custom resource under central → db → resources. However, running central with fewer resources than the recommended minimum might lead to degraded performance for RHACS.

Procedure

1. Determine the roxctl architecture for the target operating system:

   $ arch="$(uname -m | sed "s/x86_64//")"; arch="${arch:+-$arch}"

   Copy to Clipboard

2. Download the roxctl CLI:

   $ curl -L -f -o roxctl "https://mirror.openshift.com/pub/rhacs/assets/4.5.9/bin/Linux/roxctl${arch}"

   Copy to Clipboard

3. Make the roxctl binary executable:

   $ chmod +x roxctl

   Copy to Clipboard

4. Place the roxctl binary in a directory that is on your PATH:

   To check your PATH, execute the following command:

   $ echo $PATH

   Copy to Clipboard

Procedure

1. Determine the roxctl architecture for the target operating system:

   $ arch="$(uname -m | sed "s/x86_64//")"; arch="${arch:+-$arch}"

   Copy to Clipboard

2. Download the roxctl CLI:

   $ curl -L -f -o roxctl "https://mirror.openshift.com/pub/rhacs/assets/4.5.9/bin/Darwin/roxctl${arch}"

   Copy to Clipboard

3. Remove all extended attributes from the binary:

   $ xattr -c roxctl

   Copy to Clipboard

4. Make the roxctl binary executable:

   $ chmod +x roxctl

   Copy to Clipboard

5. Place the roxctl binary in a directory that is on your PATH:

   To check your PATH, execute the following command:

   $ echo $PATH

   Copy to Clipboard

Procedure

1. If you have created custom Scanner configurations, you must apply these changes before updating the Scanner configuration file:

   1. To generate Scanner, run the following command:

      $ roxctl -e "$ROX_CENTRAL_ADDRESS" scanner generate

      Copy to Clipboard

   2. To apply the TLS secrets YAML file, run the following command:

      $ oc apply -f scanner-bundle/scanner/02-scanner-03-tls-secret.yaml

      Copy to Clipboard

   3. To apply the Scanner configuration YAML file, run the following command:

      $ oc apply -f scanner-bundle/scanner/02-scanner-04-scanner-config.yaml

      Copy to Clipboard

2. To update the Scanner image, run the following command:

   $ oc -n stackrox set image deploy/scanner \
   scanner=registry.redhat.io/advanced-cluster-security/rhacs-scanner-rhel8:4.5.9

   Copy to Clipboard

3. To update the Scanner database image, run the following command:

   $ oc -n stackrox set image deploy/scanner-db \
   db=registry.redhat.io/advanced-cluster-security/rhacs-scanner-db-rhel8:4.5.9 \
   init-db=registry.redhat.io/advanced-cluster-security/rhacs-scanner-db-rhel8:4.5.9

   Copy to Clipboard

Procedure

1. Update the Sensor image:

   $ oc -n stackrox set image deploy/sensor sensor=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:4.5.9 

   1

   Copy to Clipboard

   1

   If you use Kubernetes, enter kubectl instead of oc.

2. Update the Compliance image:

   $ oc -n stackrox set image ds/collector compliance=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:4.5.9 

   1

   Copy to Clipboard

   1

   If you use Kubernetes, enter kubectl instead of oc.

3. Update the Collector image:

   $ oc -n stackrox set image ds/collector collector=registry.redhat.io/advanced-cluster-security/rhacs-collector-rhel8:4.5.9 

   1

   Copy to Clipboard

   1

   If you use Kubernetes, enter kubectl instead of oc.

   Note

   If you are using the collector slim image, run the following command instead:

   $ oc -n stackrox set image ds/collector collector=registry.redhat.io/advanced-cluster-security/rhacs-collector-slim-rhel8:{rhacs-version}

   Copy to Clipboard

4. Update the admission control image:

   $ oc -n stackrox set image deploy/admission-control admission-control=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:4.5.9

   Copy to Clipboard

Procedure

1. List all of the RHACS services that are deployed on Central and all secured clusters:

   $ oc -n stackrox describe pods | grep 'openshift.io/scc\|^Name:'

   Copy to Clipboard

   Example output

   Name:      admission-control-6f4dcc6b4c-2phwd
              openshift.io/scc: stackrox-admission-control
   #...
   Name:      central-575487bfcb-sjdx8
              openshift.io/scc: stackrox-central
   Name:      central-db-7c7885bb-6bgbd
              openshift.io/scc: stackrox-central-db
   Name:      collector-56nkr
              openshift.io/scc: stackrox-collector
   #...
   Name:      scanner-68fc55b599-f2wm6
              openshift.io/scc: stackrox-scanner
   Name:      scanner-68fc55b599-fztlh
   #...
   Name:      sensor-84545f86b7-xgdwf
              openshift.io/scc: stackrox-sensor
   #...

   Copy to Clipboard

   In this example, you can see that each pod has its own custom SCC, which is specified through the openshift.io/scc field.

2. Add the required roles and role bindings to use the Red Hat OpenShift SCCs instead of the RHACS custom SCCs.

   To add the required roles and role bindings to use the Red Hat OpenShift SCCs for the Central cluster, complete the following steps:

   1. Create a file named update-central.yaml that defines the role and role binding resources by using the following content:

      Example 3.1. Example YAML file

      apiVersion: rbac.authorization.k8s.io/v1
      kind: Role 

      1

      
      metadata:
        annotations:
           email: support@stackrox.com
           owner: stackrox
        labels:
           app.kubernetes.io/component: central
           app.kubernetes.io/instance: stackrox-central-services
           app.kubernetes.io/name: stackrox
           app.kubernetes.io/part-of: stackrox-central-services
           app.kubernetes.io/version: 4.4.0
        name: use-central-db-scc 

      2

      
        namespace: stackrox 

      3

      
      Rules: 

      4

      
      - apiGroups:
        - security.openshift.io
        resourceNames:
        - nonroot-v2
        resources:
        - securitycontextconstraints
        verbs:
        - use
      - - -
      apiVersion: rbac.authorization.k8s.io/v1
      kind: Role
      metadata:
        annotations:
           email: support@stackrox.com
           owner: stackrox
        labels:
           app.kubernetes.io/component: central
           app.kubernetes.io/instance: stackrox-central-services
           app.kubernetes.io/managed-by: Helm
           app.kubernetes.io/name: stackrox
           app.kubernetes.io/part-of: stackrox-central-services
           app.kubernetes.io/version: 4.4.0
        name: use-central-scc
        namespace: stackrox
      rules:
      - apiGroups:
        - security.openshift.io
        resourceNames:
        - nonroot-v2
        resources:
        - securitycontextconstraints
        verbs:
        - use
      - - -
      apiVersion: rbac.authorization.k8s.io/v1
      kind: Role
      metadata:
        annotations:
           email: support@stackrox.com
           owner: stackrox
        labels:
           app.kubernetes.io/component: scanner
           app.kubernetes.io/instance: stackrox-central-services
           app.kubernetes.io/name: stackrox
           app.kubernetes.io/part-of: stackrox-central-services
           app.kubernetes.io/version: 4.4.0
        name: use-scanner-scc
        namespace: stackrox
      rules:
      - apiGroups:
        - security.openshift.io
        resourceNames:
        - nonroot-v2
        resources:
        - securitycontextconstraints
        verbs:
        - use
      - - -
      apiVersion: rbac.authorization.k8s.io/v1
      kind: RoleBinding 

      5

      
      metadata:
        annotations:
           email: support@stackrox.com
           owner: stackrox
        labels:
           app.kubernetes.io/component: central
           app.kubernetes.io/instance: stackrox-central-services
           app.kubernetes.io/name: stackrox
           app.k ubernetes.io/part-of: stackrox-central-services
           app.kubernetes.io/version: 4.4.0
        name: central-db-use-scc 

      6

      
        namespace: stackrox
      roleRef: 

      7

      
        apiGroup: rbac.authorization.k8s.io
        kind: Role
        name: use-central-db-scc
      subjects: 

      8

      
      - kind: ServiceAccount
        name: central-db
        namespace: stackrox
      - - -
      apiVersion: rbac.authorization.k8s.io/v1
      kind: RoleBinding
      metadata:
        annotations:
           email: support@stackrox.com
           owner: stackrox
        labels:
           app.kubernetes.io/component: central
           app.kubernetes.io/instance: stackrox-central-services
           app.kubernetes.io/name: stackrox
           app.kubernetes.io/part-of: stackrox-central-services
           app.kubernetes.io/version: 4.4.0
        name: central-use-scc
        namespace: stackrox
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: Role
        name: use-central-scc
      subjects:
      - kind: ServiceAccount
        name: central
        namespace: stackrox
      - - -
      apiVersion: rbac.authorization.k8s.io/v1
      kind: RoleBinding
      metadata:
        annotations:
           email: support@stackrox.com
           owner: stackrox
        labels:
           app.kubernetes.io/component: scanner
           app.kubernetes.io/instance: stackrox-central-services
           app.kubernetes.io/name: stackrox
           app.kubernetes.io/part-of: stackrox-central-services
           app.kubernetes.io/version: 4.4.0
        name: scanner-use-scc
        namespace: stackrox
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: Role
        name: use-scanner-scc
      subjects:
      - kind: ServiceAccount
        name: scanner
        namespace: stackrox
      - - -

      Copy to Clipboard

      1

      The type of Kubernetes resource, in this example, Role.

      2

      The name of the role resource.

      3

      The namespace in which the role is created.

      4

      Describes the permissions granted by the role resource.

      5

      The type of Kubernetes resource, in this example, RoleBinding.

      6

      The name of the role binding resource.

      7

      Specifies the role to bind in the same namespace.

      8

      Specifies the subjects that are bound to the role.

   2. Create the role and role binding resources specified in the update-central.yaml file by running the following command:

      $ oc -n stackrox create -f ./update-central.yaml

      Copy to Clipboard

3. To add the required roles and role bindings to use the Red Hat OpenShift SCCs for all secured clusters, complete the following steps:

   1. Create a file named upgrade-scs.yaml that defines the role and role binding resources by using the following content:

      Example 3.2. Example YAML file

      apiVersion: rbac.authorization.k8s.io/v1
      kind: Role  

      1

      
      metadata:
        annotations:
           email: support@stackrox.com
           owner: stackrox
        labels:
           app.kubernetes.io/component: collector
           app.kubernetes.io/instance: stackrox-secured-cluster-services
           app.kubernetes.io/name: stackrox
           app.kubernetes.io/part-of: stackrox-secured-cluster-services
           app.kubernetes.io/version: 4.4.0
           auto-upgrade.stackrox.io/component: sensor
        name: use-privileged-scc  

      2

      
        namespace: stackrox 

      3

      
      rules:  

      4

      
      - apiGroups:
        - security.openshift.io
        resourceNames:
        - privileged
        resources:
        - securitycontextconstraints
        verbs:
        - use
      - - -
      apiVersion: rbac.authorization.k8s.io/v1
      kind: RoleBinding 

      5

      
      metadata:
        annotations:
           email: support@stackrox.com
           owner: stackrox
        labels:
           app.kubernetes.io/component: collector
           app.kubernetes.io/instance: stackrox-secured-cluster-services
           app.kubernetes.io/name: stackrox
           app.kubernetes.io/part-of: stackrox-secured-cluster-services
           app.kubernetes.io/version: 4.4.0
           auto-upgrade.stackrox.io/component: sensor
        name: collector-use-scc 

      6

      
        namespace: stackrox
      roleRef: 

      7

      
        apiGroup: rbac.authorization.k8s.io
        kind: Role
        name: use-privileged-scc
      subjects: 

      8

      
      - kind: ServiceAccount
        name: collector
        namespace: stackrox
      - - -

      Copy to Clipboard

      1

      The type of Kubernetes resource, in this example, Role.

      2

      The name of the role resource.

      3

      The namespace in which the role is created.

      4

      Describes the permissions granted by the role resource.

      5

      The type of Kubernetes resource, in this example, RoleBinding.

      6

      The name of the role binding resource.

      7

      Specifies the role to bind in the same namespace.

      8

      Specifies the subjects that are bound to the role.

   2. Create the role and role binding resources specified in the upgrade-scs.yaml file by running the following command:

      $ oc -n stackrox create -f ./update-scs.yaml

      Copy to Clipboard
      Important

      You must run this command on each secured cluster to create the role and role bindings specified in the upgrade-scs.yaml file.

4. Delete the SCCs that are specific to RHACS:

   1. To delete the SCCs that are specific to the Central cluster, run the following command:

      $ oc delete scc/stackrox-central scc/stackrox-central-db scc/stackrox-scanner

      Copy to Clipboard

   2. To delete the SCCs that are specific to all secured clusters, run the following command:

      $ oc delete scc/stackrox-admission-control scc/stackrox-collector scc/stackrox-sensor

      Copy to Clipboard
      Important

      You must run this command on each secured cluster to delete the SCCs that are specific to each secured cluster.

Procedure

1. Ensure that the bundle for the secured cluster was generated with future upgrades enabled before clicking Download YAML file and keys.
2. If possible, remove that secured cluster and generate a new bundle making sure that future upgrades are enabled.

3. If you cannot re-create the cluster, you can take these actions:

   1. Ensure that the service account sensor-upgrader exists in the same namespace as Sensor.
   2. Ensure that a ClusterRoleBinding exists (default name: <namespace>:upgrade-sensors) that grants the cluster-admin ClusterRole to the sensor-upgrader service account.

Procedure

1. Ensure that the Secured Cluster can access the registry and pull the image <image_reference:tag>.
2. Ensure that the image pull secrets are configured correctly in the secured cluster.

Procedure

1. Ensure that the upgrader has enough permissions for accessing the cluster objects. For more information, see "Upgrader is missing permissions".
2. Check the upgrader logs for more insights.