Adding upstream version 1.29.2.upstream/1.29.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 35 insertions, 26 deletions

diff --git a/claim/README.md b/claim/README.md
index ade6a221f..1d0d6eebe 100644
--- a/claim/README.md
+++ b/claim/README.md
@@ -80,29 +80,30 @@ you don't see the node in your Space after 60 seconds, see the [troubleshooting
 
 ### Claim an Agent running in Docker
 
-The claiming process works with Agents running inside of Docker containers. You can use `docker exec` to run the
-claiming script on containers already running, or append the claiming script to `docker run` to create a new container
-and immediately claim it.
+To claim an instance of the Netdata Agent running inside of a Docker container, either set claiming environment
+variables in the container to have it automatically claimed on startup or restart, or use `docker exec` to manually
+claim an already running container.
 
-#### Running Agent containers
+For claiming to work, the contents of `/var/lib/netdata` _must_ be preserved across container
+restarts using a persistent volume.  See our [recommended `docker run` and Docker Compose
+examples](/packaging/docker/README.md#create-a-new-netdata-agent-container) for details.
 
-Claim a _running Agent container_ by appending the script offered by Cloud to a `docker exec ...` command, replacing
-`netdata` with the name of your running container:
-
-```bash
-docker exec -it netdata netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
-```
+#### Using environment variables
 
-The script should return `Agent was successfully claimed.`. If the claiming script returns errors, or if
-you don't see the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting).
+The Netdata Docker container looks for the following environment variables on startup:
 
-#### New/ephemeral Agent containers
+- `NETDATA_CLAIM_TOKEN`
+- `NETDATA_CLAIM_URL`
+- `NETDATA_CLAIM_ROOMS`
+- `NETDATA_CLAIM_PROXY`
 
-Claim a newly-created container with `docker run ...`.
+If the token and URL are specified in their corresponding variables _and_ the container is not already claimed,
+it will use these values to attempt to claim the container, automatically adding the node to the specified War
+Rooms. If a proxy is specified, it will be used for the claiming process and for connecting to Netdata Cloud.
 
-In the example below, the last line calls the [daemon binary](/daemon/README.md), sets essential variables, and then
-executes claiming using the information after `-W "claim... `. You should copy the relevant token, rooms, and URL from
-Cloud.
+These variables can be specified using any mechanism supported by your container tooling for setting environment
+variables inside containers. For example, when creating a new Netdata continer using `docker run`, the following
+modified version of the command can be used to set the variables:
 
 ```bash
 docker run -d --name=netdata \
@@ -114,24 +115,32 @@ docker run -d --name=netdata \
   -v /proc:/host/proc:ro \
   -v /sys:/host/sys:ro \
   -v /etc/os-release:/host/etc/os-release:ro \
+  -e NETDATA_CLAIM_TOKEN=TOKEN \
+  -e NETDATA_CLAIM_URL="https://app.netdata.cloud" \
+  -e NETDATA_CLAIM_ROOMS=ROOM1,ROOM2 \
   --restart unless-stopped \
   --cap-add SYS_PTRACE \
   --security-opt apparmor=unconfined \
-  netdata/netdata \
-  -W set2 cloud global enabled true -W set2 cloud global "cloud base url" "https://app.netdata.cloud" -W "claim \
-  -token=TOKEN \
-  -rooms=ROOM1,ROOM2 \
-  -url=https://app.netdata.cloud"
+  netdata/netdata
 ```
 
-The container runs in detached mode, so you won't see any output. If the node does not appear in your Space, you can run
-the following to find any error output and use that to guide your [troubleshooting](#troubleshooting). Replace `netdata`
-with the name of your container if different.
+Output that would be seen from the claiming script when using other methods will be present in the container logs.
+
+Using the environment variables like this to handle claiming is the preferred method of claiming Docker containers
+as it works in the widest variety of situations and simplifies configuration management.
+
+#### Using docker exec
+
+Claim a _running Netdata Agent container_ by appending the script offered by Cloud to a `docker exec ...` command, replacing
+`netdata` with the name of your running container:
 
 ```bash
-docker logs netdata 2>&1 | grep -E --line-buffered 'ACLK|claim|cloud'
+docker exec -it netdata netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
 ```
 
+The script should return `Agent was successfully claimed.`. If the claiming script returns errors, or if
+you don't see the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting).
+
 ### Claim a Kubernetes cluster's parent Netdata pod
 
 Read our [Kubernetes installation](/packaging/installer/methods/kubernetes.md#claim-a-kubernetes-clusters-parent-pod)