@cryptotaxi247 / netdata
Code Commits Issues Pulls Sessions CI/CD
master
master
md 131 lines 5.85 KB
Rendered Raw
1 # Deploy Netdata with Ansible
2
3 Meet [Ansible](https://ansible.com), a popular tool for provisioning, configuration management, and infrastructure as code (IaC).
4
5 This guide walks you through deploying the **Netdata Agent** across multiple nodes using an [Ansible playbook](https://github.com/netdata/community/tree/main/configuration-management/ansible-quickstart/), managing configurations, and connecting to **Netdata Cloud**—all in minutes.
6
7 :::note
8
9 With Ansible, you can deploy Netdata repeatedly without disrupting your infrastructure—ensuring monitoring as code.
10
11 :::
12
13 ## Prerequisites
14
15 - Netdata Cloud account. [Sign in and create one](https://app.netdata.cloud) if you don't have one already.
16 - An administration system with [Ansible](https://www.ansible.com/) installed.
17 - One or more nodes that your administration system can access via [SSH public keys](https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key) (preferably password-less).
18
19 ## Deployment Architecture
20
21 Below is a visual representation of the deployment architecture, illustrating the relationship between the host system, Docker, the Netdata container, and key mounts/privileges.
22
23 ```mermaid
24 flowchart TD
25 A("**Host System**<br/>Administration server") -->|SSH| B("**Ansible**<br/>Configuration management")
26 B -->|Deploys| C("**Netdata Agent**<br/>Monitoring daemon")
27 C -->|Collects Metrics| D("**Monitored Services**<br/>Applications & infrastructure")
28 C -->|Sends Data| E("**Netdata Cloud**<br/>Unified dashboard")
29
30 subgraph infrastructure["Target Infrastructure"]
31 direction TB
32 C
33 D
34 end
35
36 %% Style definitions matching the reference
37 classDef alert fill: #ffeb3b, stroke: #000000, stroke-width: 3px, color: #000000, font-size: 18px
38 classDef neutral fill: #f9f9f9, stroke: #000000, stroke-width: 3px, color: #000000, font-size: 18px
39 classDef complete fill: #4caf50, stroke: #000000, stroke-width: 3px, color: #000000, font-size: 18px
40 classDef database fill: #2196F3, stroke: #000000, stroke-width: 3px, color: #000000, font-size: 18px
41 %% Apply styles
42 class A alert
43 class B database
44 class C complete
45 class D complete
46 class E neutral
47 class infrastructure database
48 ```
49
50 ## Download and Configure the Playbook
51
52 First, download the [playbook](https://github.com/netdata/community/tree/main/configuration-management/ansible-quickstart/), move it to the current directory, and remove the rest of the cloned repository, as it's not required for using the Ansible playbook.
53
54 ```bash
55 git clone https://github.com/netdata/community.git
56 mv community/configuration-management/ansible-quickstart .
57 rm -rf community
58 ```
59
60 Or if you don't want to clone the entire repository, use the [gitzip browser extension](https://gitzip.org/) to get the `netdata-agent-deployment` directory as a zip file.
61
62 Next, navigate into the Ansible directory.
63
64 ```bash
65 cd ansible-quickstart
66 ```
67
68 ### Edit the `hosts` File
69
70 The `hosts` file contains a list of IP addresses or hostnames that Ansible will target. Replace the example IP addresses with those of your nodes.
71
72 ```text
73 203.0.113.0 hostname=node-01
74 203.0.113.1 hostname=node-02
75 ```
76
77 You can also set the `hostname` variable, which appears both on the local Agent dashboard and Netdata Cloud, or omit the `hostname=` string entirely to use the system's default hostname.
78
79 #### Set the Login User (Optional)
80
81 If you SSH into your nodes as a user other than `root`, configure `hosts` accordingly using the `ansible_user` variable. For example:
82
83 ```text
84 203.0.113.0 hostname=ansible-01 ansible_user=example
85 ```
86
87 #### Set Your SSH Key (Optional)
88
89 If you use an SSH key other than `~/.ssh/id_rsa` for logging into your nodes, specify it per node in the `hosts` file with the `ansible_ssh_private_key_file` variable. For example:
90
91 ```text
92 203.0.113.0 hostname=ansible-01 ansible_ssh_private_key_file=~/.ssh/LightsailDefaultKey-us-west-2.pem
93 203.0.113.1 hostname=ansible-02 ansible_ssh_private_key_file=~/.ssh/LightsailDefaultKey-us-east-1.pem
94 ```
95
96 ### Edit the `vars/main.yml` File
97
98 To connect your node(s) to your Space in Netdata Cloud and see all their metrics in real-time, set the `claim_token` and `claim_rooms` variables.
99
100 To find your `claim_token` and `claim_rooms`, go to Netdata Cloud, click on your Space's name in the top navigation, then click on **Manage your Space**. Click on the **Nodes** tab in the panel that appears, which displays a script with `token` and `room` strings.
101
102 Copy those strings into the `claim_token` and `claim_rooms` variables.
103
104 ```yml
105 claim_token: YOUR_CLAIM_TOKEN
106 claim_rooms: YOUR_CLAIM_ROOMS
107 ```
108
109 Adjust the `dbengine_multihost_disk_space` variable to change the metrics retention policy by allocating more or less disk space for storing metrics. The default is 2048 MiB (2 GiB).
110
111 Since this node connects to Netdata Cloud, we'll view its dashboards there instead of using its IP or hostname. The playbook disables the local dashboard by setting `web_mode` to `none`, adding a small security boost by preventing unwanted access.
112
113 You can read more about this decision, or other ways to lock down the local dashboard, in our [node security documentation](https://learn.netdata.cloud/docs/netdata-agent/security/overview).
114
115 :::tip
116
117 Curious about why Netdata's dashboard is open by default? Read our [blog post](https://www.netdata.cloud/blog/netdata-agent-dashboard/) on that zero-configuration design decision.
118
119 :::
120
121 ## Run the Playbook
122
123 Execute the playbook from your administration system:
124
125 ```bash
126 ansible-playbook -i hosts tasks/main.yml
127 ```
128
129 Ansible connects to your node(s) via SSH, collects [facts](https://docs.ansible.com/ansible/latest/user_guide/playbooks_vars_facts.html#ansible-facts) about the system, and then applies the defined tasks.
130
131 The task to install Netdata may take a few minutes per node. Once the playbook reaches the "connect to Cloud" task, your nodes will start appearing in your Space in Netdata Cloud.