diff options
| author | Hugo Valente <82235632+hugovalente-pm@users.noreply.github.com> | 2021-08-31 10:32:33 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-08-31 10:32:33 +0100 |
| commit | 6fd6bc72e4c628b542aa752632cca65022bbbab4 (patch) | |
| tree | 3f5f13309a7a4322c5198f3a19534f88daa61df4 /claim | |
| parent | 24e916f79e7979cda4b9c9f638bac234ffcd8223 (diff) | |
Installation review (#11442)
* first draft of how to connect node with new scripts for installing and connecting (e.g. kickstart)
* further work on related pages to keep things synced
* reviewed the command on docker exec and aded more to-do's for review and to add details
* first draft of how to connect node with new scripts for installing and connecting (e.g. kickstart)
* further work on related pages to keep things synced
* reviewed the command on docker exec and aded more to-do's for review and to add details
* completed and reviewed some todo's based on conversation with Austin
* add the kubernetes reviewed part
* add references to macOS
* rectified the parameter and value separator from = to ' '
* added that kickstart wih claiming options needs to specific privileges
* first draft of how to connect node with new scripts for installing and connecting (e.g. kickstart)
* further work on related pages to keep things synced
* reviewed the command on docker exec and aded more to-do's for review and to add details
* first draft of how to connect node with new scripts for installing and connecting (e.g. kickstart)
* further work on related pages to keep things synced
* reviewed the command on docker exec and aded more to-do's for review and to add details
* completed and reviewed some todo's based on conversation with Austin
* add the kubernetes reviewed part
* add references to macOS
* rectified the parameter and value separator from = to ' '
* added that kickstart wih claiming options needs to specific privileges
* remove FreeBSD from text and reviewed some text as per Austin's suggestion
* removed TODOs, printscreen can be added later on and updated as per a review comment
* first draft of how to connect node with new scripts for installing and connecting (e.g. kickstart)
* further work on related pages to keep things synced
* reviewed the command on docker exec and aded more to-do's for review and to add details
* first draft of how to connect node with new scripts for installing and connecting (e.g. kickstart)
* further work on related pages to keep things synced
* reviewed the command on docker exec and aded more to-do's for review and to add details
* completed and reviewed some todo's based on conversation with Austin
* add the kubernetes reviewed part
* add references to macOS
* rectified the parameter and value separator from = to ' '
* added that kickstart wih claiming options needs to specific privileges
* remove FreeBSD from text and reviewed some text as per Austin's suggestion
* first draft of how to connect node with new scripts for installing and connecting (e.g. kickstart)
* further work on related pages to keep things synced
* reviewed the command on docker exec and aded more to-do's for review and to add details
* first draft of how to connect node with new scripts for installing and connecting (e.g. kickstart)
* further work on related pages to keep things synced
* reviewed the command on docker exec and aded more to-do's for review and to add details
* completed and reviewed some todo's based on conversation with Austin
* added that kickstart wih claiming options needs to specific privileges
* removed TODOs, printscreen can be added later on and updated as per a review comment
* rebased from master and removed kickstart for reconnect a node as a possibility
* added adding nodes from Node view after Kaskavelis callout
* added adding nodes from Node view after Kaskavelis callout
Diffstat (limited to 'claim')
| -rw-r--r-- | claim/README.md | 208 |
1 files changed, 168 insertions, 40 deletions
diff --git a/claim/README.md b/claim/README.md index 7e209dd9f6..901b0551e3 100644 --- a/claim/README.md +++ b/claim/README.md @@ -6,7 +6,7 @@ custom_edit_url: https://github.com/netdata/netdata/edit/master/claim/README.md # Connect Agent to Cloud -You can securely connect a Netdata Agent, running on a distributed node, to securely connect to Netdata Cloud. A Space's +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)](/aclk/README.md). @@ -14,10 +14,7 @@ Are you just starting out with Netdata Cloud? See our [get started with Cloud](https://learn.netdata.cloud/docs/cloud/get-started) guide for a walkthrough of the process and simplified instructions. -Connecting Agents, also referrered as **nodes**, is a security feature in Netdata Cloud. Through the connection process, you demonstrate in a few ways -that you have administrative access to that node and the configuration settings for the Netdata Agent. By logging into the node, -you prove you have access, and by using the claiming script or the Netdata command line, you prove you have write access -and administrative privileges. +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. Only the administrators of a Space in Netdata Cloud can view the claiming token and accompanying script generated by Netdata Cloud. @@ -41,27 +38,57 @@ There are two important notes regarding connecting nodes: ## 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 [empty 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 the the [Nodes view page](learn.netdata.cloud/docs/cloud/visualize/nodes) 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 you are in +* add a previously connected node to the War Room you are in + +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) + +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. +### Manage Space or War Room + 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 Cloud into your node's terminal. Hit **Enter**. +given by Netdata Cloud into your node's terminal. + +When coming from [Nodes view page](learn.netdata.cloud/docs/cloud/visualize/nodes) 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](/packaging/installer/#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 -sudo netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud ``` +bash <(curl -Ss https://my-netdata.io/kickstart.sh) --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.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). -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). If you prefer not to -use root privileges via `sudo` to run the claiming script, see the next section. +Please note that to run it you will either need to have 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. -Repeat this process with every node you want to add to Cloud during onboarding. You can also add more nodes once you've -finished onboarding. +For more details on what are the extra parameters `claim-token`, `claim-rooms` and `claim-url` please refer to [Connect node to Netdata Cloud during installation](/packaging/installer/methods/kickstart#connect-node-to-netdata-cloud-during-installation). ### Connect an agent without root privileges -If you don't want to run the claiming script with root privileges, you can discover which user is running the Agent, -switch to that user, and run the claiming script. +If you don't want to run the installation script to connect your nodes to Netdata Cloud with root privileges, you can discover which user is running the Agent, +switch to that user, and run the script. Use `grep` to search your `netdata.conf` file, which is typically located at `/etc/netdata/netdata.conf`, for the `run as user` setting. For example: +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. ```bash grep "run as user" /etc/netdata/netdata.conf @@ -69,16 +96,12 @@ grep "run as user" /etc/netdata/netdata.conf ``` The default user is `netdata`. Yours may be different, so pay attention to the output from `grep`. Switch to that user -and run the claiming script. +and run the script. ```bash -netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud +bash <(curl -Ss https://my-netdata.io/kickstart.sh) --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.netdata.cloud ``` - -Hit **Enter**. 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). - -### Connect an Agent running in Docker +### Connect an agent running in Docker To connect an instance of the Netdata Agent running inside of a Docker container, either set claiming environment variables in the container to have it automatically connected on startup or restart, or use `docker exec` to manually @@ -102,12 +125,16 @@ 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. 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: +variables inside containers. For example, when creating a new Netdata container using `docker run`, the following -```bash +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 that Netdata Cloud will provide to you is: + +```bash docker run -d --name=netdata \ -p 19999:19999 \ + -v netdataconfig:/etc/netdata \ -v netdatalib:/var/lib/netdata \ -v netdatacache:/var/cache/netdata \ -v /etc/passwd:/host/etc/passwd:ro \ @@ -115,32 +142,87 @@ 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 + -e NETDATA_CLAIM_TOKEN=TOKEN \ + -e NETDATA_CLAIM_URL="https://app.netdata.cloud" \ + -e NETDATA_CLAIM_ROOMS=ROOM1,ROOM2 \ + -e NETDATA_CLAIM_PROXY=PROXY \ + netdata/netdata ``` -Output that would be seen from the claiming script when using other methods will be present in the container logs. +The output that would be seen from the connection process when using other methods will be present in the container logs. Using the environment variables like this to handle the connection process is the preferred method of connecting Docker containers as it works in the widest variety of situations and simplifies configuration management. +#### Using Docker compose + +If you use `docker compose` you can copy the config provided by Netdata Cloud, which should be same as the one below: + +```bash +version: '3' +services: + netdata: + image: netdata/netdata + container_name: netdata + hostname: example.com # set to fqdn of host + ports: + - 19999:19999 + restart: unless-stopped + cap_add: + - SYS_PTRACE + security_opt: + - apparmor:unconfined + volumes: + - netdataconfig:/etc/netdata + - netdatalib:/var/lib/netdata + - netdatacache:/var/cache/netdata + - /etc/passwd:/host/etc/passwd:ro + - /etc/group:/host/etc/group:ro + - /proc:/host/proc:ro + - /sys:/host/sys:ro + - /etc/os-release:/host/etc/os-release:ro + environment: + - NETDATA_CLAIM_TOKEN=TOKEN + - NETDATA_CLAIM_URL="https://app.netdata.cloud" + - NETDATA_CLAIM_ROOMS=ROOM1,ROOM2 + +volumes: + netdataconfig: + netdatalib: + netdatacache: +``` + +Then run the following command in the same directory as the `docker-compose.yml` file to start the container. + +```bash +docker-compose up -d +``` + #### Using docker exec -Connect a _running Netdata Agent container_ by appending the script offered by Cloud to a `docker exec ...` command, replacing +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 `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 ``` -The script should return `Agent was successfully claimed.`. If the claiming script returns errors, or if +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). +### Connect an agent running in macOS + +To connect a node that is running on a macOS environment the script that will be provided to you by Netdata Cloud is the [kickstart](/packaging/installer/methods/macos#install-netdata-with-kickstart) 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 +bash <(curl -Ss https://my-netdata.io/kickstart.sh) --install /usr/local/ --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.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). + ### Connect a Kubernetes cluster's parent Netdata pod Read our [Kubernetes installation](/packaging/installer/methods/kubernetes.md#connect-a-kubernetes-clusters-parent-pod) @@ -173,14 +255,14 @@ For example, a SOCKS5 proxy setting may look like the following: proxy = socks5h://proxy.example.com:1080 # With a URL ``` -You can now move on to connecting. When you connect with the `netdata-claim.sh` script, add the `-proxy=` parameter and +You can now move on to connecting. When you connect with the [kickstart](/packaging/installer/#automatic-one-line-installation-script) script, add the `--claim-proxy=` parameter and append the same proxy setting you added to `netdata.conf`. ```bash -sudo netdata-claim.sh -token=MYTOKEN1234567 -rooms=room1,room2 -url=https://app.netdata.cloud -proxy=socks5h://203.0.113.0:1080 +bash <(curl -Ss https://my-netdata.io/kickstart.sh) --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.netdata.cloud --claim-proxy socks5h://203.0.113.0:1080 ``` -Hit **Enter**. The script should return `Agent was successfully claimed.`. If the claiming script returns errors, or if +Hit **Enter**. 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). ### Troubleshooting @@ -200,6 +282,23 @@ might be having with the ACLK or connection process. 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 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](/docs/get-started.mdx#install-on-linux-with-one-line-installer-recommended). + +#### kickstart: Failed to write new machine GUID + +If you run the kickstart script but don't have privileges required for the actions done on the connecting to Netdata Cloud process you will get the following error: + +```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 If you run the claiming script and see a `command not found` error, you either installed Netdata in a non-standard @@ -313,7 +412,9 @@ 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 into a different Space, you need to create a new identity by adding `-id=$(uuidgen)` to -the claiming script parameters. Make sure that you have the `uuidgen-runtime` package installed, as it is used to run the command `uuidgen`. For example, using the default claiming script: +the claiming script parameters (not yet supported on the kickstart script). Make sure that you have the `uuidgen-runtime` package installed, as it is used to run the command `uuidgen`. For example: + +**Claiming script** ```bash sudo netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud -id=$(uuidgen) @@ -322,8 +423,7 @@ sudo netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.c The agent _must be restarted_ after this change. ## Connecting reference - -In the sections below, you can find reference material for the claiming script, connecting via the Agent's command line +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 @@ -336,9 +436,35 @@ using the [ACLK](/aclk/README.md). | cloud base url | https://app.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](/aclk/README.md) and prevent your Agent from connecting to Netdata Cloud. | +### kickstart script + +The best way to install Netdata and connect your nodes to Netdata Cloud is with our automatic one-line installation script, [kickstart](/packaging/installer/#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. + +This works with: +* all Linux distributions, see [Netdata distribution support matrix](https://learn.netdata.cloud/docs/agent/packaging/distributions) +* macOS + +For details on how to run this script please check [How to connect a node](#how-to-connect-a-node) and choose your environment. + +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. + +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). + +**Linux** + +```bash +bash <(curl -Ss https://my-netdata.io/kickstart.sh) +``` + +**macOS** + +```bash +bash <(curl -Ss https://my-netdata.io/kickstart.sh) --install /usr/local/ +``` ### Claiming script -A Space's administrator can connect an Agent by directly calling the `netdata-claim.sh` script either with root privileges +A Space's administrator can also connect an Agent by directly calling the `netdata-claim.sh` script either with root privileges using `sudo`, or as the user running the Agent (typically `netdata`), and passing the following arguments: ```sh @@ -370,6 +496,8 @@ netdatacli reload-claiming-state This reloads the Agent connection state from disk. +Our recommendation is to trigger the connection process using the [kickstart](/packaging/installer/#automatic-one-line-installation-script) whenever possible. + ### Netdata Agent command line If a Netdata Agent is running, the Space's administrator can connect a node using the `netdata` service binary with @@ -400,4 +528,4 @@ 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. -[](<>) +[](<>)
\ No newline at end of file |