Utilisation de documents SSM dans des associations State Manager Comparaison des versions de documents SSM Créer un document SSM (console)Créer un document SSM (ligne de commande)Créer un document SSM (API)Suppression de documents SSM personnalisés

Utilisation de documents

Cette section inclut des informations sur l'utilisation des documents SSM.

Table des matières

Utilisation de documents SSM dans des associations State Manager
Comparaison des versions de documents SSM
Créer un document SSM (console)
Créer un document SSM (ligne de commande)
Créer un document SSM (API)
Suppression de documents SSM personnalisés
Exécution de documents à partir d'emplacements distants
Partage de documents SSM
Recherche de documents SSM

Utilisation de documents SSM dans des associations State Manager

Si vous créez un document SSM pour State Manager, une des fonctionnalités de AWS Systems Manager, vous devez l'associer à vos instances gérées après l'avoir ajouté dans le système. Pour de plus amples informations, veuillez consulter Utilisation d'associations dans Systems Manager.

Gardez à l'esprit les détails suivants lorsque vous utilisez des documents SSM dans des associations State Manager.

Vous pouvez attribuer plusieurs documents à une cible en créant différentes associations State Manager qui utilisent différents documents.
Si vous créez un document avec des plugins contradictoires (par exemple, joindre au domaine et supprimer du domaine), c'est le dernier plugin exécuté qui correspondra à l'état final. State Manager ne valide pas la séquence logique ou la cohérence des commandes ou des plugins dans votre document.
Lors du traitement des documents, les associations d'instances sont appliquées en premier, puis vient le tour des associations de groupes balisés. Si une instance fait partie de plusieurs groupes balisés, les documents appartenant au groupe balisé ne seront pas exécutés dans un ordre spécifique. Si une instance est directement ciblée par le biais de plusieurs documents en fonction de son ID d'instance, l'exécution se déroule dans un ordre aléatoire.
Si vous modifiez la version par défaut d'un document SSM pour State Manager, toute association ayant recours à ce document commencera à utiliser la nouvelle version par défaut la prochaine fois que Systems Manager appliquera l'association à l'instance.
Si vous créez une association à l'aide d'un document SSM qui a été partagé avec vous, puis le propriétaire s'arrête de partager le document avec vous, vos associations n'a plus accès à ce document. Toutefois, si le propriétaire partage le même document SSM avec vous ultérieurement, vos associations remapper automatiquement à celui-ci.

Comparaison des versions de documents SSM

Vous pouvez comparer les différences de contenu entre les versions de documents AWS Systems Manager (SSM) dans la console Systems Manager Documents. Lorsque vous comparez des versions d'un document SSM, les différences entre le contenu des versions sont mises en surbrillance.

Pour comparer le contenu d'un document SSM (console)

Ouvrez la console AWS Systems Manager à l'adresse https://console.aws.amazon.com/systems-manager/.
Dans le panneau de navigation, cliquez sur Documents.

-ou-

Si la page d'accueil AWS Systems Manager s'ouvre en premier, sélectionnez l'icône de menu ( ) pour ouvrir le panneau de navigation, puis sélectionnez Documents dans le panneau de navigation.
Dans la liste de documents, chosissez le document dont vous voulez comparer le contenu.
Sous l'onglet Content (Contenu), sélectionnez Compare versions (Comparer des versions), puis sélectionnez la version du document auquel vous voulez comparer le contenu.

Créer un document SSM (console)

Après avoir créé le contenu pour votre document SSM personnalisé, comme décrit dans Rédaction du contenu du document SSM, vous pouvez utiliser la console Systems Manager pour créer un document SSM à l'aide de votre contenu.

Pour créer un document SSM (console)

Ouvrez la console AWS Systems Manager à l'adresse https://console.aws.amazon.com/systems-manager/.
Dans le panneau de navigation, cliquez sur Documents.

-ou-

