README.md: update the readme with instructions for installation (#35)

* README.md: update the readme with instructions for installation

* Add instructions for installations from the latest release
* Add instructions to run the agent inside a container

* README.md: edit instruction to highlight agent should be running as root

README.md

@@ -4,7 +4,15 @@ This is an experimental fork of [elastic/otel-profiling-agent](https://github.co
 
 Our fork adds support for sending profiling data to the Datadog backend via the Datadog Agent. We are active members of the OpenTelemetry Profiling SIG that is working on the OpenTelemetry profiling signal. However, the signal is still under active development, so this fork can be used by Datadog users until we release our support for directly ingesting the data using OTLP.
 
-## Build
+## Installation
+
+Download pre-built amd64 and arm64 binaries for our [latest release](https://github.com/DataDog/otel-profiling-agent/releases/latest).
+
+Alternatively, you can build the agent from source. The following instructions assume you have docker installed.
+
+<details>
+<summary>Manual build instructions</summary>
+<br />
 
 To build the agent, you can use the following commands:
 
@@ -15,7 +23,7 @@ make agent
 
 This will create a `otel-profiling-agent` binary in the current directory.
 
-Alternatively you can download pre-built amd64 and arm64 binaries for our [latest release](https://github.com/DataDog/otel-profiling-agent/releases/latest).
+</details>
 
 ## Run
 
@@ -25,14 +33,57 @@ To run the agent, you need to make sure that debugfs is mounted. If it's not, yo
 sudo mount -t debugfs none /sys/kernel/debug
 ```
 
-After that, you can start the agent as shown below:
+After that, you can start the agent as shown below (make sure you run it as root):
 
 ```
 sudo otel-profiling-agent -tags 'service:myservice' -collection-agent "http://localhost:8126" -reporter-interval 60s -samples-per-second 20
 ```
 
 For this to work you need to run a Datadog agent that listens for APM traffic at `localhost:8126`. If your agent is reachable under a different address, you can modify the `-collection-agent` parameter accordingly.
 
+## Running inside a container
+
+#### Requirements
+
+When running the agent in a container, you need to ensure the following conditions are met:
+* The container is running in privileged mode.
+* The container has the `SYS_ADMIN` capability.
+* The container has Host PID enabled (and procMount: "Unmasked").
+* The host's debugfs filesystem is mounted to the container (in read-only mode).
+* The agent is running as root inside the container.
+
+#### Container name resolution
+
+To be able to resolve container names, the agent needs to be able to access the underlying container runtime (in read-only mode). The agent supports Docker and containerd.
+
+To enable this feature, you need to mount the container runtime socket to the agent container in read-only mode (`/var/run/docker.sock` for Docker, `/run/containerd/containerd.sock` for containerd).
+
+#### Pod name resolution
+
+To be able to resolve pod names in Kubernetes, the agent needs to be able to:
+
+1. Get the `KUBERNETS_NODE_NAME` environment variable:
+```yaml
+env:
+  - name: KUBERNETES_NODE_NAME
+    valueFrom:
+      fieldRef:
+        fieldPath: spec.nodeName
+```
+
+2. Access the underlying Kubernetes API server. This is usually done through a ClusterRole and ClusterRoleBinding with the following permissions:
+```yaml
+rules:
+  - verbs:
+      - get
+      - watch
+      - list
+    resources:
+      - nodes
+    apiGroups:
+      - ""
+```
+
 ## Configuration
 
 ### Local symbol upload (Experimental)