Uso del Generador de documentos para crear un manual de procedimientos - AWS Systems Manager
Crear un manual de procedimientos con el Generador de documentosCrear un manual de procedimientos que ejecute scripts

Uso del Generador de documentos para crear un manual de procedimientos

Si los manuales de procedimientos públicos de AWS Systems Manager no admiten todas las acciones que desea realizar en sus recursos de AWS, puede crear sus propios manuales. Para crear un manual de procedimientos personalizado, puede crear manualmente un archivo de formato YAML o JSON local con las acciones de automatización adecuadas. Como alternativa, puede usar el Generador de documentos en la consola de Automatización de Systems Manager para crear un manual de procedimientos personalizado.

Con el Generador de documentos, puede agregar acciones de automatización a su manual de procedimientos personalizado y proporcionar los parámetros necesarios sin tener que usar la sintaxis JSON o YAML. Después de agregar pasos y crear el manual de procedimientos, el sistema convierte las acciones que ha agregado al formato YAML que Systems Manager puede utilizar para ejecutar la automatización.

Los manuales de procedimientos admiten el uso de Markdown, un lenguaje de marcado que le permite agregar descripciones de estilo Wiki a manuales de procedimientos y pasos individuales dentro del manual. Para obtener más información acerca del uso de Markdown, consulte Uso de Markdown en AWS.

Crear un manual de procedimientos con el Generador de documentos

Antes de empezar

Le recomendamos que lea acerca de las diferentes acciones que puede usar dentro de un manual de procedimientos. Para obtener más información, consulte Referencia de acciones de Automatización de Systems Manager.

Para crear un manual de procedimientos con el Generador de documentos

  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 automation (Crear automatización).

  4. En Name (Nombre), ingrese un nombre descriptivo para el manual de procedimientos.

  5. En Document description (Descripción del documento), proporcione la descripción del estilo Markdown del manual de procedimientos. Puede proporcionar instrucciones para utilizar el manual de procedimientos, pasos numerados o cualquier otro tipo de información para describir el manual de procedimientos. Consulte el texto predeterminado para obtener información sobre cómo dar formato al contenido.

    sugerencia

    Alterna entre Hide preview (Ocultar vista previa) y Show preview (Mostrar vista previa) para ver el aspecto del contenido de la descripción mientras redacta.

  6. De forma opcional, en Assume role (Asumir rol), escriba el nombre o ARN de un rol de servicio que realizará acciones en su nombre. Si no especifica un rol, Automation utiliza los permisos de acceso del usuario que ejecuta la automatización.

    importante

    Para los manuales de procedimientos que no son propiedad de Amazon y que utilizan la acción aws:executeScript, es necesario especificar un rol. Para obtener más información, consulte Permisos para utilizar los manuales de procedimientos.

  7. (Opcional) En Outputs (Salidas), ingrese cualquier salida para la automatización de este manual de procedimientos a fin de que esté disponible para otros procesos.

    Por ejemplo, si el manual de procedimientos crea una AMI nueva, puede especificar ["CreateImage.ImageId"] y, a continuación, utilizar esta salida para crear instancias nuevas en una automatización posterior.

  8. De forma opcional, expanda la sección Input parameters (Parámetros de entrada) y haga lo siguiente.

    1. En Parameter name (Nombre de parámetro), ingrese un nombre descriptivo para el parámetro del manual de procedimientos que está creando.

    2. En Type (Tipo), elija un tipo para el parámetro, como String o MapList.

    3. En Required (Requerido), realice una de las acciones siguientes:

      • Elija Yes (Sí) si se debe proporcionar un valor para este parámetro del manual de procedimientos en el tiempo de ejecución.

      • Elija No si el parámetro no es necesario y, de forma opcional, ingrese el valor de un parámetro predeterminado en Default value (Valor predeterminado).

    4. En Description (Descripción), ingrese una descripción para el parámetro del manual de procedimientos.

    nota

    Para agregar más parámetros del manual de procedimientos, elija Add a parameter (Agregar un parámetro). Para quitar un parámetro del manual de procedimientos, elija el botón X (quitar).

  9. (Opcional) Expanda la sección Target type (Tipo de destino) y elija un tipo de destino para definir los tipos de recursos en los que se puede ejecutar la automatización. Por ejemplo, para usar un manual de procedimientos en instancias EC2, elija /AWS::EC2::Instance.

    nota

    Si especifica un valor de “/”, el manual de procedimientos puede ejecutarse en todos los tipos de recursos. Para obtener una lista de los tipos de recursos válidos, consulte la Referencia de tipos de recursos de AWS en la Guía del usuario AWS CloudFormation.

  10. (Opcional) Expanda la sección Document tags (Etiquetas del documento) e ingrese uno o más pares de clave-valor de etiqueta para aplicarlos al manual de procedimientos. Las etiquetas facilitan la identificación, la organización y la búsqueda de recursos.

  11. En la sección Step 1 (Paso 1) proporcione la siguiente información.

    • En Step name (Nombre del paso), escriba un nombre descriptivo para el primer paso de la automatización.

    • En Action type (Tipo de acción), seleccione el tipo de acción que desea utilizar para este paso.

      Para obtener una lista e información acerca de los tipos de acción disponibles, consulte Referencia de acciones de Automatización de Systems Manager.

    • En Description (Descripción), escriba una descripción del paso de automatización. Puede usar Markdown para dar formato al texto.

    • Según el Action type (Tipo de acción) seleccionado, introduzca las entradas necesarias para el tipo de acción en la sección Step inputs (Entradas de paso). Por ejemplo, si ha seleccionado la acción aws:approve, debe especificar un valor para la propiedad Approvers.

      Para obtener información acerca de los campos de entrada de pasos, consulte la entrada de Referencia de acciones de Automatización de Systems Manager correspondiente al tipo de acción seleccionado. Por ejemplo: aws:executeStateMachine: ejecutar una máquina de estado de AWS Step Functions.

    • (Opcional) En Additional inputs (Entradas adicionales), proporcione los valores de entrada adicionales que se necesitan para el manual de procedimientos. Los tipos de entrada disponibles dependen del tipo de acción seleccionado para el paso. (Tenga en cuenta que algunos tipos de acción requieren valores de entrada).

      nota

      Para agregar más entradas, elija Add optional input (Agregar entrada opcional). Para eliminar una entrada, elija el botón X (eliminar).

    • (Opcional) En Outputs (Salidas), ingrese cualquier salida que corresponda a este paso a fin de que esté disponible para otros procesos.

      nota

      Las Outputs (Salidas) no están disponibles para todos los tipos de acción.

    • (Opcional) Expanda la sección Common properties (Propiedades comunes) y especifique propiedades para las acciones que son comunes a todas las acciones de automatización. Por ejemplo, para Timeout seconds (Segundos de tiempo de espera), puede proporcionar un valor en segundos para especificar cuánto tiempo se puede ejecutar el paso antes de que se detenga.

      Para obtener más información, consulte Propiedades compartidas por todas las acciones.

    nota

    Para agregar más pasos, seleccione Add step (Agregar paso) y repita el procedimiento para crear un paso. Para quitar un paso, elija Remove step (Quitar paso).

  12. Elija Create automation (Crear automatización) para guardar el manual de procedimientos.

