Add guide: Deploy Netdata with Ansible (#10199)
* Add image * Finish rough draft * Add description * Fixes * Finish the playbook run description * Add some text about Ansible alternatives * Fixes and GIF for claiming script
Joel Hans committed
Nov 11, 2020 at 05:45 UTC
78ce3a519cda0c3b04287477541609d7ddfe4df3
1 file changed
+174
docs/guides/deploy/ansible.md
new
+174
@@ -0,0 +1,174 @@
1
+<!--
2
+title: Deploy Netdata with Ansible
3
+description: Deploy an infrastructure monitoring solution in minutes with the Netdata Agent and Ansible. Use and customize a simple playbook for monitoring as code.
4
+image: /img/seo/guides/deploy/ansible.png
5
+custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/guides/deploy/ansible.md
6
+-->
7
+
8
+# Deploy Netdata with Ansible
9
+
10
+Netdata's [one-line kickstart](https://learn.netdata.cloud/docs/get) is zero-configuration, highly adaptable, and
11
+compatible with tons of different operating systems and Linux distributions. You can use it on bare metal, VMs,
12
+containers, and everything in-between.
13
+
14
+But what if you're trying to bootstrap an infrastructure monitoring solution as quickly as possible. What if you need to
15
+deploy Netdata across an entire infrastructure with many nodes? What if you want to make this deployment reliable,
16
+repeatable, and idempotent? What if you want to write and deploy your infrastructure or cloud monitoring system like
17
+code?
18
+
19
+Enter [Ansible](https://ansible.com), a popular system provisioning, configuration management, and infrastructure as
20
+code (IaC) tool. Ansible uses **playbooks** to glue many standardized operations together with a simple syntax, then run
21
+those operations over standard and secure SSH connections. There's no agent to install on the remote system, so all you
22
+have to worry about is your application and your monitoring software.
23
+
24
+Ansible has some competition from the likes of [Puppet](https://puppet.com/) or [Chef](https://www.chef.io/), but the
25
+most valuable feature about Ansible is that every is **idempotent**. From the [Ansible
26
+glossary](https://docs.ansible.com/ansible/latest/reference_appendices/glossary.html)
27
+
28
+> An operation is idempotent if the result of performing it once is exactly the same as the result of performing it
29
+> repeatedly without any intervening actions.
30
+
31
+Idempotency means you can run an Ansible playbook against your nodes any number of times without affecting how they
32
+operate. When you deploy Netdata with Ansible, you're also deploying _monitoring as code_.
33
+
34
+In this guide, we'll walk through the process of using an [Ansible
35
+playbook](https://github.com/netdata/community/tree/main/netdata-agent-deployment/ansible-quickstart) to automatically
36
+deploy the Netdata Agent to any number of distributed nodes, manage the configuration of each node, and claim them to
37
+your Netdata Cloud account. You'll go from some unmonitored nodes to a infrastructure monitoring solution in a matter of
38
+minutes.
39
+
40
+## Prerequisites
41
+
42
+- A Netdata Cloud account. [Sign in and create one](https://app.netdata.cloud) if you don't have one already.
43
+- An administration system with [Ansible](https://www.ansible.com/) installed.
44
+- One or more nodes that your administration system can access via [SSH public
45
+ keys](https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key) (preferably password-less).
46
+
47
+## Download and configure the playbook
48
+
49
+First, download the
50
+[playbook](https://github.com/netdata/community/tree/main/netdata-agent-deployment/ansible-quickstart), move it to the
51
+current directory, and remove the rest of the cloned repository, as it's not required for using the Ansible playbook.
52
+
53
+```bash
54
+git clone https://github.com/netdata/community.git
55
+mv community/configuration-management/ansible .
56
+rm -rf community
57
+```
58
+
59
+Next, `cd` into the Ansible directory.
60
+
61
+```bash
62
+cd ansible
63
+```
64
+
65
+### Edit the `hosts` file
66
+
67
+The `hosts` file contains a list of IP addresses or hostnames that Ansible will try to run the playbook against. The
68
+`hosts` file that comes with the repository contains two example IP addresses, which you should replace according to the
69
+IP address/hostname of your nodes.
70
+
71
+```conf
72
+203.0.113.0 hostname=node-01
73
+203.0.113.1 hostname=node-02
74
+```
75
+
76
+You can also set the `hostname` variable, which appears both on the local Agent dashboard and Netdata Cloud, or you can
77
+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`, you need to configure `hosts` according to those user names. Use
82
+the `ansible_user` variable to set the login user. For example:
83
+
84
+```conf
85
+203.0.113.0 hostname=ansible-01 ansible_user=example
86
+```
87
+
88
+#### Set your SSH key (optional)
89
+
90
+If you use an SSH key other than `~/.ssh/id_rsa` for logging into your nodes, you can set that on a per-node basis in
91
+the `hosts` file with the `ansible_ssh_private_key_file` variable. For example, to log into a Lightsail instance using
92
+two different SSH keys supplied by AWS.
93
+
94
+```conf
95
+203.0.113.0 hostname=ansible-01 ansible_ssh_private_key_file=~/.ssh/LightsailDefaultKey-us-west-2.pem
96
+203.0.113.1 hostname=ansible-02 ansible_ssh_private_key_file=~/.ssh/LightsailDefaultKey-us-east-1.pem
97
+```
98
+
99
+### Edit the `vars/main.yml` file
100
+
101
+In order to claim your node(s) to your Space in Netdata Cloud, and see all their metrics in real-time in [composite
102
+charts](/docs/visualize/overview-infrastructure.md) or perform [Metric
103
+Correlations](https://learn.netdata.cloud/docs/cloud/insights/metric-correlations), you need to set the `claim_token`
104
+and `claim_room` variables.
105
+
106
+To find your `claim_token` and `claim_room`, go to Netdata Cloud, then click on your Space's name in the top navigation,
107
+then click on **Manage your Space**. Click on the **Nodes** tab in the panel that appears, which displays a script with
108
+`token` and `room` strings.
109
+
110
+
112
+
113
+Copy those strings into the `claim_token` and `claim_rooms` variables.
114
+
115
+```yml
116
+claim_token: XXXXX
117
+claim_rooms: XXXXX
118
+```
119
+
120
+Change the `dbengine_multihost_disk_space` if you want to change the metrics retention policy by allocating more or less
121
+disk space for storing metrics. The default is 2048 Mib, or 2 GiB.
122
+
123
+Because we're claiming this node to Netdata Cloud, and will view its dashboards there instead of via the IP address or
124
+hostname of the node, the playbook disables that local dashboard by setting `web_mode` to `none`. This gives a small
125
+security boost by not allowing any unwanted access to the local dashboard.
126
+
127
+You can read more about this decision, or other ways you might lock down the local dashboard, in our [node security
128
+doc](https://learn.netdata.cloud/docs/configure/secure-nodes).
129
+
130
+> Curious about why Netdata's dashboard is open by default? Read our [blog
131
+> post](https://www.netdata.cloud/blog/netdata-agent-dashboard/) on that zero-configuration design decision.
132
+
133
+## Run the playbook
134
+
135
+Time to run the playbook from your administration system:
136
+
137
+```bash
138
+ansible-playbook -i hosts tasks/main.yml
139
+```
140
+
141
+Ansible first connects to your node(s) via SSH, then [collects
142
+facts](https://docs.ansible.com/ansible/latest/user_guide/playbooks_vars_facts.html#ansible-facts) about the system.
143
+This playbook doesn't use these facts, but you could expand it to provision specific types of systems based on the
144
+makeup of your infrastructure.
145
+
146
+Next, Ansible makes changes to each node according to the `tasks` defined in the playbook, and
147
+[returns](https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#changed) whether each
148
+task results in a changed, failure, or was skipped entirely.
149
+
150
+The task to install Netdata will take a few minutes per node, so be patient! Once the playbook reaches the claiming
151
+task, your nodes start populating your Space in Netdata Cloud.
152
+
153
+## What's next?
154
+
155
+Go use Netdata!
156
+
157
+If you need a bit more guidance for how you can use Netdata for health monitoring and performance troubleshooting, see
158
+our [documentation](https://learn.netdata.cloud/docs). It's designed like a comprehensive guide, based on what you might
159
+want to do with Netdata, so use those categories to dive in.
160
+
161
+Some of the best places to start:
162
+
163
+- [Enable or configure a collector](/docs/collect/enable-configure.md)
164
+- [Supported collectors list](/collectors/COLLECTORS.md)
165
+- [See an overview of your infrastructure](/docs/visualize/overview-infrastructure.md)
166
+- [Interact with dashboards and charts](/docs/visualize/interact-dashboards-charts.md)
167
+- [Change how long Netdata stores metrics](/docs/store/change-metrics-storage.md)
168
+
169
+We're looking for more deployment and configuration management strategies, whether via Ansible or other
170
+provisioning/infrastructure as code software, such as Chef or Puppet, in our [community
171
+repo](https://github.com/netdata/community). Anyone is able to fork the repo and submit a PR, either to improve this
172
+playbook, extend it, or create an entirely new experience for deploying Netdata across entire infrastructure.
173
+
174
+[](<>)