salt/README.md

# Краткое руководство по Salt Stack

***

- [Краткое руководство по Salt Stack](#краткое-руководство-по-salt-stack)
  - [Краткая справка](#краткая-справка)
    - [Сравнение СУК](#сравнение-сук)
    - [Аналогия с Ansible](#аналогия-с-ansible)
  - [Установка Salt](#установка-salt)
    - [Master на Debian 12](#master-на-debian-12)
    - [Minion на CentOS Stream 9](#minion-на-centos-stream-9)
    - [Minion на Debian 12](#minion-на-debian-12)
  - [Настройка master](#настройка-master)
  - [Настройка minion](#настройка-minion)
  - [Ключи](#ключи)
    - [Посмотреть все ключи](#посмотреть-все-ключи)
    - [Принять ключ конкретного миньона](#принять-ключ-конкретного-миньона)
    - [Принять ключи по маске идентификаторов](#принять-ключи-по-маске-идентификаторов)
    - [Показать только принятые ключи](#показать-только-принятые-ключи)
    - [Принять все предлагаемые ключи](#принять-все-предлагаемые-ключи)
    - [Удалить ключи по маске](#удалить-ключи-по-маске)
    - [Удалить конкретный ключ](#удалить-конкретный-ключ)
    - [Удалить все ключи](#удалить-все-ключи)
    - [Переинициализация миньона](#переинициализация-миньона)
  - [Первый тест](#первый-тест)
  - [Сбор данных](#сбор-данных)
    - [Сбор всех данных](#сбор-всех-данных)
    - [Получение конкретных значений](#получение-конкретных-значений)
  - [Указание конкретных миньонов для запуска](#указание-конкретных-миньонов-для-запуска)
    - [По маске имён](#по-маске-имён)
    - [По зёрнам (`grains`) в качестве фильтров](#по-зёрнам-grains-в-качестве-фильтров)
    - [По группам узлов](#по-группам-узлов)
    - [Составные подстановки](#составные-подстановки)
  - [Модули исполнения](#модули-исполнения)
    - [Несколько полезных функций](#несколько-полезных-функций)
  - [Формулы](#формулы)
  - [Источники](#источники)

***

В качестве тестового стенда используется виртуальная лаборатория

![stand](./stand.png)

## Краткая справка

### Сравнение СУК

| СУК       | Год создания | Язык         | DSL  | Особенности                |
| --------- | :----------: | ------------ | ---- | -------------------------- |
| Puppet    |     2005     | Ruby         | Свой | Pull                       |
| Chef      |     2009     | Ruby, Erlang | Ruby | Pull, Web                  |
| SaltStack |     2011     | Python       | YAML | Pull (Push), корп-версия   |
| Ansible   |     2012     | Python       | YAML | Push (Pull), Ansible Tower |

### Аналогия с Ansible

| Значение                             | В SaltStack | В Ansible              |
| ------------------------------------ | ----------- | ---------------------- |
| Сервер                               | Мастер      | Узел (нода) управления |
| Клиент                               | Миньон      | Управляемый узел       |
| Декларативный конфиг клиента         | Формула     | Плейбук                |
| Элементарная единица конфига клиента | Состояние   | Таск                   |
| Переменная клиента                   | Грейн       | Факт                   |
| Описание узлов                       | Топ-файл    | Инвентарь (узлы)       |
| Переменные                           | Пиллары     | Переменные             |

## Установка Salt

процесс установки описан в документации <https://docs.saltproject.io/salt/install-guide/en/latest/index.html>

### Master на Debian 12

_сначала установил на Альт сервер, потом оказалось, что Salt не поддерживает работу с пакетным менеджером apt-rpm, который используется в Альте. Чтобы не усложнять жизнь на этапе освоения Salt, от использования в стенде узлов с ОС Альт отказался._

```bash
su -
apt update
apt install curl
mkdir /etc/apt/keyrings

curl -fsSL -o /etc/apt/keyrings/salt-archive-keyring-2023.gpg https://repo.saltproject.io/salt/py3/debian/12/amd64/SALT-PROJECT-GPG-PUBKEY-2023.gpg
echo "deb [signed-by=/etc/apt/keyrings/salt-archive-keyring-2023.gpg arch=amd64] https://repo.saltproject.io/salt/py3/debian/12/amd64/latest bookworm main" | tee /etc/apt/sources.list.d/salt.list

apt update
apt install salt-master salt-minion salt-ssh salt-syndic salt-cloud salt-api

systemctl enable --now salt-master
systemctl enable --now salt-minion
systemctl enable --now salt-syndic
systemctl enable --now salt-api
```

[вверх](#краткое-руководство-по-salt-stack)

### Minion на CentOS Stream 9

```bash
sudo rpm --import https://repo.saltproject.io/salt/py3/redhat/9/x86_64/SALT-PROJECT-GPG-PUBKEY-2023.pub
curl -fsSL https://repo.saltproject.io/salt/py3/redhat/9/x86_64/latest.repo | sudo tee /etc/yum.repos.d/salt.repo

sudo dnf install -y salt-minion
sudo systemctl enable --now salt-minion
```

### Minion на Debian 12

```bash
su -
apt update
apt install curl
mkdir /etc/apt/keyrings

curl -fsSL -o /etc/apt/keyrings/salt-archive-keyring-2023.gpg https://repo.saltproject.io/salt/py3/debian/12/amd64/SALT-PROJECT-GPG-PUBKEY-2023.gpg
echo "deb [signed-by=/etc/apt/keyrings/salt-archive-keyring-2023.gpg arch=amd64] https://repo.saltproject.io/salt/py3/debian/12/amd64/latest bookworm main" | tee /etc/apt/sources.list.d/salt.list

apt update && apt install -y salt-minion
systemctl enable --now salt-minion
```

[вверх](#краткое-руководство-по-salt-stack)

## Настройка master

Описание возможных директив конфигурационного файла приводится в файле `/etc/salt/master` или в документации <https://docs.saltproject.io/en/latest/ref/configuration/master.html>

Хорошим тоном является создание своих конфигурационных файлов в директории `*.d`

```bash
vim /etc/salt/master.d/master.conf
```

```bash
# The network interface to bind to
interface: 0.0.0.0

# The Request/Reply port
# Для файлового сервера, аутентификации, возврата результатов и проч.
ret_port: 4506

# The port minions bind to for commands, aka the publish port
publish_port: 4505

# Писать статистику после выполнения команд
cli_summary: true

# Директории, где лежат файлы состояний и пр.
file_roots:
  base:  # Это дефолтный saltenv
    - /srv/salt/  # Это дефолтный путь
  dev:
    - /srv/salt-dev/
  prod:
    - /srv/salt-prod/

# Объединение узлов в группы
# Пробелы в выборках нужно обрабатывать
# НЕ правильно - 'G@os:CentOS Strem'
# Правильно - 'G@os:CentOS?Stream' или 'P@os:CentOS\sStream'
nodegroups:
  alt: 'G@os:ALT'
  centos-stream: 'G@os:CentOS?Stream'
  centos: 'P@os:CentOS\sStream'
  debian: 'G@os:Debian'
  apt: 'deb-*'
  rpm: 'centos-*'
```

[вверх](#краткое-руководство-по-salt-stack)

## Настройка minion

<https://docs.saltproject.io/en/latest/ref/configuration/minion.html>

```bash
cat /etc/salt/minion.d/minion.conf
```

```bash
# Адрес мастера
master: 10.1.4.1

# Уникальный идентификатор миньона
# по-умолчанию берётся hostname
id: centos-minion-1
```

## Ключи

Для аутентификации и авторизации в Salt используются пары ключей (закрытый, открытый). При включении службы миньона формируется пара ключей, открытый ключ отправляется на мастер.

У мастера есть специальная утилита для работы с ключами - `salt-key`

Некоторые примеры работы с ней:

### Посмотреть все ключи

```bash
[root@alt-master ~]#  salt-key -L
Accepted Keys:
Denied Keys:
Unaccepted Keys:
alt-minion-5
alt-minion-6
centos-minion-1
centos-minion-2
deb-minion-3
deb-minion-4
Rejected Keys:
```

[вверх](#краткое-руководство-по-salt-stack)

### Принять ключ конкретного миньона

```bash
[root@alt-master ~]# salt-key -l accepted
Accepted Keys:
[root@alt-master ~]# salt-key -a centos-minion-1
The following keys are going to be accepted:
Unaccepted Keys:
centos-minion-1
Proceed? [n/Y] 
Key for minion centos-minion-1 accepted.
```

### Принять ключи по маске идентификаторов

```bash
[root@alt-master ~]# salt-key -a 'deb*'
The following keys are going to be accepted:
Unaccepted Keys:
deb-minion-3
deb-minion-4
Proceed? [n/Y] 
Key for minion deb-minion-3 accepted.
Key for minion deb-minion-4 accepted.
```

### Показать только принятые ключи

```bash
salt-key -l accepted
```

### Принять все предлагаемые ключи

```bash
salt-key -A
```

### Удалить ключи по маске

```bash
salt-key -d 'deb*'
```

### Удалить конкретный ключ

```bash
salt-key -d deb-minion-3
```

### Удалить все ключи

```bash
salt-key -D
```

Для дальнейшей работы необходимо принять ключи миньонов *(уверены в том, что в текущем окружении только проверенные узлы)*

```bash
[root@alt-master ~]# salt-key -A
The following keys are going to be accepted:
Unaccepted Keys:
alt-minion-5
alt-minion-6
centos-minion-2
Proceed? [n/Y] 
Key for minion alt-minion-5 accepted.
Key for minion alt-minion-6 accepted.
Key for minion centos-minion-2 accepted.
```

Таким образом должен получиться такой вывод

```bash
[root@alt-master ~]# salt-key -L
Accepted Keys:
alt-minion-5
alt-minion-6
centos-minion-1
centos-minion-2
deb-minion-3
deb-minion-4
Denied Keys:
Unaccepted Keys:
Rejected Keys:
```

[вверх](#краткое-руководство-по-salt-stack)

### Переинициализация миньона

На мастере удалить ключ миньона, затем на миньоне

```bash
systemctl stop salt-minion.service
rm -rf /etc/salt/pki/
systemctl start salt-minion.service
```

далее на мастере принять обновлённый ключ

## Первый тест

```bash
[root@alt-master ~]# salt '*' test.ping
centos-minion-2:
    True
deb-minion-3:
    True
deb-minion-4:
    True
centos-minion-1:
    True
alt-minion-6:
    True
alt-minion-5:
    True


-------------------------------------------
Summary
-------------------------------------------
# of minions targeted: 6
# of minions returned: 6
# of minions that did not return: 0
# of minions with errors: 0
-------------------------------------------
```

## Сбор данных

grains - зёрна, переменные, которые получает мастер с миньона

```bash
[root@alt-master ~]# salt 'alt-minion-6' grains.
grains.append     grains.delval     grains.fetch      grains.get        grains.item       grains.ls         grains.set        grains.setvals    
grains.delkey     grains.equals     grains.filter_by  grains.has_value  grains.items      grains.remove     grains.setval
```

двойной Tab покажет возможные варианты команды

### Сбор всех данных

```bash
salt 'alt-minion-6' grains.items
```

### Получение конкретных значений

```bash
salt 'alt-minion-6' grains.item ipv4
```

```bash
salt 'alt-minion-6' grains.item os
```

```bash
salt 'alt-minion-6' grains.item cpuarch
```

[вверх](#краткое-руководство-по-salt-stack)

## Указание конкретных миньонов для запуска

### По маске имён

```bash
salt 'deb-*' test.ping
```

`*` - и прочие подстановочные символы необходимо оборачивать кавычками, иначе оболочка их будет интерпретировать по-своему - Glob-подстановки

### По зёрнам (`grains`) в качестве фильтров

```bash
salt -G 'os:ALT' test.ping
```

```bash
salt -G 'os:CentOS Stream' test.ping
```

### По группам узлов

Группы узлов необходимо заранее создать в настройках мастера

```bash
salt -N debian test.ping
```

### Составные подстановки

В составных выборках необходимо обрабатывать пробелы, т.к. не ясно где заканчивается условие, а где составное имя  
**НЕ правильно** - `'G@os:CentOS Stream'`  
**Правильно** - `'G@os:CentOS?Stream'`  
**Правильно** - `'P@os:CentOS\sStream'`  
**Правильно** - `G@os:CentOS*`

```bash
deb_ip=$(salt 'deb-minion-3' network.ipaddrs --out=newline_values_only)
salt -C "( G@os:CentOS* and alt* ) or S@${deb_ip}" test.ping
```

[вверх](#краткое-руководство-по-salt-stack)

## Модули исполнения

Несколько стандартных модулей  

- `test`, `saltutils` - служебные модули для тестирования и диагностики
- `file`, `package`, `service`, `system`, `cmd` - назначение понятно из названия, работа с файлами, пакетами, службами systemd и пр.
- `apache`, `postgres`, `nginx`, `redis` - модули для работы с одноимёнными системами
- `ansiblegate`, `chef`, `puppet` - шлюзы для соединения с другими системами управления состоянием

Двойной Tab позволяет получить сведения о возможных командах в каждом модуле

```bash
[root@alt-master ~]# salt -G 'os:CentOS Stream' test.
test.arg                   test.conf_test             test.get_opts              test.provider              test.sleep                 test.versions_information
test.arg_clean             test.cross_test            test.kwarg                 test.providers             test.stack                 test.versions_report
test.arg_repr              test.deprecation_warning   test.module_report         test.raise_exception       test.true                  
test.arg_type              test.echo                  test.not_loaded            test.random_hash           test.try                   
test.assertion             test.exception             test.opts_pkg              test.rand_sleep            test.tty                   
test.attr_call             test.false                 test.outputter             test.rand_str              test.version               
test.collatz               test.fib                   test.ping                  test.retcode               test.versions              
[root@alt-master ~]# 
[root@alt-master ~]# 
[root@alt-master ~]# salt -G 'os:CentOS Stream' file.
file.access                      file.directory_exists            file.group_to_gid                file.mknod_blkdev                file.rmdir
file.append                      file.dirname                     file.is_blkdev                   file.mknod_chrdev                file.search
file.apply_template_on_contents  file.diskusage                   file.is_chrdev                   file.mknod_fifo                  file.sed
file.basename                    file.extract_hash                file.is_fifo                     file.move                        file.sed_contains
file.blockreplace                file.file_exists                 file.is_hardlink                 file.normpath                    file.seek_read
file.chattr                      file.find                        file.is_link                     file.open_files                  file.seek_write
file.check_file_meta             file.get_devmm                   file.join                        file.pardir                      file.set_mode
file.check_hash                  file.get_diff                    file.lchown                      file.patch                       file.set_selinux_context
file.check_managed               file.get_gid                     file.line                        file.path_exists_glob            file.source_list
file.check_managed_changes       file.get_group                   file.link                        file.prepend                     file.stats
file.check_perms                 file.get_hash                    file.list_backup                 file.psed                        file.statvfs
file.chgrp                       file.get_managed                 file.list_backups                file.read                        file.symlink
file.chown                       file.get_mode                    file.list_backups_dir            file.readdir                     file.touch
file.comment                     file.get_selinux_context         file.lsattr                      file.readlink                    file.truncate
file.comment_line                file.get_source_sum              file.lstat                       file.remove                      file.uid_to_user
file.contains                    file.get_sum                     file.makedirs                    file.remove_backup               file.uncomment
file.contains_glob               file.get_uid                     file.makedirs_perms              file.rename                      file.user_to_uid
file.contains_regex              file.get_user                    file.manage_file                 file.replace                     file.write
file.copy                        file.gid_to_group                file.mkdir                       file.restore_backup              
file.delete_backup               file.grep                        file.mknod                       file.restorecon    
```

### Несколько полезных функций

- `test.ping` - доступность миньона
- `saltutil.sync_all` - синхронизация всех сущностей, которые имеются на мастере
- `sys.doc` - получение справки о модуле
- `state.test` - проверка возможности исполнения без непосредственного исполнения, алиас для `state.apply test=True`

[вверх](#краткое-руководство-по-salt-stack)

## Формулы

`top.sls` - файл с описанием целевого состояния миньонов. В текущем стенде он находится по пути `/srv/salt`, этот путь обозначен в настройке мастера в директиве `file_roots`

```yml
---

base:
  '*':
    - highstate.common_pkgs_installed
  'N@apt':
    - highstate.apt
  'N@rpm':
    - highstate.rpm

prod: {}

dev: {}
```

`highstate.common_pkgs_installed` - путь к файлу состояния. Разделитель директории указан в виде `.` точки, а не `/`.

Таким образом полный путь к файлу состояния выглядит так - `/srv/salt/highstate/common_pkgs_installed.sls`

`common_pkgs_installed.sls`

```yml
---

# Пример установки пакетов на разные миньоны

{% set vim = 'vim' %}
{% if grains['os'] == 'CentOS Stream' %}
  {% set vim = 'vim-enhanced' %}
{% endif %}

common_pkgs_installed:
  pkg.installed:
    - pkgs:
      - {{ vim }}
      - git
      - mc
    - refresh: true
```

Для применения состояния необходимо его выполнить:

- протестировать состояние перед применением - `salt '*' state.test`
- вручную - `salt '*' state.apply`
- автоматически. В настройках миньона необходимо прописать состояние по-умолчанию или создать на мастере реактор, который будет отслеживать состояние миньонов

[вверх](#краткое-руководство-по-salt-stack)

## Источники

<https://www.youtube.com/watch?v=6zY41M2anrY></br>
<https://gitlab.com/bergentroll-docs/saltstack-tutorial></br>
<https://docs.saltproject.io/en/latest/contents.html></br>