> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-4-1/cybus-helm-charts/working-with-cybus-helm-charts/overriding-security-contexts.md). # Overriding Security Contexts {% hint style="danger" %} ## Advanced configuration, use with caution Test every security context change before deploying to production. Not all combinations of permissions and container configuration are supported. {% endhint %} ## Default Security Contexts By default, the `connectware` and `connectware-agent` Helm charts apply the following security contexts to follow best practice by running with low privileges: **Pod security context** {% code lineNumbers="true" %} ```yaml runAsNonRoot: true seccompProfile: type: RuntimeDefault fsGroup: 1000 ``` {% endcode %} **Container and init container security context** {% code lineNumbers="true" %} ```yaml allowPrivilegeEscalation: false capabilities: drop: - ALL ``` {% endcode %} These defaults follow Kubernetes security best practices, running all containers as a non-root user with a minimal set of capabilities. ## When to Override Security Contexts You may need to customize these defaults when: * **Custom compliance requirements**: Your organization may require specific `runAsUser`, `runAsGroup`, or `fsGroup` values to meet security policy or regulatory requirements. * **Restricted cluster policies**: Some clusters enforce admission controllers or OPA policies that require specific security context values. For example, OpenShift manages UID/GID assignments through `SecurityContextConstraints` (SCC), and setting `fsGroup` can conflict with OpenShift's pod admission. ## Configuration Values The following Helm values can be used to customize security contexts. All overrides accept [standard Kubernetes security context definitions](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/). {% tabs %} {% tab title="connectware Helm Chart Values" %} | Value | Description | | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `global.podSecurityContextOverride` | Overrides the pod security context. | | `global.containerSecurityContextOverride` | Overrides the container security context. | | `global.initContainerSecurityContextOverride` | Overrides the init container security context. If not set, falls back to `containerSecurityContext`. | | `${COMPONENT_NAME}.podSecurityContextOverride` | Overrides the pod security context for a specific component. | | `${COMPONENT_NAME}.containerSecurityContextOverride` | Overrides the container security context for a specific component. | | `${COMPONENT_NAME}.initContainerSecurityContextOverride` | Overrides the init container security context for a specific component. If not set, falls back to `containerSecurityContext`. | | {% endtab %} | | {% tab title="connectware-agent Helm Chart Values" %} | Value | Description | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `protocolMapperAgentDefaults.podSecurityContextOverride` | Overrides the pod security context for all agents. | | `protocolMapperAgentDefaults.containerSecurityContextOverride` | Overrides the container security context for all agents. | | `protocolMapperAgentDefaults.initContainerSecurityContextOverride` | Overrides the init container security context for all agents. If not set, falls back to `containerSecurityContext`. | | `protocolMapperAgents[].${AGENT_NAME}.podSecurityContextOverride` | Overrides the pod security context for a specific agent. | | `protocolMapperAgents[].${AGENT_NAME}.containerSecurityContextOverride` | Overrides the container security context for a specific agent. | | `protocolMapperAgents[].${AGENT_NAME}.initContainerSecurityContextOverride` | Overrides the init container security context for a specific agent. If not set, falls back to `containerSecurityContext`. | | {% endtab %} | | | {% endtabs %} | | {% hint style="warning" %} ## Overrides fully replace defaults without key merging Security context overrides **fully replace** the default security context, individual keys are not merged. If you supply a `podSecurityContextOverride` with only `runAsUser: 2000`, all other defaults (`runAsNonRoot`, `fsGroup`, `seccompProfile`) are absent from the rendered manifest. You must include every field you want to retain. {% endhint %} ## Configuring Security Contexts The following tabs show how to configure security context overrides for the `connectware` Helm chart and the `connectware-agent` Helm chart. {% tabs %} {% tab title="connectware Helm Chart" %} ## Configuring a Global Security Context Override To apply a custom security context to all Connectware components at once, set the override values under `global`. **Example: Setting a custom pod security context globally** {% code title="values.yaml" lineNumbers="true" %} ```yaml global: podSecurityContextOverride: runAsNonRoot: true runAsUser: 2000 fsGroup: 2000 seccompProfile: type: RuntimeDefault ``` {% endcode %} **Example: Setting a custom container security context globally** {% code title="values.yaml" lineNumbers="true" %} ```yaml global: containerSecurityContextOverride: allowPrivilegeEscalation: false capabilities: drop: - ALL runAsUser: 2000 ``` {% endcode %} **Example: Setting a separate init container security context globally** If not set, `initContainerSecurityContextOverride` falls back to `containerSecurityContextOverride`. {% code title="values.yaml" lineNumbers="true" %} ```yaml global: containerSecurityContextOverride: allowPrivilegeEscalation: false capabilities: drop: - ALL initContainerSecurityContextOverride: allowPrivilegeEscalation: false capabilities: drop: - ALL runAsUser: 1001 ``` {% endcode %} ## Configuring a Per-Component Security Context Override You can override the security contexts for individual components by setting the same values under their own configuration section. A component-level value takes precedence over the global value. All Connectware components support this value. **Example: Overriding the pod security context for the auth-server only** {% code title="values.yaml" lineNumbers="true" %} ```yaml global: # Note: 'authServer' is used as an example, but this configuration # is applicable to any Connectware component. authServer: podSecurityContextOverride: runAsNonRoot: true runAsUser: 1001 runAsGroup: 1001 fsGroup: 1001 seccompProfile: type: RuntimeDefault ``` {% endcode %} {% hint style="info" %} Only the `authServer` pod security context is overridden here. All other components retain their default security contexts, including other containers within the `authServer` pod. {% endhint %} ## Setting a Global Override with a Per-Component Exception To apply a global security context while overriding a specific component, combine `global` values with a component-specific `podSecurityContextOverride`. **Example: Global override with a per-component exception for the broker** {% code title="values.yaml" lineNumbers="true" %} ```yaml global: podSecurityContextOverride: runAsNonRoot: true runAsUser: 1001 fsGroup: 1001 seccompProfile: type: RuntimeDefault containerSecurityContextOverride: allowPrivilegeEscalation: false capabilities: drop: - ALL runAsUser: 1001 broker: podSecurityContextOverride: runAsNonRoot: true runAsUser: 1002 fsGroup: 1002 seccompProfile: type: RuntimeDefault ``` {% endcode %} {% hint style="info" %} The `broker` component uses its own `podSecurityContextOverride`, which takes precedence over the global value. All other components use the global security context override. {% endhint %} {% endtab %} {% tab title="connectware-agent Helm Chart" %} The `connectware-agent` Helm chart can be deployed standalone or as a subchart within the `connectware` Helm chart. Both deployment modes use the same values structure, but when deployed as a subchart, configure it under the `connectwareAgent` section. ## Configuring a Default Security Context for All Agents (Standalone Deployment) To apply a custom security context to all agent pods at once, set the override values under `protocolMapperAgentDefaults`. {% code title="values.yaml" lineNumbers="true" %} ```yaml protocolMapperAgentDefaults: podSecurityContextOverride: runAsNonRoot: true runAsUser: 1001 fsGroup: 1001 seccompProfile: type: RuntimeDefault containerSecurityContextOverride: allowPrivilegeEscalation: false capabilities: drop: - ALL protocolMapperAgents: - name: my-agent-1 - name: my-agent-2 ``` {% endcode %} ## Configuring a Security Context for a Specific Agent (Standalone Deployment) Individual agents can override the default setting by setting the same values under their own entry in `protocolMapperAgents[]`. An agent-level value completely replaces the default configuration. **Example: Overriding the pod security context for a specific agent** {% code title="values.yaml" lineNumbers="true" %} ```yaml protocolMapperAgentDefaults: podSecurityContextOverride: runAsNonRoot: true runAsUser: 1001 fsGroup: 1001 seccompProfile: type: RuntimeDefault containerSecurityContextOverride: allowPrivilegeEscalation: false capabilities: drop: - ALL protocolMapperAgents: - name: my-standard-agent - name: my-special-agent podSecurityContextOverride: runAsNonRoot: true runAsUser: 1002 fsGroup: 1002 seccompProfile: type: RuntimeDefault ``` {% endcode %} ## Deploying Agents as Part of the connectware Helm Chart with a Global Override When deploying agents as part of the `connectware` Helm chart, setting a global security context override applies to all components, including agents. {% code title="values.yaml" lineNumbers="true" %} ```yaml global: podSecurityContextOverride: runAsNonRoot: true runAsUser: 2000 runAsGroup: 2000 fsGroup: 2000 seccompProfile: type: RuntimeDefault containerSecurityContextOverride: allowPrivilegeEscalation: false capabilities: drop: - ALL connectwareAgent: # ... shared defaults protocolMapperAgents: - name: my-agent ``` {% endcode %} ## Deploying Agents as Part of the connectware Helm Chart with a Per-Agent Override When deploying agents as part of the `connectware` Helm chart, you can combine a global security context override with a per-agent exception. Set the global values under `global`, then override a specific agent within the `connectwareAgent` section. {% code title="values.yaml" lineNumbers="true" %} ```yaml global: podSecurityContextOverride: runAsNonRoot: true runAsUser: 2000 runAsGroup: 2000 fsGroup: 2000 seccompProfile: type: RuntimeDefault containerSecurityContextOverride: allowPrivilegeEscalation: false capabilities: drop: - ALL connectwareAgent: # ... shared defaults protocolMapperAgents: - name: my-standard-agent - name: my-special-agent podSecurityContextOverride: runAsNonRoot: true runAsUser: 1003 fsGroup: 1003 seccompProfile: type: RuntimeDefault ``` {% endcode %} {% hint style="info" %} Only `my-special-agent` uses its own `podSecurityContextOverride`. `my-standard-agent` inherits the global security context. {% endhint %} {% endtab %} {% endtabs %} ## Unsetting fsGroup for OpenShift On OpenShift, setting `fsGroup` in the pod security context can conflict with OpenShift's `SecurityContextConstraints` (SCC) admission. The recommended approach is to set `fsGroup` to `null`, which allows OpenShift to manage the security context according to the applied SCC. {% tabs %} {% tab title="connectware Helm Chart" %} Override the default pod security context in the `connectware` Helm chart to allow OpenShift to manage the `fsGroup` assignment: {% code title="values.yaml" lineNumbers="true" %} ```yaml global: podSecurityContextOverride: runAsNonRoot: true fsGroup: null seccompProfile: type: RuntimeDefault ``` {% endcode %} {% endtab %} {% tab title="connectware-agent Helm Chart" %} Override the default pod security context in the `connectware-agent` Helm chart to allow OpenShift to manage the `fsGroup` assignment: {% code title="values.yaml" lineNumbers="true" %} ```yaml protocolMapperAgentDefaults: podSecurityContextOverride: runAsNonRoot: true fsGroup: null seccompProfile: type: RuntimeDefault protocolMapperAgents: - name: my-agent ``` {% endcode %} {% endtab %} {% endtabs %} ## Reference For the full list of security-context-related Helm values, see the [Helm Chart Reference](/2-4-1/reference/helm-chart-reference.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cybus.io/2-4-1/cybus-helm-charts/working-with-cybus-helm-charts/overriding-security-contexts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.