elastic / elastic/docs-content
[Internal]: Provide a minimal-permission custom SCC for running Elastic Agent on OpenShift
- Dominant language
- No language data
- Stars
- 47
- Forks
- 261
- Avg merge
- 3d 12h
- Merged PRs (30d)
- 116
Description
### Description
**Summary**
There is no documentation describing a least-privilege custom SecurityContextConstraints (SCC) for running Elastic Agent on OpenShift. The current guidance for vanilla k8s doesn't work on OpenShift or pushes users toward the built-in `privileged` SCC, which grants far more access than Agent actually needs. We should document a minimal custom SCC and the steps to apply it. This would apply to all scenarios:
- Fleet managed Elastic Agent on OpenShift
- Standalone Elastic Agent on OpenShift
- Elastic Agent using the ECK Operator on OpenShift
Source documents:
* [Run Elastic Agent Standalone on Kubernetes - Red Hat Openshift](https://www.elastic.co/docs/reference/fleet/running-on-kubernetes-standalone#_red_hat_openshift_configuration) advises to grant the `privileged` SCC.
* [Grant host access permission to Elastic Agent](https://www.elastic.co/guide/en/cloud-on-k8s/master/k8s-openshift-agent.html) (ECK docs) advises to grant the `hostacess` SCC which is insufficient.
There is no equivalent page yet on the Fleet-managed (non-ECK) side — OpenShift support for Elastic Agent only became GA in stack 9.5 (see [elastic/opentelemetry#663](https://github.com/elastic/opentelemetry/pull/663)), so that guidance likely needs to be created from scratch rather than edited.
**Problem**
Elastic Agent (Fleet-managed, Standalone & ECK) commonly needs to run as a DaemonSet with `hostNetwork: true`, host path mounts (/var/log, /proc, /sys, container runtime socket), and runAsUser: 0, in order to collect host/container metrics and logs.
Two workarounds exist today, one is documented and is not the best from a security standpoint:
* Grant the `privileged SCC` to the Agent service account `(oc adm policy add-scc-to-user privileged -z elastic-agent -n )`. This is what most existing docs/examples imply, but it grants the service account far more than Agent needs (arbitrary host PID/IPC access, any capability, any SELinux context, etc.) — a real concern for security-conscious OpenShift admins and a common blocker in enterprise/regulated deployments.
* Create a custom, scoped-down SCC that grants only what Agent actually requires. This works but has never been published as official guidance.
**Impact**
* OpenShift customers/admins either over-grant permissions (privileged SCC) to get Agent running, which fails security reviews, or they can't deploy Elastic Agent/OTel Collector at all.
* Support and Services teams currently have to create a custom SCC per engagement instead of pointing to official guidance.
**Proposed solution**
Publish (in the Elastic Agent / Fleet OpenShift docs, and mirrored in ECK docs) a minimal custom SCC manifest, validated end-to-end, scoped to only the fields Agent/OTel Collector needs.
```
apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
metadata:
name: elastic-agent-scc
allowHostDirVolumePlugin: true # needed for hostPath mounts (logs, container runtime socket)
allowHostIPC: false # not required unless using specific host-based receivers
allowHostNetwork: true # needed for hostNetwork: true
allowHostPID: false # not required unless using specific host-based receivers
allowHostPorts: false
allowPrivilegeEscalation: true # required for some capabilities to take effect
allowPrivilegedContainer: false # avoid full privileged mode if possible; test with capabilities instead
allowedCapabilities:
- CHOWN
- DAC_OVERRIDE
- FOWNER
- SETUID
- SETGID
- NET_ADMIN # only if network-related integrations require it
fsGroup:
type: RunAsAny
priority: 0
readOnlyRootFilesystem: false
requiredDropCapabilities: []
runAsUser:
type: RunAsAny # needed to allow runAsUser: 0 for host log/file access
seLinuxContext:
type: RunAsAny
seccompProfiles:
- runtime/default
supplementalGroups:
type: RunAsAny
volumes:
- configMap
- emptyDir
- hostPath
- projected
- secret
users:
- system:serviceaccount::elastic-agent
groups:
- system:serviceaccounts:
```
**How to apply the custom SCC (for reference in the doc)**
```
# 1. Create the SCC
oc apply -f elastic-agent-scc.yaml
# 2. Bind it to the Agent service account
oc adm policy add-scc-to-user elastic-agent-scc -z elastic-agent -n
# 3. Verify
oc get scc elastic-agent-scc
oc describe scc elastic-agent-scc
oc get pod -n -o yaml | grep -A5 securityContext
```
### Resources
https://github.com/elastic/opentelemetry/pull/663
https://www.elastic.co/docs/reference/fleet/running-on-kubernetes-standalone#_red_hat_openshift_configuration
### Which deployment methods does this change impact?
Elastic On-Prem only (ECE, ECK, or self-managed)
### Feature differences
_No response_
### What Elastic Stack release is this request related to?
9.5
### Serverless release
_No response_
### Collaboration model
The documentation team will create the first draft
### Point of contact.
**Main contact:** @
**Stakeholders:**
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.