Crear un manual de procedimientos que ejecute scripts

El siguiente procedimiento muestra cómo usar el Generador de documentos en la consola de Automation de AWS Systems Manager para crear un manual de procedimientos personalizado que ejecuta un script.

El primer paso del manual de procedimientos que crea ejecuta un script para lanzar una instancia de Amazon Elastic Compute Cloud (Amazon EC2). El segundo paso ejecuta otro script para monitorear que el estado de la instancia pase a ser ok. A continuación, se informa el estado general Success para la automatización.

Antes de empezar

Asegúrese de haber completado los pasos siguientes:

Para crear un manual de procedimientos personalizado que ejecute scripts mediante el Generador de documentos

  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 automation (Crear automatización).

  4. En Name (Nombre), escriba este nombre descriptivo para el manual de procedimientos: LaunchInstanceAndCheckStatus.

  5. (Opcional) En Document description (Descripción del documento), reemplace el texto predeterminado con una descripción de este manual de procedimientos utilizando Markdown. A continuación, se muestra un ejemplo.

    ##Title: LaunchInstanceAndCheckState
    -----
    **Purpose**: This runbook first launches an EC2 instance using the AMI ID provided in the parameter ```imageId```. The second step of this runbook continuously checks the instance status check value for the launched instance until the status ```ok``` is returned.
    
    ##Parameters:
    -----
    Name | Type | Description | Default Value
    ------------- | ------------- | ------------- | -------------
    assumeRole | String | (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. | -
    imageId  | String | (Optional) The AMI ID to use for launching the instance. The default value uses the latest Amazon Linux AMI ID available. | {{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}

  6. En Assume role (Rol de asunción), ingrese el ARN del rol de servicio de IAM para Automation (Rol de asunción) para la automatización, en el formato arn:aws:iam::111122223333:role/AutomationServiceRole. Sustituya el ID de la Cuenta de AWS por 111122223333.

    El rol que especifique se utiliza para proporcionar los permisos necesarios para iniciar la automatización.

    importante

    Para los manuales de procedimientos que no son propiedad de Amazon y que utilizan la acción aws:executeScript, es necesario especificar un rol. Para obtener más información, consulte Permisos para utilizar los manuales de procedimientos.

  7. Expanda Input parameters (Parámetros de entrada) y haga lo siguiente.

    1. En Parameter name (Nombre de parámetro), introduzca imageId.

    2. En Type (Tipo), elija String.

    3. En Required (Requerido), elija No.

    4. En Default value (Valor predeterminado), escriba lo siguiente.

      {{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}
      nota

      Este valor lanza una instancia de Amazon EC2 con el ID de la última Amazon Machine Image (AMI) de Amazon Linux 1. Si desea utilizar una AMI diferente, reemplace el valor con el ID de su AMI.

    5. En Description (Descripción), escriba lo siguiente.

      (Optional) The AMI ID to use for launching the instance. The default value uses the latest released Amazon Linux AMI ID.

  8. Seleccione Add a parameter (Añadir un parámetro) para crear el segundo parámetro, tagValue, y escriba lo siguiente.

    1. En Parameter name (Nombre de parámetro), introduzca tagValue.

    2. En Type (Tipo), elija String.

    3. En Required (Requerido), elija No.

    4. En Default value (Valor predeterminado), introduzca LaunchedBySsmAutomation. Esto agrega el valor de par de claves de etiqueta Name:LaunchedBySsmAutomation a la instancia.

    5. En Description (Descripción), escriba lo siguiente.

      (Optional) The tag value to add to the instance. The default value is LaunchedBySsmAutomation.

  9. Seleccione Add a parameter (Añadir un parámetro) para crear el tercer parámetro, instanceType, y escriba lo siguiente.

    1. En Parameter name (Nombre de parámetro), introduzca instanceType.

    2. En Type (Tipo), elija String.

    3. En Required (Requerido), elija No.

    4. En Default value (Valor predeterminado), introduzca t2.micro.

    5. En Parameter description (Descripción del parámetro), escriba lo siguiente.

      (Optional) The instance type to use for the instance. The default value is t2.micro.

  10. Expanda Target type (Tipo de destino) y elija "/".

  11. (Opcional) Expanda Document tags (Etiquetas de documento) para aplicar etiquetas de recursos al manual de procedimientos. En Tag key (Clave de etiqueta), escriba Purpose y en Tag value (Valor de etiqueta), escriba LaunchInstanceAndCheckState.

  12. En la sección Step 1 (Paso 1) siga los pasos siguientes.

    1. En Step name (Nombre del paso), ingrese este nombre descriptivo para el primer paso de la automatización: LaunchEc2Instance.

    2. En Action type (Tipo de acción), seleccione Run a script) (aws:executeScript).

    3. En Description (Descripción), escriba una descripción para el paso de automatización, como la siguiente.

      **About This Step**
    
    This step first launches an EC2 instance using the ```aws:executeScript``` action and the provided script.

    4. Amplíe Inputs (Entradas).

    5. En Runtime (Entorno de ejecución), elija el lenguaje del entorno de ejecución que se va a usar para ejecutar el script proporcionado.

    6. En Handler (Controlador), escriba launch_instance. Este es el nombre de la función declarado en el siguiente script.

      nota

      Esto no es necesario para PowerShell.

    7. En Script, reemplace el contenido predeterminado por lo siguiente. Asegúrese de que el script coincide con el valor del entorno de ejecución.

      Python
      def launch_instance(events, context):
      import boto3
      ec2 = boto3.client('ec2')
    
      image_id = events['image_id']
      tag_value = events['tag_value']
      instance_type = events['instance_type']
    
      tag_config = {'ResourceType': 'instance', 'Tags': [{'Key':'Name', 'Value':tag_value}]}
    
      res = ec2.run_instances(ImageId=image_id, InstanceType=instance_type, MaxCount=1, MinCount=1, TagSpecifications=[tag_config])
    
      instance_id = res['Instances'][0]['InstanceId']
    
      print('[INFO] 1 EC2 instance is successfully launched', instance_id)
    
      return { 'InstanceId' : instance_id }
      PowerShell
      Install-Module AWS.Tools.EC2 -Force
    Import-Module AWS.Tools.EC2
    
    $payload = $env:InputPayload | ConvertFrom-Json
    
    $imageid = $payload.image_id
    
    $tagvalue = $payload.tag_value
    
    $instanceType = $payload.instance_type
    
    $type = New-Object Amazon.EC2.InstanceType -ArgumentList $instanceType
    
    $resource = New-Object Amazon.EC2.ResourceType -ArgumentList 'instance'
    
    $tag = @{Key='Name';Value=$tagValue}
    
    $tagSpecs = New-Object Amazon.EC2.Model.TagSpecification
    
    $tagSpecs.ResourceType = $resource
    
    $tagSpecs.Tags.Add($tag)
    
    $res = New-EC2Instance -ImageId $imageId -MinCount 1 -MaxCount 1 -InstanceType $type -TagSpecification $tagSpecs
    
    return @{'InstanceId'=$res.Instances.InstanceId}

    8. Amplíe Additional inputs (Entradas adicionales).

    9. En Input name (Nombre de entrada), elija InputPayload. En Input Value (Valor de entrada), introduzca los siguientes datos YAML. 

      image_id: "{{ imageId }}"
    tag_value: "{{ tagValue }}"
    instance_type: "{{ instanceType }}"

  13. Expanda Outputs (Salidas) y realice lo siguiente:

    • En Nombre, escriba payload.

    • Para Selector, escriba $.Payload.

    • En Type (Tipo), elija StringMap.

  14. Seleccione Add step (Agregar paso) para agregar un segundo paso al manual de procedimientos. El segundo paso consulta el estado de la instancia iniciada en el paso 1 y espera hasta que el estado devuelto sea ok.

  15. En la sección Step 2 (Paso 2) haga lo siguiente.

    1. En Step name (Nombre del paso), ingrese este nombre descriptivo para el segundo paso de la automatización: WaitForInstanceStatusOk.

    2. En Action type (Tipo de acción), seleccione Run a script) (aws:executeScript).

    3. En Description (Descripción), escriba una descripción para el paso de automatización, como la siguiente.

      **About This Step**
    
    The script continuously polls the instance status check value for the instance launched in Step 1 until the ```ok``` status is returned.

    4. En Runtime (Entorno de ejecución), elija el lenguaje del entorno de ejecución que se va a usar para ejecutar el script proporcionado.

    5. En Handler (Controlador), escriba poll_instance. Este es el nombre de la función declarado en el siguiente script.

      nota

      Esto no es necesario para PowerShell.

    6. En Script, reemplace el contenido predeterminado por lo siguiente. Asegúrese de que el script coincide con el valor del entorno de ejecución.

      Python
      def poll_instance(events, context):
      import boto3
      import time
    
      ec2 = boto3.client('ec2')
    
      instance_id = events['InstanceId']
    
      print('[INFO] Waiting for instance status check to report ok', instance_id)
    
      instance_status = "null"
    
      while True:
        res = ec2.describe_instance_status(InstanceIds=[instance_id])
    
        if len(res['InstanceStatuses']) == 0:
          print("Instance status information is not available yet")
          time.sleep(5)
          continue
    
        instance_status = res['InstanceStatuses'][0]['InstanceStatus']['Status']
    
        print('[INFO] Polling to get status of the instance', instance_status)
    
        if instance_status == 'ok':
          break
    
        time.sleep(10)
    
      return {'Status': instance_status, 'InstanceId': instance_id}
      PowerShell
      
    Install-Module AWS.Tools.EC2 -Force
    
    $inputPayload = $env:InputPayload | ConvertFrom-Json
    
    $instanceId = $inputPayload.payload.InstanceId
    
    $status = Get-EC2InstanceStatus -InstanceId $instanceId
    
    while ($status.Status.Status -ne 'ok'){
       Write-Host 'Polling get status of the instance', $instanceId
    
       Start-Sleep -Seconds 5
    
       $status = Get-EC2InstanceStatus -InstanceId $instanceId
    }
    
    return @{Status = $status.Status.Status; InstanceId = $instanceId}

    7. Amplíe Additional inputs (Entradas adicionales).

    8. En Input name (Nombre de entrada), elija InputPayload. En Input value (Valor de entrada), introduzca lo siguiente:

      {{ LaunchEc2Instance.payload }}

  16. Elija Create automation (Crear automatización) para guardar el manual de procedimientos.