diff options
Diffstat (limited to 'claim/README.md')
| -rw-r--r-- | claim/README.md | 61 |
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) |