From a80c2e5cbd8f19a299dc3b850b6f75e357424cc2 Mon Sep 17 00:00:00 2001 From: Andy Stevens Date: Wed, 10 Oct 2018 14:22:49 -0400 Subject: [PATCH 1/5] Initial Commit --- .../index.md | 254 ++++++++++++++++++ 1 file changed, 254 insertions(+) create mode 100644 docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md diff --git a/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md b/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md new file mode 100644 index 00000000000..6b5c6dc3f64 --- /dev/null +++ b/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md @@ -0,0 +1,254 @@ +--- +author: + name: Linode Community + email: docs@linode.com +description: 'How to monitor Salt minions with beacons.' +keywords: ['salt','saltstack','minion','minions','beacon','beacons','reactor','reactors','monitor','configuration drift','slack'] +license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' +published: 2018-10-10 +modified_by: + name: Linode +title: "Monitoring Salt Minions with Beacons" +external_resources: +- '[Salt Beacons Documentation](https://docs.saltstack.com/en/latest/topics/beacons/)' +- '[Salt Beacon Modules](https://docs.saltstack.com/en/latest/ref/beacons/all/index.html)' +- '[Salt Reactors Documentation](https://docs.saltstack.com/en/latest/topics/reactor/)' +--- + +Every action taken by Salt emits an event: applying a highstate, restarting a minion, accepting a key, etc. *Beacons* emit events for non-salt processes, such a system state changes or file changes. In this guide we will be using Salt beacons to notify the Salt master of changes to our minions, and Salt *reactors* to react to those changes. + +## Before You Begin + +If you don't already have a Salt master and a Salt minion, follow the first steps of our [Getting Started with Salt - Basic Installation and Setup](https://www.linode.com/docs/applications/configuration-management/getting-started-with-salt-basic-installation-and-setup/) guide. + +{{< note >}} +The steps in this guide require root privileges. Be sure to run the steps below as `root` or with the `sudo` prefix. For more information on privileges, see our [Users and Groups](/docs/tools-reference/linux-users-and-groups/) guide. +{{< /note >}} + +## Example 1: Preventing Configuration Drift + +Configuration drift occurs when there are untracked changes to a system configuration file. Salt can help prevent configuration drift by ensuring that a file is immediately reverted to a safe state upon change. In order to do this, we first have to let Salt manage the file. This section will use a NGINX configuration file as an example, but you can choose any file. + +### Manage Your File + +1. On your Salt master, create a directory for your managed files in `/srv/salt/`: + + mkdir /srv/salt/files + +2. On your Salt master, place your `nginx.conf`, or whichever file you would like to manage, in the `/srv/salt/files` folder. + +3. On your Salt master, create a state file to manage the NGINX configuration file: + + {{< file "/srv/salt/nginx_conf.sls" yaml >}} +/etc/nginx/nginx.conf: + file.managed: + - source: + - 'salt://files/nginx.conf' +{{< /file >}} + + There are two file paths in this `.sls` file. The first file path is the path to your managed file on your minion. The second, under source and prefixed with `salt://`, points to the file path on your master. `salt://` is a convenience file path that maps to `/srv/salt`. + +4. On your Salt master, create a top file if it does not already exist and add your `nginx_conf.sls`: + + {{< file "/srv/salt/top.sls" yaml >}} +base: + '*': + - nginx_conf +{{< /file >}} + +### Create a Beacon + +1. In order to be notified when a file changes, we need to install the `python-pyinotify` package. On your Salt minion, run: + + apt-get install python-pyinotify + + {{< note >}} +The inotify beacon only works on OSes that have inotify kernel support. Currently this excludes FreeBSD, macOS, and Windows. +{{< /note >}} + +2. Now we will create a beacon that will emit an event every time our `nginx.conf` changes. On your Salt minion, create the `/etc/salt/minion.d/beacons.conf` file and add the following lines: + + {{< file "/etc/salt/minion.d/beacons.conf" yaml >}} +beacons: + inotify: + - files: + /etc/nginx/nginx.conf: + mask: + - modify + - disable_during_state_run: True +{{< /file >}} + + The `disable_during_state_run` is important here as it will prevent an infinite loop from occuring when we make changes to our `nginx.conf`. + +3. Restart `salt-minion` to apply your `beacons.conf` file: + + systemctl restart salt-minion + +4. Open another shell to your Salt master and start the Salt event runner. You will use this to monitor for file change events from your beacon. + + salt-run state.event pretty=True + +5. Make a change to your `nginx.conf` file on your Salt minion, and then check out your Salt event runner shell. You should see an event like the following: + + {{< output >}} +salt/beacon/salt-minion/inotify//etc/nginx/nginx.conf { + "_stamp": "2018-10-10T13:53:47.163499", + "change": "IN_MODIFY", + "id": "salt-minion", + "path": "/etc/nginx/nginx.conf" +} +{{< /output >}} + + Note that the first line is the name of the event, and it includes your Salt minion name and the path to your managed file. We will use this event name in the next section. + +1. To revert the `nginx.conf` file to it's initial state, you can apply a highstate from your Salt master. + + salt '*' state.apply nginx_conf + + Open your managed file on your Salt minion and notice that the change has been reverted. We will automate this last step in the next section. + +### Create a Reactor + +1. On your Salt master, create the `/srv/reactor` directory: + + mkdir /srv/reactor + +2. On your Salt master, create a reactor state file in the `/srv/reactor` directory and include the following: + + {{< file "/srv/reactor/nginx_conf_reactor.sls" yaml >}} +/etc/nginx/nginx.conf: + local.state.apply: + - tgt: {{ data['id'] }} + - arg: + - nginx_conf +{{< /file >}} + + The file path in the first line is simply the name of our reactor, and can be whatever you choose. The `tgt`, or target, is the Salt minion that will recieve the highstate. In this case we use the information passed to the reactor from the beacon event, which is available as the `data` dictionary, to programatically choose the right Salt minion ID. The `arg`, or argument, is the name of the Salt state file we created to manage our `nginx.conf` file. + +1. On your Salt master, create a `reactor.conf` file and include our new reactor state file: + + {{< file "/etc/salt/master.d/reactor.conf" yaml >}} +reactor: + - 'salt/beacon/*/inotify//etc/nginx/nginx.conf': + - '/srv/reactor/nginx_conf_reactor.sls' +{{< /file >}} + + This `reactor.conf` file is essentially a list of event names matched to reactor state files. In this example we've used a glob (*) in the event name instead of specifying a specific minion ID, (which means that any change to a `nginx.conf`on any minion will trigger the reactor), but you might find a specific minion ID better suits your needs. + +4. Restart the `salt-master` service to apply the `reactor.conf` file: + + systemctl restart salt-master + +5. On your Salt minion, make a change to the `nginx.conf` file. Then check out your event runner shell and you should see a number of events. Then, check your `nginx.conf` file. The changes you made should have automatically been reverted. + +Congratulations, you know now how to manage configuration drift with Salt. All future updates to `nginx.conf` should be made on the Salt master and applied using `state.apply`. + +## Example 2: Monitoring Minion Memory Usage with Slack + +Salt comes with a number of system monitoring beacons. In this example we will monitor a minion's memory usage and send a Slack notification when the memory usage has passed a certain threshold. For this section you will need to create a Slack bot, obtain an OAuth token, and configure the bot to be able to send Slack messages on your behalf. + +### Configure Your Slack App + +1. [Create a Slack app](https://api.slack.com/apps?new_app=1). + +2. From the Slack app settings page, navigate to OAuth & Permissions. + +3. Copy down the OAuth Access Token. + +4. Under Scopes, select "Send Messages As < your app name >. + +### Create a Beacon + +1. On your Salt minion, open or create the `/etc/salt/minion.d/beacons.conf` and add the following lines. If you already have a `beacons.conf` file from the previous example, leave out the `beacons:` line, but ensure that rest of the configuration is indented two spaces: + + {{< file "/etc/salt/minion.d/beacons.conf" yaml >}} +beacons: + memusage: + - percent: 15% + - interval: 15 +{{< /file >}} + + In this example we've left the memory usage percentage low to ensure the beacon event will fire, and the event interval set to 15 seconds. In a production environment you should change these to more sane values. + +2. Restart `salt-minion` to apply your `beacons.conf`: + + systemctl restart salt-minion + +3. If you haven't already, open another shell into your Salt master and start the event runner: + + salt-run state.event pretty=True + +4. After a few seconds, assuming you've set the memory percentage low enough, you should see an event like the following: + + {{< output >}} +salt/beacon/salt-minion/memusage/ { + "_stamp": "2018-10-10T15:48:53.165368", + "id": "salt-minion", + "memusage": 20.7 +} +{{< /output >}} + + Note that the first line is the name of the event, and contains the minion name. We will use this event name in the next section. + +### Create a Reactor + +1. On your Salt master, create the `/srv/reactor` directory if you have not already done so: + + mkdir /srv/reactor + +2. On your Salt master, create a reactor state file and add the following lines, making sure to change the channel, api_key, and from_name keys to reflect your desired values. The api_key is the OAuth token you copied down in step 3 of the Configure Your Slack App section: + + {{< file "/srv/reactor/memusage.sls" yaml >}} +Send memusage to Slack: + local.slack.post_message: + - tgt: {{ data['id'] }} + - kwarg: + channel: "#general" + api_key: "xoxp-451607817121-453578458246..." + message: "{{ data['id'] }} has hit a memory usage threshold: {{ data['memusage'] }}%." + from_name: "Memusage Bot" +{{< /file >}} + + We're using the `data` dictionary provided to the reactor from the memusage event to populate the minion ID and the memory usage. + +3. On your Salt master, open or create the `reactor.conf` file. If you already have a `reactor.conf` file from the previous example, leave out the `reactor:` line, but ensure that rest of the configuration is indented two spaces: + + {{< file "/etc/salt/master.d/reactor.conf" yaml >}} +reactor: + - 'salt/beacon/*/memusage/': + - '/srv/reactor/memusage.sls' +{{< /file >}} + + In this example we've used a glob (*) in the event name instead of specifying a specific minion ID, (which means that any memusage event will trigger the reactor), but you might find a specific minion ID better suits your needs. + +4. Restart `salt-master` to apply the `reactor.conf`: + + systemctl restart salt-master + +5. In your event-runner shell, after a few seconds, you should see an event like the following: + + {{< output >}} +salt/job/20181010161053393111/ret/salt-minion { + "_stamp": "2018-10-10T16:10:53.571956", + "cmd": "_return", + "fun": "slack.post_message", + "fun_args": [ + { + "api_key": "xoxp-451607817121-453578458246-452348335312-2328ce145e5c0c724c3a8bc2afafee17", + "channel": "#general", + "from_name": "Memusage Bot", + "message": "salt-minion has hit a memory usage threshold: 20.7." + } + ], + "id": "salt-minion", + "jid": "20181010161053393111", + "retcode": 0, + "return": true, + "success": true +} +{{< /output >}} + +6. Open Slack, and you should see that your app has notified the room. + +Congratulations, you now know how to monitor your Salt minion's memory usage with Slack integration. Salt can also monitor CPU load, disk usage, and a number of other things. Refer to the More Information section below for additional resources. + From 0e04c25daceabcff5dd03aad8299bf9db741aef7 Mon Sep 17 00:00:00 2001 From: Andy Stevens Date: Wed, 10 Oct 2018 14:28:57 -0400 Subject: [PATCH 2/5] Spelling corrections and YAML corrections Added 'highstate' to dictionary 'modified' YAML --- ci/vale/dictionary.txt | 1 + .../monitoring-salt-minions-with-beacons/index.md | 1 + 2 files changed, 2 insertions(+) diff --git a/ci/vale/dictionary.txt b/ci/vale/dictionary.txt index d321b05f28c..d3313a03603 100644 --- a/ci/vale/dictionary.txt +++ b/ci/vale/dictionary.txt @@ -472,6 +472,7 @@ heartbleed heroku hexo hiera +highstate hilights hl2 hl2 diff --git a/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md b/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md index 6b5c6dc3f64..bb1b0d4c5bd 100644 --- a/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md +++ b/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md @@ -6,6 +6,7 @@ description: 'How to monitor Salt minions with beacons.' keywords: ['salt','saltstack','minion','minions','beacon','beacons','reactor','reactors','monitor','configuration drift','slack'] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' published: 2018-10-10 +modified: 2018-10-10 modified_by: name: Linode title: "Monitoring Salt Minions with Beacons" From 326bf664a89c5ecadade42e0485e54013995af65 Mon Sep 17 00:00:00 2001 From: Andy Stevens Date: Mon, 15 Oct 2018 07:55:41 -0400 Subject: [PATCH 3/5] Fixed opening sentence --- .../monitoring-salt-minions-with-beacons/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md b/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md index bb1b0d4c5bd..4a008152f45 100644 --- a/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md +++ b/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md @@ -16,7 +16,7 @@ external_resources: - '[Salt Reactors Documentation](https://docs.saltstack.com/en/latest/topics/reactor/)' --- -Every action taken by Salt emits an event: applying a highstate, restarting a minion, accepting a key, etc. *Beacons* emit events for non-salt processes, such a system state changes or file changes. In this guide we will be using Salt beacons to notify the Salt master of changes to our minions, and Salt *reactors* to react to those changes. +Every action taken by Salt, such as applying a highstate or restarting a minion, generates an event. *Beacons* emit events for non-salt processes, such a system state changes or file changes. In this guide we will be using Salt beacons to notify the Salt master of changes to our minions, and Salt *reactors* to react to those changes. ## Before You Begin From 5ecede2cfe61db1549cf86d72d73b27c0b07789a Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 17 Oct 2018 18:07:10 -0400 Subject: [PATCH 4/5] Tech edits --- .../index.md | 89 +++++++++++++------ 1 file changed, 63 insertions(+), 26 deletions(-) diff --git a/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md b/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md index 4a008152f45..6d1c0291622 100644 --- a/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md +++ b/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md @@ -16,11 +16,11 @@ external_resources: - '[Salt Reactors Documentation](https://docs.saltstack.com/en/latest/topics/reactor/)' --- -Every action taken by Salt, such as applying a highstate or restarting a minion, generates an event. *Beacons* emit events for non-salt processes, such a system state changes or file changes. In this guide we will be using Salt beacons to notify the Salt master of changes to our minions, and Salt *reactors* to react to those changes. +Every action taken by Salt, such as applying a highstate or restarting a minion, generates an event. *Beacons* emit events for non-salt processes, such as system state changes or file changes. In this guide we will use Salt beacons to notify the Salt master of changes to our minions, and Salt *reactors* to react to those changes. ## Before You Begin -If you don't already have a Salt master and a Salt minion, follow the first steps of our [Getting Started with Salt - Basic Installation and Setup](https://www.linode.com/docs/applications/configuration-management/getting-started-with-salt-basic-installation-and-setup/) guide. +If you don't already have a Salt master and a Salt minion, follow the first steps in our [Getting Started with Salt - Basic Installation and Setup](https://www.linode.com/docs/applications/configuration-management/getting-started-with-salt-basic-installation-and-setup/) guide. {{< note >}} The steps in this guide require root privileges. Be sure to run the steps below as `root` or with the `sudo` prefix. For more information on privileges, see our [Users and Groups](/docs/tools-reference/linux-users-and-groups/) guide. @@ -32,24 +32,25 @@ Configuration drift occurs when there are untracked changes to a system configur ### Manage Your File -1. On your Salt master, create a directory for your managed files in `/srv/salt/`: +1. On your Salt master, create a directory for your managed files in `/srv/salt/files`: mkdir /srv/salt/files -2. On your Salt master, place your `nginx.conf`, or whichever file you would like to manage, in the `/srv/salt/files` folder. +1. On your Salt master, place your `nginx.conf`, or whichever file you would like to manage, in the `/srv/salt/files` folder. -3. On your Salt master, create a state file to manage the NGINX configuration file: +1. On your Salt master, create a state file to manage the NGINX configuration file: {{< file "/srv/salt/nginx_conf.sls" yaml >}} /etc/nginx/nginx.conf: file.managed: - source: - - 'salt://files/nginx.conf' + - salt://files/nginx.conf + - makedirs: True {{< /file >}} There are two file paths in this `.sls` file. The first file path is the path to your managed file on your minion. The second, under source and prefixed with `salt://`, points to the file path on your master. `salt://` is a convenience file path that maps to `/srv/salt`. -4. On your Salt master, create a top file if it does not already exist and add your `nginx_conf.sls`: +1. On your Salt master, create a top file if it does not already exist and add your `nginx_conf.sls`: {{< file "/srv/salt/top.sls" yaml >}} base: @@ -57,17 +58,34 @@ base: - nginx_conf {{< /file >}} +1. Apply a highstate from your Salt master to run the `nginx_conf.sls` state on your minions. + + salt '*' state.apply + ### Create a Beacon -1. In order to be notified when a file changes, we need to install the `python-pyinotify` package. On your Salt minion, run: +1. In order to be notified when a file changes, you will need the Python `pyinotify` package. Create a Salt state that will handle installing the `pyinotify` package on your minions: + + {{< file "/srv/salt/packages.sls" >}} +python-pip: + pkg.installed - apt-get install python-pyinotify +pyinotify: + pip.installed: + - require: + - pkg: python-pip + {{}} {{< note >}} The inotify beacon only works on OSes that have inotify kernel support. Currently this excludes FreeBSD, macOS, and Windows. {{< /note >}} -2. Now we will create a beacon that will emit an event every time our `nginx.conf` changes. On your Salt minion, create the `/etc/salt/minion.d/beacons.conf` file and add the following lines: +1. On the Salt master create a `minion.d` directory to store the beacon configuration file: + + mkdir /srv/salt/files/minion.d + + +1. Now, create a beacon that will emit an event every time your `nginx.conf` file changes on your minion. Create the `/etc/salt/minion.d/beacons.conf` file and add the following lines: {{< file "/etc/salt/minion.d/beacons.conf" yaml >}} beacons: @@ -79,17 +97,35 @@ beacons: - disable_during_state_run: True {{< /file >}} - The `disable_during_state_run` is important here as it will prevent an infinite loop from occuring when we make changes to our `nginx.conf`. +1. To apply this beacon to your minions, create a new `file.managed` Salt state: -3. Restart `salt-minion` to apply your `beacons.conf` file: + {{< file "/srv/salt/beacons.sls" >}} +/etc/salt/minion.d/beacons.conf: + file.managed: + - source: + - salt://files/minion.d/beacons.conf + - makedirs: True + {{}} - systemctl restart salt-minion +1. Add the new `packages` and `beacons` states to your Salt master's top file: -4. Open another shell to your Salt master and start the Salt event runner. You will use this to monitor for file change events from your beacon. + {{< file "/srv/salt/top.sls" yaml >}} +base: + '*': + - nginx_conf + - packages + - beacons +{{< /file >}} + +1. Apply a highstate from your Salt master to implement these changes on your minions: + + salt '*' state.apply + +1. Open another shell to your Salt master and start the Salt event runner. You will use this to monitor for file change events from your beacon. salt-run state.event pretty=True -5. Make a change to your `nginx.conf` file on your Salt minion, and then check out your Salt event runner shell. You should see an event like the following: +1. On your Salt minion, make a change to your `nginx.conf` file, and then check out your Salt event runner shell. You should see an event like the following: {{< output >}} salt/beacon/salt-minion/inotify//etc/nginx/nginx.conf { @@ -114,7 +150,7 @@ salt/beacon/salt-minion/inotify//etc/nginx/nginx.conf { mkdir /srv/reactor -2. On your Salt master, create a reactor state file in the `/srv/reactor` directory and include the following: +2. Then, create a reactor state file in the `/srv/reactor` directory and include the following: {{< file "/srv/reactor/nginx_conf_reactor.sls" yaml >}} /etc/nginx/nginx.conf: @@ -124,14 +160,14 @@ salt/beacon/salt-minion/inotify//etc/nginx/nginx.conf { - nginx_conf {{< /file >}} - The file path in the first line is simply the name of our reactor, and can be whatever you choose. The `tgt`, or target, is the Salt minion that will recieve the highstate. In this case we use the information passed to the reactor from the beacon event, which is available as the `data` dictionary, to programatically choose the right Salt minion ID. The `arg`, or argument, is the name of the Salt state file we created to manage our `nginx.conf` file. + The file path in the first line is simply the name of the reactor, and can be whatever you choose. The `tgt`, or target, is the Salt minion that will receive the highstate. In this case, the information passed to the reactor from the beacon event is used to programatically choose the right Salt minion ID. This information is available as the `data` dictionary. The `arg`, or argument, is the name of the Salt state file that was created to manage the `nginx.conf` file. -1. On your Salt master, create a `reactor.conf` file and include our new reactor state file: +1. On your Salt master, create a `reactor.conf` file and include the new reactor state file: {{< file "/etc/salt/master.d/reactor.conf" yaml >}} reactor: - 'salt/beacon/*/inotify//etc/nginx/nginx.conf': - - '/srv/reactor/nginx_conf_reactor.sls' + - /srv/reactor/nginx_conf_reactor.sls {{< /file >}} This `reactor.conf` file is essentially a list of event names matched to reactor state files. In this example we've used a glob (*) in the event name instead of specifying a specific minion ID, (which means that any change to a `nginx.conf`on any minion will trigger the reactor), but you might find a specific minion ID better suits your needs. @@ -160,20 +196,21 @@ Salt comes with a number of system monitoring beacons. In this example we will m ### Create a Beacon -1. On your Salt minion, open or create the `/etc/salt/minion.d/beacons.conf` and add the following lines. If you already have a `beacons.conf` file from the previous example, leave out the `beacons:` line, but ensure that rest of the configuration is indented two spaces: +1. On your Salt master, open or create the `/srv/salt/files/minion.d/beacons.conf` file and add the following lines. If you already have a `beacons.conf` file from the previous example, leave out the `beacons:` line, but ensure that rest of the configuration is indented two spaces: - {{< file "/etc/salt/minion.d/beacons.conf" yaml >}} + {{< file "/srv/salt/files/minion.d/beacons.conf" yaml >}} beacons: memusage: - - percent: 15% - - interval: 15 + beacon.present: + - percent: 15% + - interval: 15 {{< /file >}} In this example we've left the memory usage percentage low to ensure the beacon event will fire, and the event interval set to 15 seconds. In a production environment you should change these to more sane values. -2. Restart `salt-minion` to apply your `beacons.conf`: +1. Apply a highstate from your Salt master to add the beacon to your minions: - systemctl restart salt-minion + salt '*' state.apply 3. If you haven't already, open another shell into your Salt master and start the event runner: @@ -197,7 +234,7 @@ salt/beacon/salt-minion/memusage/ { mkdir /srv/reactor -2. On your Salt master, create a reactor state file and add the following lines, making sure to change the channel, api_key, and from_name keys to reflect your desired values. The api_key is the OAuth token you copied down in step 3 of the Configure Your Slack App section: +2. On your Salt master, create a reactor state file and add the following lines, making sure to change the `channel`, `api_key`, and `from_name` keys to reflect your desired values. The `api_key` is the OAuth token you copied down in step 3 of the [Configure Your Slack App](#configure-your-slack-app) section: {{< file "/srv/reactor/memusage.sls" yaml >}} Send memusage to Slack: From 029b3ebe8b25e19ee5120ab4f3fc2c4f64fbd72f Mon Sep 17 00:00:00 2001 From: cwlinode Date: Fri, 19 Oct 2018 12:01:38 -0400 Subject: [PATCH 5/5] Copy edit --- .../index.md | 55 +++++++++---------- 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md b/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md index 6d1c0291622..0521c010f0c 100644 --- a/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md +++ b/docs/applications/configuration-management/monitoring-salt-minions-with-beacons/index.md @@ -1,12 +1,12 @@ --- author: - name: Linode Community + name: Linode email: docs@linode.com description: 'How to monitor Salt minions with beacons.' keywords: ['salt','saltstack','minion','minions','beacon','beacons','reactor','reactors','monitor','configuration drift','slack'] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' -published: 2018-10-10 -modified: 2018-10-10 +published: 2018-10-19 +modified: 2018-10-19 modified_by: name: Linode title: "Monitoring Salt Minions with Beacons" @@ -16,11 +16,11 @@ external_resources: - '[Salt Reactors Documentation](https://docs.saltstack.com/en/latest/topics/reactor/)' --- -Every action taken by Salt, such as applying a highstate or restarting a minion, generates an event. *Beacons* emit events for non-salt processes, such as system state changes or file changes. In this guide we will use Salt beacons to notify the Salt master of changes to our minions, and Salt *reactors* to react to those changes. +Every action performed by Salt, such as applying a highstate or restarting a minion, generates an event. *Beacons* emit events for non-salt processes, such as system state changes or file changes. This guide will use Salt beacons to notify the Salt master of changes to minions, and Salt *reactors* to react to those changes. ## Before You Begin -If you don't already have a Salt master and a Salt minion, follow the first steps in our [Getting Started with Salt - Basic Installation and Setup](https://www.linode.com/docs/applications/configuration-management/getting-started-with-salt-basic-installation-and-setup/) guide. +If you don't already have a Salt master and minion, follow the first steps in our [Getting Started with Salt - Basic Installation and Setup](https://www.linode.com/docs/applications/configuration-management/getting-started-with-salt-basic-installation-and-setup/) guide. {{< note >}} The steps in this guide require root privileges. Be sure to run the steps below as `root` or with the `sudo` prefix. For more information on privileges, see our [Users and Groups](/docs/tools-reference/linux-users-and-groups/) guide. @@ -28,7 +28,7 @@ The steps in this guide require root privileges. Be sure to run the steps below ## Example 1: Preventing Configuration Drift -Configuration drift occurs when there are untracked changes to a system configuration file. Salt can help prevent configuration drift by ensuring that a file is immediately reverted to a safe state upon change. In order to do this, we first have to let Salt manage the file. This section will use a NGINX configuration file as an example, but you can choose any file. +Configuration drift occurs when there are untracked changes to a system configuration file. Salt can help prevent configuration drift by ensuring that a file is immediately reverted to a safe state upon change. In order to do this, we first have to let Salt manage the file. This section will use an NGINX configuration file as an example, but you can choose any file. ### Manage Your File @@ -48,7 +48,7 @@ Configuration drift occurs when there are untracked changes to a system configur - makedirs: True {{< /file >}} - There are two file paths in this `.sls` file. The first file path is the path to your managed file on your minion. The second, under source and prefixed with `salt://`, points to the file path on your master. `salt://` is a convenience file path that maps to `/srv/salt`. + There are two file paths in this `.sls` file. The first file path is the path to your managed file on your minion. The second, under `source` and prefixed with `salt://`, points to the file path on your master. `salt://` is a convenience file path that maps to `/srv/salt`. 1. On your Salt master, create a top file if it does not already exist and add your `nginx_conf.sls`: @@ -58,7 +58,7 @@ base: - nginx_conf {{< /file >}} -1. Apply a highstate from your Salt master to run the `nginx_conf.sls` state on your minions. +1. Apply a highstate from your Salt master to run the `nginx_conf.sls` state on your minions. salt '*' state.apply @@ -80,12 +80,12 @@ pyinotify: The inotify beacon only works on OSes that have inotify kernel support. Currently this excludes FreeBSD, macOS, and Windows. {{< /note >}} -1. On the Salt master create a `minion.d` directory to store the beacon configuration file: +1. On the Salt master create a `minion.d` directory to store the beacon configuration file: mkdir /srv/salt/files/minion.d -1. Now, create a beacon that will emit an event every time your `nginx.conf` file changes on your minion. Create the `/etc/salt/minion.d/beacons.conf` file and add the following lines: +1. Now create a beacon that will emit an event every time the `nginx.conf` file changes on your minion. Create the `/etc/salt/minion.d/beacons.conf` file and add the following lines: {{< file "/etc/salt/minion.d/beacons.conf" yaml >}} beacons: @@ -97,7 +97,7 @@ beacons: - disable_during_state_run: True {{< /file >}} -1. To apply this beacon to your minions, create a new `file.managed` Salt state: +1. To apply this beacon to your minions, create a new `file.managed` Salt state: {{< file "/srv/salt/beacons.sls" >}} /etc/salt/minion.d/beacons.conf: @@ -107,7 +107,7 @@ beacons: - makedirs: True {{}} -1. Add the new `packages` and `beacons` states to your Salt master's top file: +1. Add the new `packages` and `beacons` states to your Salt master's top file: {{< file "/srv/salt/top.sls" yaml >}} base: @@ -117,7 +117,7 @@ base: - beacons {{< /file >}} -1. Apply a highstate from your Salt master to implement these changes on your minions: +1. Apply a highstate from your Salt master to implement these changes on your minions: salt '*' state.apply @@ -150,7 +150,7 @@ salt/beacon/salt-minion/inotify//etc/nginx/nginx.conf { mkdir /srv/reactor -2. Then, create a reactor state file in the `/srv/reactor` directory and include the following: +2. Then create a reactor state file in the `/srv/reactor` directory and include the following: {{< file "/srv/reactor/nginx_conf_reactor.sls" yaml >}} /etc/nginx/nginx.conf: @@ -160,7 +160,7 @@ salt/beacon/salt-minion/inotify//etc/nginx/nginx.conf { - nginx_conf {{< /file >}} - The file path in the first line is simply the name of the reactor, and can be whatever you choose. The `tgt`, or target, is the Salt minion that will receive the highstate. In this case, the information passed to the reactor from the beacon event is used to programatically choose the right Salt minion ID. This information is available as the `data` dictionary. The `arg`, or argument, is the name of the Salt state file that was created to manage the `nginx.conf` file. + The file path in the first line is simply the name of the reactor, and can be whatever you choose. The `tgt`, or target, is the Salt minion that will receive the highstate. In this case, the information passed to the reactor from the beacon event is used to programmatically choose the right Salt minion ID. This information is available as the `data` dictionary. The `arg`, or argument, is the name of the Salt state file that was created to manage the `nginx.conf` file. 1. On your Salt master, create a `reactor.conf` file and include the new reactor state file: @@ -178,7 +178,7 @@ reactor: 5. On your Salt minion, make a change to the `nginx.conf` file. Then check out your event runner shell and you should see a number of events. Then, check your `nginx.conf` file. The changes you made should have automatically been reverted. -Congratulations, you know now how to manage configuration drift with Salt. All future updates to `nginx.conf` should be made on the Salt master and applied using `state.apply`. +Congratulations, you now know how to manage configuration drift with Salt. All future updates to `nginx.conf` should be made on the Salt master and applied using `state.apply`. ## Example 2: Monitoring Minion Memory Usage with Slack @@ -188,11 +188,11 @@ Salt comes with a number of system monitoring beacons. In this example we will m 1. [Create a Slack app](https://api.slack.com/apps?new_app=1). -2. From the Slack app settings page, navigate to OAuth & Permissions. +1. From the Slack app settings page, navigate to OAuth & Permissions. -3. Copy down the OAuth Access Token. +1. Copy down the OAuth Access Token. -4. Under Scopes, select "Send Messages As < your app name >. +1. Under Scopes, select **Send Messages As < your app name >**. ### Create a Beacon @@ -212,11 +212,11 @@ beacons: salt '*' state.apply -3. If you haven't already, open another shell into your Salt master and start the event runner: +1. If you haven't already, open another shell into your Salt master and start the event runner: salt-run state.event pretty=True -4. After a few seconds, assuming you've set the memory percentage low enough, you should see an event like the following: +1. After a few seconds, assuming you've set the memory percentage low enough, you should see an event like the following: {{< output >}} salt/beacon/salt-minion/memusage/ { @@ -234,7 +234,7 @@ salt/beacon/salt-minion/memusage/ { mkdir /srv/reactor -2. On your Salt master, create a reactor state file and add the following lines, making sure to change the `channel`, `api_key`, and `from_name` keys to reflect your desired values. The `api_key` is the OAuth token you copied down in step 3 of the [Configure Your Slack App](#configure-your-slack-app) section: +1. Then create a reactor state file and add the following lines, making sure to change the `channel`, `api_key`, and `from_name` keys to reflect your desired values. The `api_key` is the OAuth token you copied down in step 3 of the [Configure Your Slack App](#configure-your-slack-app) section: {{< file "/srv/reactor/memusage.sls" yaml >}} Send memusage to Slack: @@ -249,7 +249,7 @@ Send memusage to Slack: We're using the `data` dictionary provided to the reactor from the memusage event to populate the minion ID and the memory usage. -3. On your Salt master, open or create the `reactor.conf` file. If you already have a `reactor.conf` file from the previous example, leave out the `reactor:` line, but ensure that rest of the configuration is indented two spaces: +1. Open or create the `reactor.conf` file. If you already have a `reactor.conf` file from the previous example, leave out the `reactor:` line, but ensure that rest of the configuration is indented two spaces: {{< file "/etc/salt/master.d/reactor.conf" yaml >}} reactor: @@ -259,11 +259,11 @@ reactor: In this example we've used a glob (*) in the event name instead of specifying a specific minion ID, (which means that any memusage event will trigger the reactor), but you might find a specific minion ID better suits your needs. -4. Restart `salt-master` to apply the `reactor.conf`: +1. Restart `salt-master` to apply the `reactor.conf`: systemctl restart salt-master -5. In your event-runner shell, after a few seconds, you should see an event like the following: +1. In your event-runner shell, after a few seconds, you should see an event like the following: {{< output >}} salt/job/20181010161053393111/ret/salt-minion { @@ -286,7 +286,6 @@ salt/job/20181010161053393111/ret/salt-minion { } {{< /output >}} -6. Open Slack, and you should see that your app has notified the room. - -Congratulations, you now know how to monitor your Salt minion's memory usage with Slack integration. Salt can also monitor CPU load, disk usage, and a number of other things. Refer to the More Information section below for additional resources. +1. Open Slack and you should see that your app has notified the room. +Congratulations, you now know how to monitor your Salt minion's memory usage with Slack integration. Salt can also monitor CPU load, disk usage, and a number of other things. Refer to the More Information section below for additional resources. \ No newline at end of file