Si la page d'accueil AWS Systems Manager s'ouvre en premier, sélectionnez l'icône de menu ( ) pour ouvrir le panneau de navigation, puis sélectionnez Documents dans le panneau de navigation.
Sélectionnez Create command or session (Créer une commande ou une session).
Saisissez un nom descriptif pour le document
(Facultatif) Pour Type de cible, spécifiez le type de ressources sur lequel le document peut s'exécuter.
Dans la liste Types de document, sélectionnez le type de document que vous souhaitez créer.
Supprimez les crochets du champ Contenu, puis copiez et collez le document que vous avez créé précédemment.
(Facultatif) Dans la section Balises du document appliquez une ou plusieurs paires nom/valeur de clé de balise au document.

Les balises sont des métadonnées facultatives que vous affectez à une ressource. Les balises vous permettent de classer une ressource de différentes façons, par exemple, par objectif, par propriétaire ou par environnement. Par exemple, vous pouvez baliser un document pour identifier le type de tâches qu'il exécute, le type de systèmes d'exploitation qu'il cible et l'environnement dans lequel il s'exécute. Dans ce cas, vous pouvez spécifier les paires nom/valeur de clé suivantes :
- Key=TaskType,Value=MyConfigurationUpdate
- Key=OS,Value=AMAZON_LINUX_2
- Key=Environment,Value=Production
Pour plus d'informations sur le balisage des ressources Systems Manager, consultez Balisage des ressources Systems Manager.
Sélectionnez Create document pour enregistrer le document.

Créer un document SSM (ligne de commande)

Après avoir créé le contenu pour votre document AWS Systems Manager (SSM) personnalisé, comme décrit dans Rédaction du contenu du document SSM, vous pouvez utiliser AWS Command Line Interface (AWS CLI) ou AWS Tools for PowerShell pour créer un document SSM à l'aide de votre contenu. En voici un exemple dans la commande suivante :

Avant de commencer

Installez et configurez l'AWS CLI ou AWS Tools for PowerShell si vous ne l'avez pas déjà fait. Pour plus d'informations, consultez la section Installation ou mise à jour de la version la plus récente de l'AWS CLI et Installation d'AWS Tools for PowerShell.

Exécutez la commande suivante. Remplacez chaque example resource placeholder (espace réservé pour les ressources) avec vos propres informations.

Si elle aboutit, la commande renvoie une réponse semblable à la suivante :

{
"DocumentDescription":{
  "CreatedDate":1.585061751738E9,
  "DefaultVersion":"1",
  "Description":"MyCustomDocument",
  "DocumentFormat":"JSON",
  "DocumentType":"Command",
  "DocumentVersion":"1",
  "Hash":"0d3d879b3ca072e03c12638d0255ebd004d2c65bd318f8354fcde820dEXAMPLE",
  "HashType":"Sha256",
  "LatestVersion":"1",
  "Name":"Example",
  "Owner":"111122223333",
  "Parameters":[
     --truncated--
  ],
  "PlatformTypes":[
     "Windows",
     "Linux"
  ],
  "SchemaVersion":"0.3",
  "Status":"Creating",
  "Tags": [
        {
            "Key": "Purpose",
            "Value": "Test"
        }
    ]
}
}

Créer un document SSM (API)

Après avoir créé le contenu pour votre document AWS Systems Manager (SSM) personnalisé, comme décrit dans Rédaction du contenu du document SSM, vous pouvez utiliser votre kit SDK préféré pour appeler l'opération d'API AWS Systems Manager CreateDocument afin de créer un document SSM à l'aide de votre contenu. La chaîne JSON ou YAML du paramètre de demande Content est généralement lue à partir d'un fichier. Les exemples de fonction suivants créent un document SSM à l'aide des kits SDK pour Python, Go et Java.

Python



import boto3

ssm = boto3.client('ssm')
filepath = '/path/to/file/documentContent.yaml'

def createDocumentApiExample():
with open(filepath) as openFile:
    documentContent = openFile.read()
    createDocRequest = ssm.create_document(
        Content = documentContent,
        Name = 'createDocumentApiExample',
        DocumentType = 'Automation',
        DocumentFormat = 'YAML' 
    )
    print(createDocRequest)

