Installer et configurer le plug-in master

Dans le cadre du processus de post-installation, vous devez installer, configurer et mettre à niveau le plug-in master. Le plug-in master permet à vos masters Salt de communiquer avec SaltStack Config. Le plug-in master inclut divers paramètres que vous pouvez ajuster pour améliorer les performances, ce qui est particulièrement utile pour les environnements volumineux ou occupés.

En général, vous installez le plug-in master sur chaque master Salt de votre environnement qui communique avec SaltStack Config. Par exemple, si vous utilisez une configuration incluant plusieurs masters Salt (parfois appelé configuration à plusieurs masters), vous devez installer le plug-in master sur chaque master Salt.

Note : Dans le cadre de l'initiative de VMware visant à supprimer la terminologie problématique, le terme master Salt sera remplacé par un meilleur terme dans SaltStack Config et les produits associés, ainsi que dans la documentation. Cette mise à jour terminologique peut s'étendre sur plusieurs cycles de publication.

Avant de commencer

L'installation et la configuration du plug-in master constituent une étape de post-installation d'une série de plusieurs étapes qui doivent se dérouler dans un ordre spécifique. Tout d'abord, terminez l'un des scénarios d'installation, puis lisez la page de post-installation Installer la clé de licence.

Quand devez-vous installer le plug-in master ?

Vous devez installer le plug-in master sur tous vos masters Salt après une nouvelle installation de SaltStack Config. Le plug-in master n'est pas nécessaire sur les masters Salt qui n'ont pas besoin de communiquer avec SaltStack Config.

Si vous avez utilisé le scénario d'installation Installation de SaltStack Config pour moins de 1 000 nœuds, vous n'avez pas besoin d'installer le plug-in master sur le nœud sur lequel vous avez installé SaltStack Config et son architecture associée. Le programme d'installation installe automatiquement le plug-in master sur le nœud du master Salt. Toutefois, le plug-in master est installé uniquement sur le master Salt sur lequel vous avez lancé le programme d'installation. Si vous avez plusieurs masters, vous devez toujours installer le plug-in master sur vos autres masters.

Si vous installez manuellement SaltStack Config (non recommandé), vous devez effectuer les tâches suivantes avant d'installer le plug-in master :

Installer et configurer la base de données PostgreSQL
Installer et configurer la base de données Redis
Activer SSL (facultatif)

Installer le plug-in maître

Pour installer le plug-in master sur votre master Salt :

Connectez-vous à votre master Salt.
Si nécessaire, téléchargez le fichier wheel du plug-in master sur Customer Connect.
Le plug-in master est inclus dans le fichier .tar.gz du programme d'installation automatisé. Après avoir téléchargé et extrait le fichier.tar.gz, vous pouvez trouver le plug-in master dans le répertoire sse-installer/salt/sse/eapi_plugin/files.
Installez le plug-in master en installant manuellement le fichier wheel Python mis à jour. Utilisez les exemples de commandes suivants, en utilisant le nom exact du fichier wheel :
RHEL/CentOS
```
sudo pip3 install SSEAPE-file-name.whl --prefix /usr
```
Ubuntu
```
sudo pip3 install SSEAPE-file-name.whl
```
Note : Certains utilisateurs devront éventuellement remplacer la syntaxe par pip3.6 ou pip36 pour leurs systèmes d'exploitation.

Configurer le plug-in master

Pour configurer le master Salt après l'installation du plug-in master :

Connectez-vous à votre master Salt et vérifiez que le répertoire /etc/salt/master.d existe ou créez-le.
Générez les paramètres de configuration du master.
Attention : Si vous souhaitez conserver vos paramètres lors de la mise à niveau de votre installation, sauvegardez votre fichier de configuration de plug-in master existant avant d'effectuer cette étape. Copiez ensuite les paramètres pertinents de votre configuration existante dans le fichier qui vient d'être généré.
```
sudo sseapi-config --all > /etc/salt/master.d/raas.conf
```
Si l'exécution de cette commande provoque une erreur, celle-ci peut être liée à la méthode que vous avez utilisée lors de l'installation initiale de Salt. Si vous avez installé Salt via le programme d'installation de SaltStack Config, votre installation inclut probablement un module hors ligne, appelé Salt Crystal, qui nécessite des instructions de mise à niveau spéciales. Pour plus d'informations, reportez-vous à la page Dépannage.

