diff options
Diffstat (limited to 'claim/README.md')
| -rw-r--r-- | claim/README.md | 205 |
1 files changed, 114 insertions, 91 deletions
diff --git a/claim/README.md b/claim/README.md index f1d893eb..d88167ad 100644 --- a/claim/README.md +++ b/claim/README.md @@ -1,22 +1,12 @@ -<!-- -title: "Connect Agent to Cloud" -description: "Connecting a Netdata Agent, running on a distributed node, to Netdata Cloud securely via the encrypted Agent-Cloud link (ACLK)." -custom_edit_url: "https://github.com/netdata/netdata/edit/master/claim/README.md" -sidebar_label: "Connect Agent to Cloud" -learn_status: "Published" -learn_topic_type: "Tasks" -learn_rel_path: "Setup" ---> - # Connect Agent to Cloud +This page will guide you through connecting a Netdata Agent to Netdata Cloud securely, via the encrypted Agent-Cloud link (ACLK). + You can securely connect a Netdata Agent, running on a distributed node, to Netdata Cloud. A Space's administrator creates a **claiming token**, which is used to add an Agent to their Space via the [Agent-Cloud link (ACLK)](https://github.com/netdata/netdata/blob/master/aclk/README.md). -Are you just starting out with Netdata Cloud? See our [get started with -Cloud](https://github.com/netdata/netdata/blob/master/docs/cloud/cloud.mdx) guide for a walkthrough of the process and simplified -instructions. +Are you just getting started with Netdata Cloud? You can find simplified instructions in the [Install Netdata documentation](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#get-started) When connecting an agent (also referred to as a node) to Netdata Cloud, you must complete a verification process that proves you have some level of authorization to manage the node itself. This verification is a security feature that helps prevent unauthorized users from seeing the data on your node. @@ -32,35 +22,37 @@ identity of the Netdata Agent when it connects to the Cloud. While the data does from Agents to the browser, we do not store or log it. You can connect a node during the Netdata Cloud onboarding process, or after you created a Space by clicking on **Connect -Nodes** in the [Spaces management area](https://github.com/netdata/netdata/blob/master/docs/cloud/cloud.mdx#manage-spaces). +Nodes** in the [Spaces management area](https://github.com/netdata/netdata/blob/master/docs/cloud/spaces.md#manage-spaces). There are two important notes regarding connecting nodes: -- _You can only connect any given node in a single Space_. You can, however, add that connected node to multiple War Rooms +- _You can only connect any given node in a single Space_. You can, however, add that connected node to multiple War Rooms within that one Space. -- You must repeat the connection process on every node you want to add to Netdata Cloud. +- You must repeat the connection process on every node you want to add to Netdata Cloud. ## How to connect a node There will be three main flows from where you might want to connect a node to Netdata Cloud. -* when you are on an [ -War Room](#empty-war-room) and you want to connect your first node -* when you are at the [Manage Space](#manage-space-or-war-room) area and you select **Connect Nodes** to connect a node, coming from Manage Space or Manage War Room -* when you are on the [Nodes view page](https://github.com/netdata/netdata/blob/master/docs/cloud/visualize/nodes.md) and want to connect a node - this process falls into the [Manage Space](#manage-space-or-war-room) flow + +- when you are on a [War Room](#empty-war-room) and you want to connect your first node +- when you are at the [Manage Space](#manage-space-or-war-room) area and you select **Connect Nodes** to connect a node, coming from Manage Space or Manage War Room +- when you are on the [Nodes tab](https://github.com/netdata/netdata/blob/master/docs/cloud/visualize/nodes.md) and want to connect a node - this process falls into the [Manage Space](#manage-space-or-war-room) flow Please note that only the administrators of a Space in Netdata Cloud can view the claiming token and accompanying script, generated by Netdata Cloud, to trigger the connection process. ### Empty War Room Either at your first sign in or following ones, when you enter Netdata Cloud and are at a War Room that doesn’t have any node added to it, you will be able to: -* connect a new node to Netdata Cloud and add it to the War Room -* add a previously connected node to the War Room + +- connect a new node to Netdata Cloud and add it to the War Room +- add a previously connected node to the War Room If your case is to connect a new node and add it to the War Room, you will need to tell us what environment the node is running on (Linux, Docker, macOS, Kubernetes) and then we will provide you with a script to initiate the connection process. You just will need to copy and paste it into your node's terminal. See one of the following sections depending on your case: -* [Linux](#connect-an-agent-running-in-linux) -* [Docker](#connect-an-agent-running-in-docker) -* [macOS](#connect-an-agent-running-in-macos) -* [Kubernetes](#connect-a-kubernetes-clusters-parent-netdata-pod) + +- [Linux](#connect-an-agent-running-in-linux) +- [Docker](#connect-an-agent-running-in-docker) +- [macOS](#connect-an-agent-running-in-macos) +- [Kubernetes](#connect-a-kubernetes-clusters-parent-netdata-pod) Repeat this process with every node you want to add to Netdata Cloud during onboarding. You can also add more nodes once you've finished onboarding. @@ -70,15 +62,16 @@ finished onboarding. To connect a node, select which War Rooms you want to add this node to with the dropdown, then copy and paste the script given by Netdata Cloud into your node's terminal. -When coming from [Nodes view page](https://github.com/netdata/netdata/blob/master/docs/cloud/visualize/nodes.md) the room parameter is already defined to current War Room. +When coming from the [Nodes tab](https://github.com/netdata/netdata/blob/master/docs/cloud/visualize/nodes.md) the room parameter is already defined to current War Room. ### Connect an agent running in Linux If you want to connect a node that is running on a Linux environment, the script that will be provided to you by Netdata Cloud is the [kickstart](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#automatic-one-line-installation-script) which will install the Netdata Agent on your node, if it isn't already installed, and connect the node to Netdata Cloud. It should be similar to: -``` +```bash wget -O /tmp/netdata-kickstart.sh https://my-netdata.io/kickstart.sh && sh /tmp/netdata-kickstart.sh --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://api.netdata.cloud ``` + The script should return `Agent was successfully claimed.`. If the connecting to Netdata Cloud process returns errors, or if you don't see the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting). @@ -107,18 +100,18 @@ and run the script. ```bash wget -O /tmp/netdata-kickstart.sh https://my-netdata.io/kickstart.sh && sh /tmp/netdata-kickstart.sh --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://api.netdata.cloud ``` + ### Connect an agent running in Docker To connect an instance of the Netdata Agent running inside of a Docker container, it is recommended that you follow -the instructions and use the commands provided either in the `Nodes` tab of an [empty War Room](#empty-war-room) on Netdata Cloud or -in the shelf that appears when you click **Connect Nodes** and select **Docker**. +the instructions and use the commands provided either in the `Nodes` tab of an [empty War Room](#empty-war-room) on Netdata Cloud or +in the shelf that appears when you click **Connect Nodes** and select **Docker**. -However, users can also claim a new node by claiming environment variables in the container to have it automatically +However, users can also claim a new node by claiming environment variables in the container to have it automatically connected on startup or restart. For the connection process 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](https://github.com/netdata/netdata/blob/master/packaging/docker/README.md#create-a-new-netdata-agent-container) for details. +restarts using a persistent volume. See our [recommended `docker run` and Docker Compose examples](https://github.com/netdata/netdata/blob/master/packaging/docker/README.md#create-a-new-netdata-agent-container) for details. #### Known issues on older hosts with seccomp enabled @@ -137,9 +130,9 @@ CONFIG_SECCOMP=y To resolve the issue, do one of the following actions: -- Update to a newer version of Docker and `libseccomp` (recommended). -- Create a custom profile and pass it for the container. -- Run [without the default seccomp profile](https://docs.docker.com/engine/security/seccomp/#run-without-the-default-seccomp-profile) (unsafe, not recommended). +- Update to a newer version of Docker and `libseccomp` (recommended). +- Create a custom profile and pass it for the container. +- Run [without the default seccomp profile](https://docs.docker.com/engine/security/seccomp/#run-without-the-default-seccomp-profile) (unsafe, not recommended). <details> <summary>See how to create a custom profile</summary> @@ -195,13 +188,13 @@ it will use these values to attempt to connect the container, automatically addi Rooms. If a proxy is specified, it will be used for the connection process and for connecting to Netdata Cloud. These variables can be specified using any mechanism supported by your container tooling for setting environment -variables inside containers. +variables inside containers. When using the `docker run` command, if you have an agent container already running, it is important to know that there will be a short period of downtime. This is due to the process of recreating the new agent container. The command to connect a new node to Netdata Cloud is: -```bash +```bash docker run -d --name=netdata \ -p 19999:19999 \ -v netdataconfig:/etc/netdata \ @@ -221,10 +214,11 @@ docker run -d --name=netdata \ -e NETDATA_CLAIM_PROXY=PROXY \ netdata/netdata ``` ->Note: This command is suggested for connecting a new container. Using this command for an existing container recreates the container, though data -and configuration of the old container may be preserved. If you are claiming an existing container that can not be recreated, + +>Note: This command is suggested for connecting a new container. Using this command for an existing container recreates the container, though data +and configuration of the old container may be preserved. If you are claiming an existing container that can not be recreated, you can add the container by going to Netdata Cloud, clicking the **Nodes** tab, clicking **Connect Nodes**, selecting **Docker**, and following -the instructions and commands provided or by following the instructions in an [empty War Room](#empty-war-room). +the instructions and commands provided or by following the instructions in an [empty War Room](#empty-war-room). The output that would be seen from the connection process when using other methods will be present in the container logs. @@ -274,6 +268,7 @@ Then run the following command in the same directory as the `docker-compose.yml` ```bash docker-compose up -d ``` + #### Using docker exec Connect a _running Netdata Agent container_, where you don't want to recreate the existing container, append the script offered by Netdata Cloud to a `docker exec ...` command, replacing @@ -282,7 +277,8 @@ Connect a _running Netdata Agent container_, where you don't want to recreate th ```bash docker exec -it netdata netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://api.netdata.cloud ``` -The values for `ROOM1,ROOM2` can be found by by going to Netdata Cloud, clicking the **Nodes** tab, clicking **Connect Nodes**, selecting **Docker**, and copying the `rooms=` value in the command provided. + +The values for `ROOM1,ROOM2` can be found by by going to Netdata Cloud, clicking the **Nodes** tab, clicking **Connect Nodes**, selecting **Docker**, and copying the `rooms=` value in the command provided. The script should return `Agent was successfully claimed.`. If the connection process returns errors, or if you don't see the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting). @@ -294,6 +290,7 @@ To connect a node that is running on a macOS environment the script that will be ```bash curl https://my-netdata.io/kickstart.sh > /tmp/netdata-kickstart.sh && sh /tmp/netdata-kickstart.sh --install-prefix /usr/local/ --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://api.netdata.cloud ``` + The script should return `Agent was successfully claimed.`. If the connecting to Netdata Cloud process returns errors, or if you don't see the node in your Space after 60 seconds, see the [troubleshooting information](#troubleshooting). @@ -316,9 +313,9 @@ will also be used to tunnel the ACLK. The default `proxy` setting is `none`. The `proxy` setting can take one of the following values: -- `none`: Do not use a proxy, even if the system configured otherwise. -- `env`: Try to read proxy settings from set environment variables `http_proxy`. -- `http://[user:pass@]host:ip`: The ACLK and connection process will use the specified HTTP(S) proxy. +- `none`: Do not use a proxy, even if the system configured otherwise. +- `env`: Try to read proxy settings from set environment variables `http_proxy`. +- `http://[user:pass@]host:ip`: The ACLK and connection process will use the specified HTTP(S) proxy. For example, a HTTP proxy setting may look like the following: @@ -347,15 +344,15 @@ address or hostname of your Agent. The returned JSON contains four keys that wil might be having with the ACLK or connection process. ```json - "cloud-enabled" - "cloud-available" - "agent-claimed" - "aclk-available" + "cloud-enabled" + "cloud-available" + "agent-claimed" + "aclk-available" ``` -On Netdata agent version `1.32` (`netdata -v` to find your version) and newer, the `netdata -W aclk-state` command can be used to get some diagnostic information about ACLK. Sample output: +On Netdata agent version `1.32` (`netdata -v` to find your version) and newer, `sudo netdatacli aclk-state` can be used to get some diagnostic information about ACLK. Sample output: -``` +```bash ACLK Available: Yes ACLK Implementation: Next Generation New Cloud Protocol Support: Yes @@ -369,11 +366,11 @@ Use these keys and the information below to troubleshoot the ACLK. #### kickstart: unsupported Netdata installation -If you run the kickstart script and get the following error `Existing install appears to be handled manually or through the system package manager.` you most probably installed Netdata using an unsupported package. +If you run the kickstart script and get the following error `Existing install appears to be handled manually or through the system package manager.` you most probably installed Netdata using an unsupported package. If you are using an unsupported package, such as a third-party `.deb`/`.rpm` package provided by your distribution, please remove that package and reinstall using our [recommended kickstart -script](https://github.com/netdata/netdata/blob/master/docs/get-started.mdx#install-on-linux-with-one-line-installer). +script](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#install-on-linux-with-one-line-installer). #### kickstart: Failed to write new machine GUID @@ -382,6 +379,7 @@ If you run the kickstart script but don't have privileges required for the actio ```bash Failed to write new machine GUID. Please make sure you have rights to write to /var/lib/netdata/registry/netdata.public.unique.id. ``` + For a successful execution you will need to run the script with root privileges or run it with the user that is running the agent, more details on the [Connect an agent without root privileges](#connect-an-agent-without-root-privileges) section. #### bash: netdata-claim.sh: command not found @@ -393,7 +391,7 @@ if you installed Netdata to `/opt/netdata`, use `/opt/netdata/bin/netdata-claim. If you are using an unsupported package, such as a third-party `.deb`/`.rpm` package provided by your distribution, please remove that package and reinstall using our [recommended kickstart -script](https://github.com/netdata/netdata/blob/master/docs/get-started.mdx#install-on-linux-with-one-line-installer). +script](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#install-on-linux-with-one-line-installer). #### Connecting on older distributions (Ubuntu 14.04, Debian 8, CentOS 6) @@ -437,20 +435,20 @@ installer's output should give you more error details. You may see one of the following error messages during installation: -- Failed to build libmosquitto. The install process will continue, but you will not be able to connect this node to +- Failed to build libmosquitto. The install process will continue, but you will not be able to connect this node to Netdata Cloud. -- Unable to fetch sources for libmosquitto. The install process will continue, but you will not be able to connect +- Unable to fetch sources for libmosquitto. The install process will continue, but you will not be able to connect this node to Netdata Cloud. -- Failed to build libwebsockets. The install process will continue, but you may not be able to connect this node to +- Failed to build libwebsockets. The install process will continue, but you may not be able to connect this node to Netdata Cloud. -- Unable to fetch sources for libwebsockets. The install process will continue, but you may not be able to connect +- Unable to fetch sources for libwebsockets. The install process will continue, but you may not be able to connect this node to Netdata Cloud. -- Could not find cmake, which is required to build libwebsockets. The install process will continue, but you may not +- Could not find cmake, which is required to build libwebsockets. The install process will continue, but you may not be able to connect this node to Netdata Cloud. -- Could not find cmake, which is required to build JSON-C. The install process will continue, but Netdata Cloud +- Could not find cmake, which is required to build JSON-C. The install process will continue, but Netdata Cloud support will be disabled. -- Failed to build JSON-C. Netdata Cloud support will be disabled. -- Unable to fetch sources for JSON-C. Netdata Cloud support will be disabled. +- Failed to build JSON-C. Netdata Cloud support will be disabled. +- Unable to fetch sources for JSON-C. Netdata Cloud support will be disabled. One common cause of the installer failing to build Cloud features is not having one of the following dependencies on your system: `cmake`, `json-c` and `OpenSSL`, including corresponding `devel` packages. @@ -486,6 +484,8 @@ with details about your system and relevant output from `error.log`. ### Remove and reconnect a node +#### Linux based installations + To remove a node from your Space in Netdata Cloud, delete the `cloud.d/` directory in your Netdata library directory. ```bash @@ -497,53 +497,78 @@ This node no longer has access to the credentials it was used when connecting to You will still be able to see this node in your War Rooms in an **unreachable** state. If you want to reconnect this node, you need to: + 1. Ensure that the `/var/lib/netdata/cloud.d` directory doesn't exist. In some installations, the path is `/opt/netdata/var/lib/netdata/cloud.d`. 2. Stop the agent. 3. Ensure that the `uuidgen-runtime` package is installed. Run ```echo "$(uuidgen)"``` and validate you get back a UUID. 4. Copy the kickstart.sh command to add a node from your space and add to the end of it `--claim-id "$(uuidgen)"`. Run the command and look for the message `Node was successfully claimed.` 5. Start the agent +#### Docker based installations -## Connecting reference -In the sections below, you can find reference material for the kickstart script, claiming script, connecting via the Agent's command line -tool, and details about the files found in `cloud.d`. +To remove a node from you Space in Netdata Cloud, and connect it to another Space, follow these steps: -### The `cloud.conf` file +1. Enter the running container you wish to remove from your Space -This section defines how and whether your Agent connects to [Netdata Cloud](https://github.com/netdata/netdata/blob/master/docs/cloud/cloud.mdx) -using the [ACLK](https://github.com/netdata/netdata/blob/master/aclk/README.md). + ```bash + docker exec -it CONTAINER_NAME sh + ``` -| setting | default | info | -|:-------------- |:------------------------- |:-------------------------------------------------------------------------------------------------------------------------------------- | -| cloud base url | https://api.netdata.cloud | The URL for the Netdata Cloud web application. You should not change this. If you want to disable Cloud, change the `enabled` setting. | -| enabled | yes | The runtime option to disable the [Agent-Cloud link](https://github.com/netdata/netdata/blob/master/aclk/README.md) and prevent your Agent from connecting to Netdata Cloud. | + Replacing `CONTAINER_NAME` with either the container's name or ID. -### kickstart script +2. Delete `/var/lib/netdata/cloud.d` and `/var/lib/netdata/registry/netdata.public.unique.id` -The best way to install Netdata and connect your nodes to Netdata Cloud is with our automatic one-line installation script, [kickstart](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#automatic-one-line-installation-script). This script will install the Netdata Agent, in case it isn't already installed, and connect your node to Netdata Cloud. + ```bash + rm -rf /var/lib/netdata/cloud.d/ + + rm /var/lib/netdata/registry/netdata.public.unique.id + ``` -This works with: -* most Linux distributions, see [Netdata's platform support policy](https://github.com/netdata/netdata/blob/master/packaging/PLATFORM_SUPPORT.md) -* macOS +3. Stop and remove the container -For details on how to run this script please check [How to connect a node](#how-to-connect-a-node) and choose your environment. + **Docker CLI:** -In case Netdata Agent is already installed and you run this script to connect a node to Netdata Cloud it will not upgrade your agent automatically. If you also want to upgrade the Agent installation you'll need to run the script again without the connection options. + ```bash + docker stop CONTAINER_NAME + + docker rm CONTAINER_NAME + ``` -Our suggestion is to first run kickstart to upgrade your agent by running the command below and the run the [How to connect a node] -(#how-to-connect-a-node). + Replacing `CONTAINER_NAME` with either the container's name or ID. -**Linux** + **Docker Compose:** + Inside the directory that has the `docker-compose.yml` file, run: -```bash -wget -O /tmp/netdata-kickstart.sh https://my-netdata.io/kickstart.sh && sh /tmp/netdata-kickstart.sh -``` + ```bash + docker compose down + ``` -**macOS** + **Docker Swarm:** + Run the following, and replace `STACK` with your Stack's name: + + ```bash + docker stack rm STACK + ``` + +4. Finally, go to your new Space, copy the install command with the new claim token and run it. + If you are using a `docker-compose.yml` file, you will have to overwrite it with the new claiming token. + The node should now appear online in that Space. + +## Connecting reference + +In the sections below, you can find reference material for the kickstart script, claiming script, connecting via the Agent's command line +tool, and details about the files found in `cloud.d`. + +### The `cloud.conf` file + +This section defines how and whether your Agent connects to Netdata Cloud +using the [ACLK](https://github.com/netdata/netdata/blob/master/aclk/README.md). + +| setting | default | info | +|:-------------- |:------------------------- |:-------------------------------------------------------------------------------------------------------------------------------------- | +| cloud base url | <https://api.netdata.cloud> | The URL for the Netdata Cloud web application. You should not change this. If you want to disable Cloud, change the `enabled` setting. | +| enabled | yes | The runtime option to disable the [Agent-Cloud link](https://github.com/netdata/netdata/blob/master/aclk/README.md) and prevent your Agent from connecting to Netdata Cloud. | -```bash -curl https://my-netdata.io/kickstart.sh > /tmp/netdata-kickstart.sh && sh /tmp/netdata-kickstart.sh --install-prefix /usr/local/ -``` ### Claiming script A Space's administrator can also connect an Agent by directly calling the `netdata-claim.sh` script either with root privileges @@ -609,5 +634,3 @@ Rooms you added that node to. The user can also put the Cloud endpoint's full certificate chain in `cloud.d/cloud_fullchain.pem` so that the Agent can trust the endpoint if necessary. - - |