---
title: "Configure security contexts"
description: ""
url: "https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/security/security-contexts/index.html"
---
## Overview 


**Warning**


ITRS Analytics does not support upgrading a non-PSS-restricted (less secure) cluster to a PSS-restricted (more secure) cluster.

For ITRS Analytics 2.17.x, deployments targeting clusters that enforce the highest level of Pod Security Standards (PSS) must be installed as a new deployment, with all prerequisites managed manually.



ITRS Analytics supports flexible security context configuration to meet your organization's security policies, including compliance with Kubernetes Pod Security Standards and admission controllers such as Gatekeeper and Kyverno.

Security contexts control how containers run, including:

- User and group IDs — will be assigned to the container’s main process.
- Linux capabilities — kernel capabilities are granted or dropped.
- Privilege escalation — whether processes can gain additional privileges.
- File system groups — assigned to every volume attached to the pod.

### Manual recovery for user ID changes


**Warning**


Changing `runAsUser` after installation requires manual intervention and temporarily relaxing security policies. This procedure must be performed with guidance from ITRS Support.



If you need to change `runAsUser` on an existing installation with strict security policies (Pod Security Admission, Gatekeeper, or Kyverno), see [Manual recovery: Change user IDs with strict security policies](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/security/change-runasuser-after-installation/index.html) for the complete recovery procedure.

As a best practice, configure the correct `runAsUser` and `fsGroup` before initial deployment to avoid this complexity.

### Advanced security configuration

For more information about security context configuration, see [Using admission controllers and enabling optional logs collection](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/security/security-contexts-advanced/index.html) which covers integration with admission controllers such as Gatekeeper, Kyverno, and Pod Security Admission (PSA), as well as the optional logs collection feature.

## Security context default configuration

ITRS Analytics uses the following default security contexts:

Use `applySecurityContextDefaults` to control whether ITRS Analytics applies its default cluster-assignable security context settings. This parameter is enabled by default.

- When set to `true`, ITRS Analytics applies the default pod-level fields `runAsUser`, `runAsGroup`, `fsGroup`, `supplementalGroups`, and `fsGroupChangePolicy`, together with the container `seccompProfile`.
- When set to `false`, ITRS Analytics omits those cluster-assignable fields so the cluster can provide its own values. Use this option on platforms that assign their own UID/GID ranges, such as OpenShift `restricted-v2`.
- The container hardening fields `runAsNonRoot`, `allowPrivilegeEscalation`, and `capabilities.drop` are always applied, regardless of the setting.

This toggle is available in ITRS Analytics installation package 2.18.5 and later.

#### Pod-level (.spec)

```yaml
runAsUser: 10000
runAsGroup: 10000
supplementalGroups: [10000]
fsGroup: 10000
fsGroupChangePolicy: OnRootMismatch
```

#### Container-level (.spec.containers[] or .spec.initContainers[])

```yaml
runAsNonRoot: true
allowPrivilegeEscalation: false
capabilities:
  drop: [ALL]
seccompProfile:
  type: RuntimeDefault
```

These defaults are suitable for immediate deployment on most Kubernetes clusters and adhere to the Pod Security Standard (PSS) at the Restricted level. The Restricted level enforces strong, least-privilege policies, such as prohibiting privileged containers and disallowed capabilities. This configuration is also compatible with Gatekeeper and Kyverno. On OpenShift, use `applySecurityContextDefaults: false` when you want the platform to run with cluster-assigned identities under the stock `restricted-v2` SCC.

For more information, see [Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/).

### When customization is needed

You may need to customize security contexts if:

- Your organization requires specific UID/GID ranges (different from default 10000).
- You're deploying on OpenShift with project-specific UID ranges.
- Compliance policies mandate specific UIDs outside the default range.


**Note**