Modifiez le fichier raas.conf généré et mettez à jour les valeurs comme suit pour valider le certificat que l'API (RaaS) utilise et définir son adresse IP.


Valeur	Description
`sseapi_ssl_validate_cert`	Valide le certificat que l'API (RaaS) utilise. La valeur par défaut est `True`. Si vous utilisez vos propres certificats émis par une autorité de certification, définissez cette valeur sur `True` et configurez les paramètres `sseapi_ssl_ca`, `sseapi_ssl_cert` et `sseapi_ssl_cert:`. Sinon, définissez cette valeur sur `False` pour ne pas valider le certificat. sseapi_ssl_validate_cert:False
`sseapi_server`	Adresse IP HTTP de votre nœud RaaS, par exemple, `http://example.com`, ou `https://example.com` si SSL est activé.
`sseapi_command_age_limit`	Définit l'âge (en secondes) après lequel les tâches anciennes et potentiellement périmées sont ignorées. Par exemple, pour ignorer les tâches datant de plusieurs jours, définissez-le sur : sseapi_command_age_limit:86400 Les tâches ignorées continuent à exister dans la base de données et s'affichent avec l'état `Completed` dans l'interface utilisateur de SaltStack Config. Certains environnements peuvent avoir besoin que le master Salt soit hors ligne pendant de longues périodes et auront besoin du master Salt pour exécuter les tâches qui ont été mises en file d'attente après son retour en ligne. Si cela s'applique à votre environnement, définissez la limite d'âge sur `0`.
`sseapi_windows_minion_deploy_delay`	Définit un délai pour permettre à tous les services Windows requis de devenir actifs. La valeur par défaut est de 180 secondes.
`sseapi_linux_minion_deploy_delay`	Définit un délai pour permettre à tous les services Linux requis de devenir actifs. La valeur par défaut est de 90 secondes.

FACULTATIF : cette étape est uniquement nécessaire pour les installations manuelles. Pour vérifier que vous pouvez vous connecter à SSL avant de connecter le plug-in master, modifiez le fichier raas.conf généré pour mettre à jour les valeurs suivantes. Si vous ne mettez pas à jour ces valeurs, le plug-in maître utilise le certificat généré par défaut.


Valeur	Description
`sseapi_ssl_ca`	Chemin d'accès à un fichier d'autorité de certification.
`sseapi_ssl_cert`	Chemin d'accès au certificat. La valeur par défaut est `/etc/pki/raas/certs/localhost.crt`.
`sseapi_ssl_key`	Chemin d'accès à la clé privée du certificat. La valeur par défaut est `/etc/pki/raas/certs/localhost.key`.
`id`	Mettez cette ligne en commentaire en ajoutant un `#` au début. Cela n'est pas obligatoire.

FACULTATIF : mettez à jour les paramètres liés aux performances. Pour les environnements de grande taille ou fortement sollicités, vous pouvez améliorer les performances des communications entre le master Salt et SaltStack Config en ajustant les paramètres suivants.
- Activez la file d'attente des événements (disponible dans Salt 2019.2.2 et versions ultérieures). Les événements peuvent être mis en file d'attente sur le master Salt et envoyés au système de retour d'événements par lot à l'aide d'une transaction unique pour plusieurs événements. Par défaut, ce mécanisme de file d'attente est désactivé. Pour activer la mise en file d'attente des événements, définissez ce qui suit dans le fichier de configuration du plug-in master Salt :
```
event_return_queue:2500
event_return_queue_max_seconds:5
```
  La taille de file d'attente d'événements maximale suggérée est de 2 500, comme indiqué. La file d'attente est vidée et les événements sont transmis au système de retour d'événements lorsque la file d'attente est pleine. Une valeur inférieure peut être mieux adaptée aux environnements plus petits ou aux environnements plus calmes.
  Dans certains cas, le bus d'événements Salt peut ne pas être suffisamment occupé pour que la file d'attente atteigne régulièrement sa taille maximale. La configuration de event_return_queue_max_seconds entraîne le vidage de la file d'attente lorsque l'événement le plus ancien de la file d'attente est antérieur à la valeur configurée, quel que soit le nombre d'événements qui se trouve dans la file d'attente.
