Usar pseudoparâmetros ao registrar tarefas da janela de manutenção

Ao registrar uma tarefa no Maintenance Windows, um recurso do AWS Systems Manager, é necessário especificar os parâmetros que são exclusivos para cada um dos quatro tipos de tarefa. (Nos comandos da CLI, eles são fornecidos usando a opção --task-invocation-parameters.)

Você também pode fazer referência a determinados valores usando sintaxe de pseudoparâmetro, como {{RESOURCE_ID}}, {{TARGET_TYPE}} e {{WINDOW_TARGET_ID}}. Quando a tarefa de janela de manutenção é executada, ela envia os valores corretos em vez dos espaços reservados do pseudoparâmetro. A lista completa de pseudoparâmetros que podem ser usados é mostrada mais adiante neste tópico em Pseudoparâmetros compatíveis.

Importante

Para o tipo de destino RESOURCE_GROUP, dependendo do formato de ID necessário para a tarefa, é possível escolher entre usar {{TARGET_ID}} e {{RESOURCE_ID}} para fazer referência ao recurso quando a tarefa for executada. {{TARGET_ID}} retorna o ARN completo do recurso. {{RESOURCE_ID}} retorna somente um nome mais curto ou o ID do recurso, conforme mostrado nestes exemplos.

• Formato {{TARGET_ID}}: arn:aws:ec2:us-east-1:123456789012:instance/i-02573cafcfEXAMPLE

• Formato {{RESOURCE_ID}}: i-02573cafcfEXAMPLE

Para o tipo de destino INSTANCE, os parâmetros {{TARGET_ID}} e {{RESOURCE_ID}} produzem somente o ID da instância. Para ter mais informações, consulte Pseudoparâmetros compatíveis.

{{TARGET_ID}} e {{RESOURCE_ID}} podem ser usados para passar os IDs dos recursos da AWS somente para o Automation, para o Lambda e para o Step Functions. Esses dois pseudoparâmetros não podem ser usados com as tarefas do Run Command.

Exemplos de pseudoparâmetros

Suponha que sua carga para uma tarefa do AWS Lambda precise fazer referência a uma instância por seu ID.

Se você estiver usando como destino uma janela de manutenção INSTANCE ou RESOURCE_GROUP, isso pode ser feito usando o pseudoparâmetro {{RESOURCE_ID}}. Por exemplo:

"TaskArn": "arn:aws:lambda:us-east-2:111122223333:function:SSMTestFunction",
    "TaskType": "LAMBDA",
    "TaskInvocationParameters": {
        "Lambda": {
            "ClientContext": "ew0KICAi--truncated--0KIEXAMPLE",
            "Payload": "{ \"instanceId\": \"{{RESOURCE_ID}}\" }",
            "Qualifier": "$LATEST"
        }
    }

Se a sua tarefa do Lambda tiver como objetivo ser executada em outro tipo de destino compatível, além de instâncias do Amazon Elastic Compute Cloud (Amazon EC2), como uma tabela do Amazon DynamoDB, a mesma sintaxe poderá ser usada e {{RESOURCE_ID}} produzirá somente o nome da tabela. No entanto, se você precisar do ARN completo da tabela, use {{TARGET_ID}}, conforme mostrado no exemplo a seguir.

"TaskArn": "arn:aws:lambda:us-east-2:111122223333:function:SSMTestFunction",
    "TaskType": "LAMBDA",
    "TaskInvocationParameters": {
        "Lambda": {
            "ClientContext": "ew0KICAi--truncated--0KIEXAMPLE",
            "Payload": "{ \"tableArn\": \"{{TARGET_ID}}\" }",
            "Qualifier": "$LATEST"
        }
    }

A mesma sintaxe funciona para instâncias de destino ou outros tipos de recursos. Quando vários tipos de recursos forem adicionados a um grupo de recursos, a tarefa será executada em cada um dos recursos apropriados.

Importante

Nem todos os tipos de recursos que podem ser incluídos em um grupo de recursos geram um valor para o parâmetro {{RESOURCE_ID}}. Para obter uma lista de tipos de recursos com suporte, consulte Pseudoparâmetros compatíveis.

Como outro exemplo, para executar uma tarefa do Automation que interrompa suas instâncias do EC2, especifique o documento do Systems Manager AWS-StopEC2Instance (documento SSM) como o valor TaskArn e use o pseudoparâmetro {{RESOURCE_ID}}:

"TaskArn": "AWS-StopEC2Instance",
    "TaskType": "AUTOMATION"
    "TaskInvocationParameters": {
        "Automation": {
            "DocumentVersion": "1",
            "Parameters": {
                "instanceId": [
                    "{{RESOURCE_ID}}"
                ]
            }
        }
    }

Para executar uma tarefa do Automation que copia um snapshot de um volume do Amazon Elastic Block Store (Amazon EBS), especifique o documento do SSM AWS-CopySnapshot como o valor de TaskArn e use o pseudoparâmetro {{RESOURCE_ID}}.

