Configure security contexts

Note

The procedures in this topic apply only to ITRS Analytics KOTS installations.

ITRS Analytics supports flexible security context configuration to meet your organization’s security policies, including compliance with Kubernetes Pod Security Standards, OpenShift Security Context Constraints (SCCs), and admission controllers like Gatekeeper and Kyverno.

Security contexts control how containers run, including:

• User and group IDs — which UID/GID the process runs as.
• Linux capabilities — kernel capabilities are granted or dropped.
• Privilege escalation — whether processes can gain additional privileges.
• File system groups — group owns mounted volumes.

Default configuration Copied

ITRS Analytics uses the following default security contexts:

Pod-level Copied

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

Container-level Copied

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

These defaults work out-of-the-box for most Kubernetes clusters and comply with Pod Security Admission (Restricted level), Gatekeeper, Kyverno, and OpenShift Security Context Constraints.

When customization is needed Copied

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: Changing runAsUser with strict security policies for more information.

If you change runAsUser, you must also change fsGroup at the same time. See the FAQ section for complete details on valid security context changes.

Configuration Copied

Basic configuration Copied

To customize security contexts for all ITRS Analytics components, add the following to your ITRS Analytics Platform configuration:

apiVersion: itrsgroup.com/v1
kind: IAXPlatform
metadata:
  name: iax-production
spec:
  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 to all ITRS Analytics workloads, such as databases, services, and applications.

Configuration reference Copied

Pod security context Copied

Container security context Copied

Deployment scenarios Copied

Configure custom user and groupud (UID/GID) ranges Copied

Organization requires specific UID/GID ranges (for example, 5000-6000)

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

Deploy with OpenShift-assigned UIDs Copied

Deploy on OpenShift using project-assigned UID ranges

ITRS Analytics works with OpenShift’s default restricted SCC. No elevated privileges or any UID SCC is required.

1. Find your project’s UID range:

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

2. Configure using the range start as fsGroup:

   spec:
     securityContext:
       pod:
         # Don't specify runAsUser - OpenShift assigns automatically
         fsGroup: 1000680000
       container:
         runAsNonRoot: true
         allowPrivilegeEscalation: false
         capabilities:
           drop: [ALL]
         seccompProfile:
           type: RuntimeDefault
   

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

# 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 your specified UID/GID
• No policy violations
• All pods in Running state

Troubleshooting Copied

Issue: Pods stuck in Pending state Copied

Symptom: Pods don’t start after changing security context

Possible causes:

1. UID/GID outside allowed range for your cluster
2. Conflicting pod security policies
3. Volume permission issues

Solution:

1. Check pod events: kubectl describe pod <pod-name>
2. Verify your UID/GID is within cluster’s allowed range
3. Check admission controller logs for policy violations

Issue: Permission denied errors in logs Copied

Symptom: Application can’t write to directories or volumes

Possible causes:

1. fsGroup not set correctly
2. UID/GID mismatch with volume ownership

Solution:

1. Ensure fsGroup is set and matches your security policy
2. For OpenShift, use project’s UID range for fsGroup (see Use case 2)
3. Check volume permissions: kubectl exec <pod> -- ls -la /data

Issue: Gatekeeper/Kyverno policy violations Copied

Symptom: Admission controller blocks pod creation

Possible causes:

1. Missing required security context fields
2. Not dropping all capabilities
3. Wrong UID/GID range

Solution:

1. Check constraint violations: kubectl get constraints -A
2. Review constraint details: kubectl describe <constraint-type> <constraint-name>
3. Update your security context to match policy requirements

Issue: OpenShift pods fail with “User not allowed” Copied

Symptom: OpenShift rejects pods with permission errors

Possible causes:

1. Specifying runAsUser that conflicts with SCC
2. Wrong fsGroup for project

Solution:

1. Remove runAsUser - let OpenShift assign it
2. Verify project UID range: oc describe project <namespace> | grep uid-range
3. Set fsGroup to project range start

Issue: Pods blocked with NET_ADMIN or NET_RAW capability violations Copied

Symptom: Admission controller blocks pods with errors about NET_ADMIN or NET_RAW capabilities

Possible causes:

1. Using Linkerd service mesh without CNI mode enabled
2. Linkerd injecting privileged linkerd-init containers that conflict with security policies

Solution:

If you are using Linkerd service mesh with admission controllers that enforce strict security policies (Pod Security Admission, Gatekeeper, Kyverno, or OpenShift SCCs), you must configure Linkerd in CNI mode:

1. Install the Linkerd CNI plugin before the Linkerd control plane
2. Enable CNI mode in your Linkerd installation: --set cniEnabled=true
3. See Linkerd CNI documentation for complete setup instructions

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.

Manual recovery for user ID changes Copied

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 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 Copied

For more information about security context configuration, see Using admission controllers and enabling optional logs collection that covers integration with admission controllers (Gatekeeper, Kyverno, Pod Security Admission) and optional logs collection feature.