- Activez et configurez les moteurs eventqueue et rpcqueue :
  Ces moteurs déchargent certaines communications avec SaltStack Config des chemins de code critiques pour les performances vers des processus dédiés. Pendant que les moteurs attendent de communiquer avec SaltStack Config, les charges utiles sont stockées dans le système de fichiers local du master Salt afin que les données persistent lors des redémarrages de celui-ci.
  Pour activer les moteurs, annulez la mise en commentaire des paramètres suivants dans le fichier de configuration du plug-in master Salt (raas.conf) :
```
engines:
  - sseapi: {}
  - eventqueue: {}
  - rpcqueue: {}
  - jobcompletion: {}
  - keyauth: {}
```
  Pour configurer le moteur eventqueue, annulez la mise en commentaire des paramètres suivants et mettez-les à jour :
```
sseapi_event_queue:
  name: sseapi-events
  strategy: always
  push_interval: 5
  batch_limit: 2000
  age_limit: 86400
  size_limit: 35000000
  vacuum_interval: 86400
  vacuum_limit: 350000
  forward: []
```
  Les paramètres de file d'attente peuvent être ajustés en fonction de leur interfonctionnement. Par exemple, en supposant une moyenne de 400 événements par seconde sur le bus d'événements Salt, les paramètres indiqués ci-dessus permettent de collecter environ 24 heures de trafic d'événements mis en file d'attente sur le master Salt avant que les événements les plus anciens soient supprimés pour cause de limites de taille ou d'ancienneté.
  Pour configurer le moteur rpcqueue, annulez la mise en commentaire des paramètres suivants et mettez-les à jour :
```
sseapi_rpc_queue:
    name: sseapi-rpc
    strategy: always
    push_interval: 5
    batch_limit: 500
    age_limit: 3600
    size_limit: 360000
    vacuum_interval: 86400
    vacuum_limit: 100000
```
- Activer la mise en cache de charge :
```
sseapi_local_cache:
    load:3600
```
  Note : Si le moteur rpcqueue est activé, la mise en cache de charge doit également l'être pour que le master Salt gère correctement les tâches.
- Limitez les tailles de charge utile des grains de minions :
```
sseapi_max_minion_grains_payload:2000
```
- Activez l'annulation des tâches d'une ancienneté supérieure à une période définie (en secondes). Par exemple, utilisez la valeur 86400 pour que les tâches remontant à plus d'une journée soient ignorées. Lorsque la valeur 0 est choisie, cette fonctionnalité est désactivée :
```
sseapi_command_age_limit:0
```
  Note :
  Cela est utile lors d'une mise à niveau pour empêcher l'exécution imprévue d'anciennes commandes stockées dans la base de données.
Ensemble, la mise en file d'attente des événements dans Salt et les moteurs de mise en file d'attente, la mise en cache de charge, la limite de taille de la charge utile des grains et la limite d'ancienneté des commandes dans le plug-in de master Salt augmentent le débit et réduisent la latence des communications entre le master Salt et SaltStack Config dans les chemins de code les plus sensibles aux performances.
Redémarrez le service de master.
```
sudo systemctl restart salt-master
```
FACULTATIF : vous pouvez exécuter une tâche de test pour vous assurer que le plug-in master permet désormais la communication entre les nœuds master et RaaS.
```
salt -v '*' test.ping
```

