Trabajo con documentos - AWS Systems Manager

Trabajo con documentos

Esta sección incluye información sobre cómo usar y trabajar con documentos de SSM.

Utilizar documentos de SSM en asociaciones State Manager

Si crea un documento de SSM para State Manager, una capacidad de AWS Systems Manager, debe asociar el documento a las instancias administradas después de haberlo agregado al sistema. Para obtener más información, consulte Trabajo con asociaciones en Systems Manager.

Tenga en cuenta los siguientes detalles cuando utilice documentos de SSM en asociaciones de State Manager.

  • Puede asignar varios documentos a un destino mediante la creación de diferentes asociaciones de State Manager que utilizan diferentes documentos.

  • Si crea un documento con complementos en conflicto (por ejemplo, unir al dominio y eliminar del dominio), el último complemento que se ejecute será el estado definitivo. State Manager no valida la secuencia lógica ni la racionalidad de los comandos o complementos en el documento.

  • Cuando procese los documentos, las asociaciones de instancia se aplicarán en primer lugar y, a continuación, se aplicarán las asociaciones de los grupo etiquetados. Si una instancia forma parte de varios grupos etiquetados, los documentos que formen parte del grupo etiquetado no se ejecutarán en ningún orden en particular. Si varios documentos se dirigen a una instancia directamente mediante su ID de instancia, no existe ningún orden concreto de ejecución.

  • Si cambia la versión predeterminada de un documento de política de SSM por State Manager, cualquier asociación que utilice el documento empezará a utilizar la nueva versión predeterminada la próxima vez que Systems Manager aplique la asociación a la instancia.

  • Si crea una asociación con un documento de SSM que se ha compartido con usted y, a continuación, el propietario deja de compartir el documento con usted, sus asociaciones ya no tendrán acceso a ese documento. Sin embargo, si el propietario comparte el mismo documento de SSM con usted de nuevo más tarde, sus asociaciones se volverán a mapear con el documento automáticamente.

Comparación de versiones de documentos de SSM

Puede comparar las diferencias de contenido entre las versiones de documentos AWS Systems Manager (SSM) en la consola de documentos de Systems Manager. Cuando compara versiones de un documento de SSM, se resaltan las diferencias entre el contenido de las versiones.

Para comparar el contenido del documento de SSM (consola)
  1. Abra la consola de AWS Systems Manager en https://console.aws.amazon.com/systems-manager/.

  2. En el panel de navegación, elija Documentos.

  3. En la lista de documentos, elija el documento cuyo contenido desea comparar.

  4. En la pestaña Content (Contenido), seleccione Compare versions (Comparar versiones) y elija la versión del documento con la que desee comparar el contenido.

Crear un documento de SSM (consola)

Después de crear el contenido del documento de SSM personalizado, como se describe en Escribir contenido en el documento de SSM, puede utilizar la consola de Systems Manager para crear un documento de SSM con el contenido.

Para crear un documento de SSM (consola)
  1. Abra la consola de AWS Systems Manager en https://console.aws.amazon.com/systems-manager/.

  2. En el panel de navegación, elija Documentos.

  3. Elija Create command or session (Crear comando o sesión).

  4. Ingrese un nombre descriptivo del documento

  5. (Opcional) En Tipo de destino, especifique el tipo de recursos en los que se puede ejecutar el documento.

  6. En la lista Document Type, seleccione el tipo de documento que desee crear.

  7. Elimine los corchetes del campo Content (Contenido) y, a continuación, pegue el contenido del documento creado previamente.

  8. (Opcional) En la sección Etiquetas de documento, aplique uno o más pares de nombre y valor de clave de etiqueta al documento.

    Las etiquetas son metadatos opcionales que usted asigna a un recurso. Las etiquetas permiten clasificar los recursos de diversas maneras, por ejemplo, según la finalidad, el propietario o el entorno. Por ejemplo, es posible que desee etiquetar un documento para identificar el tipo de tareas que ejecuta, el tipo de sistemas operativos al que se dirige y el entorno en el que se ejecuta. En este caso, puede especificar los siguientes pares de claves nombre-valor:

    • Key=TaskType,Value=MyConfigurationUpdate

    • Key=OS,Value=AMAZON_LINUX_2

    • Key=Environment,Value=Production

    Para obtener más información acerca del etiquetado de recursos de Systems Manager, consulte Etiquetado de recursos de Systems Manager.

  9. Elija Create document para guardar el documento.

Crear un documento de SSM (línea de comandos)

Después de crear el contenido del documento de AWS Systems Manager (SSM) personalizado, como se describe en Escribir contenido en el documento de SSM, puede utilizar la AWS Command Line Interface (AWS CLI) o AWS Tools for PowerShell para crear un documento de SSM con el contenido. Esto se muestra en el siguiente comando.

Antes de empezar

Si aún no lo ha hecho, instale y configure la AWS CLI o AWS Tools for PowerShell. Para obtener información, consulte Instalación o actualización de la última versión de la AWS CLI e Instalación de AWS Tools for PowerShell.

Ejecute el siguiente comando de la . Reemplace cada example resource placeholder con su propia información.

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"

Si se ejecuta correctamente, el comando devolverá una respuesta similar a la siguiente.

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

Crear un documento de SSM (API)

Después de crear el contenido del documento de AWS Systems Manager (SSM) personalizado, como se describe en Escribir contenido en el documento de SSM, puede utilizar el SDK de preferencia para llamar la operación de la API AWS Systems Manager CreateDocument para crear un documento de SSM con el contenido. La cadena JSON o YAML para el parámetro de solicitud Content generalmente se lee desde un archivo. Las siguientes funciones de ejemplo crean un documento de SSM mediante los SDK para Python, Go y 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 obtener más información acerca de la creación de contenido de documentos personalizado, consulte Elementos y parámetros de datos.

Eliminación de documentos de SSM personalizados

Si ya no desea utilizar un documento de SSM personalizado, puede eliminarlo desde AWS Command Line Interface (AWS CLI) o desde la consola de AWS Systems Manager.

Para eliminar un documento de SSM (AWS CLI)
  1. Antes de eliminar el documento, se recomienda que desasocie todas las instancias del documento.

    Ejecute el siguiente comando para disociar una instancia de un documento.

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

    No se obtienen resultados si el comando se ejecuta satisfactoriamente.

  2. Ejecute el siguiente comando de la . Reemplace cada example resource placeholder con su propia información.

    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'

    No se obtienen resultados si el comando se ejecuta satisfactoriamente.

    importante

    Si document-version o version-name no se proporcionan, se eliminan todas las versiones del documento.

Para eliminar un documento de SSM (consola)
  1. Abra la consola de AWS Systems Manager en https://console.aws.amazon.com/systems-manager/.

  2. En el panel de navegación, elija Documentos.

  3. Seleccione el documento que desea eliminar.

  4. Seleccione Delete (Eliminar). Cuando se le pida confirmación para eliminar el documento, seleccione Delete (Eliminar).