elastic / elastic/docs-content

[Internal]: Provide a minimal-permission custom SCC for running Elastic Agent on OpenShift

Open
#7,972 4 comments 0 reactions 2 assignees Claimed by @samuelvl View on GitHub
documentation Team:SKI triaged
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.