Même si aucune activité ne s'affiche, par exemple si aucun minion n'est connecté, cela est probablement le signe d'une configuration correcte.

Référence des paramètres de configuration

Ces paramètres dans le fichier de configuration permettent à chaque master Salt de se connecter à l'API (RaaS). Ces paramètres se trouvent dans le fichier de configuration /etc/salt/master.d/raas.conf.

Important :

Les paramètres du master Salt du fichier raas.conf sont prioritaires sur les paramètres existants dans /etc/salt/master. Si vous avez personnalisé les paramètres fileserver_backend ou ext_pillar dans /etc/salt/master, vous devez fusionner manuellement ces paramètres pour qu'ils se regroupent dans un seul fichier. Vous pouvez éventuellement redéfinir l'ordre des serveurs principaux pour en modifier la priorité.

Le tableau suivant explique les paramètres de configuration généraux :


Option	Description
`id`	ID de master Salt, autogénéré s'il n'est pas défini
`sseapi_server`	URL du serveur SSEAPI, par exemple `https://sse.example.com:443`
`engines`	Moteurs Salt à activer, `sseapi`, `eventqueue`, `rpcqueue`, `jobcompletion` et `keyauth` recommandés.
`master_job_cache`	`sseapi` pour utiliser le cache des tâches de master SaltStack Config
`event_return`	Système de retour d'événements Salt, `sseapi` recommandé pour utiliser le système de retour d'événements SaltStack Config
`ext_pillar`	sources de Pillar externes, `sseapi` recommandés
`fileserver_backend`	serveurs principaux de fichiers, `sseapi` et `roots` recommandés
`sseapi_update_interval`	fréquence de mise à jour à partir du serveur de fichiers (secondes, valeur par défaut 60)
`sseapi_poll_interval`	fréquence d'interrogation de SaltStack Config pour obtenir de nouvelles données (secondes, valeur par défaut 30)
`sseapi_jce_poll_interval`	ajoute un délai entre les itérations dans le moteur `jobcompletion` afin qu'un maximum de 5 760 commandes `find_job` soient envoyées par jour par le master Salt (en secondes, 15 par défaut)
`sseapi_timeout`	délai d'attente pour les appels API (RaaS) (secondes, valeur par défaut 200)
`sseapi_pubkey_path`	chemin d'accès au fichier de clé publique pour l'authentification du master Salt dans SaltStack Config
`sseapi_key_rotation`	Intervalle de rotation de la clé d'authentification SaltStack Config du master Salt (secondes, 86 400 par défaut)
`sseapi_cache_pillar`	mise en cache éventuelle des données du Pillar dans SaltStack Config (True ou False, False par défaut)
`sseapi_cluster_id`	(facultatif) Nom du cluster du master Salt, pour regrouper les masters Salt en clusters dans SaltStack Config
`sseapi_failover_master`	le master Salt est un master Salt de basculement (True ou False, False par défaut)
`sseapi_command_age_limit`	ignorer ou non les commandes API (RaaS) plus anciennes qu'une durée définie (secondes, 0 pour désactiver, valeur par défaut 0)

Le tableau suivant explique les paramètres SSL :


Option	Description
`sseapi_ssl_key`	chemin d'accès à la clé privée du certificat
`sseapi_ssl_cert`	chemin d'accès au certificat
`sseapi_ssl_validate_cert`	valider ou non le certificat SSL de SaltStack Config (True ou False, True par défaut)

Le tableau suivant explique les paramètres du moteur de file d'attente des événements, qui figurent sous le titre sseapi_event_queue :