"TaskArn": "AWS-CopySnapshot",
    "TaskType": "AUTOMATION"
    "TaskInvocationParameters": {
        "Automation": {
            "DocumentVersion": "1",
            "Parameters": {
                "SourceRegion": "us-east-2",
                "targetType":"RESOURCE_GROUP",
                "SnapshotId": [
                    "{{RESOURCE_ID}}"
                ]
            }
        }
    }

Pseudoparâmetros compatíveis

A lista a seguir descreve os pseudoparâmetros que podem ser especificados usando a sintaxe {{PSEUDO_PARAMETER}} na opção --task-invocation-parameters.

• WINDOW_ID: o ID da janela de manutenção do destino.

• WINDOW_TASK_ID: o ID da tarefa da janela que está em execução.

• WINDOW_TARGET_ID: o ID do destino de janela que inclui o destino (ID de destino).

• WINDOW_EXECUTION_ID: o ID da execução de janela atual.

• TASK_EXECUTION_ID: o ID da execução de tarefa atual.

• INVOCATION_ID: o ID da invocação atual.

• TARGET_TYPE: o tipo de destino. Os tipos com suporte incluem RESOURCE_GROUP e INSTANCE.

• TARGET_ID:

  Se o tipo de destino especificado for INSTANCE, o pseudoparâmetro TARGET_ID será substituído pelo ID da instância. Por exemplo, i-078a280217EXAMPLE.

  Se o tipo de destino especificado for RESOURCE_GROUP, o valor referenciado para a execução da tarefa será o ARN completo do recurso. Por exemplo: arn:aws:ec2:us-east-1:123456789012:instance/i-078a280217EXAMPLE. A tabela a seguir fornece valores de exemplo de TARGET_ID para tipos de recursos específicos em um grupo de recursos.

  nota

  TARGET_ID não tem suporte para tarefas do Run Command.

  Tipo de recurso	Exemplo de TARGET_ID
  AWS::CloudWatch::Alarm	arn:aws:cloudwatch:us-east-1:123456789012:alarm:MyCloudWatchAlarmi-078a280217EXAMPLE
  AWS::EC2::Instance	arn:aws:ec2:us-east-1:123456789012:instance/i-078a280217EXAMPLE
  AWS::EC2::Image	arn:aws:ec2:us-east-1:123456789012:image/ami-02250b3732EXAMPLE
  AWS::EC2::SecurityGroup	arn:aws:ec2:us-east-1:123456789012:security-group/sg-cEXAMPLE
  AWS::EC2::Snapshot	arn:aws:ec2:us-east-1:123456789012:snapshot/snap-03866bf003EXAMPLE
  AWS::EC2::Volume	arn:aws:ec2:us-east-1:123456789012:volume/vol-0912e04d78EXAMPLE
  AWS::DynamoDB::Table	arn:aws:dynamodb:us-east-1:123456789012:table/MyTable
  AWS::RDS::DBCluster	arn:aws:rds:us-east-2:123456789012:cluster:My-Cluster
  AWS::RDS::DBInstance	arn:aws:rds:us-east-1:123456789012:db:My-SQL-Instance
  AWS::S3::Bucket	arn:aws:s3::: DOC-EXAMPLE-BUCKET
  AWS::SSM::ManagedInstance	arn:aws:ssm:us-east-1:123456789012:managed-instance/mi-0feadcf2d9EXAMPLE

• RESOURCE_ID: o ID curto de um tipo de recurso contido em um grupo de recursos. A tabela a seguir fornece valores de exemplo de RESOURCE_ID para tipos de recursos específicos em um grupo de recursos.

  nota

  RESOURCE_ID não tem suporte para tarefas do Run Command.

  Tipo de recurso	Exemplo de RESOURCE_ID
  AWS::CloudWatch::Alarm	MyCloudWatchAlarm
  AWS::EC2::Instance	i-078a280217EXAMPLE
  AWS::EC2::Image	ami-02250b3732EXAMPLE
  AWS::EC2::SecurityGroup	sg-cEXAMPLE
  AWS::EC2::Snapshot	snap-03866bf003EXAMPLE
  AWS::EC2::Volume	vol-0912e04d78EXAMPLE
  AWS::DynamoDB::Table	MyTable
  AWS::RDS::DBCluster	My-Cluster
  AWS::RDS::DBInstance	My-SQL-Instance
  AWS::S3::Bucket	DOC-EXAMPLE-BUCKET
  AWS::SSM::ManagedInstance	mi-0feadcf2d9EXAMPLE

  nota

  Se o grupo de recursos da AWS especificado incluir tipos de recursos que não produzem um valor de RESOURCE_ID e que não estiverem listados na tabela acima, o parâmetro RESOURCE_ID não será preenchido. Uma invocação de execução ainda ocorrerá para esse recurso. Nesses casos, use o pseudoparâmetro TARGET_ID no lugar, que será substituído pelo ARN completo do recurso.