createDocumentApiExample()

Go



package main

import (
"github.com/aws/aws-sdk-go/aws"
"github.com/aws/aws-sdk-go/aws/session"
"github.com/aws/aws-sdk-go/service/ssm"

"fmt"
"io/ioutil"
"log"
)


func main() {
openFile, err := ioutil.ReadFile("/path/to/file/documentContent.yaml")
if err != nil {
    log.Fatal(err)
}
documentContent := string(openFile)
sesh := session.Must(session.NewSessionWithOptions(session.Options{
    SharedConfigState: session.SharedConfigEnable}))

ssmClient := ssm.New(sesh)
createDocRequest, err := ssmClient.CreateDocument(&ssm.CreateDocumentInput{
    Content: &documentContent,
    Name:  aws.String("createDocumentApiExample"),
    DocumentType: aws.String("Automation"),
    DocumentFormat: aws.String("YAML"),
})
result := *createDocRequest
fmt.Println(result)
}

Java



import java.io.IOException;
import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;

import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonServiceException;
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.profile.ProfileCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.simplesystemsmanagement.AWSSimpleSystemsManagement;
import com.amazonaws.services.simplesystemsmanagement.AWSSimpleSystemsManagementClientBuilder;
import com.amazonaws.services.simplesystemsmanagement.model.*;

public class createDocumentApiExample {
public static void main(String[] args) {
try {
  createDocumentMethod(getDocumentContent());
}
catch (IOException e) {
  e.printStackTrace();
}
}
public static String getDocumentContent() throws IOException {
  String filepath = new String("/path/to/file/documentContent.yaml");
    byte[] encoded = Files.readAllBytes(Paths.get(filepath));
    String documentContent = new String(encoded, StandardCharsets.UTF_8);
    return documentContent;
}

public static void createDocumentMethod (final String documentContent) {
  AWSSimpleSystemsManagement ssm = AWSSimpleSystemsManagementClientBuilder.defaultClient();
  final CreateDocumentRequest createDocRequest = new CreateDocumentRequest()
    .withContent(documentContent)
    .withName("createDocumentApiExample")
    .withDocumentType("Automation")
    .withDocumentFormat("YAML");
  final CreateDocumentResult result = ssm.createDocument(createDocRequest);
}
}

Pour plus d'informations sur la création de contenu de documents personnalisés, consultez Éléments de données et paramètres.

Suppression de documents SSM personnalisés

Si vous ne voulez plus utiliser un document SSM personnalisé, vous pouvez le supprimer à l'aide de la AWS Command Line Interface (AWS CLI) ou de la console AWS Systems Manager.

Pour supprimer un document SSM (AWS CLI)

Avant de supprimer le document, nous vous recommandons de dissocier toutes les instances qui lui sont associées.

Exécutez la commande suivante pour dissocier une instance d'un document.
```
aws ssm delete-association --instance-id "123456789012" --name "documentName"
```
Il n'y a pas de sortie si la commande réussit.

Exécutez la commande suivante. Remplacez chaque example resource placeholder (espace réservé pour les ressources) avec vos propres informations.

Il n'y a pas de sortie si la commande réussit.

Important

Si la document-version ou le version-name ne sont pas fournis, toutes les versions du document sont supprimées.

Pour supprimer un document SSM (console)

Ouvrez la console AWS Systems Manager à l'adresse https://console.aws.amazon.com/systems-manager/.
Dans le panneau de navigation, cliquez sur Documents.

-ou-

Si la page d'accueil AWS Systems Manager s'ouvre en premier, sélectionnez l'icône de menu ( ) pour ouvrir le panneau de navigation, puis sélectionnez Documents dans le panneau de navigation.
Sélectionnez le document que vous souhaitez supprimer.
Sélectionnez Delete (Supprimer). Lorsque vous êtes invité à supprimer le document, sélectionnez Delete (Supprimer).

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Création du contenu du document SSM

Exécution de documents à partir d'emplacements distants