Update claiming docs for Docker containers. (#10570)
* Update claiming docs for Docker containers. * Updates requested by @joelhans. * Further address feedback.
Austin S. Hemmelgarn committed
Feb 10, 2021 at 13:49 UTC
7cb1450b7b42117dfb261f21137019cf5585b4fb
1 file changed
+35
-26
claim/README.md
+35
-26
@@ -80,29 +80,30 @@ you don't see the node in your Space after 60 seconds, see the [troubleshooting
80
81
### Claim an Agent running in Docker
82
83
-The claiming process works with Agents running inside of Docker containers. You can use `docker exec` to run the
84
-claiming script on containers already running, or append the claiming script to `docker run` to create a new container
85
-and immediately claim it.
83
+To claim an instance of the Netdata Agent running inside of a Docker container, either set claiming environment
84
+variables in the container to have it automatically claimed on startup or restart, or use `docker exec` to manually
85
+claim an already running container.
86
87
-#### Running Agent containers
87
+For claiming to work, the contents of `/var/lib/netdata` _must_ be preserved across container
88
+restarts using a persistent volume. See our [recommended `docker run` and Docker Compose
89
+examples](/packaging/docker/README.md#create-a-new-netdata-agent-container) for details.
90
89
-Claim a _running Agent container_ by appending the script offered by Cloud to a `docker exec ...` command, replacing
90
-`netdata` with the name of your running container:
91
-
92
-```bash
93
-docker exec -it netdata netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
94
-```
91
+#### Using environment variables
92
96
-The script should return `Agent was successfully claimed.`. If the claiming script returns errors, or if
97
-you don't see the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting).
93
+The Netdata Docker container looks for the following environment variables on startup:
94
99
-#### New/ephemeral Agent containers
95
+- `NETDATA_CLAIM_TOKEN`
96
+- `NETDATA_CLAIM_URL`
97
+- `NETDATA_CLAIM_ROOMS`
98
+- `NETDATA_CLAIM_PROXY`
99
101
-Claim a newly-created container with `docker run ...`.
100
+If the token and URL are specified in their corresponding variables _and_ the container is not already claimed,
101
+it will use these values to attempt to claim the container, automatically adding the node to the specified War
102
+Rooms. If a proxy is specified, it will be used for the claiming process and for connecting to Netdata Cloud.
103
103
-In the example below, the last line calls the [daemon binary](/daemon/README.md), sets essential variables, and then
104
-executes claiming using the information after `-W "claim... `. You should copy the relevant token, rooms, and URL from
105
-Cloud.
104
+These variables can be specified using any mechanism supported by your container tooling for setting environment
105
+variables inside containers. For example, when creating a new Netdata continer using `docker run`, the following
106
+modified version of the command can be used to set the variables:
107
108
```bash
109
docker run -d --name=netdata \
@@ -114,24 +115,32 @@ docker run -d --name=netdata \
115
-v /proc:/host/proc:ro \
116
-v /sys:/host/sys:ro \
117
-v /etc/os-release:/host/etc/os-release:ro \
118
+ -e NETDATA_CLAIM_TOKEN=TOKEN \
119
+ -e NETDATA_CLAIM_URL="https://app.netdata.cloud" \
120
+ -e NETDATA_CLAIM_ROOMS=ROOM1,ROOM2 \
121
--restart unless-stopped \
122
--cap-add SYS_PTRACE \
123
--security-opt apparmor=unconfined \
120
- netdata/netdata \
121
- -W set2 cloud global enabled true -W set2 cloud global "cloud base url" "https://app.netdata.cloud" -W "claim \
122
- -token=TOKEN \
123
- -rooms=ROOM1,ROOM2 \
124
- -url=https://app.netdata.cloud"
124
+ netdata/netdata
125
```
126
127
-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
128
-the following to find any error output and use that to guide your [troubleshooting](#troubleshooting). Replace `netdata`
129
-with the name of your container if different.
127
+Output that would be seen from the claiming script when using other methods will be present in the container logs.
128
+
129
+Using the environment variables like this to handle claiming is the preferred method of claiming Docker containers
130
+as it works in the widest variety of situations and simplifies configuration management.
131
+
132
+#### Using docker exec
133
+
134
+Claim a _running Netdata Agent container_ by appending the script offered by Cloud to a `docker exec ...` command, replacing
135
+`netdata` with the name of your running container:
136
137
```bash
132
-docker logs netdata 2>&1 | grep -E --line-buffered 'ACLK|claim|cloud'
138
+docker exec -it netdata netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
139
```
140
141
+The script should return `Agent was successfully claimed.`. If the claiming script returns errors, or if
142
+you don't see the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting).
143
+
144
### Claim a Kubernetes cluster's parent Netdata pod
145
146
Read our [Kubernetes installation](/packaging/installer/methods/kubernetes.md#claim-a-kubernetes-clusters-parent-pod)