docs: add Linux capabilities config for pyroscope java #3599
Conversation
marcsanmi
force-pushed
the
marcsanmi/update-java-examples-docs
branch
from
b0f4205
to
a83a4ee
Compare
|
Would the team consider backporting this to the latest release? I'd love to confirm that the backport workflow, most recently modified in #3585, is behaving as intended. |
| ```yaml | ||
| alloy: | ||
| securityContext: | ||
| runAsUser: 0 | ||
| runAsNonRoot: false | ||
| capabilities: | ||
| add: | ||
| - PERFMON | ||
| - SYS_PTRACE | ||
| - SYS_RESOURCE | ||
| - SYS_ADMIN | ||
| ``` |
There was a problem hiding this comment.
Technical question: If we are setting runAsUser: 0 and runAsNonRoot: false, does the process not already have complete capabilities as the process is running as the root user?
There was a problem hiding this comment.
For context, this comes from grafana/alloy#1616.
In Kubernetes, runAsUser: 0 and runAsNonRoot: false run the container as root. However, root privileges don't automatically grant all capabilities in containerized environments. The capabilities setting adds specific capabilities, but its exact behavior depends on the Container Runtime Interface (CRI) used.
AFAIK, in Docker, "The operator can whitelist specific capabilities, and any capabilities not whitelisted are dropped from the container." However, other CRIs may behave differently... 🤔
Maybe adding a comment such as:
# Note: Capability behavior depends on CRI settings. In Docker, non-whitelisted capabilities are dropped by default.
There was a problem hiding this comment.
If you choose to add the note, consider changing whitelisted to allowlisted instead.
Co-authored-by: Jack Baldry <jack.baldry@grafana.com>
marcsanmi
added
type/docs
| ## Additional Configuration for Linux Capabilities | ||
|
|
||
| If your Kubernetes environment has Linux capabilities enabled, configure the following in your Helm values to ensure `pyroscope.java` functions properly: | ||
|
|
||
| ```yaml | ||
| alloy: | ||
| securityContext: | ||
| runAsUser: 0 | ||
| runAsNonRoot: false | ||
| capabilities: | ||
| add: | ||
| - PERFMON | ||
| - SYS_PTRACE | ||
| - SYS_RESOURCE | ||
| - SYS_ADMIN | ||
| ``` | ||
| These capabilities enable Alloy to access performance monitoring subsystems, trace processes, override resource limits, and perform necessary system administration tasks for profiling. | ||
| {{< admonition type="note" >}} | ||
| Adjust capabilities based on your specific security requirements and environment, following the principle of least privilege. | ||
| {{< /admonition >}} | ||
|
|
There was a problem hiding this comment.
I am not sure if this section makes sense to be in this file. We don't use Helm in this example so we can't configure this. Having it in the public docs is definitely great.
On a separate note, the {{<admonition>}} macros wouldn't work in these files afaik.
There was a problem hiding this comment.
You're right, this can be confusing. While alloy is listed as a dependency in pyroscope chart, we're configuring it in our values.yaml. Even moving this configuration next to the pyroscope chart wouldn't make sense.
On a separate note, the {{}} macros wouldn't work in these files afaik.
Good catch! This was me copy-pasting from the other PR 😅
I'm closing it.
There was a problem hiding this comment.
I've made a suggestion to change the admonition shortcode to one used by GitHub markdown.
Instead of including the duplicate contents in the README, you can also just link to the other docs that have the Helm info from the README.
| @@ -78,6 +78,27 @@ see [profiler-options](https://github.com/async-profiler/async-profiler?tab=read | |||
| You must run the collector, either Grafana Alloy (recommended) or Agent (legacy), as root and inside host `pid` namespace for the `pyroscope.java` | |||
| and `discover.process` components to work. | |||
|
|
|||
| ### Additional configuration for Linux capabilities | |||
There was a problem hiding this comment.
| ### Additional configuration for Linux capabilities | |
| ### Optional: Configure Linux capabilities | |
| @@ -40,6 +40,27 @@ After the container is operational, the Grafana Agent profiles the Java applicat | |||
|
|
|||
| You need root privileges to run the Grafana Agent for profiling. The Agent must be executed within the host's PID namespace. | |||
|
|
|||
| ## Additional Configuration for Linux Capabilities | |||
There was a problem hiding this comment.
| ## Additional Configuration for Linux Capabilities | |
| ## Optional: Configure Linux capabilities |
| {{< admonition type="note" >}} | ||
| Adjust capabilities based on your specific security requirements and environment, following the principle of least privilege. | ||
| {{< /admonition >}} |
There was a problem hiding this comment.
Change Hugo shortcode to GitHub flavored Markdown admonition.
| {{< admonition type="note" >}} | |
| Adjust capabilities based on your specific security requirements and environment, following the principle of least privilege. | |
| {{< /admonition >}} | |
| > [!NOTE] | |
| > Adjust capabilities based on your specific security requirements and environment, following the principle of least privilege. |
knylander-grafana
added
the
backport release/v1.8
|
As suggested, I'm closing it to avoid confusion :) |
|
This PR must be merged before a backport PR will be created. |
As per grafana/alloy#1788 (comment)