Docs: Add Docker instructions to claiming (#8755)
* Trying some options * Add Docker command to claiming * Fix linter error * Fix broken links * Add docker run command * Added sections for running/ephemeral containers * Fixes for James
Joel Hans committed
Apr 21, 2020 at 11:16 UTC
a153129c0c01492d44073a141f5ee1d5e174d037
2 files changed
+57
-14
aclk/README.md
+1
-1
@@ -27,7 +27,7 @@ in the `[cloud]` section of `netdata.conf`.
27
```
28
29
If your Agent needs to use a proxy to access the internet, you must [set up a proxy for
30
-claiming](/claim/README.md#claiming-through-a-proxy).
30
+claiming](/claim/README.md#claim-through-a-proxy).
31
32
## Disable the ACLK
33
claim/README.md
+56
-13
@@ -54,14 +54,60 @@ With `sudo`:
54
sudo netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
55
```
56
57
-Hit **Enter**. The script should return `Agent was successfully claimed.`.
57
+Hit **Enter**. The script should return `Agent was successfully claimed.`. If the claiming script returns errors, see
58
+the [troubleshooting information](#troubleshooting).
59
60
> Your node may need up to 60 seconds to connect to Netdata Cloud after finishing the claiming process. Please be
61
> patient!
62
62
-If the claiming script returns errors, see the [troubleshooting information](#troubleshooting).
63
+### Claim an Agent running in Docker
64
64
-### Claiming through a proxy
65
+The claiming process works with Agents running inside of Docker containers. You can use `docker exec` to run the
66
+claiming script on containers already running, or append the claiming script to `docker run` to create a new container
67
+and immediately claim it.
68
+
69
+#### Running Agent containers
70
+
71
+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:
72
+
73
+```bash
74
+docker exec -it netdata netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
75
+```
76
+
77
+The script should return `Agent was successfully claimed.`. If the claiming script returns errors, see the
78
+[troubleshooting information](#troubleshooting).
79
+
80
+#### New/ephemeral Agent containers
81
+
82
+Claim a newly-created container with `docker run ...`.
83
+
84
+In the example below, the last line calls the [daemon binary](/daemon/README.md), sets essential variables, and then
85
+executes claiming using the information after `-W "claim... `. You should copy the relevant token, rooms, and URL from
86
+Cloud.
87
+
88
+```bash
89
+docker run -d --name=netdata \
90
+ -p 19999:19999 \
91
+ -v /etc/passwd:/host/etc/passwd:ro \
92
+ -v /etc/group:/host/etc/group:ro \
93
+ -v /proc:/host/proc:ro \
94
+ -v /sys:/host/sys:ro \
95
+ -v /etc/os-release:/host/etc/os-release:ro \
96
+ --cap-add SYS_PTRACE \
97
+ --security-opt apparmor=unconfined \
98
+ netdata/netdata \
99
+ /usr/sbin/netdata -D -W set global "netdata cloud" enable -W set cloud "cloud base url" "https://app.netdata.cloud" -W "claim -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud"
100
+```
101
+
102
+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
103
+the following to find any error output and use that to guide your [troubleshooting](#troubleshooting). Replace `netdata`
104
+with the name of your container if different.
105
+
106
+```bash
107
+docker logs netdata 2>&1 | grep -E --line-buffered 'ACLK|claim|cloud'
108
+```
109
+
110
+### Claim through a proxy
111
112
A Space's administrator can claim a node through a SOCKS5 or HTTP(S) proxy.
113
@@ -88,7 +134,8 @@ For example, a SOCKS5 proxy setting may look like the following:
134
proxy = socks5h://proxy.example.com:1080 # With a URL
135
```
136
91
-You can now move on to claiming. Be sure to switch to the `netdata` user or use `sudo` as explained in the [step above](#how-to-claim-a-node).
137
+You can now move on to claiming. Be sure to switch to the `netdata` user or use `sudo` as explained in the [step
138
+above](#how-to-claim-a-node).
139
140
When you claim with the `netdata-claim.sh` script, add the `-proxy=` parameter and append the same proxy setting you
141
added to `netdata.conf`.
@@ -97,19 +144,15 @@ added to `netdata.conf`.
144
netdata-claim.sh -token=MYTOKEN1234567 -rooms=room1,room2 -url=https://app.netdata.cloud -proxy=socks5h://203.0.113.0:1080
145
```
146
100
-Hit **Enter**. The script should return `Agent was successfully claimed.`.
101
-
102
-> Your node may need up to 60 seconds to connect to Netdata Cloud after finishing the claiming process. Please be
103
-> patient!
104
-
105
-If the claiming script returns errors, see the [troubleshooting information](#troubleshooting).
147
+Hit **Enter**. The script should return `Agent was successfully claimed.`. If the claiming script returns errors, see
148
+the [troubleshooting information](#troubleshooting).
149
150
### Troubleshooting
151
152
If you're having trouble claiming a node, this may be because the ACLK cannot connect to Cloud.
153
111
-With the Netdata Agent running, visit `http://127.0.0.1/api/v1/info` in your browser. The returned JSON contains four
112
-keys that will be helpful to diagnose any issues you might be having with the ACLK or claiming process.
154
+With the Netdata Agent running, visit `http://localhost:19999/api/v1/info` in your browser. The returned JSON contains
155
+four keys that will be helpful to diagnose any issues you might be having with the ACLK or claiming process.
156
157
```json
158
"cloud-enabled"
@@ -182,7 +225,7 @@ If `aclk-available` is `false` and all other keys are `true`, your Agent is havi
225
through the ACLK. Please check your system's firewall.
226
227
If your Agent needs to use a proxy to access the internet, you must [set up a proxy for
185
-claiming](#claiming-through-a-proxy).
228
+claiming](#claim-through-a-proxy).
229
230
If you are certain firewall and proxy settings are not the issue, you should consult the Agent's `error.log` at
231
`/var/log/netdata/error.log` and contact us by [creating an issue on