Trabalhar com documentos - AWS Systems Manager

Trabalhar com documentos

Esta seção contém informações sobre como usar e trabalhar com documentos do SSM.

Usar documentos do SSM no State Manager Associations

Se criar um documento do State Manager para o AWS Systems Manager, você deverá associá-lo às suas instâncias gerenciadas depois que adicioná-lo ao sistema. Para ter mais informações, consulte Para obter informações, consulte Trabalhar com associações no Systems Manager..

Tenha em mente os detalhes a seguir ao usar documentos do State Manager em associações do State Manager.

  • Você pode atribuir vários documentos a um destino criando diferentes associações do State Manager que usam documentos distintos.

  • Se você criar um documento com plugins conflitantes (por exemplo, ingresso em domínio e remoção do domínio), o último plugin executado será o estado final. O State Manager não valida a sequência lógica ou o raciocínio dos comandos ou plugins no seu documento.

  • Ao processar documentos, as associações de instâncias são aplicadas primeiro e as próximas associações de grupo marcadas são aplicadas. Se uma instância fizer parte de vários grupos marcados, os documentos que fizerem parte do grupo marcado não serão executados em uma ordem específica. Se uma instância for visada diretamente em vários documentos por seu ID de instância, não haverá uma ordem de execução específica.

  • Se você alterar a versão padrão de um documento de Política do SSM para o State Manager, qualquer associação que usar esse documento começará a usar a nova versão padrão na próxima vez em que o Systems Manager aplicar a associação à instância.

  • Se você criar uma associação usando um documento SSM que foi compartilhado com você e, em seguida, o proprietário interromper esse compartilhamento, suas associações não terão mais acesso a ele. No entanto, se o proprietário compartilhar o mesmo documento SSM com você novamente mais tarde, suas associações serão automaticamente remapeadas para esse documento.

Comparar versões de documentos do SSM

Você pode comparar as diferenças de conteúdo entre versões doAWS Systems Manager(SSM) no console Documents do Systems Manager. Ao comparar versões de um documento SSM, as diferenças entre o conteúdo das versões são realçadas.

Para comparar o conteúdo do documento SSM (console)
  1. Abra o console AWS Systems Manager em https://console.aws.amazon.com/systems-manager/.

  2. No painel de navegação, escolha Documents.

  3. Na lista de documentos, escolha o documento cujo conteúdo você deseja comparar.

  4. NoConteúdo, selecioneComparar versõesE escolha a versão do documento com a qual você deseja comparar o conteúdo.

Criar um documento SSM (console)

Depois que criar o conteúdo do documento SSM personalizado, conforme descrito em Escrever conteúdo de documento do , você poderá usar o console do Systems Manager para criar um documento do SSM usando seu conteúdo.

Para criar um documento SSM (console)
  1. Abra o console AWS Systems Manager em https://console.aws.amazon.com/systems-manager/.

  2. No painel de navegação, escolha Documents.

  3. Escolha Create command or session (Criar comando ou sessão).

  4. Insira um nome descritivo para o documento

  5. (Opcional) No Tipo de destino, especifique o tipo de recursos nos quais o documento pode ser executado.

  6. Na lista Document type (Tipo de documento), escolha o tipo de documento que você deseja criar.

  7. Exclua os parênteses no campo Content (Conteúdo) e cole o conteúdo do documento que você criou anteriormente.

  8. (Opcional) Na seção Tags de documento, aplique um ou mais pares de nome/valor de chave de tag ao documento.

    Tags são metadados opcionais que você atribui a um recurso. As tags permitem categorizar um recurso de diferentes formas, como por finalidade, proprietário ou ambiente. Por exemplo, você pode querer marcar um documento para identificar o tipo de tarefas que ele executa, o tipo de sistemas operacionais que ele direciona e o ambiente em que ele é executado. Nesse caso, você pode especificar os seguintes pares de nome/valor:

    • Key=TaskType,Value=MyConfigurationUpdate

    • Key=OS,Value=AMAZON_LINUX_2

    • Key=Environment,Value=Production

    Para obter mais informações sobre como marcar um recurso do Systems Manager, consulte Marcar recursos do Systems Manager.

  9. Escolha Create document (Criar documento) para salvar o documento.