Configure security contexts before initial deployment. Changing `runAsUser` after installation requires manual intervention and temporarily relaxing security policies. See [Manual recovery: Change user IDs with strict security policies](#manual-recovery-for-user-id-changes) for more information.

If you change `runAsUser`, you must also change `fsGroup` at the same time. See the [Troubleshooting section](#troubleshooting) for complete details on valid security context changes.



## Configuration

### Basic configuration

You can customize security contexts for ITRS Analytics during installation by specifying the required values in the Helm values files for the Platform and each app.

```yaml
iax:
  securityContext:
    pod:
      runAsUser: 5000
      runAsGroup: 5000
      supplementalGroups: [5000]
      fsGroup: 5000
      fsGroupChangePolicy: OnRootMismatch
    container:
      runAsNonRoot: true
      allowPrivilegeEscalation: false
      capabilities:
        drop: [ALL]
      seccompProfile:
        type: RuntimeDefault
```

This configuration applies only to the ITRS Analytics Platform components. Each app has its own Helm chart, so you must configure security contexts separately in the values file for every app.

### Configuration reference

#### Top-level security context

| Field                          | Description                                                                                                                                                                     | Type    | Default |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- |
| `applySecurityContextDefaults` | When `false`, omits the cluster-assignable pod fields and the container `seccompProfile` so the cluster can assign them. Container hardening still applies.                  | Boolean | `true`  |

#### Pod security context

| Field                 | Description                                         | Type            | Example          |
| --------------------- | --------------------------------------------------- | --------------- | ---------------  |
| `runAsUser`           | Assign this user ID to the main process.            | Number          | `5000`           |
| `runAsGroup`          | Assign this group ID to the main process.           | Number          | `5000`           |
| `supplementalGroups`  | Additional group IDs to assign to the main process. | List of numbers | `[5000, 6000]`   |
| `fsGroup`             | Change group ownership of mounted volumes.          | Number          | `5000`           |
| `fsGroupChangePolicy` | When to change volume ownership.                    | String          | `OnRootMismatch` |

#### Container security context

| Field                      | Description                                                            | Type            | Example          |
| -------------------------- | ---------------------------------------------------------------------- | --------------- | ---------------- |
| `runAsNonRoot`             | (Recommended) Require non-root user.                                   | Boolean         | `true`           |
| `allowPrivilegeEscalation` | (Required for PSA "Restricted") Prevent gaining additional privileges. | Boolean         | `false`          |
| `capabilities.drop`        | (Recommended) Linux capabilities to remove.                            | List of strings | `[ALL]`          |
| `seccompProfile.type`      | (required for PSA "Restricted") Seccomp profile for syscall filtering. | String          | `RuntimeDefault` |

## Deployment scenarios

### Configure custom user and group ID (UID/GID) ranges

Use this procedure when your organization has security policies that require ITRS Analytics to run with specific UID/GID ranges (for example, 5000-6000).

1. Determine the UID/GID range required by your organization's security policy.
2. Edit your ITRS Analytics configuration to include the following security context settings:

    ```yaml
    spec:
      securityContext:
        pod:
          runAsUser: 5000
          runAsGroup: 5000
          supplementalGroups: [5000]
          fsGroup: 5000
          fsGroupChangePolicy: OnRootMismatch
        container:
          runAsNonRoot: true
          allowPrivilegeEscalation: false
          capabilities:
            drop: [ALL]
          seccompProfile:
            type: RuntimeDefault
    ```

3. Replace `5000` with your organization's required UID/GID values.
4. Apply the configuration changes.

### Deploy with OpenShift-assigned UIDs

Use this procedure when deploying ITRS Analytics on Red Hat OpenShift Container Platform. OpenShift automatically assigns UID ranges to projects for enhanced security isolation.

1. Find your project's UID range.

   ```bash
   oc describe project <namespace> | grep uid-range
   # Example output: openshift.io/sa.scc.uid-range: 1000680000/10000
   ```

2. Configure the platform to use OpenShift-assigned identities:

   ```yaml
   spec:
     securityContext:
       applySecurityContextDefaults: false
       pod:
         fsGroup: 1000680000   # Optional; OpenShift assigns the rest
   ```

   
**Note**


This configuration is available beginning with ITRS Analytics installation package 2.18.5 and later.



   Container hardening is applied automatically. Do not set `seccompProfile`, because OpenShift injects `RuntimeDefault`.

   No custom SecurityContextConstraints (SCC) is required for this deployment model. The platform runs under the stock `restricted-v2` SCC.

3. After applying your configuration, verify the security contexts are working:

    ```bash
    # Check pod security context
    kubectl get pod <pod-name> -n <namespace> -o yaml | grep -A 10 "securityContext:"

    # Verify process UID/GID inside container
    kubectl exec <pod-name> -n <namespace> -- id

    # Check for policy violations (if using Gatekeeper)
    kubectl get constraints -A
    ```

    Expected output:

    - Process runs with an OpenShift-assigned UID/GID
    - No policy violations
    - All pods in `Running` state

## Troubleshooting

#### My pods don’t start after changing the security context

This issue can occur due to several reasons:

- The UID/GID is outside the allowed range for your cluster.
- There are conflicting pod security policies enforced by admission controllers.
- There are permission issues with attached volumes.

To resolve the issue:

1. Check the pod events using:

    ```
    kubectl describe pod <pod-name>
    ```

2. Verify that your UID/GID is within the cluster’s allowed range.
3. Review admission controller logs to identify any policy violations.

#### Why am I seeing "Permission denied" errors in the logs?

These errors occur when the application cannot write to certain directories or volumes. Common causes include an incorrectly set `fsGroup`, leaving `applySecurityContextDefaults` enabled on a cluster that assigns its own UID/GID range, or a UID/GID mismatch with the volume ownership.

To resolve the issue:

1. Ensure `fsGroup` is set and matches your security policy.
2. If using OpenShift `restricted-v2`, set `applySecurityContextDefaults: false` and only set `fsGroup` if required for your storage configuration. See [Deploy with OpenShift-assigned UIDs](#deploy-with-openshift-assigned-uids).
3. Check volume permissions by running:

    ```
    kubectl exec <pod> -- ls -la /data
    ```

#### Why is my pod creation being blocked by Gatekeeper or Kyverno policies?

This usually happens when the admission controller detects policy violations. Common causes include:

- Missing required security context fields
- Not dropping all capabilities
- Using an incorrect UID/GID range

To resolve the issue:

1. Check which constraints are being violated.

    ```
    kubectl get constraints -A
    ```

2. Review the details of the specific constraint.

    ```
    kubectl describe <constraint-type> <constraint-name>
    ```

3. Update your pod’s security context to comply with the policy requirements.

#### Why do my OpenShift pods fail with “User not allowed”?

This error occurs when OpenShift rejects pods due to permission issues. Common causes include:

- Leaving `applySecurityContextDefaults` enabled so the platform still sets fixed UID/GID values that conflict with the Security Context Constraints (SCC).
- Using an `fsGroup` value that does not match your project or storage requirements.

To resolve the issue:

1. Set `applySecurityContextDefaults: false` so OpenShift can assign the pod UID/GID automatically.
2. Verify project UID range.

    ```
    oc describe project <namespace> | grep uid-range
    ```

3. Set `fsGroup` only if required, typically to the start of the project’s UID range.

#### Why are my pods being blocked with NET_ADMIN or NET_RAW capability violations?

This typically occurs when an admission controller blocks pods due to violations of strict security policies. Common causes include:

- Using Linkerd service mesh without CNI mode enabled.
- Linkerd injecting privileged `linkerd-init` containers that conflict with policies enforced by Pod Security Admission, Gatekeeper, Kyverno, or OpenShift SCCs.

To resolve the issue:

If you are using Linkerd with strict security policies, you must configure Linkerd in CNI mode.

1. Installing the Linkerd CNI plugin before deploying the Linkerd control plane.
2. Enabling CNI mode during Linkerd installation by setting `--set cniEnabled=true`.
3. Following the complete setup instructions in the [Linkerd CNI documentation](https://linkerd.io/2.14/features/cni/).

CNI mode moves traffic redirection from privileged pod init containers to a node-level DaemonSet, allowing your application pods to remain compliant with "drop all capabilities" policies.