Option	Description
`name`	Nom de la file d'attente des événements (`sseapi-events` par défaut, il n'est pas nécessaire de le modifier)
`strategy`	Quand mettre en file d'attente des événements (`always`, `on_failure` ou `never`, `never` par défaut)
`push_interval`	Fréquence de transmission d'événements à SaltStack Config (secondes, 5 par défaut)
`batch_limit`	Nombre maximal d'événements à transmettre à SaltStack Config par intervalle (2 000 par défaut)
`age_limit`	Ancienneté maximale de l'événement mis en file d'attente ; abandonner les événements les plus anciens (secondes, 86 400 par défaut)
`size_limit`	Taille maximale de la file d'attente ; abandonner les événements les plus anciens (événements, 35 000 000 par défaut)
`vacuum_interval`	Fréquence de vidage de la base de données de file d'attente (secondes, 86 400 par défaut)
`vacuum_limit`	Taille maximale de la file d'attente lors du vidage de la base de données de file d'attente (événements, 350 000 par défaut)
`forward`	Systèmes de retour Salt supplémentaires auxquels envoyer des événements lors de la purge de la file d'attente (aucun par défaut) L'élément de configuration `forward` peut spécifier une liste d'un ou de plusieurs noms de système de retour Salt. Chaque fois que la file d'attente des événements est vidée, les événements en file d'attente sont envoyés à SaltStack Config, ainsi qu'à chaque système de retour figurant dans cette liste. Cela permet d'ajouter la fonctionnalité de file d'attente et de persistance du moteur de file d'attente d'événements à n'importe quel système de retour Salt standard. Voici ci-dessous un extrait de configuration qui entraîne l'écriture d'événements dans un fichier local chaque fois qu'ils sont envoyés à SaltStack Config : sseapi_event_queue: # ...other queue settings... forward: - rawfile_json # rawfile_json returner configuration rawfile_json.filename: /var/log/salt/events.json

Le tableau suivant explique les paramètres du moteur de file d'attente RPC, qui s'affichent sous le titre sseapi_rpc_queue :


Option	Description
`name`	Nom de la file d'attente des événements (`sseapi-rpc` par défaut, il n'est pas nécessaire de le modifier)
`strategy`	Quand mettre en file d'attente des événements (`always`, `on_failure` ou `never`, `never` par défaut)
`push_interval`	Fréquence d'envoi d'appels SaltStack Config (secondes, 5 par défaut)
`batch_limit`	Nombre maximal d'appels à transmettre à SaltStack Config par intervalle (500 par défaut)
`age_limit`	Ancienneté maximale des appels mis en file d'attente ; abandonner les entrées les plus anciennes (secondes, 3 600 par défaut)
`size_limit`	Taille maximale de la file d'attente ; abandonner les entrées les plus anciennes (événements, 360 000 par défaut)
`vacuum_interval`	Fréquence de vidage de la base de données de file d'attente (secondes, 86 400 par défaut)
`vacuum_limit`	Taille maximale de la file d'attente lors du vidage de la base de données de file d'attente (entrées, 100 000 par défaut)

Le tableau suivant explique les paramètres de chemin d'accès. Après la génération de la configuration initiale, modifiez avec précaution ces paramètres. Les modules seront copiés dans ces répertoires à partir du processus d'installation. Cependant, l'ajout de chemins supplémentaires n'aura pas d'effet négatif.


Option	Description
`beacons_dirs`	chemin(s) de modules externes de balise
`engines_dirs`	chemin(s) de modules externes de moteurs
`fileserver_dirs`	chemin(s) de modules externes de serveur de fichiers
`pillar_dirs`	chemin(s) de modules externes de Pillar
`returner_dirs`	chemin(s) de modules externes de système de retour
`roster_dirs`	chemin(s) de modules externes de liste
`runner_dirs`	chemin(s) de modules externes d'exécuteur
`module_dirs`	chemin(s) de modules externes Salt
`proxy_dirs`	chemin(s) de modules externes de proxy
`metaproxy_dirs`	chemin(s) de modules externes de métaproxy
`states_dirs`	chemin(s) de modules externes d'états

Étape suivante

Après l'installation et la configuration du plug-in master, vous devez effectuer des étapes de post-installation supplémentaires. L'étape suivante consiste à configurer le nœud RaaS. Pour poursuivre le processus de post-installation, consultez Vérifier le fichier de configuration RaaS.