Criar um documento do SSM (linha de comando)

Depois que criar o conteúdo para o documento do AWS Systems Manager personalizado, conforme descrito em Escrever conteúdo de documento do , você poderá usar a AWS Command Line Interface ou a AWS CLI para criar um documento do AWS Tools for PowerShell usando seu conteúdo. Isso é mostrado no comando a seguir.

Antes de começar

Instale e configure a AWS CLI ou o AWS Tools for PowerShell, caso ainda não o tenha feito. Para obter informações, consulte Instalar ou atualizar a versão mais recente da AWS CLI e Instalar o AWS Tools for PowerShell.

Execute o seguinte comando . Substitua cada espaço reservado para recurso de exemplo por suas próprias informações.

Linux & macOS
aws ssm create-document \ --content file://path/to/file/documentContent.json \ --name "document-name" \ --document-type "Command" \ --tags "Key=tag-key,Value=tag-value"
Windows
aws ssm create-document ^ --content file://C:\path\to\file\documentContent.json ^ --name "document-name" ^ --document-type "Command" ^ --tags "Key=tag-key,Value=tag-value"
PowerShell
$json = Get-Content -Path "C:\path\to\file\documentContent.json" | Out-String New-SSMDocument ` -Content $json ` -Name "document-name" ` -DocumentType "Command" ` -Tags "Key=tag-key,Value=tag-value"

Se houver êxito, o comando retornará uma resposta semelhante à seguinte.

{
"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"
        }
    ]
}
}

Criar um documento do SSM (API)

Depois que criar o conteúdo para o documento do AWS Systems Manager (SSM) personalizado, conforme descrito em Escrever conteúdo de documento do , você poderá usar a AWS Systems Manager ou a operação da API CreateDocument para criar um documento do SSM usando seu conteúdo. A string JSON ou YAML do parâmetro de solicitação Content, em geral, é lida de um arquivo. As funções de amostra a seguir criam um documento do usando os SDKs para Python, Go e 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); } }

Para obter mais informações sobre como criar documentos personalizados, consulte Elementos e parâmetros de dados.

Excluir documentos do SSM personalizados

Se não quiser mais usar um documento SSM personalizado, você poderá excluí-lo usando a AWS Command Line Interface (AWS CLI) ou o console do AWS Systems Manager.

Para excluir um documento do SSM (AWS CLI)
  1. Antes de excluir o documento, recomendamos que você desassocie todas as instâncias associadas ao documento.

    Execute o comando a seguir para desassociar uma instância de um documento.

    aws ssm delete-association --instance-id "123456789012" --name "documentName"

    Não haverá saída se o comando for bem-sucedido.

  2. Execute o seguinte comando . Substitua cada espaço reservado para recurso de exemplo por suas próprias informações.

    Linux
    aws ssm delete-document \ --name "document-name" \ --document-version "document-version" \ --version-name "version-name"
    Windows
    aws ssm delete-document ^ --name "document-name" ^ --document-version "document-version" ^ --version-name "version-name"
    PowerShell
    Delete-SSMDocument ` -Name "document-name" ` -DocumentVersion 'document-version' ` -VersionName 'version-name'

    Não haverá saída se o comando for bem-sucedido.

    Importante

    Se a document-version ou a version-name não forem fornecidas, todas as versões do documento serão excluídas.

Para excluir um documento do SSM (console)
  1. Abra o console AWS Systems Manager em https://console.aws.amazon.com/systems-manager/.

  2. No painel de navegação, escolha Documents.

  3. Selecione a função que você deseja excluir.

  4. SelectExcluir. Quando solicitado a excluir o documento, selecioneExcluir.