• O AWS Systems Manager CloudWatch Dashboard não estará mais disponível a partir de 30 de abril de 2026. Os clientes podem continuar usando o console do Amazon CloudWatch para visualizar, criar e gerenciar os painéis do Amazon CloudWatch exatamente como fazem hoje. Para obter mais informações, consulte a [documentação do Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html).
# Ferramentas de gerenciamento de alterações do AWS Systems Manager
O AWS Systems Manager fornece as ferramentas a seguir para fazer alterações em seus recursos da AWS.
**Topics**
+ [AWS Systems Manager Automation](systems-manager-automation.md)
+ [AWS Systems Manager Change Calendar](systems-manager-change-calendar.md)
+ [AWS Systems Manager Change Manager](change-manager.md)
+ [Documentos do AWS Systems Manager](documents.md)
+ [AWS Systems Manager Maintenance Windows](maintenance-windows.md)
+ [AWS Systems Manager Quick Setup](systems-manager-quick-setup.md)
# AWS Systems Manager Automation
O Automation, uma ferramenta do AWS Systems Manager, simplifica as tarefas comuns de manutenção, implantação e correção para Serviços da AWS como o Amazon Elastic Compute Cloud (Amazon EC2), o Amazon Relational Database Service (Amazon RDS), o Amazon Redshift, o Amazon Simple Storage Service (Amazon S3) e muitos outros. Para começar a usar o Automation, abra o [Systems Manager console (Console do gerenciador de sistemas).](https://console.aws.amazon.com/systems-manager/automation) No painel de navegação à esquerda, escolha **Automation**.
O Automation ajuda você a criar soluções automatizadas para implantar, configurar e gerenciar recursos da AWS em escala. Com o Automation, você tem controle granular sobre a simultaneidade de suas automações. Isso significa que você pode especificar quantos recursos a destinar simultaneamente e quantos erros podem ocorrer antes que uma automação seja interrompida.
Para ajudar você a começar a usar o Automation, a AWS desenvolve e mantém vários runbooks predefinidos. Dependendo do seu caso de uso, você pode usar esses runbooks predefinidos que executam uma variedade de tarefas ou criar seus próprios runbooks personalizados que possam atender melhor às suas necessidades. Para monitorar o progresso e o status de suas automações, você pode usar o console do Automation do Systems Manager ou sua ferramenta da linha de comando preferida. O Automation também se integra ao Amazon EventBridge para ajudar você a criar arquitetura orientada a eventos em escala.
**nota**
Para clientes que são novos no Systems Manager Automation a partir de 14 de agosto de 2025, o nível gratuito de automação não está disponível. Para clientes que já usam o Systems Manager Automation, o nível gratuito de serviço termina em 31 de dezembro de 2025. Para obter mais informações sobre os custos dos serviços, consulte [preços do AWS Systems Manager](https://aws.amazon.com/systems-manager/pricing/).
## Como o Automation beneficia minha organização?
O Automation oferece os seguintes benefícios:
+ **Suporte a scripts no conteúdo do runbook**
Com o uso da ação `aws:executeScript`, você pode executar funções de Python e PowerShell personalizadas diretamente de seus runbooks. Isso oferece maior flexibilidade na criação de runbooks personalizados, pois você pode concluir várias tarefas que outras ações do Automation não suportam. Você também tem maior controle sobre a lógica do runbook. Para obter um exemplo de como essa ação pode ser usada e como ela pode ajudar a melhorar uma solução automatizada existente, consulte [Criar runbooks do Automation](automation-authoring-runbooks.md).
+ **Execute automações em várias Contas da AWS e Regiões da AWS a partir de um local centralizado**
Os administradores podem executar automações em recursos em várias contas e regiões a partir do console do Systems Manager.
+ **Melhoria das operações de segurança**
Os administradores têm um lugar centralizado para conceder e revogar o acesso a runbooks. Usando somente políticas do AWS Identity and Access Management (IAM), você pode controlar quais usuários individuais ou grupos na sua organização podem usar o Automation e quais nós gerenciados eles podem acessar.
+ **Automatize tarefas comuns de TI**
A automatização de tarefas comuns pode ajudar a melhorar a eficiência operacional, impor padrões organizacionais e reduzir erros do operador. Por exemplo, você pode usar o runbook `AWS-UpdateCloudFormationStackWithApproval` para atualizar os recursos que foram implantados usando um modelo AWS CloudFormation. A atualização aplica-se a um novo modelo. Você pode configurar a Automação para solicitar aprovação de um ou mais usuários do antes de a atualização começar.
+ **Execução segura e em massa de tarefas problemáticas**
O Automation inclui recursos, como controles de taxa, que permitem controlar a implantação de uma automação em toda a frota, especificando um valor de simultaneidade e um limiar de erro. Para obter mais informações sobre como trabalhar com controles de taxas, consulte [Executar operações automatizadas em escala](running-automations-scale.md).
+ **Simplificação de tarefas complexas**
O Automation fornece runbooks predefinidos que simplificam tarefas complexas e demoradas, como a criação de Amazon Machine Images de ouro (AMIs). Use os runbooks `AWS-UpdateLinuxAmi` e `AWS-UpdateWindowsAmi` para criar AMIs de ouro a partir de uma AMI de origem. Com o us desses runbooks, você pode executar scripts personalizados antes e depois que as atualizações são aplicadas. Você pode também incluir ou excluir pacotes de software específicos com relação à instalação. Para obter exemplos de como usar esses runbooks, consulte [Tutoriais](automation-tutorials.md).
+ **Definição das limitações para entradas**
Você pode definir restrições em runbooks personalizados para limitar os valores que o Automation aceitará para um parâmetro de entrada específico. Por exemplo, `allowedPattern` só aceitará valores para um parâmetro de entrada que corresponda à expressão regular que você definir. Se você especificar `allowedValues` para um parâmetro de entrada, somente os valores especificados no runbook são aceitos.
+ **Registre a saída das ações de automação no Amazon CloudWatch Logs**
Para satisfazer os requisitos de segurança ou operacionais em sua organização, pode ser necessário fornecer um registro dos scripts executados durante um runbook. Com o CloudWatch Logs, é possível monitorar, armazenar e acessar os arquivos de log de vários Serviços da AWS. Você pode enviar a saída da ação `aws:executeScript` para um grupo de logs do CloudWatch Logs para fins de depuração e solução de problemas. Os dados de log podem ser enviados ao seu grupo de logs com ou sem criptografia do AWS KMS usando sua chave do KMS. Para obter mais informações, consulte [Registro de saída de ações do Automation em log com o CloudWatch Logs](automation-action-logging.md).
+ **Integração com o Amazon EventBridge**
Há suporte para o Automation como um tipo *destino* nas regras do Amazon EventBridge. Isso significa que você pode acionar runbooks usando eventos. Para obter mais informações, consulte [Monitorar eventos do Systems Manager com o Amazon EventBridge](monitoring-eventbridge-events.md) e [Referência: padrões e tipos de eventos do Amazon EventBridge para o Systems Manager](reference-eventbridge-events.md).
+ **Compartilhe práticas recomendadas organizacionais**
Você pode definir práticas recomendadas para gerenciamento de recursos, tarefas de operações e muito mais em runbooks compartilhados entre contas e regiões.
## Quem deve usar o Automation?
+ Qualquer cliente da AWS que deseje melhorar sua eficiência operacional em escala, reduzir erros associados à intervenção manual e reduzir o tempo de resolução de problemas comuns.
+ Especialistas em infraestrutura que desejem automatizar tarefas de implantação e configuração.
+ Administradores que desejem resolver problemas comuns de forma confiável, melhorar a eficiência da solução de problemas e reduzir operações repetitivas.
+ Usuários que desejarem automatizar uma tarefa que normalmente executam manualmente.
## O que é uma automação?
Uma *automação* consiste em todas as tarefas que são definidas em um runbook e são executadas pelo serviço Automation. O Automation usa os seguintes componentes para executar automações.
****
| Conceito | Detalhes |
| --- | --- |
| Runbook do Automation | Um runbook do Systems Manager Automation define a automação (as ações que o Systems Manager realiza em nós gerenciados e nos recursos da AWS). O Automation inclui vários runbooks predefinidos que você pode usar para executar tarefas comuns, como reiniciar uma ou mais instâncias do Amazon EC2 ou criar uma Amazon Machine Image (AMI). Você também pode criar seus próprios runbooks. Os runbooks usam YAML ou JSON e incluem etapas e parâmetros especificados por você. As etapas são executadas em ordem sequencial. Para obter mais informações, consulte [Criação dos seus próprios runbooks](automation-documents.md). Runbooks são documentos do Systems Manager do tipo `Automation`, ao contrário dos documentos `Command`, `Policy` e `Session`. Runbooks oferecem suporte para o esquema versão 0.3. Documentos de comando usam a versão de esquema 1.2, 2.0 ou 2.2. Documentos de política usam a versão de esquema 2.0 ou posterior. |
| Ação de automação | A automação definida em um runbook inclui uma ou mais etapas. Cada etapa está associada a uma ação específica. A ação determina as entradas, o comportamento e as saídas da etapa. As etapas são definidas na seção `mainSteps` do seu runbook. A automação oferece suporte a 20 tipos de ação distintos. Para mais informações, consulte [Referência de ações do Systems Manager Automation](automation-actions.md). |
| Cota de automação | Cada Conta da AWS pode executar 100 automações simultaneamente. Isso inclui automações filho (automações que são iniciadas por outra automação) e automações de controle de taxa. Se você tentar executar mais do que isso, o Systems Manager adicionará as outras automações em uma fila e exibirá o status Pending (Pendente). Essa cota pode ser ajustada usando a simultaneidade adaptativa. Para obter mais informações, consulte [Permitir que o Automation se adapte às suas necessidades de simultaneidade](adaptive-concurrency.md). Para obter mais informações sobre como executar automações, consulte [Executar uma operação automatizada com tecnologia do Systems Manager Automation](running-simple-automations.md). |
| Cota de filas da automação | Se você tentar executar mais automações do que o limite de automação simultânea, as automações subsequentes serão adicionadas a uma fila. Cada Conta da AWS pode colocar 5.000 automações na fila. Quando uma automação for concluída (ou atingir um estado terminal), a primeira automação na fila será iniciada. |
| Cota da automação do controle de taxas | Cada Conta da AWS pode executar 25 automações de controle de taxas simultaneamente. Se você tentar executar mais automações de controle de taxas do que o limite de automação de controle de taxa simultânea, o Systems Manager adiciona as automações de controle subsequentes a uma fila e exibe o status Pending (Pendente). Para obter mais informações sobre como executar automações de controle de taxas, consulte [Executar operações automatizadas em escala](running-automations-scale.md). |
| Cota da fila de automação do controle de taxas | Se você tentar executar mais automações do que o limite de automação de controle de taxa simultânea, as automações subsequentes serão adicionadas a uma fila. Cada Conta da AWS pode colocar 1.000 automações na fila. Quando uma automação for concluída (ou atingir um estado terminal), a primeira automação na fila será iniciada. |
**Topics**
+ [Como o Automation beneficia minha organização?](#automation-benefits)
+ [Quem deve usar o Automation?](#automation-who)
+ [O que é uma automação?](#what-is-an-automation)
+ [Configurar a automação](automation-setup.md)
+ [Executar uma operação automatizada com tecnologia do Systems Manager Automation](running-simple-automations.md)
+ [Executar novamente as execuções de automação](automation-rerun-executions.md)
+ [Executar uma automação que exija aprovações](running-automations-require-approvals.md)
+ [Executar operações automatizadas em escala](running-automations-scale.md)
+ [Executar automações em várias regiões e contas da Regiões da AWS](running-automations-multiple-accounts-regions.md)
+ [Executar automações com base em eventos do EventBridge](running-automations-event-bridge.md)
+ [Executar uma automação passo a passo](automation-working-executing-manually.md)
+ [Programação de automações com associações do State Manager](scheduling-automations-state-manager-associations.md)
+ [Agendar automações com janelas de manutenção](scheduling-automations-maintenance-windows.md)
+ [Referência de ações do Systems Manager Automation](automation-actions.md)
+ [Criação dos seus próprios runbooks](automation-documents.md)
+ [Referência de runbooks do Systems Manager Automation](automation-documents-reference.md)
+ [Tutoriais](automation-tutorials.md)
+ [Saiba mais sobre os status retornados pelo Systems Manager Automation](automation-statuses.md)
+ [Solução de problemas do Systems Manager Automation](automation-troubleshooting.md)
# Configurar a automação
Para configurar o Automation, uma ferramenta do AWS Systems Manager, é necessário verificar o acesso do usuário ao serviço do Automation e configurar os perfis de forma que o serviço possa executar ações nos recursos. Também recomendamos que você opte pelo modo de simultaneidade adaptativo em suas preferências do Automation. A simultaneidade adaptativa dimensiona automaticamente sua cota de automação para atender às suas necessidades. Para obter mais informações, consulte [Permitir que o Automation se adapte às suas necessidades de simultaneidade](adaptive-concurrency.md).
Para garantir o acesso adequado ao Automation AWS Systems Manager, revise os seguintes requisitos de função de serviço e usuário.
## Verificar o acesso do usuário aos runbooks
Verifique se você tem permissão para usar runbooks. Se seu usuário, grupo ou perfil tiver permissões de administrador atribuídas, você terá acesso ao Systems Manager Automation. Se você não tiver permissões de administrador, um administrador deverá conceder as permissões ao atribuir a política gerenciada `AmazonSSMFullAccess` ou uma política que forneça permissões comparáveis ao seu usuário, grupo ou perfil.
**Importante**
A política do IAM `AmazonSSMFullAccess` concede permissões para ações do Systems Manager. No entanto, alguns runbooks exigem permissões para outros serviços, como o documento `AWS-ReleaseElasticIP`, que requer permissões do IAM para o `ec2:ReleaseAddress`. Portanto, é necessário analisar as ações executadas em um runbook para garantir que seu usuário, grupo ou perfil tenha as permissões necessárias atribuídas para executar as ações inclusas no runbook.
## Configurar o acesso a uma função de serviço (função assumida) para automações
As automações podem ser iniciadas no contexto de uma função de serviço (ou *função assumida*). Isso permite que o serviço execute ações em seu nome. Se você não especificar uma função a ser assumida, o Automation usará o contexto do usuário que invocou a execução.
No entanto, as seguintes situações ainda exigem que você especifique uma função de serviço para o Automation:
+ Quando você quer restringir as permissões de um usuário em um recurso, mas deseja que esse usuário execute uma automação que exija privilégios elevados. Nesse cenário, você poderá criar uma função de serviço com permissões elevadas e permitir que o usuário execute a automação.
+ Quando você cria uma associação do Systems Manager State Manager que executa um runbook.
+ Ao ter operações que espera executar por mais de 12 horas.
+ Quando você estiver executando um runbook que não pertence à Amazon, e que usa a ação `aws:executeScript` para chamar uma operação de API da AWS ou para agir em um recurso da AWS. Para obter mais informações, consulte [Permissões para usar runbooks](automation-document-script-considerations.md#script-permissions).
Se você precisar criar uma função de serviço para o Automation, poderá usar um dos métodos a seguir.
**Topics**
+ [Verificar o acesso do usuário aos runbooks](#automation-setup-user-access)
+ [Configurar o acesso a uma função de serviço (função assumida) para automações](#automation-setup-configure-role)
+ [Criar perfis de serviço do Automation usando o CloudFormation](automation-setup-cloudformation.md)
+ [Criar perfis de serviço para o Automation usando o console](automation-setup-iam.md)
+ [Exemplos de configuração de políticas baseadas em identidade](automation-setup-identity-based-policies.md)
+ [Permitir que o Automation se adapte às suas necessidades de simultaneidade](adaptive-concurrency.md)
+ [Configurar a repetição automática para operações com controle de utilização](automation-throttling-retry.md)
+ [Implementação de controles de alteração para o Automation](automation-change-calendar-integration.md)
# Criar perfis de serviço do Automation usando o CloudFormation
É possível criar um perfil de serviço para o Automation, uma ferramenta do AWS Systems Manager, com base em um modelo do AWS CloudFormation. Depois de criar a função de serviço, você poderá especificar a função do serviço nos runbooks, usando o parâmetro `AutomationAssumeRole`.
## Criar a função de serviço com o CloudFormation
Use o procedimento a seguir para criar as funções do AWS Identity and Access Management (IAM) necessárias para o Systems Manager Automation, usando o CloudFormation.
**Para criar as funções do IAM necessárias**
1. Baixe e descompacte o arquivo [https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWS-SystemsManager-AutomationServiceRole.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWS-SystemsManager-AutomationServiceRole.zip). Este arquivo inclui o arquivo de modelo do `AWS-SystemsManager-AutomationServiceRole.yaml` CloudFormation.
1. Abra o console do CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Selecione **Create Stack** (Criar pilha).
1. Na seção **Specify template** (Especificar modelo) escolha **Upload a template file** (Fazer upload de um arquivo de modelo).
1. Escolha **Browse (Procurar)** e, depois, escolha o arquivo de modelo `AWS-SystemsManager-AutomationServiceRole.yaml` do CloudFormation.
1. Escolha **Próximo**.
1. Na página **Specify stack details (Especificar detalhes da tarefa)**, no campo **Stack name (Nome da pilha)**, insira um nome.
1. Na página **Configure stack options (Configurar opções de pilha)** não é necessário fazer nenhuma seleção. Escolha **Próximo**.
1. Na página **Review**, role para baixo e escolha a opção **I acknowledge that CloudFormation might create IAM resources**.
1. Escolha **Criar**.
O CloudFormation mostra o status **CREATE\$1IN\$1PROGRESS** por cerca de três minutos. O status mudará para **CREATE\$1COMPLETE** depois que a pilha for criada e suas funções estiverem prontas para uso.
**Importante**
Se você executar um fluxo de trabalho de automação que chama outros serviços usando uma função de serviço do AWS Identity and Access Management (IAM), esteja ciente de que esta função deve ser configurada com permissão para chamar esses serviços. Esse requisito aplica-se a todos os runbooks do Automation da AWS (runbooks da `AWS-*`), como os runbooks `AWS-ConfigureS3BucketLogging`, `AWS-CreateDynamoDBBackup` e `AWS-RestartEC2Instance`, entre outros. Esse requisito também se aplica a todos os runbooks personalizados do Automation criados que invoquem outros Serviços da AWS, usando ações que chamam outros serviços. Por exemplo, se você usar as ações `aws:executeAwsApi`, `aws:createStack` ou `aws:copyImage`, configure a função de serviço com permissão para invocar esses serviços. É possível habilitar permissões para outros Serviços da AWS, adicionando uma política em linha do IAM à função. Para obter mais informações, consulte [(Opcional) Adicione uma política em linha ou uma política gerenciada pelo cliente para invocar outros Serviços da AWS](automation-setup-iam.md#add-inline-policy).
## Copiar informações de função para a automação
Use o procedimento a seguir para copiar as informações sobre a função de serviço de Automação por meio do console do CloudFormation. É necessário especificar essas funções ao usar um runbook.
**nota**
Você não precisará copiar as informações da função usando esse procedimento, se executar os runbooks `AWS-UpdateLinuxAmi` ou `AWS-UpdateWindowsAmi`. Esses runbooks já possuem as funções necessárias especificadas como valores padrão. As funções especificadas nesses runbooks usam as políticas gerenciadas do IAM.
**Para copiar nomes de funções**
1. Abra o console do CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Selecione o **Stack name (Nome da pilha)** do Automation que você criou no procedimento anterior.
1. Escolha a guia **Resources** (Recursos).
1. Escolha o link **Physical ID** para **AutomationServiceRole**. O console do IAM é aberto em um resumo da função de serviço do Automation.
1. Copie o nome do recurso da Amazon (ARN) ao lado de **Role ARN (ARN da função)**. O ARN é semelhante ao seguinte: `arn:aws:iam::12345678:role/AutomationServiceRole`
1. Cole o ARN em um arquivo de texto para uso posterior.
Você concluiu a configuração da função de serviço para Automação. Agora você pode usar o ARN da função de serviço do Automation em seus runbooks.
# Criar perfis de serviço para o Automation usando o console
Se você precisar criar um perfil de serviço para o Automation, uma ferramenta do AWS Systems Manager, conclua as tarefas a seguir. Para obter mais informações sobre quando uma função de serviço é necessária para o Automation, consulte [Configurar a automação](automation-setup.md).
**Topics**
+ [Tarefa 1: Criar uma função de serviço para a automação](#create-service-role)
+ [Tarefa 2: Anexar a política iam:PassRole à função de automação](#attach-passrole-policy)
## Tarefa 1: Criar uma função de serviço para a automação
Use o procedimento a seguir para criar uma função de serviço (ou *função assumida*) para o Systems Manager Automation.
**nota**
Você também pode usar essa função em runbooks, como no runbook `AWS-CreateManagedLinuxInstance`. O uso dessa função ou do nome do recurso da Amazon (ARN) de uma função do AWS Identity and Access Management (IAM) em runbooks permite que o Automation realize ações no seu ambiente, como iniciar novas instâncias e executar ações em seu nome.
**Para criar uma função do IAM e permitir que ela seja assumida pelo Automation**
1. Abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. No painel de navegação, escolha **Roles** e **Create role**.
1. Em **Select type of trusted entity (Selecionar o tipo de entidade confiável)**, escolha **AWS service (serviço)**.
1. Na seção **Selecionar um caso de uso**, selecione **Systems Manager** e **Próximo: permissões**.
1. Na página **Attached permissions policy**, procure a política **AmazonSSMAutomationRole**, escolha essa política e, em seguida, escolha **Next: Review**.
1. Na página **Review** (Análise), digite um nome na caixa **Role name** (Nome da função) e, em seguida, uma descrição.
1. Selecione **Create role** (Criar função). O sistema faz com que você retorne para a página **Roles**.
1. Na página **Roles** (Funções), escolha a função que você acabou de criar para abrir a página **Summary** (Resumo). Anote os valores de **Role Name (Nome da função)** e **Role ARN (ARN da função)**. Você especificará o ARN da função ao associar a política **iam:PassRole** à sua conta do IAM no próximo procedimento. Você também pode especificar o nome da função e o ARN nos runbooks.
**nota**
A política `AmazonSSMAutomationRole` atribui a permissão de função do Automation a um subconjunto de funções do AWS Lambda na sua conta. Essas funções começam com "Automation". Se você planeja usar o Automation com funções Lambda, o ARN Lambda deverá usar o seguinte formato:
`"arn:aws:lambda:*:*:function:Automation*"`
Se você tiver funções Lambda cujos ARNs não usam esse formato, também precisará anexar uma política Lambda adicional à sua função de automação, como a política **AWSLambdaRole**. A política ou função adicional deve fornecer acesso mais amplo às funções Lambda na Conta da AWS.
Depois de criar sua função de serviço, recomendamos editar a política de confiança para ajudar a evitar o problema entre serviços confused deputy. O *problema confused deputy* é um problema de segurança em que uma entidade que não tem permissão para executar uma ação pode coagir uma entidade mais privilegiada a executá-la. Na AWS, a personificação entre serviços pode resultar no problema do ‘confused deputy’. A personificação entre serviços pode ocorrer quando um serviço (o *serviço de chamada*) chama outro serviço (o *serviço chamado*). O serviço de chamada pode ser manipulado de modo a usar suas permissões para atuar nos recursos de outro cliente de uma forma na qual ele não deveria ter permissão para acessar. Para evitar isso, o AWS fornece ferramentas que ajudam você a proteger seus dados para todos os serviços com entidades principais de serviço que receberam acesso aos recursos em sua conta.
Recomendamos o uso das chaves de contexto de condição global [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) e [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount) em políticas de recursos para limitar as permissões que o Automation concede a outro serviço para o recurso. Se o valor `aws:SourceArn` não contiver o ID da conta, como um ARN de bucket do Amazon S3, você deve usar ambas as chaves de contexto de condição global para limitar as permissões. Se você utilizar ambas as chaves de contexto de condição global, e o valor `aws:SourceArn` contiver o ID da conta, o valor `aws:SourceAccount` e a conta no valor `aws:SourceArn` deverão utilizar o mesmo ID de conta quando utilizados na mesma declaração da política. Use `aws:SourceArn` se quiser apenas um recurso associado a acessibilidade de serviço. Use `aws:SourceAccount` se quiser permitir que qualquer recurso nessa conta seja associado ao uso entre serviços. O valor de `aws:SourceArn` deve ser o ARN para execuções de automação. Se você não souber o ARN completo do recurso ou se estiver especificando vários recursos, use a chave da condição de contexto global `aws:SourceArn` com curingas (`*`) para as partes desconhecidas do ARN. Por exemplo, `arn:aws:ssm:*:123456789012:automation-execution/*`.
O exemplo a seguir mostra como é possível usar as chaves de contexto de condição global `aws:SourceArn` e `aws:SourceAccount` para o Automation, a fim de evitar o problema confused deputy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"ssm.amazonaws.com"
]
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:ssm:*:123456789012:automation-execution/*"
}
}
}
]
}
```
------
**Para modificar a política de confiança da função**
1. Abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. No painel de navegação, selecione **Roles** (Funções).
1. Na lista de funções em sua conta, escolha o nome da função do serviço do Automation.
1. Escolha a guia **Trust relationships (Relacionamentos de confiança)** e, em seguida, selecione **Edit trust relationship (Editar relacionamento de confiança)**.
1. Edite a política de confiança usando as chaves de contexto de condição global `aws:SourceArn` e `aws:SourceAccount` para o Automation, a fim de evitar o problema confused deputy.
1. Para salvar a alteração, escolha **Update Trust Policy** (Atualizar política de confiança).
### (Opcional) Adicione uma política em linha ou uma política gerenciada pelo cliente para invocar outros Serviços da AWS
Se você executar uma automação que invoca outros Serviços da AWS usando uma função de serviço do IAM, essa última deverá ser configurada com permissão para invocar esses serviços. Esse requisito aplica-se a todos os runbooks do Automation da AWS (runbooks da `AWS-*`), como os runbooks `AWS-ConfigureS3BucketLogging`, `AWS-CreateDynamoDBBackup` e `AWS-RestartEC2Instance`, entre outros. Esse requisito também se aplica a todos os runbooks personalizados criados que invoquem outros Serviços da AWS, usando ações que chamam outros serviços. Por exemplo, se você usar as ações `aws:executeAwsApi`, `aws:CreateStack` ou `aws:copyImage`, entre outras, deverá configurar a função de serviço com permissão para chamar esses serviços. É possível habilitar permissões para outros Serviços da AWS, adicionando uma política em linha do IAM ou uma política gerenciada pelo cliente ao perfil.
**Para incorporar uma política em linha para uma função de serviço (console do IAM)**
1. Faça login no Console de gerenciamento da AWS e abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. No painel de navegação, escolha **Perfis**.
1. Na lista, selecione o nome da função que você deseja editar.
1. Escolha a aba **Permissões**.
1. Na seção **Adicionar permissões**, selecione **Anexar políticas** ou **Criar política em linha**.
1. Ao escolher **Anexar políticas**, marque a caixa de seleção ao lado da política que deseja adicionar e escolha **Adicionar permissões**.
1. Se você escolher **Criar política em linha**, escolha a guia **JSON**.
1. Insira um documento de política JSON para os Serviços da AWS que você deseja chamar. Veja a seguir dois exemplos de documentos da política JSON.
**Exemplo do PutObject e GetObject do Amazon S**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
}
]
}
```
------
**Exemplos CreateSnapshot e DescribeSnapShots do Amazon EC**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshot",
"Resource":"*"
},
{
"Effect":"Allow",
"Action":"ec2:DescribeSnapshots",
"Resource":"*"
}
]
}
```
------
Para obter detalhes sobre a linguagem da política do IAM, consulte a [Referência da política JSON do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) no *Manual do usuário do IAM*.
1. Ao concluir, selecione **Review policy (Revisar política)**. O [Validador de política](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_policy-validator.html) indica se há qualquer erro de sintaxe.
1. Na página **Review policy** (Revisar política), insira um nome em **Name** para a política que você está criando. Revise o **Resumo** da política para ver as permissões que são concedidas pela política. Em seguida, escolha **Criar política** para salvar seu trabalho.
1. Após a criação de uma política em linha, ela é automaticamente incorporada à sua função.
## Tarefa 2: Anexar a política iam:PassRole à função de automação
Use o procedimento a seguir para associar a política `iam:PassRole` à sua função de serviço de Automação. Isso permite que o serviço do Automation passe o perfil a outros serviços ou ferramentas do Systems Manager ao executar as automações.
**Para anexar a política iam:PassRole à sua função de Automação**
1. Na página **Summary** da função que você acabou de criar, escolha a guia **Permissions** (Permissões).
1. Escolha **Add inline policy** (Adicionar política em linha).
1. Na página **Create policy** (Criar política), selecione a guia **Visual editor** (Editor visual).
1. Selecione **Service** (Serviço) e, em seguida, selecione **IAM**.
1. Selecione **Select actions** (Selecionar ações).
1. Na caixa de texto **Filter actions (Filtrar ações)**, digite **PassRole** e selecione a opção **PassRole**.
1. Escolha **atributos**. Verifique se **Specific** (Específico) está selecionado e, em seguida, selecione **Add ARN** (Adicionar ARN).
1. No campo **Specify ARN for role** (Especificar ARN para função) cole o ARN da função de Automação que você copiou no final da Tarefa 1. O sistema preenche os campos **Account (Conta)** e **Role name with path (Nome da função com caminho)**.
**nota**
Se você quiser que a função de serviço do Automation associe uma função de perfil da instância do IAM a uma instância do EC2, você deverá adicionar o ARN da função de perfil da instância do IAM. Isso permite que a função de serviço do Automation passe a função do perfil da instância do IAM para a instância de destino do EC2.
1. Escolha **Add** (Adicionar).
1. Escolha **Review policy** (Revisar política).
1. Na página **Review Policy** (Revisar política), digite um nome e, em seguida, selecione **Create Policy** (Criar política).
# Exemplos de configuração de políticas baseadas em identidade
As seções a seguir fornecem exemplos de políticas baseadas em identidade do IAM para o serviço de Automação do AWS Systems Manager. Para obter mais informações sobre como criar uma política baseada em identidade do IAM usando esses documentos de política JSON de exemplo, consulte [Criar políticas do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-json-editor), no *Guia do usuário do IAM*.
**nota**
Todos os exemplos contêm IDs de contas fictícias. A ID da conta não deve ser especificada no nome do recurso da Amazon (ARN) para documentos públicos de propriedade da AWS.
**Exemplos**
+ [Exemplo 1: Permitir que um usuário execute um documento de automação e visualize a execução da automação](#automation-setup-identity-based-policies-example-1)
+ [Exemplo 2: Permitir que um usuário execute uma versão específica de um documento de automação](#automation-setup-identity-based-policies-example-2)
+ [Exemplo 3: Permitir que um usuário execute documentos de automação com uma tag específica](#automation-setup-identity-based-policies-example-3)
+ [Exemplo 4: Permitir que um usuário execute um documento de automação quando uma tag específica for fornecida para a execução da automação](#automation-setup-identity-based-policies-example-4)
## Exemplo 1: Permitir que um usuário execute um documento de automação e visualize a execução da automação
A seguinte política do IAM de exemplo permite que um usuário faça o seguinte:
+ Execute o documento de automação especificado na política. O nome do documento é determinado pela entrada a seguir.
```
arn:aws:ssm:*:111122223333:document/{{DocumentName}}
```
+ Interrompa e envie sinais para uma execução de automação.
+ Veja detalhes sobre a execução da automação após ela ter sido iniciada.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "ssm:StartAutomationExecution",
"Effect": "Allow",
"Resource": [
"arn:aws:ssm:*:111122223333:document/{{DocumentName}}",
"arn:aws:ssm:*:111122223333:automation-execution/*"
]
},
{
"Action": [
"ssm:StopAutomationExecution",
"ssm:GetAutomationExecution",
"ssm:DescribeAutomationExecutions",
"ssm:DescribeAutomationStepExecutions",
"ssm:SendAutomationSignal"
],
"Resource": [
"arn:aws:ssm:*:111122223333:automation-execution/*"
],
"Effect": "Allow"
}
]
}
```
------
## Exemplo 2: Permitir que um usuário execute uma versão específica de um documento de automação
A seguinte política do IAM permite que um usuário do IAM execute uma versão específica de um documento de automação:
+ O nome do documento de automação é determinado pela entrada a seguir.
```
arn:aws:ssm:*:111122223333:document/{{DocumentName}}
```
+ A versão do documento de automação é determinada pela entrada a seguir.
```
"ssm:DocumentVersion": "5"
```
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "ssm:StartAutomationExecution",
"Effect": "Allow",
"Resource": [
"arn:aws:ssm:*:111122223333:document/{{DocumentName}}"
],
"Condition": {
"ForAnyValue:StringEquals": {
"ssm:DocumentVersion": ["5"]
}
}
},
{
"Action": [
"ssm:StartAutomationExecution"
],
"Resource": [
"arn:aws:ssm:*:111122223333:automation-execution/*"
],
"Effect": "Allow"
},
{
"Action": [
"ssm:StopAutomationExecution",
"ssm:GetAutomationExecution",
"ssm:DescribeAutomationExecutions",
"ssm:DescribeAutomationStepExecutions",
"ssm:SendAutomationSignal"
],
"Resource": [
"arn:aws:ssm:*:111122223333:automation-execution/*"
],
"Effect": "Allow"
}
]
}
```
------
## Exemplo 3: Permitir que um usuário execute documentos de automação com uma tag específica
A seguinte política do IAM permite que um usuário execute qualquer documento de automação que tenha uma tag específica:
+ O nome do documento de automação é determinado pela entrada a seguir.
```
arn:aws:ssm:*:111122223333:document/{{DocumentName}}
```
+ A tag do documento de automação é determinada pela entrada a seguir.
```
"ssm:DocumentVersion": "5"
```
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "ssm:StartAutomationExecution",
"Effect": "Allow",
"Resource": [
"arn:aws:ssm:*:111122223333:document/*"
],
"Condition": {
"StringEquals": {
"aws:ResourceTag/stage": "production"
}
}
},
{
"Action": [
"ssm:StartAutomationExecution"
],
"Resource": [
"arn:aws:ssm:*:111122223333:automation-execution/*"
],
"Effect": "Allow"
},
{
"Action": [
"ssm:StopAutomationExecution",
"ssm:GetAutomationExecution",
"ssm:DescribeAutomationExecutions",
"ssm:DescribeAutomationStepExecutions",
"ssm:SendAutomationSignal"
],
"Resource": [
"arn:aws:ssm:*:111122223333:automation-execution/*"
],
"Effect": "Allow"
}
]
}
```
------
## Exemplo 4: Permitir que um usuário execute um documento de automação quando uma tag específica for fornecida para a execução da automação
A seguinte política do IAM concede permissões a um usuário para executar documentos de automação quando uma etiqueta específica é fornecida para a execução da automação:
+ Execute o documento de automação especificado na política. O nome do documento é determinado pela entrada a seguir.
```
arn:aws:ssm:*:111122223333:document/{{DocumentName}}
```
+ É necessário fornecer um parâmetro de tag específico para a execução da automação. O parâmetro de tag para o recurso de execução da automação é determinado pela seguinte entrada.
```
"aws:ResourceTag/stage": "production"
```
+ Interrompa e envie sinais para execuções de automação que tenham a tag especificada.
+ Veja detalhes sobre as execuções de automação que possuem a tag especificada.
+ Adicione a tag especificada aos recursos do SSM.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "ssm:StartAutomationExecution",
"Effect": "Allow",
"Resource": [
"arn:aws:ssm:*:111122223333:document/{{DocumentName}}"
]
},
{
"Action": [
"ssm:StartAutomationExecution",
"ssm:StopAutomationExecution",
"ssm:GetAutomationExecution",
"ssm:DescribeAutomationExecutions",
"ssm:DescribeAutomationStepExecutions",
"ssm:SendAutomationSignal"
],
"Resource": [
"arn:aws:ssm:*:111122223333:automation-execution/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceTag/environment": "beta"
}
}
},
{
"Action": "ssm:AddTagsToResource",
"Effect": "Allow",
"Resource": [
"arn:aws:ssm:*:111122223333:automation-execution/*"
]
}
]
}
```
------
# Permitir que o Automation se adapte às suas necessidades de simultaneidade
Por padrão, o Automation permite que você execute até 100 automações simultâneas por vez. O Automation também fornece uma configuração opcional que você pode usar para ajustar sua cota de automação de simultaneidade automaticamente. Com essa configuração, sua cota de automação de simultaneidade pode acomodar até 500 automações simultâneas, dependendo dos recursos disponíveis.
**nota**
Se sua automação chamar operações de API, o dimensionamento adaptativo para seus destinos pode resultar em exceções de limitação. Se ocorrerem exceções de limitação recorrentes ao executar automações com simultaneidade adaptativa ativada, talvez seja necessário solicitar aumentos de cotas para a operação da API, se disponível.
**Para ativar a simultaneidade adaptativa usando o Console de gerenciamento da AWS**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação à esquerda, escolha **Automation** (Automação).
1. Escolha a guia **Preferences (Preferências)** e, em seguida, escolha **Edit (Editar)**.
1. Marque a caixa de seleção ao lado de **Enable adaptive concurrency** (Ativar simultaneidade adaptativa).
1. Escolha **Salvar**.
**Para ativar a simultaneidade adaptativa usando a linha de comando**
+ Abra a AWS CLI ou as ferramentas para Windows PowerShell e execute o comando a seguir para ativar a simultaneidade adaptativa para sua conta na região solicitante.
------
#### [ Linux & macOS ]
```
aws ssm update-service-setting \
--setting-id /ssm/automation/enable-adaptive-concurrency \
--setting-value True
```
------
#### [ Windows ]
```
aws ssm update-service-setting ^
--setting-id /ssm/automation/enable-adaptive-concurrency ^
--setting-value True
```
------
#### [ PowerShell ]
```
Update-SSMServiceSetting `
-SettingId "/ssm/automation/enable-adaptive-concurrency" `
-SettingValue "True"
```
------
# Configurar a repetição automática para operações com controle de utilização
Há um limite quanto ao número de execuções simultâneas de automação que podem ser executadas em cada conta. A tentativa de executar várias automações simultaneamente em uma conta pode causar problemas de controle de utilização. Você pode usar o recurso de repetição de controle de utilização automática para configurar o comportamento de repetição para etapas de automação com controle de utilização.
A nova tentativa automática de controle de utilização para ações de automação fornece um ambiente de execução mais resiliente para operações de alta escala. O recurso de repetição de controle de utilização suporta todas as [ações de automação](automation-actions.md), com exceção de `aws:executeScript`.
A configuração de repetição de controle de utilização funciona além da propriedade de etapa `maxAttempts` existente. Quando ambos estão configurados, o sistema primeiro tenta executar repetições de controle de utilização dentro do limite de tempo especificado e, em seguida, aplica a configuração `maxAttempts` se a etapa continuar falhando.
**Para configurar a repetição de controle de utilização usando o Console de gerenciamento da AWS**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação à esquerda, escolha **Automation** (Automação).
1. Escolha a guia **Preferences (Preferências)** e, em seguida, escolha **Edit (Editar)**.
1. No campo **Limite do tempo de repetição do controle de utilização**, insira um valor entre 0 e 3600 segundos. Isso especifica o tempo máximo em que o sistema tenta novamente uma etapa que foi submetida ao controle de utilização.
1. Escolha **Salvar**.
**Para configurar a repetição de controle de utilização usando a linha de comando**
+ Abra a AWS CLI ou as ferramentas para Windows PowerShell e execute o comando a seguir para configurar a repetição de controle de utilização para sua conta na região solicitante.
------
#### [ Linux & macOS ]
```
aws ssm update-service-setting \
--setting-id /ssm/automation/throttling-retry-time-limit \
--setting-value 3600
```
------
#### [ Windows ]
```
aws ssm update-service-setting ^
--setting-id /ssm/automation/throttling-retry-time-limit ^
--setting-value 3600
```
------
#### [ PowerShell ]
```
Update-SSMServiceSetting `
-SettingId "/ssm/automation/throttling-retry-time-limit" `
-SettingValue "3600"
```
------
# Implementação de controles de alteração para o Automation
Por padrão, o Automation permite que você use runbooks sem restrições de data e hora. Ao integrar o Automation com o Change Calendar, é possível implementar controles de alteração para todas as automações em sua Conta da AWS. Com essa configuração, as entidades principais do AWS Identity and Access Management (IAM) em sua conta poderão somente executar automações durante os períodos permitidos pelo calendário de alterações. Para saber mais sobre como trabalhar com o Change Calendar, consulte [Trabalhar com o Change Calendar](systems-manager-change-calendar-working.md).
**Como ativar os controles de alteração (console)**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação à esquerda, escolha **Automation** (Automação).
1. Escolha a guia **Preferences (Preferências)** e, em seguida, escolha **Edit (Editar)**.
1. Marque a caixa de seleção ao lado de **Ativar a integração do Change Calendar**.
1. Na lista suspensa **Escolher um calendário de alterações**, escolha o calendário de alterações que você deseja que o Automation siga.
1. Escolha **Salvar**.
# Executar uma operação automatizada com tecnologia do Systems Manager Automation
Ao executar uma automação, por padrão, a automação será executada no contexto do usuário que iniciou a automação. Isso significa, por exemplo, que se o usuário tiver permissões de administrador, a automação será executada com permissões de administrador e acesso total aos recursos que estão sendo configurados pela automação. Como uma prática recomendada de segurança, sugerimos que você execute a automação usando um perfil de serviço do IAM, nesse caso, conhecido como o perfil *assumir*, que é configurado com a política gerenciada AmazonSSMAutomationRole. Talvez seja necessário adicionar outras políticas do IAM ao seu perfil assumir para usar vários runbooks. O uso de uma função de serviço do IAM para executar a automação é chamado de *administração delegada*.
Quando você usa uma função de serviço, a automação tem permissão para ser executada nos recursos da AWS, mas o usuário que executou a automação tem acesso restrito (ou nenhum acesso) a esses recursos. Por exemplo, é possível configurar uma função de serviço e usá-la com o Automation para reiniciar uma ou mais instâncias do Amazon Elastic Compute Cloud (Amazon EC2). O Automation é uma ferramenta do AWS Systems Manager. A automação reinicia as instâncias, mas a função do serviço não concede permissão ao usuário para acessar essas instâncias.
Você pode especificar uma função de serviço em runtime ao executar uma automação ou você pode criar runbooks personalizados e especificar a função de serviço diretamente no runbook. Se você especificar uma função de serviço, seja em runtime ou em um runbook, o serviço será executado no contexto da função de serviço especificada. Se você não especificar uma função de serviço, o sistema criará uma sessão temporária no contexto do usuário e executará a automação.
**nota**
Especifique uma função de serviço para as automações que você espera que sejam executadas por mais de 12 horas. Se você iniciar uma automação de execução prolongada no contexto de um usuário, a sessão temporária do usuário expirará após 12 horas.
A administração delegada garante segurança e controle elevados de seus recursos da AWS. Isso também permite uma experiência de auditoria aprimorada, pois as ações estão sendo executadas nos recursos por uma função de serviço central em vez de várias contas do IAM.
**Antes de começar**
Antes de concluir o procedimento a seguir, é necessário criar o perfil de serviço do IAM e configurar uma relação de confiança para o Automation, uma ferramenta do AWS Systems Manager. Para obter mais informações, consulte [Tarefa 1: Criar uma função de serviço para a automação](automation-setup-iam.md#create-service-role).
Os procedimentos a seguir descrevem como usar o console do Systems Manager ou a ferramenta de linha de comando de sua preferência para executar uma automação simples.
## Executar uma automação simples (console)
O procedimento a seguir descreve como usar o console do Systems Manager para executar uma automação simples.
**Para executar uma automação simples**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, selecione **Automation** e **Execute automation (Executar automação)**.
1. Na lista **Automation document** (Documento do Automation), escolha um runbook. Escolha uma ou mais opções no painel **Document categories** (Categorias de documentos) para filtrar documentos SSM de acordo com sua finalidade. Para visualizar um runbook que você tenha, escolha a guia **Owned by me** (De minha propriedade). Para visualizar um runbook compartilhado com sua conta, escolha a guia **Shared with me** (Compartilhado comigo). Para visualizar todos os runbooks, escolha a guia **All documents** (Todos os documentos).
**nota**
Você pode visualizar informações sobre um runbook, selecionando o nome dele.
1. Na seção **Document details** (Detalhes do documento), verifique se **Document version** (Versão do documento) está definida como a versão que você quer executar. O sistema inclui as seguintes opções de versão:
+ **Versão padrão no runtime**: escolha essa opção se o runbook do Automation for atualizado periodicamente e uma nova versão padrão for atribuída.
+ **Versão mais recente no runtime**: escolha essa opção se o runbook do Automation for atualizado periodicamente e se você quiser executar a versão mais recente.
+ **1 (padrão):** escolha esta opção para executar a primeira versão do documento, que é a versão padrão.
1. Escolha **Próximo**.
1. Na seção **Execution mode (Modo de execução)**, escolha **Simple execution (Execução simples)**.
1. Na seção **Input parameters (Parâmetros de entrada)**, especifique as entradas necessárias. Opcionalmente, você pode escolher uma função de serviço do IAM na lista **AutomationAssumeRole**.
1. (Opcional) Escolha um alarme do CloudWatch a fim de aplicar à sua automação para monitoramento. Para anexar um alarme do CloudWatch à sua automação, a entidade principal do IAM que inicia a automação deve ter permissão para a ação `iam:createServiceLinkedRole`. Para obter mais informações sobre alarmes do CloudWatch, consulte [Usar alarmes do Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html). Observe que a automação será interrompida se o alarme for ativado. Se você usar o AWS CloudTrail, você verá a chamada de API em sua trilha.
1. Clique em **Executar**.
O console exibe o status da automação. Se houver falha na execução da automação, consulte [Solução de problemas do Systems Manager Automation](automation-troubleshooting.md).
Depois que uma execução de automação for concluída, você pode executá-la novamente com os mesmos parâmetros ou com parâmetros modificados. Para obter mais informações, consulte [Executar novamente as execuções de automação](automation-rerun-executions.md).
## Executar uma automação simples (linha de comando)
O procedimento a seguir descreve como usar a AWS CLI (no Linux ou no Windows) ou o Ferramentas da AWS para PowerShell para executar uma automação simples.
**Para executar uma automação simples**
1. Instale e configure a AWS CLI ou o Ferramentas da AWS para PowerShell, caso ainda não o tenha feito.
Para obter informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) e [Instalar o Ferramentas da AWS para PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
1. Execute o comando a seguir para iniciar uma automação simples. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name runbook name \
--parameters runbook parameters
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name runbook name ^
--parameters runbook parameters
```
------
#### [ PowerShell ]
```
Start-SSMAutomationExecution `
-DocumentName runbook name `
-Parameter runbook parameters
```
------
Este é um exemplo que usa o runbook `AWS-RestartEC2Instance` para reiniciar a instância do EC2 especificada.
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name "AWS-RestartEC2Instance" \
--parameters "InstanceId=i-02573cafcfEXAMPLE"
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name "AWS-RestartEC2Instance" ^
--parameters "InstanceId=i-02573cafcfEXAMPLE"
```
------
#### [ PowerShell ]
```
Start-SSMAutomationExecution `
-DocumentName AWS-RestartEC2Instance `
-Parameter @{"InstanceId"="i-02573cafcfEXAMPLE"}
```
------
O sistema retorna informações como estas.
------
#### [ Linux & macOS ]
```
{
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab"
}
```
------
#### [ Windows ]
```
{
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab"
}
```
------
#### [ PowerShell ]
```
4105a4fc-f944-11e6-9d32-0123456789ab
```
------
1. Execute o comando a seguir para recuperar o status da automação.
------
#### [ Linux & macOS ]
```
aws ssm describe-automation-executions \
--filter "Key=ExecutionId,Values=4105a4fc-f944-11e6-9d32-0123456789ab"
```
------
#### [ Windows ]
```
aws ssm describe-automation-executions ^
--filter "Key=ExecutionId,Values=4105a4fc-f944-11e6-9d32-0123456789ab"
```
------
#### [ PowerShell ]
```
Get-SSMAutomationExecutionList | `
Where {$_.AutomationExecutionId -eq "4105a4fc-f944-11e6-9d32-0123456789ab"}
```
------
O sistema retorna informações como estas.
------
#### [ Linux & macOS ]
```
{
"AutomationExecutionMetadataList": [
{
"AutomationExecutionStatus": "InProgress",
"CurrentStepName": "stopInstances",
"Outputs": {},
"DocumentName": "AWS-RestartEC2Instance",
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab",
"DocumentVersion": "1",
"ResolvedTargets": {
"ParameterValues": [],
"Truncated": false
},
"AutomationType": "Local",
"Mode": "Auto",
"ExecutionStartTime": 1564600648.159,
"CurrentAction": "aws:changeInstanceState",
"ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/Admin",
"LogFile": "",
"Targets": []
}
]
}
```
------
#### [ Windows ]
```
{
"AutomationExecutionMetadataList": [
{
"AutomationExecutionStatus": "InProgress",
"CurrentStepName": "stopInstances",
"Outputs": {},
"DocumentName": "AWS-RestartEC2Instance",
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab",
"DocumentVersion": "1",
"ResolvedTargets": {
"ParameterValues": [],
"Truncated": false
},
"AutomationType": "Local",
"Mode": "Auto",
"ExecutionStartTime": 1564600648.159,
"CurrentAction": "aws:changeInstanceState",
"ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/Admin",
"LogFile": "",
"Targets": []
}
]
}
```
------
#### [ PowerShell ]
```
AutomationExecutionId : 4105a4fc-f944-11e6-9d32-0123456789ab
AutomationExecutionStatus : InProgress
AutomationType : Local
CurrentAction : aws:changeInstanceState
CurrentStepName : startInstances
DocumentName : AWS-RestartEC2Instance
DocumentVersion : 1
ExecutedBy : arn:aws:sts::123456789012:assumed-role/Administrator/Admin
ExecutionEndTime : 1/1/0001 12:00:00 AM
ExecutionStartTime : 7/31/2019 7:17:28 PM
FailureMessage :
LogFile :
MaxConcurrency :
MaxErrors :
Mode : Auto
Outputs : {}
ParentAutomationExecutionId :
ResolvedTargets : Amazon.SimpleSystemsManagement.Model.ResolvedTargets
Target :
TargetMaps : {}
TargetParameterName :
Targets : {}
```
------
# Executar novamente as execuções de automação
Você pode executar novamente as execuções de automação AWS Systems Manager para repetir tarefas com parâmetros idênticos ou modificados. O recurso de nova execução permite replicar com eficiência as execuções de automação sem recriar manualmente as configurações de automação, reduzindo a sobrecarga operacional e possíveis erros de configuração.
Quando você executa novamente uma execução de automação, o Systems Manager preserva os parâmetros originais do runbook, os alarmes do Amazon CloudWatch e as tags da execução anterior. O sistema cria uma nova execução com um novo ID de execução e registros de data e hora atualizados. Você pode executar novamente qualquer tipo de execução de automação, incluindo execuções simples, execuções de controle de taxas, execuções entre contas e regiões e execuções manuais.
## Execute novamente uma execução de automação (console)
O procedimento a seguir descreve como usar o console do Systems Manager para executar novamente uma execução de automação.
**Para executar novamente uma execução de automação a partir da página inicial de automação**
Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação à esquerda, escolha **Automation** (Automação).
1. Na lista de execuções, selecione a execução que você deseja executar novamente.
1. Escolha **Executar novamente a execução**.
1. Na página **Executar documento de automação**, revise os parâmetros pré-preenchidos, o modo de execução e a configuração de destino da execução original.
1. (Opcional) Modifique quaisquer parâmetros, alvos ou outras configurações conforme necessário para sua nova execução.
1. Escolha **Executar** para iniciar a nova execução com um novo ID de execução.
**Para executar novamente uma execução de automação a partir da página de detalhes da execução**
Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação à esquerda, escolha **Automation** (Automação).
1. Escolha o ID de execução da automação que você deseja executar novamente.
1. Na página de detalhes da execução, escolha **Executar novamente a execução**.
1. Na página **Executar documento de automação**, revise os parâmetros pré-preenchidos, o modo de execução e a configuração de destino da execução original.
1. (Opcional) Modifique quaisquer parâmetros, alvos ou outras configurações conforme necessário para sua nova execução.
1. Escolha **Executar** para iniciar a nova execução com um novo ID de execução.
**Para copiar uma execução de automação para uma nova execução**
Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação à esquerda, escolha **Automation** (Automação).
1. Escolha o ID de execução da automação que você deseja copiar.
1. Na página de detalhes da execução, escolha **Ações** e, em seguida, escolha **Copiar para novo**.
1. Na página **Executar documento de automação**, revise os parâmetros pré-preenchidos, o modo de execução e a configuração de destino da execução original.
1. (Opcional) Modifique quaisquer parâmetros, alvos ou outras configurações conforme necessário para sua nova execução.
1. Selecione **Executar** para iniciar a nova execução.
# Executar uma automação que exija aprovações
Os procedimentos a seguir descrevem como usar o console do AWS Systems Manager e a AWS Command Line Interface (AWS CLI) para executar uma automação com aprovações usando uma execução simples. A automação usa a ação `aws:approve`, que pausa temporariamente a automação até que as entidades principais designadas aprovem ou neguem a ação. A automação é executada no contexto do usuário atual. Isso significa que você não precisa configurar outras permissões do IAM, desde que tenha permissão para usar o runbook e qualquer ação chamada pelo runbook. Se você tiver permissões de administrador no IAM, isso significa que você já tem permissão para usar esse runbook.
**Antes de começar**
Além das entradas padrão exigidas pelo runbook, a ação `aws:approve` requer os dois parâmetros a seguir:
+ Uma lista de aprovadores. A lista de aprovadores deve conter, no mínimo, um aprovador na forma de um nome de usuário ou ARN de usuário. Se vários aprovadores forem fornecidos, uma contagem de aprovações mínimas correspondente também deverá ser especificada no runbook.
+ ARN do tópico de um Amazon Simple Notification Service (Amazon SNS) O nome do tópico do Amazon SNS deve começar com `Automation`.
Esse procedimento pressupõe que você já tenha criado um tópico do Amazon SNS, que é necessário para fornecer a solicitação de aprovação. Para obter informações, consulte [Criar um tópico](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html#CreateTopic) no *Manual do desenvolvedor do Amazon Simple Notification Service*.
## Executar uma automação com aprovadores (console)
**Para executar uma automação com aprovadores**
O procedimento a seguir descreve como usar o console do Systems Manager para executar uma automação com aprovadores.
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, selecione **Automation** e **Execute automation (Executar automação)**.
1. Na lista **Automation document** (Documento do Automation), escolha um runbook. Escolha uma ou mais opções no painel **Document categories** (Categorias de documentos) para filtrar documentos SSM de acordo com sua finalidade. Para visualizar um runbook que você tenha, escolha a guia **Owned by me** (De minha propriedade). Para visualizar um runbook compartilhado com sua conta, escolha a guia **Shared with me** (Compartilhado comigo). Para visualizar todos os runbooks, escolha a guia **All documents** (Todos os documentos).
**nota**
Você pode visualizar informações sobre um runbook, selecionando o nome dele.
1. Na seção **Document details** (Detalhes do documento), verifique se **Document version** (Versão do documento) está definida como a versão que você quer executar. O sistema inclui as seguintes opções de versão:
+ **Versão padrão no runtime**: escolha essa opção se o runbook do Automation for atualizado periodicamente e uma nova versão padrão for atribuída.
+ **Versão mais recente no runtime**: escolha essa opção se o runbook do Automation for atualizado periodicamente e se você quiser executar a versão mais recente.
+ **1 (padrão):** escolha esta opção para executar a primeira versão do documento, que é a versão padrão.
1. Escolha **Próximo**.
1. Na página **Execute automation document (Executar documento de automação)**, escolha **Simple execution (Execução simples)**.
1. Na seção **Input parameters (Parâmetros de entrada)**, especifique os parâmetros de entrada necessários.
Por exemplo, se você escolheu o runbook `AWS-StartEC2InstanceWithApproval`, deverá especificar ou escolher IDs de instância para o parâmetro **InstanceId**.
1. Na seção **Aprovadores**, especifique os nomes de usuário ou os ARNs de usuário dos aprovadores para a ação de automação.
1. Na seção **SNSTopicARN**, especifique o ARN do tópico do SNS a ser usado para enviar notificações de aprovação. O nome do tópico do SNS deve começar com **Automation (Automação)**.
1. Opcionalmente, você pode escolher uma função de serviço do IAM na lista **AutomationAssumeRole**. Se seu destino tem mais de 100 contas e regiões, é necessário especificar o `AWS-SystemsManager-AutomationAdministrationRole`.
1. Escolha **Execute automation**.
O aprovador especificado recebe uma notificação do Amazon SNS com detalhes para aprovar ou rejeitar a automação. Essa ação de aprovação é válida por 7 dias a contar da data de emissão e pode ser emitida usando o console do Systems Manager ou a AWS Command Line Interface (AWS CLI).
Se você optou por aprovar a automação, ela continuará a executar as etapas incluídas no runbook especificado. O console exibe o status da automação. Se houver falha na execução da automação, consulte [Solução de problemas do Systems Manager Automation](automation-troubleshooting.md).
**Para aprovar ou negar uma automação**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Automation** (Automação) e selecione a automação que foi executada no procedimento anterior.
1. Escolha **Actions (Ações)** e depois **Approve/Deny (Aprovar/negar)**.
1. Escolha entre **Approve (Aprovar)** ou **Deny (Negar)** e, opcionalmente, forneça um comentário.
1. Selecione **Enviar**.
## Executar uma automação com aprovadores (linha de comando)
O procedimento a seguir descreve como usar a AWS CLI (no Linux ou no Windows) ou o Ferramentas da AWS para PowerShell para executar uma automação com aprovadores.
**Para executar uma automação com aprovadores**
1. Instale e configure a AWS CLI ou o Ferramentas da AWS para PowerShell, caso ainda não o tenha feito.
Para obter informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) e [Instalar o Ferramentas da AWS para PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
1. Execute o comando a seguir para executar uma automação com aprovadores. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações. Na seção de nome do documento, especifique um runbook que inclua a ação de automação ., `aws:approve`.
Em `Approvers`, especifique os nomes de usuário ou os ARNs de usuário dos aprovadores para a ação. Em `SNSTopic`, especifique o ARN do tópico do SNS a ser usado para enviar a notificação de aprovação. O nome do tópico do Amazon SNS deve começar com `Automation`.
**nota**
Os nomes específicos dos valores dos parâmetros para aprovadores e o tópico do SNS dependem dos valores especificados no runbook escolhido.
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name "AWS-StartEC2InstanceWithApproval" \
--parameters "InstanceId=i-02573cafcfEXAMPLE,Approvers=arn:aws:iam::123456789012:role/Administrator,SNSTopicArn=arn:aws:sns:region:123456789012:AutomationApproval"
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name "AWS-StartEC2InstanceWithApproval" ^
--parameters "InstanceId=i-02573cafcfEXAMPLE,Approvers=arn:aws:iam::123456789012:role/Administrator,SNSTopicArn=arn:aws:sns:region:123456789012:AutomationApproval"
```
------
#### [ PowerShell ]
```
Start-SSMAutomationExecution `
-DocumentName AWS-StartEC2InstanceWithApproval `
-Parameters @{
"InstanceId"="i-02573cafcfEXAMPLE"
"Approvers"="arn:aws:iam::123456789012:role/Administrator"
"SNSTopicArn"="arn:aws:sns:region:123456789012:AutomationApproval"
}
```
------
O sistema retorna informações como estas.
------
#### [ Linux & macOS ]
```
{
"AutomationExecutionId": "df325c6d-b1b1-4aa0-8003-6cb7338213c6"
}
```
------
#### [ Windows ]
```
{
"AutomationExecutionId": "df325c6d-b1b1-4aa0-8003-6cb7338213c6"
}
```
------
#### [ PowerShell ]
```
df325c6d-b1b1-4aa0-8003-6cb7338213c6
```
------
**Para aprovar uma automação**
+ Execute o comando a seguir para aprovar uma automação. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
------
#### [ Linux & macOS ]
```
aws ssm send-automation-signal \
--automation-execution-id "df325c6d-b1b1-4aa0-8003-6cb7338213c6" \
--signal-type "Approve" \
--payload "Comment=your comments"
```
------
#### [ Windows ]
```
aws ssm send-automation-signal ^
--automation-execution-id "df325c6d-b1b1-4aa0-8003-6cb7338213c6" ^
--signal-type "Approve" ^
--payload "Comment=your comments"
```
------
#### [ PowerShell ]
```
Send-SSMAutomationSignal `
-AutomationExecutionId df325c6d-b1b1-4aa0-8003-6cb7338213c6 `
-SignalType Approve `
-Payload @{"Comment"="your comments"}
```
------
Não haverá saída se o comando for bem-sucedido.
**Para negar uma automação**
+ Execute o comando a seguir para negar uma automação. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
------
#### [ Linux & macOS ]
```
aws ssm send-automation-signal \
--automation-execution-id "df325c6d-b1b1-4aa0-8003-6cb7338213c6" \
--signal-type "Deny" \
--payload "Comment=your comments"
```
------
#### [ Windows ]
```
aws ssm send-automation-signal ^
--automation-execution-id "df325c6d-b1b1-4aa0-8003-6cb7338213c6" ^
--signal-type "Deny" ^
--payload "Comment=your comments"
```
------
#### [ PowerShell ]
```
Send-SSMAutomationSignal `
-AutomationExecutionId df325c6d-b1b1-4aa0-8003-6cb7338213c6 `
-SignalType Deny `
-Payload @{"Comment"="your comments"}
```
------
Não haverá saída se o comando for bem-sucedido.
# Executar operações automatizadas em escala
Com o AWS Systems Manager Automation, você pode executar automações em uma frota de recursos da AWS usando *destinos*. Além disso, você pode controlar a implantação da automação em toda a frota, especificando um valor de simultaneidade e um erro limite. Os recursos de simultaneidade e limite de erros são coletivamente chamados de *controles de taxa*. O valor de simultaneidade determina quantos recursos são permitidos para executar a automação simultaneamente. O Automation também fornece um modo de simultaneidade adaptativa que você pode optar por participar. A simultaneidade adaptativa dimensiona automaticamente sua cota de automação de 100 automações em execução simultânea até 500. Um limite de erro determina quantas automações podem falhar antes do Systems Manager parar de enviar a automação para outros recursos.
Para obter mais informações sobre simultaneidade e limites de erro, consulte [Automações de controle em grande escala](running-automations-scale-controls.md). Para obter mais informações sobre destinos, consulte [Mapeamento de destino para uma automação](running-automations-map-targets.md).
Os procedimentos a seguir descrevem como ativar a simultaneidade adaptativa e como executar uma automação com destinos e controles de taxa usando o console do Systems Manager e a AWS Command Line Interface (AWS CLI).
## Executar uma automação com destinos e controles de taxa (console)
O procedimento a seguir descreve como usar o console do Systems Manager para executar uma automação com destinos e controles de taxa.
**Para executar uma automação com destinos e controles de taxa**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, selecione **Automation** e **Execute automation (Executar automação)**.
1. Na lista **Automation document** (Documento do Automation), escolha um runbook. Escolha uma ou mais opções no painel **Document categories** (Categorias de documentos) para filtrar documentos SSM de acordo com sua finalidade. Para visualizar um runbook que você tenha, escolha a guia **Owned by me** (De minha propriedade). Para visualizar um runbook compartilhado com sua conta, escolha a guia **Shared with me** (Compartilhado comigo). Para visualizar todos os runbooks, escolha a guia **All documents** (Todos os documentos).
**nota**
Você pode visualizar informações sobre um runbook, selecionando o nome dele.
1. Na seção **Document details** (Detalhes do documento), verifique se **Document version** (Versão do documento) está definida como a versão que você quer executar. O sistema inclui as seguintes opções de versão:
+ **Versão padrão no runtime**: escolha essa opção se o runbook do Automation for atualizado periodicamente e uma nova versão padrão for atribuída.
+ **Versão mais recente no runtime**: escolha essa opção se o runbook do Automation for atualizado periodicamente e se você quiser executar a versão mais recente.
+ **1 (padrão):** escolha esta opção para executar a primeira versão do documento, que é a versão padrão.
1. Escolha **Próximo**.
1. Na seção **Execution Mode (Modo de execução)**, escolha **Rate Control (Controle de taxa)**. Você deve usar esse modo ou **Multi-account and Region (Várias contas e regiões)** se quiser usar destinos e controles de taxa.
1. Na seção **Targets** (Destinos), escolha como você quer definir os destinos dos recursos da AWS em que você deseja executar o Automation. Essas opções são obrigatórias.
1. Use a lista **Parameter (Parâmetro)** para escolher um parâmetro. Os itens na lista **Parameter** (Parâmetro) são determinados pelos parâmetros no runbook do Automation que você selecionou no início deste procedimento. Ao escolher um parâmetro, você define o tipo de recurso em que o fluxo de trabalho da Automação é executado.
1. Use a lista **Targets (Destinos)** para escolher como você deseja definir o destino dos recursos.
1. Se você optar por definir o destino dos recursos usando valores de parâmetro, insira o valor do parâmetro para aquele escolhido na seção **Input parameters** (Parâmetros de entrada).
1. Se você escolher definir o destino dos recursos usando o AWS Resource Groups, escolha o nome do grupo na lista **Resource Group (Grupo de recursos)**.
1. Se você optar por definir o destino dos recursos usando tags, insira a chave de tag e (opcionalmente) o valor da tag nos campos fornecidos. Escolha **Adicionar**.
1. Se você quiser executar um runbook do Automation em todas as instâncias nas Conta da AWS e Região da AWS atuais, escolha **All instances** (Todas as instâncias).
1. Na seção **Input parameters (Parâmetros de entrada)**, especifique as entradas necessárias. Opcionalmente, você pode escolher uma função de serviço do IAM na lista **AutomationAssumeRole**.
**nota**
Pode ser que não seja necessário escolher algumas das opções na seção **Input parameters** (Parâmetros de entrada). Isso ocorre porque você definiu o destino dos recursos usando tags ou um grupo de recursos. Por exemplo, se você escolheu o runbook `AWS-RestartEC2Instance`, você não precisará especificar ou escolher IDs de instância na seção **Input parameters** (Parâmetros de entrada). A execução do Automation localiza as instâncias para reiniciar usando as tags ou grupos de recursos que você especificou.
1. Use as opções na seção **Rate control** (Controle de taxa) para restringir o número de recursos da AWS que podem executar o Automation dentro de cada par conta-região.
Na seção **Concurrency** (Simultaneidade), escolha uma opção:
+ Escolha **Targets (Destinos)** para inserir um número absoluto de destinos que podem executar o fluxo de trabalho de Automação simultaneamente.
+ Escolha **Percentage (Porcentagem)** para inserir uma porcentagem do conjunto de destino que pode executar o fluxo de trabalho de Automação simultaneamente.
1. Na seção **Error threshold (Limite de erro)**, escolha uma opção:
+ Escolha **errors (erros)** para inserir um número absoluto de erros permitidos antes que a Automação deixe de enviar o fluxo de trabalho para outros recursos.
+ Escolha **percentage (porcentagem)** para inserir uma porcentagem de erros permitidos antes que a Automação deixe de enviar o fluxo de trabalho para outros recursos.
1. (Opcional) Escolha um alarme do CloudWatch a fim de aplicar à sua automação para monitoramento. Para anexar um alarme do CloudWatch à sua automação, a entidade principal do IAM que inicia a automação deve ter permissão para a ação `iam:createServiceLinkedRole`. Para obter mais informações sobre alarmes do CloudWatch, consulte [Usar alarmes do Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html). Observe que a automação será interrompida se o alarme for ativado. Se você usar o AWS CloudTrail, você verá a chamada de API em sua trilha.
1. Clique em **Executar**.
Para visualizar automações iniciadas pela automação do controle de taxa, no painel de navegação, escolha Automation (Automação) e depois selecione **Show child automations** (Mostrar automações filho).
Depois que uma execução de automação for concluída, você pode executá-la novamente com os mesmos parâmetros ou com parâmetros modificados. Para obter mais informações, consulte [Executar novamente as execuções de automação](automation-rerun-executions.md).
## Executar uma automação com destinos e controles de taxa (linha de comando)
O procedimento a seguir descreve como usar a AWS CLI (no Linux ou no Windows) ou o Ferramentas da AWS para PowerShell para executar uma automação com destinos e controles de taxa.
**Para executar uma automação com destinos e controles de taxa**
1. Instale e configure a AWS CLI ou o Ferramentas da AWS para PowerShell, caso ainda não o tenha feito.
Para obter informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) e [Instalar o Ferramentas da AWS para PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
1. Execute o comando a seguir para visualizar uma lista de documentos.
------
#### [ Linux & macOS ]
```
aws ssm list-documents
```
------
#### [ Windows ]
```
aws ssm list-documents
```
------
#### [ PowerShell ]
```
Get-SSMDocumentList
```
------
Anote o nome do runbook que você quer usar.
1. Execute o comando a seguir para visualizar os detalhes sobre o runbook. Substitua o *runbook name* (nome do runbook) pelo nome do runbook cujos detalhes deseja visualizar. Além disso, anote o nome de um parâmetro (por exemplo, `InstanceId`) que deseja usar para a opção `--target-parameter-name`. Esse parâmetro determina o tipo de recurso em que a automação é executada.
------
#### [ Linux & macOS ]
```
aws ssm describe-document \
--name runbook name
```
------
#### [ Windows ]
```
aws ssm describe-document ^
--name runbook name
```
------
#### [ PowerShell ]
```
Get-SSMDocumentDescription `
-Name runbook name
```
------
1. Crie um comando que use as opções de destino e controle de taxa que você deseja executar. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
*Definir destino usando tags*
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name runbook name \
--targets Key=tag:key name,Values=value \
--target-parameter-name parameter name \
--parameters "input parameter name=input parameter value,input parameter 2 name=input parameter 2 value" \
--max-concurrency 10 \
--max-errors 25%
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name runbook name ^
--targets Key=tag:key name,Values=value ^
--target-parameter-name parameter name ^
--parameters "input parameter name=input parameter value,input parameter 2 name=input parameter 2 value" ^
--max-concurrency 10 ^
--max-errors 25%
```
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "tag:key name"
$Targets.Values = "value"
Start-SSMAutomationExecution `
DocumentName "runbook name" `
-Targets $Targets `
-TargetParameterName "parameter name" `
-Parameter @{"input parameter name"="input parameter value";"input parameter 2 name"="input parameter 2 value"} `
-MaxConcurrency "10" `
-MaxError "25%"
```
------
*Definir destino usando valores de parâmetro*
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name runbook name \
--targets Key=ParameterValues,Values=value,value 2,value 3 \
--target-parameter-name parameter name \
--parameters "input parameter name=input parameter value" \
--max-concurrency 10 \
--max-errors 25%
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name runbook name ^
--targets Key=ParameterValues,Values=value,value 2,value 3 ^
--target-parameter-name parameter name ^
--parameters "input parameter name=input parameter value" ^
--max-concurrency 10 ^
--max-errors 25%
```
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "ParameterValues"
$Targets.Values = "value","value 2","value 3"
Start-SSMAutomationExecution `
-DocumentName "runbook name" `
-Targets $Targets `
-TargetParameterName "parameter name" `
-Parameter @{"input parameter name"="input parameter value"} `
-MaxConcurrency "10" `
-MaxError "25%"
```
------
*Definir destino usando AWS Resource Groups*
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name runbook name \
--targets Key=ResourceGroup,Values=Resource group nname \
--target-parameter-name parameter name \
--parameters "input parameter name=input parameter value" \
--max-concurrency 10 \
--max-errors 25%
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name runbook name ^
--targets Key=ResourceGroup,Values=Resource group name ^
--target-parameter-name parameter name ^
--parameters "input parameter name=input parameter value" ^
--max-concurrency 10 ^
--max-errors 25%
```
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "ResourceGroup"
$Targets.Values = "Resource group name"
Start-SSMAutomationExecution `
-DocumentName "runbook name" `
-Targets $Targets `
-TargetParameterName "parameter name" `
-Parameter @{"input parameter name"="input parameter value"} `
-MaxConcurrency "10" `
-MaxError "25%"
```
------
*Direcionar todas as instâncias do Amazon EC2 na Conta da AWS e na Região da AWS atuais*
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name runbook name \
--targets "Key=AWS::EC2::Instance,Values=*" \
--target-parameter-name instanceId \
--parameters "input parameter name=input parameter value" \
--max-concurrency 10 \
--max-errors 25%
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name runbook name ^
--targets Key=AWS::EC2::Instance,Values=* ^
--target-parameter-name instanceId ^
--parameters "input parameter name=input parameter value" ^
--max-concurrency 10 ^
--max-errors 25%
```
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "AWS::EC2::Instance"
$Targets.Values = "*"
Start-SSMAutomationExecution `
-DocumentName "runbook name" `
-Targets $Targets `
-TargetParameterName "instanceId" `
-Parameter @{"input parameter name"="input parameter value"} `
-MaxConcurrency "10" `
-MaxError "25%"
```
------
O comando retorna um ID de execução. Copie esse ID para a área de transferência. Você pode usar esse ID para visualizar o status da automação.
------
#### [ Linux & macOS ]
```
{
"AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE"
}
```
------
#### [ Windows ]
```
{
"AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE"
}
```
------
#### [ PowerShell ]
```
a4a3c0e9-7efd-462a-8594-01234EXAMPLE
```
------
1. Execute o comando a seguir para visualizar a automação. Substitua cada *automation execution ID* (ID de execução de automação) por suas próprias informações.
------
#### [ Linux & macOS ]
```
aws ssm describe-automation-executions \
--filter Key=ExecutionId,Values=automation execution ID
```
------
#### [ Windows ]
```
aws ssm describe-automation-executions ^
--filter Key=ExecutionId,Values=automation execution ID
```
------
#### [ PowerShell ]
```
Get-SSMAutomationExecutionList | `
Where {$_.AutomationExecutionId -eq "automation execution ID"}
```
------
1. Para visualizar detalhes sobre o andamento da automação, execute o comando a seguir. Substitua cada *automation execution ID* (ID de execução de automação) por suas próprias informações.
------
#### [ Linux & macOS ]
```
aws ssm get-automation-execution \
--automation-execution-id automation execution ID
```
------
#### [ Windows ]
```
aws ssm get-automation-execution ^
--automation-execution-id automation execution ID
```
------
#### [ PowerShell ]
```
Get-SSMAutomationExecution `
-AutomationExecutionId automation execution ID
```
------
O sistema retorna informações como estas.
------
#### [ Linux & macOS ]
```
{
"AutomationExecution": {
"StepExecutionsTruncated": false,
"AutomationExecutionStatus": "Success",
"MaxConcurrency": "1",
"Parameters": {},
"MaxErrors": "1",
"Outputs": {},
"DocumentName": "AWS-StopEC2Instance",
"AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE",
"ResolvedTargets": {
"ParameterValues": [
"i-02573cafcfEXAMPLE"
],
"Truncated": false
},
"ExecutionEndTime": 1564681619.915,
"Targets": [
{
"Values": [
"DEV"
],
"Key": "tag:ENV"
}
],
"DocumentVersion": "1",
"ExecutionStartTime": 1564681576.09,
"ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/Admin",
"StepExecutions": [
{
"Inputs": {
"InstanceId": "i-02573cafcfEXAMPLE"
},
"Outputs": {},
"StepName": "i-02573cafcfEXAMPLE",
"ExecutionEndTime": 1564681619.093,
"StepExecutionId": "86c7b811-3896-4b78-b897-01234EXAMPLE",
"ExecutionStartTime": 1564681576.836,
"Action": "aws:executeAutomation",
"StepStatus": "Success"
}
],
"TargetParameterName": "InstanceId",
"Mode": "Auto"
}
}
```
------
#### [ Windows ]
```
{
"AutomationExecution": {
"StepExecutionsTruncated": false,
"AutomationExecutionStatus": "Success",
"MaxConcurrency": "1",
"Parameters": {},
"MaxErrors": "1",
"Outputs": {},
"DocumentName": "AWS-StopEC2Instance",
"AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE",
"ResolvedTargets": {
"ParameterValues": [
"i-02573cafcfEXAMPLE"
],
"Truncated": false
},
"ExecutionEndTime": 1564681619.915,
"Targets": [
{
"Values": [
"DEV"
],
"Key": "tag:ENV"
}
],
"DocumentVersion": "1",
"ExecutionStartTime": 1564681576.09,
"ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/Admin",
"StepExecutions": [
{
"Inputs": {
"InstanceId": "i-02573cafcfEXAMPLE"
},
"Outputs": {},
"StepName": "i-02573cafcfEXAMPLE",
"ExecutionEndTime": 1564681619.093,
"StepExecutionId": "86c7b811-3896-4b78-b897-01234EXAMPLE",
"ExecutionStartTime": 1564681576.836,
"Action": "aws:executeAutomation",
"StepStatus": "Success"
}
],
"TargetParameterName": "InstanceId",
"Mode": "Auto"
}
}
```
------
#### [ PowerShell ]
```
AutomationExecutionId : a4a3c0e9-7efd-462a-8594-01234EXAMPLE
AutomationExecutionStatus : Success
CurrentAction :
CurrentStepName :
DocumentName : AWS-StopEC2Instance
DocumentVersion : 1
ExecutedBy : arn:aws:sts::123456789012:assumed-role/Administrator/Admin
ExecutionEndTime : 8/1/2019 5:46:59 PM
ExecutionStartTime : 8/1/2019 5:46:16 PM
FailureMessage :
MaxConcurrency : 1
MaxErrors : 1
Mode : Auto
Outputs : {}
Parameters : {}
ParentAutomationExecutionId :
ProgressCounters :
ResolvedTargets : Amazon.SimpleSystemsManagement.Model.ResolvedTargets
StepExecutions : {i-02573cafcfEXAMPLE}
StepExecutionsTruncated : False
Target :
TargetLocations : {}
TargetMaps : {}
TargetParameterName : InstanceId
Targets : {tag:Name}
```
------
**nota**
Você pode também monitorar o status da automação no console. Na lista de **execuções do Automation**, escolha a execução que você acabou de processar e depois escolha a guia **Execution steps** (Etapas da execução). Esta guia mostra o status das ações de automação.
# Mapeamento de destino para uma automação
Use o parâmetro `Targets` para definir rapidamente quais recursos serão usados como destino por uma automação. Por exemplo, se você quiser executar uma automação que reinicia suas instâncias gerenciadas, em vez de selecionar manualmente dezenas de IDs de instância no console ou digitá-los em um comando, especifique as instâncias de destino especificando as tags do Amazon Elastic Compute Cloud (Amazon EC2) com o parâmetro `Targets`.
Quando você executa uma automação que usa um destino, o AWS Systems Manager cria uma automação filho para cada destino. Por exemplo, se você definir o destino dos volumes do Amazon Elastic Block Store (Amazon EBS) especificando tags, e essas tags forem resolvidas para 100 volumes do Amazon EBS, o Systems Manager criará 100 automações filho. A automação pai é concluída quando todas as automações filho alcançam um estado final.
**nota**
Quaisquer `input parameters` especificados em runtime (na seção **Input parameters** (parâmetros de entrada) do console ou usando a opção `parameters` na linha de comando) serão automaticamente processados por todas as automações filho.
Você pode definir recursos como o destino para uma automação usando tags, grupos de recursos e valores de parâmetros. Além disso, você pode usar a opção `TargetMaps` para definir o destino de vários valores de parâmetro na linha de comando ou em um arquivo. A seção a seguir descreve cada uma dessas opções de destino em mais detalhes.
## Definir uma etiqueta como destino
É possível especificar uma única etiqueta como o destino de uma automação. Muitos recursos da AWS oferecem suporte a tags, incluindo instâncias do Amazon Elastic Compute Cloud (Amazon EC2) e Amazon Relational Database Service (Amazon RDS), volumes e snapshots do Amazon Elastic Block Store (Amazon EBS), grupos de recursos e buckets do Amazon Simple Storage Service (Amazon S3), entre outros. É possível executar rapidamente a automação nos recursos da AWS definindo uma etiqueta como destino. Uma etiqueta é um par de chave-valor, como Operating\$1System:Linux ou Department:Finance. Se você atribuir um nome específico a um recurso, você também pode usar a palavra "Name" como chave, e o nome do recurso como valor.
Quando você especifica uma tag como o destino para uma automação, você também deve especificar um parâmetro de destino. O parâmetro de destino usa a opção `TargetParameterName`. Ao escolher um parâmetro de destino, você define o tipo de recurso no qual a automação é executada. O parâmetro de destino especificado com a tag deve ser um parâmetro válido definido no runbook. Por exemplo, para ter dezenas de instâncias do EC2 como destino usando tags, escolha o parâmetro de destino `InstanceId`. Ao escolher este parâmetro, você define as *instâncias* como o tipo de recurso para a automação. Ao criar um runbook personalizado, é necessário especificar o **Tipo de destino** como `/AWS::EC2::Instance` para garantir que somente instâncias sejam usadas. Caso contrário, todos os recursos com a mesma etiqueta serão direcionados. Ao definir instâncias como destino usando uma etiqueta, é possível incluir instâncias encerradas.
A captura de tela a seguir usa o runbook `AWS-DetachEBSVolume`. O parâmetro de destino lógico é `VolumeId`.
![\[Usar uma etiqueta como destino para o Systems Manager Automation\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/automation-rate-control-tags-1-new.png)
O runbook `AWS-DetachEBSVolume` também inclui uma propriedade especial chamada **Target type** (Tipo de destino), que é definida como `/AWS::EC2::Volume`. Isso significa que, se o par de tag e chave `Finance:TestEnv` retornar diferentes tipos de recursos (por exemplo, instâncias do EC2, volumes do Amazon EBS e snapshots do Amazon EBS), apenas os volumes do Amazon EBS serão usados.
**Importante**
Os nomes dos parâmetros de destino diferenciam maiúsculas de minúsculas. Se você executar automações usando a AWS Command Line Interface (AWS CLI) ou AWS Tools for Windows PowerShell, insira o nome do parâmetro de destino exatamente como ele é definido no runbook. Se não fizer isso, o sistema retornará um erro `InvalidAutomationExecutionParametersException`. Você pode usar a operação de API [DescribeDocument](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeDocument.html) para ver informações sobre os parâmetros de destino disponíveis em um runbook específico. Veja a seguir um exemplo de comando da AWS CLI que fornece informações sobre o documento `AWS-DeleteSnapshot`.
```
aws ssm describe-document \
--name AWS-DeleteSnapshot
```
Aqui estão alguns exemplos de comandos da AWS CLI que definem recursos como destino usando etiquetas.
**Exemplo 1: definir uma etiqueta como destino usando um par de chave-valor para reiniciar instâncias do Amazon EC**
Este exemplo reinicia todas as instâncias do Amazon EC2 que estiverem marcadas com uma chave *Department* e um valor *HumanResources*. O parâmetro de destino usa o parâmetro *InstanceId* do runbook. O exemplo usa um parâmetro adicional para executar a automação usando uma função de serviço do Automation (também chamado de *função assumida*).
```
aws ssm start-automation-execution \
--document-name AWS-RestartEC2Instance \
--targets Key=tag:Department,Values=HumanResources \
--target-parameter-name InstanceId \
--parameters "AutomationAssumeRole=arn:aws:iam::111122223333:role/AutomationServiceRole"
```
**Exemplo 2: definir uma etiqueta como destino usando um par de chave-valor para excluir snapshots do Amazon EBS**
O exemplo a seguir usa o runbook `AWS-DeleteSnapshot` para excluir todos os snapshots com uma chave de *Nome* e um valor de *January2018Backups*. O parâmetro de destino usa o parâmetro *VolumeId*.
```
aws ssm start-automation-execution \
--document-name AWS-DeleteSnapshot \
--targets Key=tag:Name,Values=January2018Backups \
--target-parameter-name VolumeId
```
## como destino AWS Resource Groups
É possível especificar um único grupo de recursos da AWS como o destino de uma automação. O Systems Manager cria uma automação filho para cada objeto no grupo de recursos de destino.
Por exemplo, digamos que um de seus grupos de recursos tenha o nome de PatchedAMIs. Esse grupo de recursos inclui uma lista de 25 Amazon Machine Images (AMIs) do Windows que recebem patches rotineiramente. Se você executar uma automação que use o runbook `AWS-CreateManagedWindowsInstance` e tenha como destino esse grupo de recursos, o Systems Manager criará uma automação filho para cada uma das 25 AMIs. Isso significa que, ao especificar o grupo de recursos PatchedAMIs, a automação cria 25 instâncias em uma lista de corrigidas pelos patches AMIs. A automação pai é concluída quando todas as automações filho finalizam o processamento ou alcançam um estado final.
O comando da AWS CLI a seguir se aplica ao exemplo do grupo de recursos PatchAMIs. O comando usa o parâmetro *Amild* para a opção `--target-parameter-name`. O comando não inclui um parâmetro adicional que define qual tipo de instância criar a partir de cada AMI. O runbook `AWS-CreateManagedWindowsInstance` usa como padrão o tipo de instância t2.medium. Esse comando criaria 25 instâncias t2.medium do Amazon EC2 para o Windows Server.
```
aws ssm start-automation-execution \
--document-name AWS-CreateManagedWindowsInstance \
--targets Key=ResourceGroup,Values=PatchedAMIs \
--target-parameter-name AmiId
```
O exemplo de console a seguir usa um grupo de recursos chamado t2-micro-instances.
![\[Selecionar um grupo de recursos da AWS como destino com uma automação do Systems Manager\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/automation-rate-control-resource-groups-new.png)
## Direcionar valores de parâmetro
Você também pode direcionar um valor de parâmetro. Insira `ParameterValues` como chave e, em seguida, insira o valor do recurso específico em que você deseja que a automação seja executada. Se você especificar vários valores, o Systems Manager executará uma automação secundária em cada valor especificado.
Por exemplo, digamos que o runbook inclui um parâmetro **InstanceID**. Se você direcionar os valores do parâmetro **InstanceID** ao executar o Automation, o Systems Manager executará uma automação filho para cada valor especificado para o ID da instância. A automação pai é concluída quando a automação conclui a execução de cada instância especificada, ou se a automação falha. Você pode direcionar um máximo de 50 valores de parâmetro.
O exemplo a seguir usa o runbook `AWS-CreateImage`. O nome do parâmetro de destino especificado é *InstanceId*. A chave usa *ParameterValues*. Os valores são dois IDs de instâncias do Amazon EC2. Esse comando cria uma automação para cada instância, que produz uma AMI em cada instância.
```
aws ssm start-automation-execution
--document-name AWS-CreateImage \
--target-parameter-name InstanceId \
--targets Key=ParameterValues,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE
```
**nota**
`AutomationAssumeRole` não é um parâmetro válido. Não escolha esse item ao executar fluxos automações que direcionam um valor de parâmetro.
### Direcionar mapas de valores de parâmetros
A opção `TargetMaps` expande sua capacidade de direcionar `ParameterValues`. Você pode inserir um conjunto de valores de parâmetro usando `TargetMaps` na linha de comando. Você pode especificar um máximo de 50 valores de parâmetro na linha de comando. Se quiser executar comandos que especificam mais de 50 valores de parâmetro, você poderá inserir os valores em um arquivo JSON. Você pode, então, chamar o arquivo da linha de comando.
**nota**
A opção `TargetMaps` não tem suporte no console.
Use o formato a seguir para especificar vários valores de parâmetro usando a opção `TargetMaps` em um comando. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
```
aws ssm start-automation-execution \
--document-name runbook name \
--target-maps “parameter=value, parameter 2=value, parameter 3=value” “parameter 4=value, parameter 5=value, parameter 6=value”
```
Se você deseja inserir mais de 50 valores de parâmetro para a opção `TargetMaps`, especifique os valores em um arquivo usando o seguinte formato JSON. Usar um arquivo JSON também melhora a legibilidade ao fornecer vários valores de parâmetro.
```
[
{“parameter”: "value", “parameter 2”: "value", “parameter 3”: "value"},
{“parameter 4”: "value", “parameter 5”: "value", "parameter 6": "value"}
]
```
Salve o arquivo com a extensão .json. Você pode chamar o arquivo usando o seguinte comando: Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
```
aws ssm start-automation-execution \
--document-name runbook name \
–-parameters input parameters \
--target-maps path to file/file name.json
```
Você também pode baixar o arquivo de um bucket do Amazon Simple Storage Service (Amazon S3), desde que tenha permissão para ler dados do bucket. Use o seguinte formato de comando: Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
```
aws ssm start-automation-execution \
--document-name runbook name \
--target-maps http://amzn-s3-demo-bucket.s3.amazonaws.com/file_name.json
```
Este é um cenário de exemplo para ajudar você a compreender a opção `TargetMaps`. Nesse cenário, um usuário deseja criar instâncias do Amazon EC2 de diferentes tipos em diferentes AMIs. Para executar essa tarefa, o usuário cria um runbook chamado AMI\$1Testing. Este runbook define dois parâmetros de entrada: `instanceType` e `imageId`.
```
{
"description": "AMI Testing",
"schemaVersion": "0.3",
"assumeRole": "{{assumeRole}}",
"parameters": {
"assumeRole": {
"type": "String",
"description": "Role under which to run the automation",
"default": ""
},
"instanceType": {
"type": "String",
"description": "Type of EC2 Instance to launch for this test"
},
"imageId": {
"type": "String",
"description": "Source AMI id from which to run instance"
}
},
"mainSteps": [
{
"name": "runInstances",
"action": "aws:runInstances",
"maxAttempts": 1,
"onFailure": "Abort",
"inputs": {
"ImageId": "{{imageId}}",
"InstanceType": "{{instanceType}}",
"MinInstanceCount": 1,
"MaxInstanceCount": 1
}
}
],
"outputs": [
"runInstances.InstanceIds"
]
}
```
O usuário especifica os seguintes valores de parâmetro de destino em um arquivo chamado `AMI_instance_types.json`.
```
[
{
"instanceType" : ["t2.micro"],
"imageId" : ["ami-b70554c8"]
},
{
"instanceType" : ["t2.small"],
"imageId" : ["ami-b70554c8"]
},
{
"instanceType" : ["t2.medium"],
"imageId" : ["ami-cfe4b2b0"]
},
{
"instanceType" : ["t2.medium"],
"imageId" : ["ami-cfe4b2b0"]
},
{
"instanceType" : ["t2.medium"],
"imageId" : ["ami-cfe4b2b0"]
}
]
```
O usuário pode executar a automação e criar as cinco instâncias do EC2 definidas em `AMI_instance_types.json`, executando o seguinte comando:
```
aws ssm start-automation-execution \
--document-name AMI_Testing \
--target-parameter-name imageId \
--target-maps file:///home/TestUser/workspace/runinstances/AMI_instance_types.json
```
## Direcionar todas as instâncias do Amazon EC2
É possível executar uma automação em todas as instâncias do Amazon EC2 na Conta da AWS e na Região da AWS atuais ao escolher **Todas as instâncias** na lista **Destinos**. Por exemplo, se você quiser reiniciar todas as instâncias do Amazon EC2 em sua Conta da AWS e nas Região da AWS atuais, escolha o runbook `AWS-RestartEC2Instance` e selecione **Todas as instâncias** na lista **Destinos**.
![\[Segmentação de todas as instâncias do Amazon EC2 para um runbook\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/automation-rate-control-target-all-instances.png)
Depois de escolher **All instances** (Todas as instâncias), o Systems Manager preenche o campo **Instância** com um asterisco (\$1) e torna o campo indisponível para alterações (o campo ficará esmaecido). O Systems Manager também torna o campo **InstanceId** em **Input parameters** (Parâmetros de entrada) indisponível para alterações. Tornar esses campos indisponíveis para alterações será o comportamento esperado se você optar por direcionar todas as instâncias.
# Automações de controle em grande escala
Você pode controlar a implantação de uma automação em uma frota de recursos da AWS, especificando um valor de simultaneidade e um limite de erro. Simultaneidade e limite de erro são coletivamente chamados de *controles de taxa*.
**Simultaneidade**
Use a simultaneidade para especificar quantos recursos podem executar uma automação simultaneamente. A simultaneidade ajuda a limitar o impacto ou o tempo de inatividade em seus recursos ao processar uma automação. Você pode especificar um número absoluto de recursos, por exemplo, 20 ou uma porcentagem do conjunto de destino, por exemplo, 10%.
O sistema de fila fornece a automação a um único recurso e aguarda até que a invocação inicial seja concluída antes de enviar a automação para mais dois recursos. O sistema envia a automação de forma exponencial para mais recursos até que o valor de simultaneidade seja atingido.
**Limites de erro**
Um limite de erro permite que você especifique quantas automações podem falhar antes que o AWS Systems Manager pare de enviá-las para outros recursos. Você pode especificar um número absoluto de erros, como 10, ou uma porcentagem do conjunto de destino, como 10%.
Se você especificar um número absoluto de 3 erros, por exemplo, o sistema deixará de executar a automação quando o quarto erro for recebido. Se você especificar 0, o sistema deixará de executar a automação em destinos adicionais depois que o primeiro resultado do erro for retornado.
Se você enviar uma automação para 50 instâncias, por exemplo, e definir o limite de erro como 10%, o sistema deixará de enviar o comando para instâncias adicionais quando o quinto erro for recebido. As invocações que já estiverem executando uma automação, quando um limite de erro for atingido, poderão ser concluídas, mas algumas dessas automações também podem falhar. Se você precisar garantir que não haverá mais erros do que o número especificado para o limite de erro, defina o valor de **Concurrency** (Simultaneidade) como 1 para que as automações prossigam uma de cada vez.
# Executar automações em várias regiões e contas da Regiões da AWS
Você pode executar automações do AWS Systems Manager em várias Regiões da AWS e Contas da AWS ou em unidades organizacionais (UOs) do AWS Organizations em uma conta central. O Automation é uma ferramenta do AWS Systems Manager. Executar automações em várias regiões e contas ou UOs reduz o tempo necessário para administrar os recursos da AWS, ao mesmo tempo em que melhora a segurança do ambiente de computação.
Por exemplo, você pode fazer o seguinte usando runbooks de automação:
+ Implementar atualizações de patches e segurança de maneira centralizada.
+ Corrigir desvios de conformidade em configurações da VPC ou em políticas de bucket do Amazon S3.
+ Gerenciar recursos, como instâncias do EC2 do Amazon Elastic Compute Cloud (Amazon EC2), em grande escala.
O diagrama a seguir mostra um exemplo de um usuário que está executando o runbook `AWS-RestartEC2Instances` em várias regiões e contas usando uma conta central. A automação localiza as instâncias usando as tags especificadas nas regiões e contas de destino.
![\[Ilustração mostrando a execução do Systems Manager Automation em várias regiões e contas.\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/automation-multi-region-and-multi-account.png)
**Escolher uma conta central para o Automation**
Se você quiser executar automações em UOs, a conta central deve ter permissões para listar todas as contas nas UOs. Isso só é possível usando uma conta de administrador delegado ou a conta de gerenciamento da organização. Recomendamos seguir as práticas recomendadas do AWS Organizations e usar uma conta de administrador delegado. Para obter mais informações sobre as práticas recomendadas do AWS Organizations, consulte [Práticas recomendadas para a conta de gerenciamento](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_best-practices_mgmt-acct.html) no *Guia do usuário do AWS Organizations*. Para criar uma conta de administrador delegado para o Systems Manager, você pode usar o comando `register-delegated-administrator` com a AWS CLI, conforme exibido no exemplo a seguir.
```
aws organizations register-delegated-administrator \
--account-id delegated admin account ID \
--service-principal ssm.amazonaws.com
```
Se você quiser executar automações em várias contas que não sejam gerenciadas pelo AWS Organizations, recomendamos a criação de uma conta dedicada para o gerenciamento de automação. A execução de todas as automações entre contas usando uma conta dedicada simplifica o gerenciamento de permissões do IAM, os esforços de solução de problemas e cria uma camada de separação entre operações e administração. Essa abordagem também é recomendada se você usar o AWS Organizations, mas só quiser segmentar contas individuais e não UOs.
**Funcionamento da execução de automações**
Executar automações em várias regiões e contas ou UOs ocorre da seguinte forma:
1. Acesse a conta que você deseja configurar como a conta central do Automation.
1. Siga o procedimento [Configurar permissões da conta de gerenciamento para execução da automação de várias regiões e contas](#setup-management-account-iam-roles) neste tópico para criar os seguintes perfis do IAM:
+ `AWS-SystemsManager-AutomationAdministrationRole`: essa função permite que o usuário execute automação em várias contas e UOs.
+ `AWS-SystemsManager-AutomationExecutionRole`: essa função permite que o usuário execute automação nas contas de destino.
1. Escolha o runbook, as regiões e as contas ou OUs em que você deseja executar a automação.
**nota**
Certifique-se de que a UO de destino contenha as contas desejadas. Se você escolher um runbook personalizado, ele deverá ser compartilhado com todas as contas de destino. Para obter informações sobre como compartilhar runbooks, consulte [Compartilhar documentos do Systems Manager](documents-ssm-sharing.md). Para obter informações sobre como usar runbooks compartilhados, consulte [Usar documentos compartilhados do](documents-ssm-sharing.md#using-shared-documents).
1. Execute a automação.
1. Use as operações de API [GetAutomationExecution](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetAutomationExecution.html), [DescribeAutomationStepExecutions](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeAutomationStepExecutions.html) e [DescribeAutomationExecutions](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeAutomationExecutions.html) no console do AWS Systems Manager ou o AWS CLI para monitorar o andamento da automação. O resultado das etapas para a automação em sua conta principal será o `AutomationExecutionId`das automações filho. Para exibir a saída das automações filho criadas em suas contas de destino, especifique a conta, região e `AutomationExecutionId` apropriadas na sua solicitação.
## Configurar permissões da conta de gerenciamento para execução da automação de várias regiões e contas
Use o procedimento a seguir para criar as funções do IAM necessárias para a automação do Systems Manager Automation em várias regiões e várias contas, usando o AWS CloudFormation. Esse procedimento descreve como criar a função `AWS-SystemsManager-AutomationAdministrationRole`. Você só precisa criar essa função na conta de gerenciamento do Automation. Esse procedimento também descreve como criar a função `AWS-SystemsManager-AutomationExecutionRole`. Você deve criar essa função em *todas* as contas que deseja direcionar para executar automações em várias regiões e contas. Recomendamos usar o CloudFormation StackSets para criar a função `AWS-SystemsManager-AutomationExecutionRole` nas contas que você quiser direcionar para executar automações em várias regiões e contas.
**Criar as funções de administração do IAM necessárias para automações em várias regiões e várias contas usando o CloudFormation**
1. Faça download e descompacte [https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWS-SystemsManager-AutomationAdministrationRole.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWS-SystemsManager-AutomationAdministrationRole.zip).
- ou -
Se suas contas forem gerenciadas pelo AWS Organizations [https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWS-SystemsManager-AutomationAdministrationRole (org).zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWS-SystemsManager-AutomationAdministrationRole (org).zip).
Esses arquivos contêm os modelos de arquivos `AWS-SystemsManager-AutomationAdministrationRole.yaml` e `AWS-SystemsManager-AutomationAdministrationRole (org).yaml` CloudFormation, respectivamente.
1. Abra o console do CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Selecione **Criar pilha**.
1. Na seção **Specify template** (Especificar modelo) escolha **Upload a template ** (Fazer upload de um modelo).
1. Selecione **Escolher arquivo** e, em seguida, selecione o modelo de arquivo `AWS-SystemsManager-AutomationAdministrationRole.yaml` ou `AWS-SystemsManager-AutomationAdministrationRole (org).yaml` CloudFormation, dependendo da sua seleção na etapa 1.
1. Escolha **Próximo**.
1. Na página **Specify stack details (Especificar detalhes da tarefa)**, no campo **Stack name (Nome da pilha)**, insira um nome.
1. Escolha **Próximo**.
1. Na página **Configure stack options** (Configurar opções de pilha), insira valores para as opções que você quiser usar. Escolha **Próximo**.
1. Na página **Review** (Revisão) role para baixo e escolha a opção **I acknowledge that CloudFormation might create IAM resources with custom names** (Estou ciente de que o poderá criar recursos do IAM com nomes personalizados).
1. Selecione **Criar pilha**.
O CloudFormation mostra o status **CREATE\$1IN\$1PROGRESS** por cerca de três minutos. O status mudará para **CREATE\$1COMPLETE**.
É necessário repetir esse procedimento em *todas* as contas que você quiser direcionar para executar automações em várias regiões e contas.
**Criar as funções de automação do IAM necessárias para automações em várias regiões e várias contas usando o CloudFormation**
1. Faça download do [https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWS-SystemsManager-AutomationExecutionRole.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWS-SystemsManager-AutomationExecutionRole.zip).
ou
Se suas contas forem gerenciadas pelo AWS Organizations [https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWS-SystemsManager-AutomationExecutionRole (org).zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWS-SystemsManager-AutomationExecutionRole (org).zip).
Esses arquivos contêm os modelos de arquivos `AWS-SystemsManager-AutomationExecutionRole.yaml` e `AWS-SystemsManager-AutomationExecutionRole (org).yaml`CloudFormation, respectivamente.
1. Abra o console do CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Selecione **Criar pilha**.
1. Na seção **Specify template** (Especificar modelo) escolha **Upload a template ** (Fazer upload de um modelo).
1. Selecione **Escolher arquivo** e, em seguida, selecione o modelo de arquivo `AWS-SystemsManager-AutomationExecutionRole.yaml` ou `AWS-SystemsManager-AutomationExecutionRole (org).yaml` CloudFormation, dependendo da sua seleção na etapa 1.
1. Escolha **Próximo**.
1. Na página **Specify stack details (Especificar detalhes da tarefa)**, no campo **Stack name (Nome da pilha)**, insira um nome.
1. Na seção **Parameters** (Parâmetros), no campo **AdminAccountId**, insira o ID da conta central do Automation.
1. Se você estiver configurando essa função para um ambiente AWS Organizations, haverá outro campo chamado **OrganizationId** na seção. Insira o ID da sua organização da AWS.
1. Escolha **Próximo**.
1. Na página **Configure stack options** (Configurar opções de pilha), insira valores para as opções que você quiser usar. Escolha **Próximo**.
1. Na página **Review** (Revisão) role para baixo e escolha a opção **I acknowledge that CloudFormation might create IAM resources with custom names** (Estou ciente de que o poderá criar recursos do IAM com nomes personalizados).
1. Selecione **Criar pilha**.
O CloudFormation mostra o status **CREATE\$1IN\$1PROGRESS** por cerca de três minutos. O status mudará para **CREATE\$1COMPLETE**.
## Execute uma automação em várias regiões e contas (console)
O procedimento a seguir descreve como usar o console do Systems Manager para executar uma automação em várias regiões e contas da conta de gerenciamento do Automation.
**Antes de começar**
Antes de concluir o seguinte procedimento, anote as seguintes informações:
+ O usuário ou o perfil usado para executar uma automação em diversas regiões ou diversas contas deve ter a permissão `iam:PassRole` para o perfil `AWS-SystemsManager-AutomationAdministrationRole`.
+ Conta da AWSIDs de contas da ou UOs nos quais você deseja executar a automação.
+ [Regiões suportadas pelo Systems Manager](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) onde você deseja executar a automação.
+ A chave e o valor da tag, ou o nome do grupo de recursos, nos quais você deseja executar a automação.
**Para executar uma automação em várias regiões e contas**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, selecione **Automation** e **Execute automation (Executar automação)**.
1. Na lista **Automation document** (Documento do Automation), escolha um runbook. Escolha uma ou mais opções no painel **Document categories** (Categorias de documentos) para filtrar documentos SSM de acordo com sua finalidade. Para visualizar um runbook que você tenha, escolha a guia **Owned by me** (De minha propriedade). Para visualizar um runbook compartilhado com sua conta, escolha a guia **Shared with me** (Compartilhado comigo). Para visualizar todos os runbooks, escolha a guia **All documents** (Todos os documentos).
**nota**
Você pode visualizar informações sobre um runbook, selecionando o nome dele.
1. Na seção **Document details** (Detalhes do documento), verifique se **Document version** (Versão do documento) está definida como a versão que você quer executar. O sistema inclui as seguintes opções de versão:
+ **Versão padrão no runtime**: escolha essa opção se o runbook do Automation for atualizado periodicamente e uma nova versão padrão for atribuída.
+ **Versão mais recente no runtime**: escolha essa opção se o runbook do Automation for atualizado periodicamente e se você quiser executar a versão mais recente.
+ **1 (padrão):** escolha esta opção para executar a primeira versão do documento, que é a versão padrão.
1. Escolha **Próximo**.
1. Na página **Execute automation document (Executar documento de automação)**, escolha **Multi-account and Region (Várias contas e região)**.
1. Na seção **Regiões e contas de destino**, use o campo **Contas e unidades organizacionais, (UOs) e raízes** para especificar as diferentes Contas da AWS ou unidades organizacionais (UOs) da AWS em que você deseja executar a automação. Separe várias contas ou UOs com uma vírgula.
1. (Opcional) Selecione a caixa de seleção **Incluir UOs subordinadas** para incluir todas as unidades organizacionais subordinadas nas UOs especificadas.
1. (Opcional) No campo **Excluir contas e unidades organizacionais (UOs)**, insira uma lista separada por vírgulas de IDs de conta e IDs de UO que você deseja excluir das entidades expandidas inseridas acima.
1. Use a lista **Regiões da AWS** para escolher uma ou mais regiões em que você deseja executar a automação.
1. Use as opções **Multi-Region and account rate control** (Controle da taxa de várias contas e regiões) para restringir a execução da automação para um número limitado de contas em execução em um número limitado de regiões. Essas opções não restringem o número de recursos da AWS que podem executar as automações.
1. Na seção **Location (account-Region pair) concurrency** (Simultaneidade da localização - par conta/região), escolha uma opção para restringir o número de automações que podem ser executadas em várias contas e regiões ao mesmo tempo. Por exemplo, se você optar por executar uma automação em cinco (5) contas da Contas da AWS que estiverem localizadas em quatro (4) Regiões da AWS, o Systems Manager executará as automações em um total de 20 pares de conta/região. Você pode usar essa opção para especificar um número absoluto, como **2**, para que a automação seja executada simultaneamente em apenas dois pares de contas ou regiões. Outra opção é especificar uma porcentagem dos pares conta/região que podem ser executados ao mesmo tempo. Por exemplo, com 20 pares de conta/região, se você especificar 20%, a automação será executada simultaneamente em um máximo de cinco (5) pares de conta/região.
+ Escolha **targets** (destinos) para inserir um número absoluto de pares de conta/região que podem executar a automação simultaneamente.
+ Escolha **percent (por cento)** para inserir uma porcentagem do número total de pares de contas/regiões que podem executar a automação simultaneamente.
1. Na seção **Error threshold (Limite de erro)**, escolha uma opção:
+ Escolha **errors** (erros) para inserir um número absoluto de erros permitidos antes que o Automation pare de enviar a automação para outros recursos.
+ Escolha **percent** (por cento) para inserir uma porcentagem de erros permitidos antes que o Automation deixe de enviar a automação para outros recursos.
1. Na seção **Targets** (Destinos), escolha como você quer definir os destinos dos recursos da AWS em que você deseja executar o Automation. Essas opções são obrigatórias.
1. Use a lista **Parameter (Parâmetro)** para escolher um parâmetro. Os itens na lista **Parameter** (Parâmetro) são determinados pelos parâmetros no runbook do Automation que você selecionou no início deste procedimento. Ao escolher um parâmetro, você define o tipo de recurso em que o fluxo de trabalho da Automação é executado.
1. Use a lista **Targets (Destinos)** para escolher como você deseja definir o destino dos recursos.
1. Se você optar por definir o destino dos recursos usando valores de parâmetro, insira o valor do parâmetro para aquele escolhido na seção **Input parameters** (Parâmetros de entrada).
1. Se você escolher definir o destino dos recursos usando o AWS Resource Groups, escolha o nome do grupo na lista **Resource Group (Grupo de recursos)**.
1. Se você optar por definir o destino dos recursos usando tags, insira a chave de tag e (opcionalmente) o valor da tag nos campos fornecidos. Escolha **Adicionar**.
1. Se você quiser executar um runbook do Automation em todas as instâncias nas Conta da AWS e Região da AWS atuais, escolha **All instances** (Todas as instâncias).
1. Na seção **Input parameters (Parâmetros de entrada)**, especifique as entradas necessárias. Escolha o perfil de serviço do IAM `AWS-SystemsManager-AutomationAdministrationRole` na lista **AutomationAssumeRole**.
**nota**
Pode ser que não seja necessário escolher algumas das opções na seção **Input parameters** (Parâmetros de entrada). Isso ocorre porque você definiu o destino de recursos em várias regiões e contas usando tags ou um grupo de recursos. Por exemplo, se você escolheu o runbook `AWS-RestartEC2Instance`, você não precisará especificar ou escolher IDs de instância na seção **Input parameters** (Parâmetros de entrada). A automação localiza as instâncias para reiniciar usando as tags que você especificou.
1. (Opcional) Escolha um alarme do CloudWatch a fim de aplicar à sua automação para monitoramento. Para anexar um alarme do CloudWatch à sua automação, a entidade principal do IAM que inicia a automação deve ter permissão para a ação `iam:createServiceLinkedRole`. Para obter mais informações sobre alarmes do CloudWatch, consulte [Usar alarmes do Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html). A automação será cancelada se o alarme for ativado, e as etapas `OnCancel` que você definiu serão executadas. Se você usar o AWS CloudTrail, você verá a chamada de API em sua trilha.
1. Use as opções na seção **Rate control** (Controle de taxa) para restringir o número de recursos da AWS que podem executar o Automation dentro de cada par conta-região.
Na seção **Concurrency** (Simultaneidade), escolha uma opção:
+ Escolha **Targets (Destinos)** para inserir um número absoluto de destinos que podem executar o fluxo de trabalho de Automação simultaneamente.
+ Escolha **Percentage (Porcentagem)** para inserir uma porcentagem do conjunto de destino que pode executar o fluxo de trabalho de Automação simultaneamente.
1. Na seção **Error threshold (Limite de erro)**, escolha uma opção:
+ Escolha **errors (erros)** para inserir um número absoluto de erros permitidos antes que a Automação deixe de enviar o fluxo de trabalho para outros recursos.
+ Escolha **percentage (porcentagem)** para inserir uma porcentagem de erros permitidos antes que a Automação deixe de enviar o fluxo de trabalho para outros recursos.
1. Clique em **Executar**.
Depois que uma execução de automação for concluída, você pode executá-la novamente com os mesmos parâmetros ou com parâmetros modificados. Para obter mais informações, consulte [Executar novamente as execuções de automação](automation-rerun-executions.md).
## Executar uma automação em várias regiões e contas (linha de comando)
O procedimento a seguir descreve como usar a AWS CLI (no Linux ou no Windows) ou o Ferramentas da AWS para PowerShell para executar uma automação em várias regiões e contas da conta de gerenciamento do Automation.
**Antes de começar**
Antes de concluir o seguinte procedimento, anote as seguintes informações:
+ Conta da AWSIDs de contas da ou UOs nos quais você deseja executar a automação.
+ [Regiões suportadas pelo Systems Manager](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) onde você deseja executar a automação.
+ A chave e o valor da tag, ou o nome do grupo de recursos, nos quais você deseja executar a automação.
**Para executar uma automação em várias regiões e contas**
1. Instale e configure a AWS CLI ou o Ferramentas da AWS para PowerShell, caso ainda não o tenha feito.
Para obter informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) e [Instalar o Ferramentas da AWS para PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
1. Use o formato a seguir para criar um comando para executar uma automação em várias regiões e contas: Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name runbook name \
--parameters AutomationAssumeRole=arn:aws:iam::management account ID:role/AWS-SystemsManager-AutomationAdministrationRole \
--target-parameter-name parameter name \
--targets Key=tag key,Values=value \
--target-locations Accounts=account ID,account ID 2,Regions=Region,Region 2,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name runbook name ^
--parameters AutomationAssumeRole=arn:aws:iam::management account ID:role/AWS-SystemsManager-AutomationAdministrationRole ^
--target-parameter-name parameter name ^
--targets Key=tag key,Values=value ^
--target-locations Accounts=account ID,account ID 2,Regions=Region,Region 2,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
```
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "tag key"
$Targets.Values = "value"
Start-SSMAutomationExecution `
-DocumentName "runbook name" `
-Parameter @{
"AutomationAssumeRole"="arn:aws:iam::management account ID:role/AWS-SystemsManager-AutomationAdministrationRole" } `
-TargetParameterName "parameter name" `
-Target $Targets `
-TargetLocation @{
"Accounts"="account ID","account ID 2";
"Regions"="Region","Region 2";
"ExecutionRoleName"="AWS-SystemsManager-AutomationExecutionRole" }
```
------
**Exemplo: executar uma automação em várias regiões e contas**
Veja a seguir exemplos que demonstram como usar o AWS CLI e o PowerShell para executar automações em várias contas e regiões com um único comando.
**Exemplo 1**: este exemplo reinicia instâncias do EC2 em três regiões em uma organização do AWS Organizations inteira. Para fazer isso, é necessário usar o ID da conta de usuário-raiz da organização como alvo e incluir OUs secundárias.
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name "AWS-RestartEC2Instance" \
--target-parameter-name InstanceId \
--targets '[{"Key":"AWS::EC2::Instance","Values":["*"]}]' \
--target-locations '[{
"Accounts": ["r-example"],
"IncludeChildOrganizationUnits": true,
"Regions": ["us-east-1", "us-east-2", "us-west-2"]
}]'
```
------
#### [ Windows ]
```
aws ssm start-automation-execution \
--document-name "AWS-RestartEC2Instance" ^
--target-parameter-name InstanceId ^
--targets '[{"Key":"AWS::EC2::Instance","Values":["*"]}]' ^
--target-locations '[{
"Accounts": ["r-example"],
"IncludeChildOrganizationUnits": true,
"Regions": ["us-east-1", "us-east-2", "us-west-2"]
}]'
```
------
#### [ PowerShell ]
```
Start-SSMAutomationExecution `
-DocumentName "AWS-RestartEC2Instance" `
-TargetParameterName "InstanceId" `
-Targets '[{"Key":"AWS::EC2::Instance","Values":["*"]}]'
-TargetLocation @{
"Accounts"="r-example";
"Regions"="us-east-1", "us-east-2", "us-west-2";
"IncludeChildOrganizationUnits"=true}
```
------
**Exemplo 2**: este exemplo reinicia instâncias específicas do EC2 em contas e regiões diferentes.
**nota**
A opção `TargetLocationMaxConcurrency` está disponível usando os SDKs AWS CLI e AWS.
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name "AWS-RestartEC2Instance" \
--target-parameter-name InstanceId \
--target-locations '[{
"Accounts": ["123456789012"],
"Targets": [{
"Key":"ParameterValues",
"Values":["i-02573cafcfEXAMPLE", "i-0471e04240EXAMPLE"]
}],
"TargetLocationMaxConcurrency": "100%",
"Regions": ["us-east-1"]
}, {
"Accounts": ["987654321098"],
"Targets": [{
"Key":"ParameterValues",
"Values":["i-07782c72faEXAMPLE"]
}],
"TargetLocationMaxConcurrency": "100%",
"Regions": ["us-east-2"]
}]'
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name "AWS-RestartEC2Instance" ^
--target-parameter-name InstanceId ^
--target-locations '[{
"Accounts": ["123456789012"],
"Targets": [{
"Key":"ParameterValues",
"Values":["i-02573cafcfEXAMPLE", "i-0471e04240EXAMPLE"]
}],
"TargetLocationMaxConcurrency": "100%",
"Regions": ["us-east-1"]
}, {
"Accounts": ["987654321098"],
"Targets": [{
"Key":"ParameterValues",
"Values":["i-07782c72faEXAMPLE"]
}],
"TargetLocationMaxConcurrency": "100%",
"Regions": ["us-east-2"]
}]'
```
------
#### [ PowerShell ]
```
Start-SSMAutomationExecution `
-DocumentName "AWS-RestartEC2Instance" `
-TargetParameterName "InstanceId" `
-Targets '[{"Key":"AWS::EC2::Instance","Values":["*"]}]'
-TargetLocation @({
"Accounts"="123456789012",
"Targets"= @{
"Key":"ParameterValues",
"Values":["i-02573cafcfEXAMPLE", "i-0471e04240EXAMPLE"]
},
"TargetLocationMaxConcurrency"="100%",
"Regions"=["us-east-1"]
}, {
"Accounts"="987654321098",
"Targets": @{
"Key":"ParameterValues",
"Values":["i-07782c72faEXAMPLE"]
},
"TargetLocationMaxConcurrency": "100%",
"Regions"=["us-east-2"]
})
```
------
**Exemplo 3**: este exemplo demonstra a especificação de várias contas Contas da AWS e regiões em que a automação deve ser executada usando a opção `--target-locations-url`. O valor dessa opção deve ser um arquivo JSON em uma [URL pré-assinada do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html) acessível ao público.
**nota**
`--target-locations-url` está disponível ao usar os SDKs AWS CLI e AWS.
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name "MyCustomAutomationRunbook" \
--target-locations-url "https://amzn-s3-demo-bucket.s3.amazonaws.com/target-locations.json"
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name "MyCustomAutomationRunbook" ^
--target-locations-url "https://amzn-s3-demo-bucket.s3.amazonaws.com/target-locations.json"
```
------
#### [ PowerShell ]
```
Start-SSMAutomationExecution `
-DocumentName "MyCustomAutomationRunbook" `
-TargetLocationsUrl "https://amzn-s3-demo-bucket.s3.amazonaws.com/target-locations.json"
```
------
Conteúdo de amostra para o arquivo JSON:
```
[
{
"Accounts": [ "123456789012", "987654321098", "456789123012" ],
"ExcludeAccounts": [ "111222333444", "999888444666" ],
"ExecutionRoleName": "MyAutomationExecutionRole",
"IncludeChildOrganizationUnits": true,
"Regions": [ "us-east-1", "us-west-2", "ap-south-1", "ap-northeast-1" ],
"Targets": ["Key": "AWS::EC2::Instance", "Values": ["i-2"]],
"TargetLocationMaxConcurrency": "50%",
"TargetLocationMaxErrors": "10",
"TargetsMaxConcurrency": "20",
"TargetsMaxErrors": "12"
}
]
```
**Exemplo 4**: este exemplo reinicia instâncias do EC2 nas contas `123456789012` e `987654321098`, que estão localizadas nas regiões `us-east-2` e `us-west-1`. As instâncias devem ser marcadas com o valor do par de chaves da tag `Env-PROD`.
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name AWS-RestartEC2Instance \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole \
--target-parameter-name InstanceId \
--targets Key=tag:Env,Values=PROD \
--target-locations Accounts=123456789012,987654321098,Regions=us-east-2,us-west-1,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name AWS-RestartEC2Instance ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole ^
--target-parameter-name InstanceId ^
--targets Key=tag:Env,Values=PROD ^
--target-locations Accounts=123456789012,987654321098,Regions=us-east-2,us-west-1,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
```
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "tag:Env"
$Targets.Values = "PROD"
Start-SSMAutomationExecution `
-DocumentName "AWS-RestartEC2Instance" `
-Parameter @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole" } `
-TargetParameterName "InstanceId" `
-Target $Targets `
-TargetLocation @{
"Accounts"="123456789012","987654321098";
"Regions"="us-east-2","us-west-1";
"ExecutionRoleName"="AWS-SystemsManager-AutomationExecutionRole" }
```
------
**Exemplo 5**: este exemplo reinicia instâncias do EC2 nas contas `123456789012` e `987654321098`, as quais estão localizadas na região `eu-central-1`. As instâncias devem ser membros do grupo de recursos `prod-instances` da AWS.
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name AWS-RestartEC2Instance \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole \
--target-parameter-name InstanceId \
--targets Key=ResourceGroup,Values=prod-instances \
--target-locations Accounts=123456789012,987654321098,Regions=eu-central-1,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name AWS-RestartEC2Instance ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole ^
--target-parameter-name InstanceId ^
--targets Key=ResourceGroup,Values=prod-instances ^
--target-locations Accounts=123456789012,987654321098,Regions=eu-central-1,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
```
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "ResourceGroup"
$Targets.Values = "prod-instances"
Start-SSMAutomationExecution `
-DocumentName "AWS-RestartEC2Instance" `
-Parameter @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole" } `
-TargetParameterName "InstanceId" `
-Target $Targets `
-TargetLocation @{
"Accounts"="123456789012","987654321098";
"Regions"="eu-central-1";
"ExecutionRoleName"="AWS-SystemsManager-AutomationExecutionRole" }
```
------
**Exemplo 6**: este exemplo reinicia instâncias do EC2 na unidade organizacional (UO) `ou-1a2b3c-4d5e6c` da AWS. As instâncias estão localizadas nas regiões `us-west-1` e `us-west-2`. As instâncias devem ser membros do grupo de recursos `WebServices` da AWS.
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name AWS-RestartEC2Instance \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole \
--target-parameter-name InstanceId \
--targets Key=ResourceGroup,Values=WebServices \
--target-locations Accounts=ou-1a2b3c-4d5e6c,Regions=us-west-1,us-west-2,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name AWS-RestartEC2Instance ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole ^
--target-parameter-name InstanceId ^
--targets Key=ResourceGroup,Values=WebServices ^
--target-locations Accounts=ou-1a2b3c-4d5e6c,Regions=us-west-1,us-west-2,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
```
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "ResourceGroup"
$Targets.Values = "WebServices"
Start-SSMAutomationExecution `
-DocumentName "AWS-RestartEC2Instance" `
-Parameter @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole" } `
-TargetParameterName "InstanceId" `
-Target $Targets `
-TargetLocation @{
"Accounts"="ou-1a2b3c-4d5e6c";
"Regions"="us-west-1";
"ExecutionRoleName"="AWS-SystemsManager-AutomationExecutionRole" }
```
------
O sistema retorna informações semelhantes às seguintes.
------
#### [ Linux & macOS ]
```
{
"AutomationExecutionId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE"
}
```
------
#### [ Windows ]
```
{
"AutomationExecutionId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE"
}
```
------
#### [ PowerShell ]
```
4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE
```
------
1. Execute o comando a seguir para visualizar os detalhes sobre a automação. Substitua *automation execution ID* (ID de execução da automação) por suas próprias informações.
------
#### [ Linux & macOS ]
```
aws ssm describe-automation-executions \
--filters Key=ExecutionId,Values=automation execution ID
```
------
#### [ Windows ]
```
aws ssm describe-automation-executions ^
--filters Key=ExecutionId,Values=automation execution ID
```
------
#### [ PowerShell ]
```
Get-SSMAutomationExecutionList | `
Where {$_.AutomationExecutionId -eq "automation execution ID"}
```
------
1. Execute o comando a seguir para visualizar os detalhes sobre o andamento da automação.
------
#### [ Linux & macOS ]
```
aws ssm get-automation-execution \
--automation-execution-id 4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE
```
------
#### [ Windows ]
```
aws ssm get-automation-execution ^
--automation-execution-id 4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE
```
------
#### [ PowerShell ]
```
Get-SSMAutomationExecution `
-AutomationExecutionId a4a3c0e9-7efd-462a-8594-01234EXAMPLE
```
------
**nota**
Você pode também monitorar o status da automação no console. Na lista de **execuções do Automation**, escolha a execução que você acabou de processar e depois escolha a guia **Execution steps** (Etapas da execução). Esta guia mostra o status das ações de automação.
**Mais informações**
[Aplicação de patch centralizada em várias contas e regiões com a Automação do AWS Systems Manager](https://aws.amazon.com/blogs/mt/centralized-multi-account-and-multi-region-patching-with-aws-systems-manager-automation/)
# Executar automações com base em eventos do EventBridge
Você pode iniciar uma automação especificando um runbook como o destino de um evento do Amazon EventBridge. É possível iniciar automações de acordo com um cronograma ou quando ocorrer um evento específico do sistema da AWS. Por exemplo, digamos que você crie um runbook chamado *BootStrapInstances*, que instala softwares em uma instância quando ela for iniciada. Para especificar o runbook *BootStrapInstances* (e a automação correspondente) como um destino de um evento do EventBridge, primeiro crie uma nova regra do EventBridge. (Aqui está uma regra de exemplo: **Nome do serviço**: EC2, **Tipo de evento**: Notificação de alteração de status da instância do EC2, **Estado(s) específico(s)**: em execução, **Qualquer instância**.) Depois, use os seguintes procedimentos para especificar o runbook *BootStrapInstances* como o destino do evento, usando o console do EventBridge e a AWS Command Line Interface (AWS CLI). Quando uma nova instância for iniciada, o sistema executará a automação e instalará o software.
Para obter informações sobre como criar runbooks, consulte [Criação dos seus próprios runbooks](automation-documents.md).
## Criar um evento do EventBridge que use um runbook (console)
Use o procedimento a seguir para configurar um runbook como o destino de um evento do EventBridge.
**Para configurar um runbook como destino de uma regra de evento do EventBridge**
1. Abra o console do Amazon EventBridge em [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. No painel de navegação, escolha **Regras**.
1. Escolha **Create rule**.
1. Insira um nome e uma descrição para a regra.
Uma regra não pode ter o mesmo nome que outra na mesma Região e barramento de eventos.
1. Em **Barramento de eventos**, selecione o barramento de eventos que você deseja associar a essa regra. Se você quiser que essa regra responda a eventos correspondentes provenientes da sua Conta da AWS, selecione **default** (padrão). Quando um AWS service (Serviço da AWS) na sua conta emite um evento, ele sempre vai para o barramento de eventos padrão da sua conta.
1. Escolha como a regra é acionada.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/running-automations-event-bridge.html)
1. Escolha **Next** (Avançar).
1. Em **Target types** (Tipos de destinos), escolha **AWS service** (Serviço da AWS).
1. Para **Select a target** (Selecionar um destino), escolha **Systems Manager Automation** (Automation do Systems Manager).
1. Para **Document** (Documento), escolha um runbook a ser usado quando o destino for invocado.
1. Na seção **Configure automation parameter(s)** (Configurar parâmetros de automação), mantenha os valores dos parâmetros padrão (se disponíveis) ou insira seus próprios valores.
**nota**
Para criar um destino, você deve especificar um valor para cada parâmetro obrigatório. Se não fizer isso, o sistema criará a regra, mas a regra não será executada.
1. Para muitos tipos de destino, o Eventbridge precisa de permissões para enviar eventos ao destino. Nesses casos, o Eventbridge pode criar o perfil do IAM necessário para o perfil ser executado. Execute um destes procedimentos:
+ Para criar um perfil do IAM automaticamente, escolha **Criar um novo perfil para este recurso específico**.
+ Para usar um perfil do IAM que você criou anteriormente, escolha **Use existing role** (Usar função existente). Observe que talvez seja necessário atualizar a política de confiança do seu perfil do IAM para incluir o EventBridge. Este é um exemplo:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": [
"events.amazonaws.com",
"ssm.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. Escolha **Próximo**.
1. (Opcional) Insira uma ou mais tags para a regra. Para obter mais informações, consulte [Marcar recursos do Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-tagging.html) no *Guia do usuário do Amazon EventBridge*.
1. Escolha **Próximo**.
1. Analise os detalhes da regra e selecione **Criar regra**.
## Crie um evento do EventBridge que use um runbook (linha de comando)
O procedimento a seguir descreve como usar a AWS CLI (no Linux ou no Windows) ou o Ferramentas da AWS para PowerShell para criar uma regra de evento do EventBridge e configurar um runbook como o destino.
**Para configurar um runbook como destino de uma regra de evento do EventBridge**
1. Instale e configure a AWS CLI ou o Ferramentas da AWS para PowerShell, caso ainda não o tenha feito.
Para obter informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) e [Instalar o Ferramentas da AWS para PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
1. Crie um comando para especificar uma nova regra de evento do EventBridge. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
*Triggers com base em uma programação*
------
#### [ Linux & macOS ]
```
aws events put-rule \
--name "rule name" \
--schedule-expression "cron or rate expression"
```
------
#### [ Windows ]
```
aws events put-rule ^
--name "rule name" ^
--schedule-expression "cron or rate expression"
```
------
#### [ PowerShell ]
```
Write-CWERule `
-Name "rule name" `
-ScheduleExpression "cron or rate expression"
```
------
O exemplo a seguir cria uma regra de evento do EventBridge que é iniciada todos os dias às 9h (UTC).
------
#### [ Linux & macOS ]
```
aws events put-rule \
--name "DailyAutomationRule" \
--schedule-expression "cron(0 9 * * ? *)"
```
------
#### [ Windows ]
```
aws events put-rule ^
--name "DailyAutomationRule" ^
--schedule-expression "cron(0 9 * * ? *)"
```
------
#### [ PowerShell ]
```
Write-CWERule `
-Name "DailyAutomationRule" `
-ScheduleExpression "cron(0 9 * * ? *)"
```
------
*Dispara com base em um evento*
------
#### [ Linux & macOS ]
```
aws events put-rule \
--name "rule name" \
--event-pattern "{\"source\":[\"aws.service\"],\"detail-type\":[\"service event detail type\"]}"
```
------
#### [ Windows ]
```
aws events put-rule ^
--name "rule name" ^
--event-pattern "{\"source\":[\"aws.service\"],\"detail-type\":[\"service event detail type\"]}"
```
------
#### [ PowerShell ]
```
Write-CWERule `
-Name "rule name" `
-EventPattern '{"source":["aws.service"],"detail-type":["service event detail type"]}'
```
------
O exemplo a seguir cria uma regra de evento do EventBridge que é iniciada quando o estado de qualquer instância do EC2 na região é alterado.
------
#### [ Linux & macOS ]
```
aws events put-rule \
--name "EC2InstanceStateChanges" \
--event-pattern "{\"source\":[\"aws.ec2\"],\"detail-type\":[\"EC2 Instance State-change Notification\"]}"
```
------
#### [ Windows ]
```
aws events put-rule ^
--name "EC2InstanceStateChanges" ^
--event-pattern "{\"source\":[\"aws.ec2\"],\"detail-type\":[\"EC2 Instance State-change Notification\"]}"
```
------
#### [ PowerShell ]
```
Write-CWERule `
-Name "EC2InstanceStateChanges" `
-EventPattern '{"source":["aws.ec2"],"detail-type":["EC2 Instance State-change Notification"]}'
```
------
O comando retorna detalhes da nova regra do EventBridge, semelhantes aos seguintes:
------
#### [ Linux & macOS ]
```
{
"RuleArn": "arn:aws:events:us-east-1:123456789012:rule/automationrule"
}
```
------
#### [ Windows ]
```
{
"RuleArn": "arn:aws:events:us-east-1:123456789012:rule/automationrule"
}
```
------
#### [ PowerShell ]
```
arn:aws:events:us-east-1:123456789012:rule/EC2InstanceStateChanges
```
------
1. Crie um comando para especificar um runbook como o destino da regra de evento do EventBridge que você criou na etapa 2. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
------
#### [ Linux & macOS ]
```
aws events put-targets \
--rule rule name \
--targets '{"Arn": " arn:aws:ssm:region:account ID:automation-definition/runbook name","Input":"{\"Message\":[\"{\\\"Key\\\":\\\"key name\\\",\\\"Values\\\":[\\\"value\\\"]}\"]}","Id": "target ID","RoleArn": "arn:aws:iam::123456789012:role/service-role/EventBridge service role"}'
```
------
#### [ Windows ]
```
aws events put-targets ^
--rule rule name ^
--targets '{"Arn": "arn:aws:ssm:region:account ID:automation-definition/runbook name","Input":"{\"Message\":[\"{\\\"Key\\\":\\\"key name\\\",\\\"Values\\\":[\\\"value\\\"]}\"]}","Id": "target ID","RoleArn": "arn:aws:iam::123456789012:role/service-role/EventBridge service role"}'
```
------
#### [ PowerShell ]
```
$Target = New-Object Amazon.CloudWatchEvents.Model.Target
$Target.Id = "target ID"
$Target.Arn = "arn:aws:ssm:region:account ID:automation-definition/runbook name"
$Target.RoleArn = "arn:aws:iam::123456789012:role/service-role/EventBridge service role"
$Target.Input = '{"input parameter":["value"],"AutomationAssumeRole":["arn:aws:iam::123456789012:role/AutomationServiceRole"]}'
Write-CWETarget `
-Rule "rule name" `
-Target $Target
```
------
O exemplo a seguir cria um destino para um evento do EventBridge que inicia o ID de instância especificado usando o runbook `AWS-StartEC2Instance`.
------
#### [ Linux & macOS ]
```
aws events put-targets \
--rule DailyAutomationRule \
--targets '{"Arn": "arn:aws:ssm:region:*:automation-definition/AWS-StartEC2Instance","Input":"{\"InstanceId\":[\"i-02573cafcfEXAMPLE\"],\"AutomationAssumeRole\":[\"arn:aws:iam::123456789012:role/AutomationServiceRole\"]}","Id": "Target1","RoleArn": "arn:aws:iam::123456789012:role/service-role/AWS_Events_Invoke_Start_Automation_Execution_1213609520"}'
```
------
#### [ Windows ]
```
aws events put-targets ^
--rule DailyAutomationRule ^
--targets '{"Arn": "arn:aws:ssm:region:*:automation-definition/AWS-StartEC2Instance","Input":"{\"InstanceId\":[\"i-02573cafcfEXAMPLE\"],\"AutomationAssumeRole\":[\"arn:aws:iam::123456789012:role/AutomationServiceRole\"]}","Id": "Target1","RoleArn": "arn:aws:iam::123456789012:role/service-role/AWS_Events_Invoke_Start_Automation_Execution_1213609520"}'
```
------
#### [ PowerShell ]
```
$Target = New-Object Amazon.CloudWatchEvents.Model.Target
$Target.Id = "Target1"
$Target.Arn = "arn:aws:ssm:region:*:automation-definition/AWS-StartEC2Instance"
$Target.RoleArn = "arn:aws:iam::123456789012:role/service-role/AWS_Events_Invoke_Start_Automation_Execution_1213609520"
$Target.Input = '{"InstanceId":["i-02573cafcfEXAMPLE"],"AutomationAssumeRole":["arn:aws:iam::123456789012:role/AutomationServiceRole"]}'
Write-CWETarget `
-Rule "DailyAutomationRule" `
-Target $Target
```
------
O sistema retorna informações como estas.
------
#### [ Linux & macOS ]
```
{
"FailedEntries": [],
"FailedEntryCount": 0
}
```
------
#### [ Windows ]
```
{
"FailedEntries": [],
"FailedEntryCount": 0
}
```
------
#### [ PowerShell ]
Não haverá saída se o comando for bem-sucedido para PowerShell.
------
# Executar uma automação passo a passo
Os procedimentos a seguir descrevem como usar o console do AWS Systems Manager e a AWS Command Line Interface (AWS CLI) para executar uma automação usando o modo de execução manual. Usando o modo de execução manual, a automação é iniciada em um status *Waiting* (Aguardando) e faz uma pausa no status *Waiting (Aguardando)* entre cada etapa. Isso permite que você controle quando automação deve prosseguir, o que é útil quando for necessário revisar o resultado de uma etapa antes de continuar.
A automação é executada no contexto do usuário atual. Isso significa que você não precisa configurar outras permissões do IAM, desde que tenha permissão para usar o runbook e qualquer ação chamada pelo runbook. Se você tiver permissões de administrador no IAM, isso significa que você já tem permissão para executar essa automação.
## Executar uma automação passo a passo (console)
O procedimento a seguir mostra como usar o console do Systems Manager para executar manualmente uma automação passo a passo.
**Para executar uma automação passo a passo**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, selecione **Automation** e **Execute automation (Executar automação)**.
1. Na lista **Automation document** (Documento do Automation), escolha um runbook. Escolha uma ou mais opções no painel **Document categories** (Categorias de documentos) para filtrar documentos SSM de acordo com sua finalidade. Para visualizar um runbook que você tenha, escolha a guia **Owned by me** (De minha propriedade). Para visualizar um runbook compartilhado com sua conta, escolha a guia **Shared with me** (Compartilhado comigo). Para visualizar todos os runbooks, escolha a guia **All documents** (Todos os documentos).
**nota**
Você pode visualizar informações sobre um runbook, selecionando o nome dele.
1. Na seção **Document details** (Detalhes do documento), verifique se **Document version** (Versão do documento) está definida como a versão que você quer executar. O sistema inclui as seguintes opções de versão:
+ **Versão padrão no runtime**: escolha essa opção se o runbook do Automation for atualizado periodicamente e uma nova versão padrão for atribuída.
+ **Versão mais recente no runtime**: escolha essa opção se o runbook do Automation for atualizado periodicamente e se você quiser executar a versão mais recente.
+ **1 (padrão):** escolha esta opção para executar a primeira versão do documento, que é a versão padrão.
1. Escolha **Próximo**.
1. Na seção **Execution mode (Modo de execução)**, escolha **Manual execution (Execução manual)**.
1. Na seção **Input parameters (Parâmetros de entrada)**, especifique as entradas necessárias. Opcionalmente, você pode escolher uma função de serviço do IAM na lista **AutomationAssumeRole**.
1. Clique em **Executar**.
1. Selecione **Execute this step** (Execute esta etapa) quando estiver pronto para iniciar a primeira etapa da automação. A automação prossegue com a etapa 1 e pausa antes de executar qualquer etapa subsequente especificada no runbook que você escolheu na etapa 3 deste procedimento. Se o runbook tiver várias etapas, você deverá selecionar **Execute this step** (Executar esta etapa) em cada etapa para que a automação prossiga. Cada vez que você escolher **Execute this step** (Executar esta etapa) a ação será executada.
**nota**
O console exibe o status da automação. Se a automação não executar uma etapa, consulte [Solução de problemas do Systems Manager Automation](automation-troubleshooting.md).
1. Depois de concluir todas as etapas especificadas no runbook, escolha **Complete and view results** (Concluir e visualizar os resultados) para concluir a automação e visualizar os resultados.
Depois que uma execução de automação for concluída, você pode executá-la novamente com os mesmos parâmetros ou com parâmetros modificados. Para obter mais informações, consulte [Executar novamente as execuções de automação](automation-rerun-executions.md).
## Executar uma automação passo a passo (linha de comando)
O procedimento a seguir descreve como usar a AWS CLI (no Linux, macOS ou no Windows) ou o Ferramentas da AWS para PowerShell para executar manualmente uma automação passo a passo.
**Para executar uma automação passo a passo**
1. Instale e configure a AWS CLI ou o Ferramentas da AWS para PowerShell, caso ainda não o tenha feito.
Para obter informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) e [Instalar o Ferramentas da AWS para PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
1. Execute o comando a seguir para iniciar uma automação manual. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name runbook name \
--mode Interactive \
--parameters runbook parameters
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name runbook name ^
--mode Interactive ^
--parameters runbook parameters
```
------
#### [ PowerShell ]
```
Start-SSMAutomationExecution `
-DocumentName runbook name `
-Mode Interactive `
-Parameter runbook parameters
```
------
Este é um exemplo que usa o runbook `AWS-RestartEC2Instance` para reiniciar a instância do EC2 especificada.
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name "AWS-RestartEC2Instance" \
--mode Interactive \
--parameters "InstanceId=i-02573cafcfEXAMPLE"
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name "AWS-RestartEC2Instance" ^
--mode Interactive ^
--parameters "InstanceId=i-02573cafcfEXAMPLE"
```
------
#### [ PowerShell ]
```
Start-SSMAutomationExecution `
-DocumentName AWS-RestartEC2Instance `
-Mode Interactive
-Parameter @{"InstanceId"="i-02573cafcfEXAMPLE"}
```
------
O sistema retorna informações como estas.
------
#### [ Linux & macOS ]
```
{
"AutomationExecutionId": "ba9cd881-1b36-4d31-a698-0123456789ab"
}
```
------
#### [ Windows ]
```
{
"AutomationExecutionId": "ba9cd881-1b36-4d31-a698-0123456789ab"
}
```
------
#### [ PowerShell ]
```
ba9cd881-1b36-4d31-a698-0123456789ab
```
------
1. Execute o comando a seguir quando estiver pronto para iniciar a primeira etapa da automação. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações. A automação prossegue com a etapa 1 e pausa antes de executar qualquer etapa subsequente especificada no runbook que você escolheu na etapa 1 deste procedimento. Se o runbook tiver várias etapas, você deverá executar o seguinte comando para cada etapa, para que a automação prossiga.
------
#### [ Linux & macOS ]
```
aws ssm send-automation-signal \
--automation-execution-id ba9cd881-1b36-4d31-a698-0123456789ab \
--signal-type StartStep \
--payload StepName="stopInstances"
```
------
#### [ Windows ]
```
aws ssm send-automation-signal ^
--automation-execution-id ba9cd881-1b36-4d31-a698-0123456789ab ^
--signal-type StartStep ^
--payload StepName="stopInstances"
```
------
#### [ PowerShell ]
```
Send-SSMAutomationSignal `
-AutomationExecutionId ba9cd881-1b36-4d31-a698-0123456789ab `
-SignalType StartStep
-Payload @{"StepName"="stopInstances"}
```
------
Não haverá saída se o comando for bem-sucedido.
1. Execute o comando a seguir para recuperar o status da execução de cada etapa na automação.
------
#### [ Linux & macOS ]
```
aws ssm describe-automation-step-executions \
--automation-execution-id ba9cd881-1b36-4d31-a698-0123456789ab
```
------
#### [ Windows ]
```
aws ssm describe-automation-step-executions ^
--automation-execution-id ba9cd881-1b36-4d31-a698-0123456789ab
```
------
#### [ PowerShell ]
```
Get-SSMAutomationStepExecution `
-AutomationExecutionId ba9cd881-1b36-4d31-a698-0123456789ab
```
------
O sistema retorna informações como estas.
------
#### [ Linux & macOS ]
```
{
"StepExecutions": [
{
"StepName": "stopInstances",
"Action": "aws:changeInstanceState",
"ExecutionStartTime": 1557167178.42,
"ExecutionEndTime": 1557167220.617,
"StepStatus": "Success",
"Inputs": {
"DesiredState": "\"stopped\"",
"InstanceIds": "[\"i-02573cafcfEXAMPLE\"]"
},
"Outputs": {
"InstanceStates": [
"stopped"
]
},
"StepExecutionId": "654243ba-71e3-4771-b04f-0123456789ab",
"OverriddenParameters": {},
"ValidNextSteps": [
"startInstances"
]
},
{
"StepName": "startInstances",
"Action": "aws:changeInstanceState",
"ExecutionStartTime": 1557167273.754,
"ExecutionEndTime": 1557167480.73,
"StepStatus": "Success",
"Inputs": {
"DesiredState": "\"running\"",
"InstanceIds": "[\"i-02573cafcfEXAMPLE\"]"
},
"Outputs": {
"InstanceStates": [
"running"
]
},
"StepExecutionId": "8a4a1e0d-dc3e-4039-a599-0123456789ab",
"OverriddenParameters": {}
}
]
}
```
------
#### [ Windows ]
```
{
"StepExecutions": [
{
"StepName": "stopInstances",
"Action": "aws:changeInstanceState",
"ExecutionStartTime": 1557167178.42,
"ExecutionEndTime": 1557167220.617,
"StepStatus": "Success",
"Inputs": {
"DesiredState": "\"stopped\"",
"InstanceIds": "[\"i-02573cafcfEXAMPLE\"]"
},
"Outputs": {
"InstanceStates": [
"stopped"
]
},
"StepExecutionId": "654243ba-71e3-4771-b04f-0123456789ab",
"OverriddenParameters": {},
"ValidNextSteps": [
"startInstances"
]
},
{
"StepName": "startInstances",
"Action": "aws:changeInstanceState",
"ExecutionStartTime": 1557167273.754,
"ExecutionEndTime": 1557167480.73,
"StepStatus": "Success",
"Inputs": {
"DesiredState": "\"running\"",
"InstanceIds": "[\"i-02573cafcfEXAMPLE\"]"
},
"Outputs": {
"InstanceStates": [
"running"
]
},
"StepExecutionId": "8a4a1e0d-dc3e-4039-a599-0123456789ab",
"OverriddenParameters": {}
}
]
}
```
------
#### [ PowerShell ]
```
Action: aws:changeInstanceState
ExecutionEndTime : 5/6/2019 19:45:46
ExecutionStartTime : 5/6/2019 19:45:03
FailureDetails :
FailureMessage :
Inputs : {[DesiredState, "stopped"], [InstanceIds, ["i-02573cafcfEXAMPLE"]]}
IsCritical : False
IsEnd : False
MaxAttempts : 0
NextStep :
OnFailure :
Outputs : {[InstanceStates, Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]]}
OverriddenParameters : {}
Response :
ResponseCode :
StepExecutionId : 8fcc9641-24b7-40b3-a9be-0123456789ab
StepName : stopInstances
StepStatus : Success
TimeoutSeconds : 0
ValidNextSteps : {startInstances}
```
------
1. Execute o comando a seguir para concluir a automação depois que todas as etapas especificadas no runbook escolhido tiverem sido concluídas. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
------
#### [ Linux & macOS ]
```
aws ssm stop-automation-execution \
--automation-execution-id ba9cd881-1b36-4d31-a698-0123456789ab \
--type Complete
```
------
#### [ Windows ]
```
aws ssm stop-automation-execution ^
--automation-execution-id ba9cd881-1b36-4d31-a698-0123456789ab ^
--type Complete
```
------
#### [ PowerShell ]
```
Stop-SSMAutomationExecution `
-AutomationExecutionId ba9cd881-1b36-4d31-a698-0123456789ab `
-Type Complete
```
------
Não haverá saída se o comando for bem-sucedido.
# Programação de automações com associações do State Manager
É possível iniciar uma automação criando uma associação do State Manager com um runbook. O State Manager é uma ferramenta do AWS Systems Manager. Ao criar uma associação do State Manager com um runbook, você pode direcionar diferentes tipos de recursos da AWS. Por exemplo, é possível criar associações que aplicam um estado desejado a um recurso da AWS, incluindo o seguinte:
+ Anexe uma função do Systems Manager às instâncias do Amazon Elastic Compute Cloud (Amazon EC2) para torná-las *instâncias gerenciadas*.
+ Aplicar regras de entrada e saída desejadas a um grupo de segurança.
+ Crie ou exclua backups do Amazon DynamoDB.
+ Crie ou exclua snapshots do Amazon Elastic Block Store (Amazon EBS).
+ Desative as permissões de leitura e gravação em buckets do Amazon Simple Storage Service (Amazon S3).
+ Inicie, reinicie ou interrompa instâncias gerenciadas e instâncias do Amazon Relational Database Service (Amazon RDS).
+ Aplique patches às macOS do Linux, AMIs e Windows.
Use os procedimentos a seguir para criar uma associação do State Manager que executa uma automação usando o console do AWS Systems Manager e a AWS Command Line Interface (AWS CLI). Para obter informações gerais sobre associações e informações sobre como criar uma associação que usa um documento SSM `Command` ou um documento `Policy`, consulte [Criar associações](state-manager-associations-creating.md).
**Antes de começar**
Observe estes detalhes importantes, antes de executar uma automação usando o . State Manager:
+ Antes de criar uma associação que usa um runbook, verifique se você configurou permissões para o Automation, uma ferramenta do AWS Systems Manager. Para obter mais informações, consulte [Configurar a automação](automation-setup.md).
+ State Manager As associações do que executam runbooks contribuem para o número máximo de automações em execução simultânea na sua conta da Conta da AWS. É possível ter no máximo 100 automações em execução ao mesmo tempo. Para obter informações, consulte as [cotas de serviço do Systems Manager](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm) no *Referência geral da Amazon Web Services*.
+ Ao executar uma automação, o State Manager não registra em log as operações de API iniciadas pela automação em AWS CloudTrail.
+ O Systems Manager cria automaticamente uma função vinculada ao serviço para que o State Manager tenha permissão para chamar operações de API do Systems Manager Automation. Se desejar, você pode criar a função vinculada ao serviço por conta própria executando o seguinte comando na AWS CLI ou no Ferramentas da AWS para PowerShell.
------
#### [ Linux & macOS ]
```
aws iam create-service-linked-role \
--aws-service-name ssm.amazonaws.com
```
------
#### [ Windows ]
```
aws iam create-service-linked-role ^
--aws-service-name ssm.amazonaws.com
```
------
#### [ PowerShell ]
```
New-IAMServiceLinkedRole `
-AWSServiceName ssm.amazonaws.com
```
------
Para obter mais informações sobre funções vinculadas ao serviço, consulte [Usar perfis vinculados a serviço do Systems Manager](using-service-linked-roles.md).
## Criar uma associação que executa uma automação (console)
O procedimento a seguir descreve como usar o console do Systems Manager para criar uma associação do State Manager que executa uma automação.
**Como criar uma associação do State Manager que execute uma automação**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **State Manager** e selecione **Create association**.
1. No campo **Name**, especifique um nome. Isso é opcional, mas recomendado.
1. Na lista **Document** (Documento), escolha um runbook. Use a barra de pesquisa para filtrar os runboks **Document type : Equal : Automation**. Para visualizar mais runbooks, use os números à direita da barra de pesquisa.
**nota**
Você pode visualizar informações sobre um runbook, selecionando o nome dele.
1. Escolha **Simple execution (Execução simples)** para executar a automação em um ou mais destinos, especificando o ID do recurso desses destinos. Escolha **Rate control (Controle de taxa)** para executar a automação em uma frota de recursos da AWS, especificando uma opção de direcionamento, como tags ou o AWS Resource Groups. Você também pode controlar a operação da automação nos seus recursos, especificando a simultaneidade e limites de erro.
Se você escolheu **Rate control** (Controle de taxa), a seção **Targets** (Destinos) será exibida.
1. Na seção **Targets (Destinos)**, escolha um método para definir recursos de direcionamento.
1. (Necessário) Na lista **Parameter (Parâmetro)**, escolha um parâmetro. Os itens na lista **Parameter** (Parâmetro) são determinados pelos parâmetros no runbook que você selecionou no início deste procedimento. Ao escolher um parâmetro, você define o tipo de recurso no qual a automação é executada.
1. (Necessário) Na lista **Targets (Destinos)**, escolha um método para definir destinos para os recursos.
+ **Resource Group (Grupo de recursos)**: escolha o nome do grupo na lista **Resource Group (Grupo de recursos)**. Para obter mais informações sobre o direcionamento do AWS Resource Groups em runbooks, consulte [como destino AWS Resource Groups](running-automations-map-targets.md#target-resource-groups).
+ **Tags**: insira a chave de tag e (opcionalmente) o valor da tag nos campos fornecidos. Escolha **Adicionar**. Para obter mais informações sobre o direcionamento de tags em runbooks, consulte [Definir uma etiqueta como destino](running-automations-map-targets.md#target-tags).
+ **Parameter Values (Valores de parâmetros)**: insira valores na seção **Input parameters (Parâmetros de entrada)**. Se você especificar vários valores, o Systems Manager executará uma automação secundária em cada valor especificado.
Por exemplo, digamos que o runbook inclui um parâmetro **InstanceID**. Se você direcionar os valores do parâmetro **InstanceID** ao executar a automação, o Systems Manager executará uma automação filho para cada valor especificado para o ID da instância. A automação pai é concluída quando a automação conclui a execução de cada instância especificada, ou se a automação falha. Você pode direcionar um máximo de 50 valores de parâmetro. Para obter mais informações sobre direcionar valores de parâmetros em runbooks, consulte [Direcionar valores de parâmetro](running-automations-map-targets.md#target-parameter-values).
1. Na seção **Input parameters (Parâmetros de entrada)**, especifique os parâmetros de entrada necessários.
Se você optar por definir o destino dos recursos usando tags ou um grupo de recursos, talvez não precise escolher algumas das opções na seção **Input parameters** (Parâmetros de entrada). Por exemplo, se você tiver escolhido o runbook `AWS-RestartEC2Instance`, e definiu o destino das instâncias usando tags, você não precisará especificar ou escolher IDs de instância na seção **Input parameters** (Parâmetros de entrada). A automação localiza as instâncias para reiniciar usando as tags que você especificou.
**Importante**
Especifique um ARN de função no campo **AutomationAssumeRole**. O State Manager assume a função para chamar Serviços da AWS especificados no runbook e para executar associações do Automation em seu nome.
1. Na seção **Specify schedule (Especificar programação)**, escolha **On Schedule (Na programação)** se quiser executar a associação em intervalos regulares. Se você escolher essa opção, use as opções fornecidas para criar a programação usando expressões Cron ou Rate. Para obter mais informações sobre expressões Cron e Rate para o State Manager, consulte [Expressões cron e rate para associações](reference-cron-and-rate-expressions.md#reference-cron-and-rate-expressions-association).
**nota**
Expressões de taxa são o mecanismo preferencial de programação para associações do State Manager que usam runbooks. Essas expressões proporcionam mais flexibilidade para a execução de associações, caso você atinja o número máximo de automações executadas ao mesmo tempo. Com uma programação de taxas, o Systems Manager pode tentar a automação novamente logo depois de receber a notificação de que as automações simultâneas atingiram seu limite máximo e foram controladas.
Escolha **No schedule (Sem programação)** se quiser executar a associação apenas uma vez.
1. (Opcional) Na seção **Controle de taxa**, escolha as opções **Simultaneidade** e **Limiar de erros** para controlar a implantação da automação nos seus recursos da AWS.
1. Na seção **Concurrency** (Simultaneidade), escolha uma opção:
+ Escolha **targets** (destinos) para inserir um número absoluto de destinos que podem executar a automação simultaneamente.
+ Escolha **percentage** (porcentagem) para inserir uma porcentagem do conjunto de destino que pode executar a automação simultaneamente.
1. Na seção **Error threshold (Limite de erro)**, escolha uma opção:
+ Escolha **errors** (erros) para inserir um número absoluto de erros permitidos antes que o Automation pare de enviar a automação para outros recursos.
+ Escolha **percent** (por cento) para inserir uma porcentagem de erros permitidos antes que o Automation pare de enviar a automação para outros recursos.
Para obter mais informações sobre o uso de destinos e controles de taxa com a Automação, consulte [Executar operações automatizadas em escala](running-automations-scale.md).
1. Escolha **Create Association (Criar associação)**.
**Importante**
Quando você cria uma associação, ela é executada imediatamente nos destinos especificados. Em seguida, a associação é executada com base na expressão Cron ou Rate que você escolheu. Se você escolheu **No schedule** (Sem programação), a associação não será executada novamente.
## Criar uma associação que executa uma automação (linha de comando)
O procedimento a seguir descreve como usar a AWS CLI (no Linux ou Windows Server) ou o Ferramentas da AWS para PowerShell para criar uma associação do State Manager que executa uma automação.
**Antes de começar**
Antes de concluir o procedimento a seguir, certifique-se de ter criado um perfil de serviço do IAM com as permissões necessárias para executar o runbook e configurado uma relação de confiança para o Automation, uma ferramenta do AWS Systems Manager. Para obter mais informações, consulte [Tarefa 1: Criar uma função de serviço para a automação](automation-setup-iam.md#create-service-role).
**Para criar uma associação que executa uma automação**
1. Instale e configure a AWS CLI ou o Ferramentas da AWS para PowerShell, caso ainda não o tenha feito.
Para obter informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) e [Instalar o Ferramentas da AWS para PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
1. Execute o comando a seguir para visualizar uma lista de documentos.
------
#### [ Linux & macOS ]
```
aws ssm list-documents
```
------
#### [ Windows ]
```
aws ssm list-documents
```
------
#### [ PowerShell ]
```
Get-SSMDocumentList
```
------
Anote o nome do runbook que você quer usar para a associação.
1. Execute o comando a seguir para visualizar os detalhes sobre o runbook. No comando a seguir, substitua *runbook name* por suas próprias informações.
------
#### [ Linux & macOS ]
```
aws ssm describe-document \
--name runbook name
```
Anote o nome de um parâmetro (por exemplo, `InstanceId`) que você deseja usar para a opção `--automation-target-parameter-name`. Esse parâmetro determina o tipo de recurso em que a automação é executada.
------
#### [ Windows ]
```
aws ssm describe-document ^
--name runbook name
```
Anote o nome de um parâmetro (por exemplo, `InstanceId`) que você deseja usar para a opção `--automation-target-parameter-name`. Esse parâmetro determina o tipo de recurso em que a automação é executada.
------
#### [ PowerShell ]
```
Get-SSMDocumentDescription `
-Name runbook name
```
Anote o nome de um parâmetro (por exemplo, `InstanceId`) que você deseja usar para a opção `AutomationTargetParameterName`. Esse parâmetro determina o tipo de recurso em que a automação é executada.
------
1. Crie um comando que execute uma automação usando uma associação do State Manager. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
*Definir destino usando tags*
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--association-name association name \
--targets Key=tag:key name,Values=value \
--name runbook name \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole \
--automation-target-parameter-name target parameter \
--schedule "cron or rate expression"
```
**nota**
Se você criar uma associação usando o AWS CLI, use o parâmetro `--targets` para as instâncias de destino da associação. Não use o parâmetro `--instance-id`. O parâmetro `--instance-id` é um parâmetro legado.
------
#### [ Windows ]
```
aws ssm create-association ^
--association-name association name ^
--targets Key=tag:key name,Values=value ^
--name runbook name ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole ^
--automation-target-parameter-name target parameter ^
--schedule "cron or rate expression"
```
**nota**
Se você criar uma associação usando o AWS CLI, use o parâmetro `--targets` para as instâncias de destino da associação. Não use o parâmetro `--instance-id`. O parâmetro `--instance-id` é um parâmetro legado.
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "tag:key name"
$Targets.Values = "value"
New-SSMAssociation `
-AssociationName "association name" `
-Target $Targets `
-Name "runbook name" `
-Parameters @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/RunbookAssumeRole" } `
-AutomationTargetParameterName "target parameter" `
-ScheduleExpression "cron or rate expression"
```
**nota**
Se você criar uma associação usando o Ferramentas da AWS para PowerShell, use o parâmetro `Target` para as instâncias de destino da associação. Não use o parâmetro `InstanceId`. O parâmetro `InstanceId` é um parâmetro legado.
------
*Definir destino usando valores de parâmetro*
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--association-name association name \
--targets Key=ParameterValues,Values=value,value 2,value 3 \
--name runbook name \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole \
--automation-target-parameter-name target parameter \
--schedule "cron or rate expression"
```
------
#### [ Windows ]
```
aws ssm create-association ^
--association-name association name ^
--targets Key=ParameterValues,Values=value,value 2,value 3 ^
--name runbook name ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole ^
--automation-target-parameter-name target parameter ^
--schedule "cron or rate expression"
```
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "ParameterValues"
$Targets.Values = "value","value 2","value 3"
New-SSMAssociation `
-AssociationName "association name" `
-Target $Targets `
-Name "runbook name" `
-Parameters @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/RunbookAssumeRole"} `
-AutomationTargetParameterName "target parameter" `
-ScheduleExpression "cron or rate expression"
```
------
*Definir destino usando AWS Resource Groups*
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--association-name association name \
--targets Key=ResourceGroup,Values=resource group name \
--name runbook name \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole \
--automation-target-parameter-name target parameter \
--schedule "cron or rate expression"
```
------
#### [ Windows ]
```
aws ssm create-association ^
--association-name association name ^
--targets Key=ResourceGroup,Values=resource group name ^
--name runbook name ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole ^
--automation-target-parameter-name target parameter ^
--schedule "cron or rate expression"
```
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "ResourceGroup"
$Targets.Values = "resource group name"
New-SSMAssociation `
-AssociationName "association name" `
-Target $Targets `
-Name "runbook name" `
-Parameters @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/RunbookAssumeRole"} `
-AutomationTargetParameterName "target parameter" `
-ScheduleExpression "cron or rate expression"
```
------
*Selecionar várias contas e regiões como destino*
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--association-name association name \
--targets Key=ResourceGroup,Values=resource group name \
--name runbook name \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole \
--automation-target-parameter-name target parameter \
--schedule "cron or rate expression" \
--target-locations Accounts=111122223333,444455556666,444455556666,Regions=region,region
```
------
#### [ Windows ]
```
aws ssm create-association ^
--association-name association name ^
--targets Key=ResourceGroup,Values=resource group name ^
--name runbook name ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole ^
--automation-target-parameter-name target parameter ^
--schedule "cron or rate expression" ^
--target-locations Accounts=111122223333,444455556666,444455556666,Regions=region,region
```
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "ResourceGroup"
$Targets.Values = "resource group name"
New-SSMAssociation `
-AssociationName "association name" `
-Target $Targets `
-Name "runbook name" `
-Parameters @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/RunbookAssumeRole"} `
-AutomationTargetParameterName "target parameter" `
-ScheduleExpression "cron or rate expression" `
-TargetLocations @{
"Accounts"=["111122223333,444455556666,444455556666"],
"Regions"=["region,region"]
```
------
O comando retorna detalhes da nova associação semelhantes ao seguinte.
------
#### [ Linux & macOS ]
```
{
"AssociationDescription": {
"ScheduleExpression": "cron(0 7 ? * MON *)",
"Name": "AWS-StartEC2Instance",
"Parameters": {
"AutomationAssumeRole": [
"arn:aws:iam::123456789012:role/RunbookAssumeRole"
]
},
"Overview": {
"Status": "Pending",
"DetailedStatus": "Creating"
},
"AssociationId": "1450b4b7-bea2-4e4b-b340-01234EXAMPLE",
"DocumentVersion": "$DEFAULT",
"AutomationTargetParameterName": "InstanceId",
"LastUpdateAssociationDate": 1564686638.498,
"Date": 1564686638.498,
"AssociationVersion": "1",
"AssociationName": "CLI",
"Targets": [
{
"Values": [
"DEV"
],
"Key": "tag:ENV"
}
]
}
}
```
------
#### [ Windows ]
```
{
"AssociationDescription": {
"ScheduleExpression": "cron(0 7 ? * MON *)",
"Name": "AWS-StartEC2Instance",
"Parameters": {
"AutomationAssumeRole": [
"arn:aws:iam::123456789012:role/RunbookAssumeRole"
]
},
"Overview": {
"Status": "Pending",
"DetailedStatus": "Creating"
},
"AssociationId": "1450b4b7-bea2-4e4b-b340-01234EXAMPLE",
"DocumentVersion": "$DEFAULT",
"AutomationTargetParameterName": "InstanceId",
"LastUpdateAssociationDate": 1564686638.498,
"Date": 1564686638.498,
"AssociationVersion": "1",
"AssociationName": "CLI",
"Targets": [
{
"Values": [
"DEV"
],
"Key": "tag:ENV"
}
]
}
}
```
------
#### [ PowerShell ]
```
Name : AWS-StartEC2Instance
InstanceId :
Date : 8/1/2019 7:31:38 PM
Status.Name :
Status.Date :
Status.Message :
Status.AdditionalInfo :
```
------
**nota**
Se você usar tags para criar uma associação em uma ou mais instâncias de destino e, em seguida, remover as tags de uma instância, essa instância não executará mais a associação. A instância será dissociada do documento do State Manager.
## Automações de solução de problemas executadas por associações do State Manager
O Systems Manager Automation impõe um limite de 100 automações simultâneas e 1.000 automações em fila por conta e região. Se uma associação do State Manager que executa um runbook para mostrar um status **Failed** (Falha) e um status detalhado de **AutomationExecutionLimitExceeded**, isso significa que a automação pode ter atingido o limite. Como resultado, o Systems Manager controlará as automações. Para resolver esse problema, faça o seguinte:
+ Use uma expressão Cron ou Rate diferente para a sua associação. Por exemplo, se a associação estiver programada para execução a cada 30 minutos, altere-a para que ela seja executada a cada uma ou duas horas.
+ Exclua as automações existentes com um status **Pending** (Pendente). Ao excluir essas automações, você limpa a fila atual.
# Agendar automações com janelas de manutenção
Você pode iniciar uma automação configurando um runbook como uma tarefa registrada para uma janela de manutenção. Com o registro do runbook como uma tarefa registrada, a janela de manutenção executa a automação durante o período de manutenção programada.
Por exemplo, digamos que você crie um runbook chamado `CreateAMI` que cria uma Amazon Machine Image (AMI) de instâncias registradas como destinos para a janela de manutenção. Para especificar o runbook `CreateAMI` (e a automação correspondente) como uma tarefa registrada de uma janela de manutenção, primeiro você deve criar uma janela de manutenção e registrar destinos. Depois, use o procedimento a seguir para especificar o documento `CreateAMI` como uma tarefa registrada na janela de manutenção. Quando a janela de manutenção for iniciada durante o período programado, o sistema executará a automação e criará uma AMI dos destinos registrados.
Para obter informações sobre como criar runbooks do Automation, consulte [Criação dos seus próprios runbooks](automation-documents.md). O Automation é uma ferramenta do AWS Systems Manager.
Use os procedimentos a seguir para configurar uma automação como uma tarefa registrada para uma janela de manutenção, usando o console do AWS Systems Manager, a AWS Command Line Interface (AWS CLI) ou o AWS Tools for Windows PowerShell.
## Registrar uma tarefa de automação em uma janela de manutenção (console)
O procedimento a seguir descreve como usar o console do Systems Manager para configurar uma automação como uma tarefa registrada para uma janela de manutenção.
**Antes de começar**
Antes de concluir o procedimento a seguir, você deve criar uma janela de manutenção e registrar pelo menos um destino. Para obter mais informações, consulte os procedimentos a seguir:
+ [Crie uma janela de manutenção usando o console](sysman-maintenance-create-mw.md).
+ [Atribua destinos a uma janela de manutenção usando o console](sysman-maintenance-assign-targets.md)
**Para configurar uma automação como uma tarefa registrada para uma janela de manutenção**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação à esquerda, selecione **Maintenance Windows** e depois selecione a janela de manutenção com a qual você deseja registrar uma tarefa Automação.
1. Escolha **Ações**. Em seguida, escolha **Register Automation task** (Registrar tarefa do Automation para executar sua opção de automação nos destinos, usando um runbook.
1. Em **Name (Nome)**, insira um nome para a tarefa.
1. Em **Descrição**, insira uma descrição.
1. Em **Document** (Documento), escolha o runbook que define as tarefas a serem executadas.
1. Em **Document version (Versão do documento)**, escolha a versão do runbook a ser usada.
1. Em **Task priority** (Prioridade de tarefas), escolha uma prioridade. `1` é a prioridade mais alta. As tarefas em uma janela de manutenção são programadas em ordem de prioridade, as tarefas que têm a mesma prioridade são programadas em paralelo.
1. Na seção **Targets** (Destinos), se o runbook selecionado executar tarefas nos recursos, identifique os destinos nos quais você deseja executar essa automação, especificando tags ou selecionando instâncias manualmente.
**nota**
Se você quiser passar os recursos pelos parâmetros de entrada em vez de destinos, não é necessário especificar um destino de janela de manutenção.
Em muitos casos, você não precisa especificar explicitamente um destino para uma tarefa de automação. Por exemplo, digamos que você esteja criando uma tarefa do tipo Automation para atualizar uma Amazon Machine Image (AMI) para Linux, usando o runbook `AWS-UpdateLinuxAmi`. Quando a tarefa for executada, a AMI será atualizada com os pacotes de distribuição Linux e o software da Amazon mais recentes disponível. As novas instâncias criadas na AMI já têm essas atualizações instaladas. Como o ID da AMI a ser atualizado é especificado nos parâmetros de entrada para o runbook, não há necessidade de especificar um destino novamente na tarefa da janela de manutenção.
Para obter informações sobre tarefas da janela de manutenção que não exigem destinos, consulte [Registrar tarefas da janela de manutenção sem destinos](maintenance-windows-targetless-tasks.md).
1. (Opcional) Em **Rate control (Controle de taxa)**:
**nota**
Se a tarefa que você estiver executando não especificar destinos, você não precisará especificar controles de taxa.
+ Para **Concurrency (Simultaneidade)**, especifique um número ou uma porcentagem de destinos nos quais executar a automação ao mesmo tempo.
Se você selecionou destinos escolhendo pares de chave/valor de tags, e não tem certeza de quantos destinos usam as tags selecionadas, limite o número de automações que podem ser executadas ao mesmo tempo, especificando uma porcentagem.
Quando a janela de manutenção é executada, uma nova execução da automação é iniciada por destino. Há um limite de 100 automações simultâneas por Conta da AWS. Se você especificar uma taxa de simultaneidade maior que 100, as automações simultâneas superiores a 100 serão automaticamente adicionadas à fila de automação. Para obter informações, consulte as [cotas de serviço do Systems Manager](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm) no *Referência geral da Amazon Web Services*.
+ Para **Error threshold** (Limite de erros), especifique quando interromper a execução da automação em outros destinos depois que ela falhar em um número ou em uma porcentagem de destinos. Por exemplo, se você especificar três erros, o Systems Manager deixará de executar as automação quando o quarto erro for recebido. Os destinos que ainda estiverem processando a automação também poderão enviar erros.
1. Na seção **Input Parameters** (Parâmetros de entrada), especifique os parâmetros para o runbook. Para runbooks, o sistema preenche automaticamente alguns dos valores. Você pode manter ou substituir esses valores.
**Importante**
Para runbooks, existe a opção de especificar uma função assumida no Automation. Se você não especificar uma função para esse parâmetro, a automação assumirá a função de serviço da janela de manutenção que você escolher na etapa 11. Dessa forma, você deve garantir que a função de serviço da janela de manutenção escolhida tenha as permissões apropriadas do AWS Identity and Access Management (IAM) para realizar as ações definidas no runbook.
Por exemplo, a função vinculada ao serviço para o Systems Manager não tem a permissão `ec2:CreateSnapshot` do IAM, que é necessária para executar o runbook `AWS-CopySnapshot`. Nesse cenário, você deve usar uma função de serviço da janela de manutenção personalizada ou especificar uma função de admissão de Automação que tenha permissões `ec2:CreateSnapshot`. Para mais informações, consulte [Configurar a automação](automation-setup.md).
1. Na área **IAM service role** (Perfil de serviço do IAM), escolha um perfil para fornecer permissões ao Systems Manager para iniciar a automação.
Para criar um perfil de serviço para tarefas de janela de manutenção, consulte [Configurar o Maintenance Windows](setting-up-maintenance-windows.md).
1. Escolha **Register Automation task (Registrar tarefa de Automação)**.
## Registrar uma tarefa do Automation em uma janela de manutenção (linha de comando)
O procedimento a seguir descreve como usar a AWS CLI (no Linux ou Windows Server) ou o Ferramentas da AWS para PowerShell para configurar uma automação como uma tarefa registrada para uma janela de manutenção.
**Antes de começar**
Antes de concluir o procedimento a seguir, você deve criar uma janela de manutenção e registrar pelo menos um destino. Para obter mais informações, consulte os procedimentos a seguir:
+ [Etapa 1: Criar a janela de manutenção usando a AWS CLI](mw-cli-tutorial-create-mw.md).
+ [Etapa 2: Registrar um nó de destino na janela de manutenção usando a AWS CLI](mw-cli-tutorial-targets.md)
**Para configurar uma automação como uma tarefa registrada para uma janela de manutenção**
1. Instale e configure a AWS CLI ou o Ferramentas da AWS para PowerShell, caso ainda não o tenha feito.
Para obter informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) e [Instalar o Ferramentas da AWS para PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
1. Crie um comando para configurar uma automação como uma tarefa registrada para uma janela de manutenção. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
------
#### [ Linux & macOS ]
```
aws ssm register-task-with-maintenance-window \
--window-id window ID \
--name task name \
--task-arn runbook name \
--targets Key=targets,Values=value \
--service-role-arn IAM role arn \
--task-type AUTOMATION \
--task-invocation-parameters task parameters \
--priority task priority \
--max-concurrency 10% \
--max-errors 5
```
**nota**
Se você configurar uma automação como uma tarefa registrada usando a AWS CLI, use o parâmetro `--Task-Invocation-Parameters` para especificar os parâmetros a serem passados para uma tarefa quando ela for executada. Não use o parâmetro `--Task-Parameters`. O parâmetro `--Task-Parameters` é um parâmetro legado.
Para tarefas de janela de manutenção sem um destino especificado, você não pode fornecer valores para `--max-errors` e `--max-concurrency`. Em vez disso, o sistema insere um valor de espaço reservado de `1`, que pode ser relatado na resposta a comandos como [https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-maintenance-window-tasks.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-maintenance-window-tasks.html) e [https://docs.aws.amazon.com/cli/latest/reference/ssm/get-maintenance-window-task.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/get-maintenance-window-task.html). Esses valores não afetam a execução da tarefa e podem ser ignorados.
Para obter informações sobre tarefas da janela de manutenção que não exigem destinos, consulte [Registrar tarefas da janela de manutenção sem destinos](maintenance-windows-targetless-tasks.md).
------
#### [ Windows ]
```
aws ssm register-task-with-maintenance-window ^
--window-id window ID ^
--name task name ^
--task-arn runbook name ^
--targets Key=targets,Values=value ^
--service-role-arn IAM role arn ^
--task-type AUTOMATION ^
--task-invocation-parameters task parameters ^
--priority task priority ^
--max-concurrency 10% ^
--max-errors 5
```
**nota**
Se você configurar uma automação como uma tarefa registrada usando a AWS CLI, use o parâmetro `--task-invocation-parameters` para especificar os parâmetros a serem passados para uma tarefa quando ela for executada. Não use o parâmetro `--task-parameters`. O parâmetro `--task-parameters` é um parâmetro legado.
Para tarefas de janela de manutenção sem um destino especificado, você não pode fornecer valores para `--max-errors` e `--max-concurrency`. Em vez disso, o sistema insere um valor de espaço reservado de `1`, que pode ser relatado na resposta a comandos como [https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-maintenance-window-tasks.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-maintenance-window-tasks.html) e [https://docs.aws.amazon.com/cli/latest/reference/ssm/get-maintenance-window-task.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/get-maintenance-window-task.html). Esses valores não afetam a execução da tarefa e podem ser ignorados.
Para obter informações sobre tarefas da janela de manutenção que não exigem destinos, consulte [Registrar tarefas da janela de manutenção sem destinos](maintenance-windows-targetless-tasks.md).
------
#### [ PowerShell ]
```
Register-SSMTaskWithMaintenanceWindow `
-WindowId window ID `
-Name "task name" `
-TaskArn "runbook name" `
-Target @{ Key="targets";Values="value" } `
-ServiceRoleArn "IAM role arn" `
-TaskType "AUTOMATION" `
-Automation_Parameter @{ "task parameter"="task parameter value"} `
-Priority task priority `
-MaxConcurrency 10% `
-MaxError 5
```
**nota**
Se você configurar uma automação como uma tarefa registrada usando o Ferramentas da AWS para PowerShell, use o parâmetro `-Automation_Parameter` para especificar os parâmetros a serem passados para uma tarefa quando ela for executada. Não use o parâmetro `-TaskParameters`. O parâmetro `-TaskParameters` é um parâmetro legado.
Para tarefas de janela de manutenção sem um destino especificado, você não pode fornecer valores para `-MaxError` e `-MaxConcurrency`. Em vez disso, o sistema insere um valor de espaço reservado de 1, que pode ser relatado na resposta a comandos como `Get-SSMMaintenanceWindowTaskList` e `Get-SSMMaintenanceWindowTask`. Esses valores não afetam a execução da tarefa e podem ser ignorados.
Para obter informações sobre tarefas da janela de manutenção que não exigem destinos, consulte [Registrar tarefas da janela de manutenção sem destinos](maintenance-windows-targetless-tasks.md).
------
O exemplo a seguir configura uma automação como uma tarefa registrada para uma janela de manutenção com prioridade 1. Ele também demonstra a omissão das opções de `--targets`, `--max-errors` e `--max-concurrency` para uma tarefa da janela de manutenção sem destino. A automação usa o runbook `AWS-StartEC2Instance` e a função assumida do Automation especificada para iniciar as instâncias do EC2 registradas como destinos para a janela de manutenção. A janela de manutenção executa a automação simultaneamente em 5 instâncias, no máximo, a qualquer momento. Além disso, a tarefa registrada interromperá a execução em mais instâncias por um intervalo específico, se a contagem de erros exceder 1.
------
#### [ Linux & macOS ]
```
aws ssm register-task-with-maintenance-window \
--window-id mw-0c50858d01EXAMPLE \
--name StartEC2Instances \
--task-arn AWS-StartEC2Instance \
--service-role-arn arn:aws:iam::123456789012:role/MaintenanceWindowRole \
--task-type AUTOMATION \
--task-invocation-parameters "{\"Automation\":{\"Parameters\":{\"InstanceId\":[\"{{TARGET_ID}}\"],\"AutomationAssumeRole\":[\"arn:aws:iam::123456789012:role/AutomationAssumeRole\"]}}}" \
--priority 1
```
------
#### [ Windows ]
```
aws ssm register-task-with-maintenance-window ^
--window-id mw-0c50858d01EXAMPLE ^
--name StartEC2Instances ^
--task-arn AWS-StartEC2Instance ^
--service-role-arn arn:aws:iam::123456789012:role/MaintenanceWindowRole ^
--task-type AUTOMATION ^
--task-invocation-parameters "{\"Automation\":{\"Parameters\":{\"InstanceId\":[\"{{TARGET_ID}}\"],\"AutomationAssumeRole\":[\"arn:aws:iam::123456789012:role/AutomationAssumeRole\"]}}}" ^
--priority 1
```
------
#### [ PowerShell ]
```
Register-SSMTaskWithMaintenanceWindow `
-WindowId mw-0c50858d01EXAMPLE `
-Name "StartEC2" `
-TaskArn "AWS-StartEC2Instance" `
-ServiceRoleArn "arn:aws:iam::123456789012:role/MaintenanceWindowRole" `
-TaskType "AUTOMATION" `
-Automation_Parameter @{ "InstanceId"="{{TARGET_ID}}";"AutomationAssumeRole"="arn:aws:iam::123456789012:role/AutomationAssumeRole" } `
-Priority 1
```
------
O comando retorna detalhes da nova tarefa registrada semelhantes aos seguintes.
------
#### [ Linux & macOS ]
```
{
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE"
}
```
------
#### [ Windows ]
```
{
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE"
}
```
------
#### [ PowerShell ]
```
4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE
```
------
1. Para visualizar a tarefa registrada, execute o seguinte comando. Substitua *maintenance windows ID* (ID das janelas de manutenção) por suas próprias informações.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-tasks \
--window-id maintenance window ID
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-tasks ^
--window-id maintenance window ID
```
------
#### [ PowerShell ]
```
Get-SSMMaintenanceWindowTaskList `
-WindowId maintenance window ID
```
------
O sistema retorna informações como estas.
------
#### [ Linux & macOS ]
```
{
"Tasks": [
{
"ServiceRoleArn": "arn:aws:iam::123456789012:role/MaintenanceWindowRole",
"MaxErrors": "1",
"TaskArn": "AWS-StartEC2Instance",
"MaxConcurrency": "1",
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
"TaskParameters": {},
"Priority": 1,
"WindowId": "mw-0c50858d01EXAMPLE",
"Type": "AUTOMATION",
"Targets": [
],
"Name": "StartEC2"
}
]
}
```
------
#### [ Windows ]
```
{
"Tasks": [
{
"ServiceRoleArn": "arn:aws:iam::123456789012:role/MaintenanceWindowRole",
"MaxErrors": "1",
"TaskArn": "AWS-StartEC2Instance",
"MaxConcurrency": "1",
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
"TaskParameters": {},
"Priority": 1,
"WindowId": "mw-0c50858d01EXAMPLE",
"Type": "AUTOMATION",
"Targets": [
],
"Name": "StartEC2"
}
]
}
```
------
#### [ PowerShell ]
```
Description :
LoggingInfo :
MaxConcurrency : 5
MaxErrors : 1
Name : StartEC2
Priority : 1
ServiceRoleArn : arn:aws:iam::123456789012:role/MaintenanceWindowRole
Targets : {}
TaskArn : AWS-StartEC2Instance
TaskParameters : {}
Type : AUTOMATION
WindowId : mw-0c50858d01EXAMPLE
WindowTaskId : 4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE
```
------
# Referência de ações do Systems Manager Automation
Essa referência descreve as ações do Automation que você pode especificar em um runbook do Automation. O Automation é uma ferramenta do AWS Systems Manager. Essas ações não podem ser usadas em outros tipos de documentos do Systems Manager (SSM). Para obter informações sobre plugins para outros tipos de documento do SSM, consulte [Referência de plug-ins de documentos de comando](documents-command-ssm-plugin-reference.md).
O Systems Manager Automation executa as etapas definidas em runbooks de automação. Cada etapa está associada a uma ação específica. A ação determina as entradas, o comportamento e as saídas da etapa. As etapas são definidas na seção `mainSteps` do seu runbook.
Não é necessário especificar as saídas de uma ação ou etapa. As saídas são predeterminadas pela ação associada à etapa. Quando você especifica entradas de etapa em seus runbooks, você pode fazer referência a um ou mais resultados de uma etapa anterior. Por exemplo, você pode disponibilizar a saída de `aws:runInstances` para uma ação `aws:runCommand` subsequente. Você também pode referenciar resultados de etapas anteriores na seção `Output` do runbook.
**Importante**
Se você executar um fluxo de trabalho de automação que chama outros serviços usando uma função de serviço do AWS Identity and Access Management (IAM), esteja ciente de que esta função deve ser configurada com permissão para chamar esses serviços. Esse requisito aplica-se a todos os runbooks do Automation da AWS (runbooks da `AWS-*`), como os runbooks `AWS-ConfigureS3BucketLogging`, `AWS-CreateDynamoDBBackup` e `AWS-RestartEC2Instance`, entre outros. Esse requisito também se aplica a todos os runbooks personalizados do Automation criados que invoquem outros Serviços da AWS, usando ações que chamam outros serviços. Por exemplo, se você usar as ações `aws:executeAwsApi`, `aws:createStack` ou `aws:copyImage`, configure a função de serviço com permissão para invocar esses serviços. É possível habilitar permissões para outros Serviços da AWS, adicionando uma política em linha do IAM à função. Para obter mais informações, consulte [(Opcional) Adicione uma política em linha ou uma política gerenciada pelo cliente para invocar outros Serviços da AWS](automation-setup-iam.md#add-inline-policy).
**Topics**
+ [Propriedades compartilhadas por todas as ações](#automation-common)
+ [`aws:approve` – Pausa uma automação para aprovação manual](automation-action-approve.md)
+ [`aws:assertAwsResourceProperty`: define um estado do recurso da AWS ou o estado do evento](automation-action-assertAwsResourceProperty.md)
+ [`aws:branch` – Executa etapas de automação condicionais](automation-action-branch.md)
+ [`aws:changeInstanceState`: altera ou declara o estado da instância](automation-action-changestate.md)
+ [`aws:copyImage` – copia ou criptografa um Amazon Machine Image](automation-action-copyimage.md)
+ [`aws:createImage`: cria uma imagem de máquina da Amazon](automation-action-create.md)
+ [`aws:createStack`: cria uma pilha do CloudFormation](automation-action-createstack.md)
+ [`aws:createTags`: cria tags para os recursos da AWS](automation-action-createtag.md)
+ [`aws:deleteImage`: exclui uma Imagem de máquina da Amazon](automation-action-delete.md)
+ [`aws:deleteStack`: exclui uma pilha do CloudFormation](automation-action-deletestack.md)
+ [`aws:executeAutomation` – Executa outra automação](automation-action-executeAutomation.md)
+ [`aws:executeAwsApi`: chama e executa as operações de API do AWS](automation-action-executeAwsApi.md)
+ [`aws:executeScript` – Executa um script](automation-action-executeScript.md)
+ [`aws:executeStateMachine` – Executa uma máquina de estado do AWS Step Functions](automation-action-executeStateMachine.md)
+ [`aws:invokeWebhook` — Invoque uma integração de webhook do Automation](invoke-webhook.md)
+ [`aws:invokeLambdaFunction` – Invoca uma função do AWS Lambda](automation-action-lamb.md)
+ [`aws:loop`: itera nas etapas de uma automação](automation-action-loop.md)
+ [`aws:pause` – Pausa uma automação](automation-action-pause.md)
+ [`aws:runCommand` – Executa um comando em uma instância gerenciada](automation-action-runcommand.md)
+ [`aws:runInstances` – Executa uma instância do Amazon EC2](automation-action-runinstance.md)
+ [`aws:sleep`: atrasa uma automação](automation-action-sleep.md)
+ [`aws:updateVariable`: atualiza um valor para uma variável do runbook](automation-action-update-variable.md)
+ [`aws:waitForAwsResourceProperty`: aguarde uma propriedade de recurso da AWS](automation-action-waitForAwsResourceProperty.md)
+ [Variáveis de sistema de automação](automation-variables.md)
## Propriedades compartilhadas por todas as ações
Propriedades comuns são parâmetros ou opções encontradas em todas as ações. Algumas opções definem o comportamento para uma etapa, como o tempo de espera para que uma etapa seja concluída e o que fazer se a etapa falhar. As seguintes propriedades são comuns a todas as ações.
[description](#descriptProp)
Informações que você fornece para descrever a finalidade de um runbook ou de uma etapa.
Tipo: String
Obrigatório: Não
[name](#nameProp)
Um identificador que deve ser exclusivo em todos os nomes de etapas do runbook.
Tipo: String
Padrão permitido: [a-zA-Z0-9\$1]\$1\$1
Obrigatório: Sim
[action](#actProp)
O nome da ação que a etapa deve executar. [`aws:runCommand` – Executa um comando em uma instância gerenciada](automation-action-runcommand.md) é um exemplo de uma ação que você pode especificar aqui. Esse documento fornece informações detalhadas sobre todas as ações disponíveis.
Tipo: string
Obrigatório: sim
[maxAttempts](#maxProp)
Quantas vezes a etapa deve ser repetida em caso de falha. Se o valor for maior que 1, a etapa não será considerada falha até que todas as novas tentativas tenham falhado. O valor padrão é 1.
Tipo: inteiro
Obrigatório: não
[timeoutSeconds](#timeProp)
O valor de tempo limite para a etapa. Se o tempo limite for atingido, e o valor de `maxAttempts` for maior que 1, a etapa não será considerada expirada até que todas as novas tentativas tenham sido feitas.
Tipo: inteiro
Obrigatório: Não
[onFailure](#failProp)
Indica se a automação deve ser interrompida, se deve continuar ou seguir para outra etapa, no caso de falha. O valor padrão desta opção é anular.
Tipo: String
Valores válidos: Anular \$1 Continuar \$1 etapa:*step\$1name*
Obrigatório: Não
[onCancel](#canProp)
Indica para qual etapa a automação deve passar no caso de um usuário cancelar a automação. A automação executa o fluxo de trabalho de cancelamento por um máximo de dois minutos.
Tipo: String
Valores válidos: Abort \$1 step:*step\$1name*
Obrigatório: Não
A propriedade `onCancel` não oferece suporte para mover para as seguintes ações:
+ `aws:approve`
+ `aws:copyImage`
+ `aws:createImage`
+ `aws:createStack`
+ `aws:createTags`
+ `aws:loop`
+ `aws:pause`
+ `aws:runInstances`
+ `aws:sleep`
[isEnd](#endProp)
Essa opção interrompe automação no final de determinada etapa. A automação é interrompida se a execução da etapa falhar ou for bem-sucedida. O valor padrão é falso.
Tipo: booliano
Valores válidos: verdadeiro \$1 falso
Obrigatório: Não
[nextStep](#nextProp)
Especifica qual etapa de uma automação deve ser processada imediatamente após a conclusão bem-sucedida de uma etapa.
Tipo: String
Obrigatório: Não
[isCritical](#critProp)
Designa uma etapa como essencial para a conclusão bem sucedida da automação. Se uma etapa com essa designação falhar, a automação relatará o status final do Automation como Failed (com falha). Essa propriedade só será avaliada se você a definir explicitamente em sua etapa. Se o a propriedade `onFailure` for definida como `Continue` em uma etapa, o valor padrão será falso. Caso contrário, valor padrão desta opção é verdadeiro.
Tipo: booliano
Valores válidos: verdadeiro \$1 falso
Obrigatório: Não
[inputs](#inProp)
As propriedades específicas da ação.
Tipo: mapa
Obrigatório: sim
### Exemplo
```
---
description: "Custom Automation Example"
schemaVersion: '0.3'
assumeRole: "{{ AutomationAssumeRole }}"
parameters:
AutomationAssumeRole:
type: String
description: "(Required) The ARN of the role that allows Automation to perform
the actions on your behalf. If no role is specified, Systems Manager Automation
uses your IAM permissions to run this runbook."
default: ''
InstanceId:
type: String
description: "(Required) The Instance Id whose root EBS volume you want to restore the latest Snapshot."
default: ''
mainSteps:
- name: getInstanceDetails
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- "{{ InstanceId }}"
outputs:
- Name: availabilityZone
Selector: "$.Reservations[0].Instances[0].Placement.AvailabilityZone"
Type: String
- Name: rootDeviceName
Selector: "$.Reservations[0].Instances[0].RootDeviceName"
Type: String
nextStep: getRootVolumeId
- name: getRootVolumeId
action: aws:executeAwsApi
maxAttempts: 3
onFailure: Abort
inputs:
Service: ec2
Api: DescribeVolumes
Filters:
- Name: attachment.device
Values: ["{{ getInstanceDetails.rootDeviceName }}"]
- Name: attachment.instance-id
Values: ["{{ InstanceId }}"]
outputs:
- Name: rootVolumeId
Selector: "$.Volumes[0].VolumeId"
Type: String
nextStep: getSnapshotsByStartTime
- name: getSnapshotsByStartTime
action: aws:executeScript
timeoutSeconds: 45
onFailure: Abort
inputs:
Runtime: python3.8
Handler: getSnapshotsByStartTime
InputPayload:
rootVolumeId : "{{ getRootVolumeId.rootVolumeId }}"
Script: |-
def getSnapshotsByStartTime(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
rootVolumeId = events['rootVolumeId']
snapshotsQuery = ec2.describe_snapshots(
Filters=[
{
"Name": "volume-id",
"Values": [rootVolumeId]
}
]
)
if not snapshotsQuery['Snapshots']:
noSnapshotFoundString = "NoSnapshotFound"
return { 'noSnapshotFound' : noSnapshotFoundString }
else:
jsonSnapshots = snapshotsQuery['Snapshots']
sortedSnapshots = sorted(jsonSnapshots, key=lambda k: k['StartTime'], reverse=True)
latestSortedSnapshotId = sortedSnapshots[0]['SnapshotId']
return { 'latestSnapshotId' : latestSortedSnapshotId }
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: latestSnapshotId
Selector: $.Payload.latestSnapshotId
Type: String
- Name: noSnapshotFound
Selector: $.Payload.noSnapshotFound
Type: String
nextStep: branchFromResults
- name: branchFromResults
action: aws:branch
onFailure: Abort
onCancel: step:startInstance
inputs:
Choices:
- NextStep: createNewRootVolumeFromSnapshot
Not:
Variable: "{{ getSnapshotsByStartTime.noSnapshotFound }}"
StringEquals: "NoSnapshotFound"
isEnd: true
- name: createNewRootVolumeFromSnapshot
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateVolume
AvailabilityZone: "{{ getInstanceDetails.availabilityZone }}"
SnapshotId: "{{ getSnapshotsByStartTime.latestSnapshotId }}"
outputs:
- Name: newRootVolumeId
Selector: "$.VolumeId"
Type: String
nextStep: stopInstance
- name: stopInstance
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: StopInstances
InstanceIds:
- "{{ InstanceId }}"
nextStep: verifyVolumeAvailability
- name: verifyVolumeAvailability
action: aws:waitForAwsResourceProperty
timeoutSeconds: 120
inputs:
Service: ec2
Api: DescribeVolumes
VolumeIds:
- "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
PropertySelector: "$.Volumes[0].State"
DesiredValues:
- "available"
nextStep: verifyInstanceStopped
- name: verifyInstanceStopped
action: aws:waitForAwsResourceProperty
timeoutSeconds: 120
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- "{{ InstanceId }}"
PropertySelector: "$.Reservations[0].Instances[0].State.Name"
DesiredValues:
- "stopped"
nextStep: detachRootVolume
- name: detachRootVolume
action: aws:executeAwsApi
onFailure: Abort
isCritical: true
inputs:
Service: ec2
Api: DetachVolume
VolumeId: "{{ getRootVolumeId.rootVolumeId }}"
nextStep: verifyRootVolumeDetached
- name: verifyRootVolumeDetached
action: aws:waitForAwsResourceProperty
timeoutSeconds: 30
inputs:
Service: ec2
Api: DescribeVolumes
VolumeIds:
- "{{ getRootVolumeId.rootVolumeId }}"
PropertySelector: "$.Volumes[0].State"
DesiredValues:
- "available"
nextStep: attachNewRootVolume
- name: attachNewRootVolume
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: AttachVolume
Device: "{{ getInstanceDetails.rootDeviceName }}"
InstanceId: "{{ InstanceId }}"
VolumeId: "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
nextStep: verifyNewRootVolumeAttached
- name: verifyNewRootVolumeAttached
action: aws:waitForAwsResourceProperty
timeoutSeconds: 30
inputs:
Service: ec2
Api: DescribeVolumes
VolumeIds:
- "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
PropertySelector: "$.Volumes[0].Attachments[0].State"
DesiredValues:
- "attached"
nextStep: startInstance
- name: startInstance
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: StartInstances
InstanceIds:
- "{{ InstanceId }}"
```
# `aws:approve` – Pausa uma automação para aprovação manual
Pausa temporariamente uma automação, até que as entidades principais designadas aprovem ou rejeitem a ação. Depois que o número necessário de aprovações for atingido, a execução da automação será retomada. Você pode inserir a etapa de aprovação em qualquer lugar na seção `mainSteps` do runbook.
**nota**
Essa ação não é compatível com automações de várias contas e regiões. O tempo limite padrão para essa ação é de 7 dias (604.800 segundos) e o valor máximo é de 30 dias (2.592.000 segundos). Você pode limitar ou prolongar o tempo limite especificando o parâmetro `timeoutSeconds` para uma etapa `aws:approve`.
No exemplo a seguir, a ação `aws:approve` pausa temporariamente a automação até que um aprovador a aceite ou rejeite. Após a aprovação, a automação executa um comando simples do PowerShell.
------
#### [ YAML ]
```
---
description: RunInstancesDemo1
schemaVersion: '0.3'
assumeRole: "{{ assumeRole }}"
parameters:
assumeRole:
type: String
message:
type: String
mainSteps:
- name: approve
action: aws:approve
timeoutSeconds: 1000
onFailure: Abort
inputs:
NotificationArn: arn:aws:sns:us-east-2:12345678901:AutomationApproval
Message: "{{ message }}"
MinRequiredApprovals: 1
Approvers:
- arn:aws:iam::12345678901:user/AWS-User-1
- name: run
action: aws:runCommand
inputs:
InstanceIds:
- i-1a2b3c4d5e6f7g
DocumentName: AWS-RunPowerShellScript
Parameters:
commands:
- date
```
------
#### [ JSON ]
```
{
"description":"RunInstancesDemo1",
"schemaVersion":"0.3",
"assumeRole":"{{ assumeRole }}",
"parameters":{
"assumeRole":{
"type":"String"
},
"message":{
"type":"String"
}
},
"mainSteps":[
{
"name":"approve",
"action":"aws:approve",
"timeoutSeconds":1000,
"onFailure":"Abort",
"inputs":{
"NotificationArn":"arn:aws:sns:us-east-2:12345678901:AutomationApproval",
"Message":"{{ message }}",
"MinRequiredApprovals":1,
"Approvers":[
"arn:aws:iam::12345678901:user/AWS-User-1"
]
}
},
{
"name":"run",
"action":"aws:runCommand",
"inputs":{
"InstanceIds":[
"i-1a2b3c4d5e6f7g"
],
"DocumentName":"AWS-RunPowerShellScript",
"Parameters":{
"commands":[
"date"
]
}
}
}
]
}
```
------
É possível aprovar ou negar automações que estão aguardando aprovação no console.
**Para aprovar ou negar automações em espera**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação à esquerda, escolha **Automation** (Automação).
1. Escolha a opção ao lado de uma automação com o status **Waiting (Em espera)**.
![\[Acessar a página Approve/Deny Automation\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/automation-approve-action-aws.png)
1. Escolha **Approve/Deny** (Aprovar/negar).
1. Analise os detalhes da automação.
1. Escolha **Approve (Aprovar)** ou **Deny (Negar)**, digite um comentário opcional e escolha **Submit (Enviar)**.
**Exemplo de entrada**
------
#### [ YAML ]
```
NotificationArn: arn:aws:sns:us-west-1:12345678901:Automation-ApprovalRequest
Message: Please approve this step of the Automation.
MinRequiredApprovals: 3
Approvers:
- IamUser1
- IamUser2
- arn:aws:iam::12345678901:user/IamUser3
- arn:aws:iam::12345678901:role/IamRole
```
------
#### [ JSON ]
```
{
"NotificationArn":"arn:aws:sns:us-west-1:12345678901:Automation-ApprovalRequest",
"Message":"Please approve this step of the Automation.",
"MinRequiredApprovals":3,
"Approvers":[
"IamUser1",
"IamUser2",
"arn:aws:iam::12345678901:user/IamUser3",
"arn:aws:iam::12345678901:role/IamRole"
]
}
```
------
NotificationArn
O tópico do nome do recurso da Amazon (ARN de um Amazon Simple Notification Service, Amazon SNS) para aprovações do Automation. Quando você especifica uma etapa `aws:approve` em um runbook, o Automation envia uma mensagem a esse tópico, permitindo que as entidades principais saibam se devem aprovar ou rejeitar uma etapa do Automation. O título do tópico do Amazon SNS deve ser prefixado com "Automation".
Tipo: string
Obrigatório: não
Mensagem
As informações que você deseja incluir no tópico do Amazon SNS quando a solicitação de aprovação é enviada. O comprimento máximo da mensagem é de 4096 caracteres.
Tipo: string
Obrigatório: não
MinRequiredApprovals
O número mínimo de aprovações necessárias para retomar a automação. Se você não especificar um valor, o sistema assumirá 1 como padrão. O valor desse parâmetro deve ser um número positivo. O valor desse parâmetro não pode exceder o número de aprovadores definidas pelo parâmetro `Approvers`.
Tipo: inteiro
Obrigatório: não
Approvers
Uma lista de entidades principais autenticadas da AWS que podem aprovar ou rejeitar a ação. O número máximo de aprovadores é 10. É possível especificar entidades principais usando qualquer um dos seguintes formatos:
+ Um nome de usuário
+ Um ARN do usuário
+ Um ARN de função do IAM
+ Um IAM assume o perfil do ARN
Tipo: StringList
Obrigatório: Sim
EnhancedApprovals
Essa entrada é usada somente para modelos do Change Manager. Uma lista de entidades principais autenticadas pela AWS que podem aprovar ou rejeitar a ação, o tipo de entidade principal do IAM e o número mínimo de aprovadores. Este é um exemplo:
```
schemaVersion: "0.3"
emergencyChange: false
autoApprovable: false
mainSteps:
- name: ApproveAction1
action: aws:approve
timeoutSeconds: 604800
inputs:
Message: Please approve this change request
MinRequiredApprovals: 3
EnhancedApprovals:
Approvers:
- approver: John Stiles
type: IamUser
minRequiredApprovals: 0
- approver: Ana Carolina Silva
type: IamUser
minRequiredApprovals: 0
- approver: GroupOfThree
type: IamGroup
minRequiredApprovals: 0
- approver: RoleOfTen
type: IamRole
minRequiredApprovals: 0
```
Tipo: StringList
Obrigatório: Sim
**Output**
ApprovalStatus
O status de aprovação da etapa. O status pode ser um dos seguintes: Approved, Rejected ou Waiting. Waiting significa que a Automação está aguardando a entrada de aprovadores.
Tipo: string
ApproverDecisions
Um mapa JSON que inclui a decisão de aprovação de cada aprovador.
Tipo: MapList
# `aws:assertAwsResourceProperty`: define um estado do recurso da AWS ou o estado do evento
A ação `aws:assertAwsResourceProperty` permite que você declare um estado de recurso específico ou estado de evento para uma determinada etapa do Automation.
**nota**
A ação `aws:assertAwsResourceProperty` suporta uma nova tentativa automática de controle de utilização. Para obter mais informações, consulte [Configurar a repetição automática para operações com controle de utilização](automation-throttling-retry.md).
Para obter mais exemplos de como usar essa ação, consulte [Exemplos adicionais de runbook](automation-document-examples.md).
**Input**
As entradas são definidas pela operação de API que você escolher.
------
#### [ YAML ]
```
action: aws:assertAwsResourceProperty
inputs:
Service: The official namespace of the service
Api: The API operation or method name
API operation inputs or parameters: A value
PropertySelector: Response object
DesiredValues:
- Desired property values
```
------
#### [ JSON ]
```
{
"action": "aws:assertAwsResourceProperty",
"inputs": {
"Service":"The official namespace of the service",
"Api":"The API operation or method name",
"API operation inputs or parameters":"A value",
"PropertySelector": "Response object",
"DesiredValues": [
"Desired property values"
]
}
}
```
------
Serviço
O namespace do AWS service (Serviço da AWS) que contém a operação de API que você deseja executar. Por exemplo, o namespace para o Systems Manager é `ssm`. O namespace do Amazon EC2 é `ec2`. Você pode visualizar uma lista de namespaces de AWS service (Serviço da AWS) compatíveis na seção [Available Services](https://docs.aws.amazon.com/cli/latest/reference/#available-services) (Serviços disponíveis) da *Referência de comandos da AWS CLI*.
Tipo: String
Exigido: sim
API
O nome da operação de API que você deseja executar. Você pode visualizar as operações de API (também chamadas de métodos), escolhendo um serviço na navegação à esquerda na seguinte página de [Referência de serviços](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html): Escolha um método na seção **Client (Cliente)** para o serviço que você deseja invocar. Por exemplo, todas as operações de API (métodos) do Amazon Relational Database Service (Amazon RDS) estão listadas na seguinte página: [Amazon RDS methods](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html) (Métodos do Amazon RDS).
Tipo: String
Exigido: sim
Entradas de operação da API
Uma ou mais entradas de operação da API. Você pode visualizar as entradas disponíveis (também chamadas de parâmetros), escolhendo um serviço na navegação à esquerda na seguinte página de [Referência de serviços](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html). Escolha um método na seção **Client (Cliente)** para o serviço que você deseja invocar. Por exemplo, todos os métodos de API estão listados na página a seguir: [Métodos do Amazon RDS](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html). Escolha o método [describe\$1db\$1instances](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html#RDS.Client.describe_db_instances) e role para baixo para ver os parâmetros disponíveis, como **DBInstanceIdentifier**, **Name (Nome)** e **Values (Valores)**. Use o formato a seguir para especificar mais de uma entrada.
```
inputs:
Service: The official namespace of the service
Api: The API operation name
API input 1: A value
API Input 2: A value
API Input 3: A value
```
```
"inputs":{
"Service":"The official namespace of the service",
"Api":"The API operation name",
"API input 1":"A value",
"API Input 2":"A value",
"API Input 3":"A value"
}
```
Tipo: determinado pela ação de API escolhida
Obrigatório: Sim
PropertySelector
O JSONPath para um determinado atributo no objeto de resposta. Você pode visualizar os objetos de resposta escolhendo um serviço na navegação à esquerda na seguinte página de [Referência de serviços](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html). Escolha um método na seção **Client (Cliente)** para o serviço que você deseja invocar. Por exemplo, todos os métodos de API estão listados na página a seguir: [Métodos do Amazon RDS](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html). Escolha o método [describe\$1db\$1instances](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html#RDS.Client.describe_db_instances) e role para baixo até a seção **Response Structure (Estrutura de resposta)**. **DBInstances** é listado como um objeto de resposta.
Tipo: String
Exigido: sim
DesiredValues
O status ou estado esperado no qual a automação deve continuar. Se você especificar um valor booleano, você deve usar uma letra maiúscula, como Verdadeiro ou Falso.
Tipo: StringList
Obrigatório: Sim
# `aws:branch` – Executa etapas de automação condicionais
A ação `aws:branch` permite que você crie uma automação dinâmica que avalia diferentes opções em uma única etapa e, em seguida, salta para outra etapa no runbook, com base nos resultados da avaliação.
Quando você especifica a ação `aws:branch` para uma etapa, você especifica as `Choices` que a automação deve avaliar. As `Choices` podem ser baseadas no valor especificado na seção `Parameters` do runbook ou em um valor dinâmico gerado como saída da etapa anterior. A automação avalia cada opção usando uma expressão booleana. Se a primeira opção for verdadeira, a automação pulará para a etapa designada para essa opção. Se a primeira opção for falsa, a automação avaliará a próxima opção. A automação continua a avaliar cada opção até processar uma opção verdadeira. A automação pula para a etapa designada para a opção true (verdadeira).
Se nenhuma das opções for verdadeira, a automação verificará se a etapa contém um valor `default`. Um valor padrão define uma etapa para a qual a automação deve saltar se nenhuma das opções for verdadeira. Se nenhum valor `default` for especificado para a etapa, a automação processará a próxima etapa no runbook.
A ação `aws:branch` oferece suporte a avaliações de opções complexas usando uma combinação de operadores `And`, `Not` e `Or`. Para obter mais informações sobre como usar o `aws:branch`, incluindo runbooks de exemplo e exemplos que usam operadores diferentes, consulte [Uso de instruções condicionais em runbooks](automation-branch-condition.md).
**Input**
Especifique uma ou mais `Choices` em uma etapa. As `Choices` podem ser baseadas no valor especificado na seção `Parameters` do runbook ou em um valor dinâmico gerado como saída da etapa anterior. Aqui está um exemplo de YAML que avalia um parâmetro.
```
mainSteps:
- name: chooseOS
action: aws:branch
inputs:
Choices:
- NextStep: runWindowsCommand
Variable: "{{Name of a parameter defined in the Parameters section. For example: OS_name}}"
StringEquals: windows
- NextStep: runLinuxCommand
Variable: "{{Name of a parameter defined in the Parameters section. For example: OS_name}}"
StringEquals: linux
Default:
sleep3
```
Aqui está um exemplo de YAML que avalia a saída de uma etapa anterior.
```
mainSteps:
- name: chooseOS
action: aws:branch
inputs:
Choices:
- NextStep: runPowerShellCommand
Variable: "{{Name of a response object. For example: GetInstance.platform}}"
StringEquals: Windows
- NextStep: runShellCommand
Variable: "{{Name of a response object. For example: GetInstance.platform}}"
StringEquals: Linux
Default:
sleep3
```
Choices
Uma ou mais expressões que a Automação deve avaliar ao determinar a próxima etapa para a ser processada. Choices são avaliadas usando uma expressão booliana. Cada opção deve definir as seguintes opções:
+ **NextStep**: a próxima etapa no runbook para processar se a opção designada é verdadeira.
+ **Variable**: especifique o nome de um parâmetro definido na seção `Parameters` do runbook. Ou especifique um objeto de saída de uma etapa anterior no runbook. Para obter mais informações sobre como criar variáveis para `aws:branch`, consulte [Sobre a criação de variáveis de saída](automation-branch-condition.md#branch-action-output).
+ **Operation**: os critérios usados para avaliar a opção. A ação `aws:branch` oferece suporte às seguintes operações:
**Operações de string**
+ StringEquals
+ EqualsIgnoreCase
+ StartsWith
+ EndsWith
+ Contém
**Operações numéricas**
+ NumericEquals
+ NumericGreater
+ NumericLesser
+ NumericGreaterOrEquals
+ NumericLesser
+ NumericLesserOrEquals
**Operação booleana**
+ BooleanEquals
**Importante**
Quando você cria um runbook, o sistema valida cada operação dele. Se uma operação não for suportada, o sistema retornará um erro ao tentar criar o runbook.
Padrão
O nome de uma etapa para a qual a automação deve saltar, se nenhuma das `Choices` forem verdadeiras.
Tipo: string
Obrigatório: não
**nota**
A ação `aws:branch` oferece suporte a operadores `And`, `Or` e `Not`. Para obter exemplos de `aws:branch` que usam operadores, consulte [Uso de instruções condicionais em runbooks](automation-branch-condition.md).
# `aws:changeInstanceState`: altera ou declara o estado da instância
Altera ou declara o estado da instância.
Essa ação pode ser usada no modo de declaração (não executa a API para alterar o estado, mas verifica se a instância está no estado desejado). Para usar o modo de declaração, defina o parâmetro `CheckStateOnly` como true. Esse modo é útil no Windows Server ao executar o comando Sysprep, um comando assíncrono que pode ser executado em segundo plano por um longo tempo. Você pode garantir que a instância seja interrompida antes de criar uma Amazon Machine Image (AMI).
**nota**
O valor de tempo limite padrão para esta ação é 3600 segundos (uma hora). Você pode limitar ou prolongar o tempo limite especificando o parâmetro `timeoutSeconds` para uma etapa `aws:changeInstanceState`.
**nota**
A ação `aws:changeInstanceState` suporta uma nova tentativa automática de controle de utilização. Para obter mais informações, consulte [Configurar a repetição automática para operações com controle de utilização](automation-throttling-retry.md).
**Entrada**
------
#### [ YAML ]
```
name: stopMyInstance
action: aws:changeInstanceState
maxAttempts: 3
timeoutSeconds: 3600
onFailure: Abort
inputs:
InstanceIds:
- i-1234567890abcdef0
CheckStateOnly: true
DesiredState: stopped
```
------
#### [ JSON ]
```
{
"name":"stopMyInstance",
"action": "aws:changeInstanceState",
"maxAttempts": 3,
"timeoutSeconds": 3600,
"onFailure": "Abort",
"inputs": {
"InstanceIds": ["i-1234567890abcdef0"],
"CheckStateOnly": true,
"DesiredState": "stopped"
}
}
```
------
InstanceIds
Os IDs das instâncias.
Tipo: StringList
Obrigatório: Sim
CheckStateOnly
Se false, define o estado da instância como o estado desejado. Se true, declara o estado desejado usando sondagem.
Padrão: `false`
Tipo: booliano
Obrigatório: não
DesiredState
O estado desejado. Quando definida como `running`, essa ação aguarda que o estado do Amazon EC2 seja `Running`, o status da instância seja `OK` e o status do sistema seja `OK`, antes de concluir.
Tipo: string
Valores válidos: `running` \$1 `stopped` \$1 `terminated`
Obrigatório: Sim
Force
Se configurado, força a interrupção das instâncias. As instâncias não têm a oportunidade de liberar os caches ou metadados do sistema de arquivos. Se você usar essa opção, deve executar a verificação do sistema de arquivos e os procedimentos de reparo. Essa opção não é recomendada para instâncias do EC2 para Windows Server.
Tipo: booliano
Obrigatório: não
AdditionalInfo
Reservado.
Tipo: string
Obrigatório: não
**Output**
Nenhum
# `aws:copyImage` – copia ou criptografa um Amazon Machine Image
Copia uma Amazon Machine Image (AMI) de qualquer Região da AWS para a região atual. Essa ação também pode criptografar a nova AMI.
**nota**
A ação `aws:copyImage` suporta uma nova tentativa automática de controle de utilização. Para obter mais informações, consulte [Configurar a repetição automática para operações com controle de utilização](automation-throttling-retry.md).
**Input**
Essa ação oferece suporte para a maioria dos parâmetros `CopyImage`. Para obter mais informações, consulte [CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html).
O exemplo a seguir cria uma cópia de uma AMI na região de Seul (`SourceImageID`: ami-0fe10819. `SourceRegion`: ap-northeast-2). A nova AMI é copiada para a região em que você iniciou a ação do Automation. A AMI copiada será criptografada, pois o sinalizador `Encrypted` opcional está definido como `true`.
------
#### [ YAML ]
```
name: createEncryptedCopy
action: aws:copyImage
maxAttempts: 3
onFailure: Abort
inputs:
SourceImageId: ami-0fe10819
SourceRegion: ap-northeast-2
ImageName: Encrypted Copy of LAMP base AMI in ap-northeast-2
Encrypted: true
```
------
#### [ JSON ]
```
{
"name": "createEncryptedCopy",
"action": "aws:copyImage",
"maxAttempts": 3,
"onFailure": "Abort",
"inputs": {
"SourceImageId": "ami-0fe10819",
"SourceRegion": "ap-northeast-2",
"ImageName": "Encrypted Copy of LAMP base AMI in ap-northeast-2",
"Encrypted": true
}
}
```
------
SourceRegion
A região em que a AMI de origem existe.
Tipo: String
Exigido: sim
SourceImageId
O ID de AMI a ser copiado da região de origem.
Tipo: String
Exigido: sim
ImageName
O nome da nova imagem.
Tipo: String
Exigido: sim
ImageDescription
Uma descrição da imagem de destino.
Tipo: string
Obrigatório: não
Criptografado
Criptografe a de destino AMI.
Tipo: booliano
Obrigatório: não
KmsKeyId
O nome do recurso da Amazon (ARN) completo da AWS KMS key a ser usado para criptografar os snapshots de uma imagem durante uma operação de cópia. Para obter mais informações, consulte [CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/api_copyimage.html).
Tipo: string
Obrigatório: não
ClientToken
Um identificador único e com diferenciação entre maiúsculas de minúsculas que você fornece para garantir a idempotência da solicitação. Para obter mais informações, consulte [CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/api_copyimage.html).
Tipo: string
Obrigatório: nãoOutput
ImageId
O ID da imagem copiada.
ImageState
O estado da imagem copiada.
Valores válidos: `available` \$1 `pending` \$1 `failed`
# `aws:createImage`: cria uma imagem de máquina da Amazon
Cria uma Amazon Machine Image (AMI) de uma instância que está em execução, parando ou parada e solicita que `ImageState` seja `available`.
**nota**
A ação `aws:createImage` suporta uma nova tentativa automática de controle de utilização. Para obter mais informações, consulte [Configurar a repetição automática para operações com controle de utilização](automation-throttling-retry.md).
**Input**
Essa ação oferece suporte aos seguintes parâmetros de `CreateImage`: Para obter mais informações, consulte [CreateImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateImage.html).
------
#### [ YAML ]
```
name: createMyImage
action: aws:createImage
maxAttempts: 3
onFailure: Abort
inputs:
InstanceId: i-1234567890abcdef0
ImageName: AMI Created on{{global:DATE_TIME}}
NoReboot: true
ImageDescription: My newly created AMI
```
------
#### [ JSON ]
```
{
"name": "createMyImage",
"action": "aws:createImage",
"maxAttempts": 3,
"onFailure": "Abort",
"inputs": {
"InstanceId": "i-1234567890abcdef0",
"ImageName": "AMI Created on{{global:DATE_TIME}}",
"NoReboot": true,
"ImageDescription": "My newly created AMI"
}
}
```
------
InstanceId
O ID da instância.
Tipo: String
Exigido: sim
ImageName
O nome da imagem.
Tipo: String
Exigido: sim
ImageDescription
Uma descrição da imagem.
Tipo: string
Obrigatório: não
NoReboot
Um literal booleana.
Por padrão, o Amazon Elastic Compute Cloud (Amazon EC2) tenta desligar e reinicializar a instância antes de criar a imagem. Se a opção **No Reboot** (Não reinicializar) estiver definida como `true`, o Amazon EC2 não desligará a instância antes de criar a imagem. Quando esta opção é usada, não é possível garantir a integridade do sistema de arquivos na imagem criada.
Se você não quiser executar a instância depois de criar uma AMI nela, primeiro use a ação [`aws:changeInstanceState`: altera ou declara o estado da instância](automation-action-changestate.md) para interromper a instância e, depois, use a ação `aws:createImage` com a opção **NoReboot** (Não inicializar) definida como `true`.
Tipo: booliano
Obrigatório: não
BlockDeviceMappings
Os dispositivos de bloco para a instância.
Tipo: mapa
Obrigatório: nãoOutput
ImageId
O ID da imagem recém-criada.
Tipo: string
ImageState
O estado atual da imagem. Se o estado estiver disponível, a imagem será registrada com êxito e poderá ser usada para executar uma instância.
Tipo: string
# `aws:createStack`: cria uma pilha do CloudFormation
Cria uma pilha do AWS CloudFormation a partir de um modelo.
**nota**
A ação `aws:createStack` suporta uma nova tentativa automática de controle de utilização. Para obter mais informações, consulte [Configurar a repetição automática para operações com controle de utilização](automation-throttling-retry.md).
Para obter informações adicionais sobre como criar pilhas do CloudFormation, consulte [CreateStack](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) na *Referência da API no AWS CloudFormation*.
**Entrada**
------
#### [ YAML ]
```
name: makeStack
action: aws:createStack
maxAttempts: 1
onFailure: Abort
inputs:
Capabilities:
- CAPABILITY_IAM
StackName: myStack
TemplateURL: http://s3.amazonaws.com/amzn-s3-demo-bucket/myStackTemplate
TimeoutInMinutes: 5
Parameters:
- ParameterKey: LambdaRoleArn
ParameterValue: "{{LambdaAssumeRole}}"
- ParameterKey: createdResource
ParameterValue: createdResource-{{automation:EXECUTION_ID}}
```
------
#### [ JSON ]
```
{
"name": "makeStack",
"action": "aws:createStack",
"maxAttempts": 1,
"onFailure": "Abort",
"inputs": {
"Capabilities": [
"CAPABILITY_IAM"
],
"StackName": "myStack",
"TemplateURL": "http://s3.amazonaws.com/amzn-s3-demo-bucket/myStackTemplate",
"TimeoutInMinutes": 5,
"Parameters": [
{
"ParameterKey": "LambdaRoleArn",
"ParameterValue": "{{LambdaAssumeRole}}"
},
{
"ParameterKey": "createdResource",
"ParameterValue": "createdResource-{{automation:EXECUTION_ID}}"
}
}
}
```
------
Capacidades
Uma lista de valores que você especifica antes que o CloudFormation possa criar certas pilhas. Alguns modelos de pilha podem incluir recursos que podem afetar as permissões na sua Conta da AWS. Para essas pilhas, você deve confirmar explicitamente seus recursos especificando esse parâmetro.
Os valores válidos são `CAPABILITY_IAM`, `CAPABILITY_NAMED_IAM` e `CAPABILITY_AUTO_EXPAND`.
**CAPABILITY\$1IAM e CAPABILITY\$1NAMED\$1IAM**
Se você tiver recursos do IAM, poderá especificar qualquer recurso. Se tiver recursos do IAM com nomes personalizados, você deverá especificar `CAPABILITY_NAMED_IAM`. Se você não especificar esse parâmetro, essa ação retornará um erro `InsufficientCapabilities`. Os seguintes recursos exigem especificar `CAPABILITY_IAM` ou `CAPABILITY_NAMED_IAM`.
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-accesskey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-accesskey.html)
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-group.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-group.html)
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-instanceprofile.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-instanceprofile.html)
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-policy.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-policy.html)
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html)
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-user.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-user.html)
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-addusertogroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-addusertogroup.html)
Se o seu modelo de pilha contiver esses recursos, recomendamos que você reveja todas as permissões associadas a eles e edite suas permissões, se necessário.
Para obter mais informações, consulte o tópico sobre como [Reconhecer recursos do IAM em modelos do CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html#capabilities).
**CAPABILITY\$1AUTO\$1EXPAND**
Alguns modelos contêm macros. Macros executam o processamento personalizado em modelos. Isso inclui ações simples, como operações de localizar e substituir até transformações extensas de modelos inteiros. Por isso, os usuários geralmente criam um conjunto de alterações no modelo processado para que seja possível revisar as alterações resultantes das macros antes de criar a pilha de fato. Se o modelo de pilha tiver uma ou mais macros, e você optar por criar uma pilha diretamente do modelo processado sem primeiro revisar as alterações resultantes em um conjunto de alterações, será necessário reconhecer esse recurso.
Para obter mais informações, consulte [Usar macros do AWS CloudFormation para executar processamento personalizado em modelos](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-macros.html) no *Manual do usuário do AWS CloudFormation*.
Tipo: matriz de strings
Valores válidos: `CAPABILITY_IAM | CAPABILITY_NAMED_IAM | CAPABILITY_AUTO_EXPAND`
Obrigatório: não
ClientRequestToken
Um identificador exclusivo para essa solicitação CreateStack. Especifique este token se definir maxAttempts nesta etapa como um valor maior que 1. Especificando esse token, o CloudFormation saberá que você não está tentando criar uma nova pilha com o mesmo nome.
Tipo: string
Obrigatório: não
Restrições de Tamanho: Tamanho mínimo 1. O comprimento máximo é 128.
Padrão: [a-zA-Z0-9][-a-zA-Z0-9]\$1
DisableRollback
Defina como `true` para desativar a reversão da pilha se a criação da pilha tiver falhado.
Condicional: é possível especificar o parâmetro `DisableRollback` ou `OnFailure`, mas não ambos.
Padrão: `false`
Tipo: booliano
Obrigatório: não
NotificationARNs
Os ARNs de tópicos do Amazon Simple Notification Service (Amazon SNS) para publicar eventos relacionados à pilha. Você pode encontrar ARNs de tópicos do SNS usando o console do Amazon SNS, [https://console.aws.amazon.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home).
Tipo: matriz de strings
Membros da matriz: número máximo de 5 itens.
Obrigatório: não
OnFailure
Determina a ação a ser realizada se a criação da pilha falhar. Você deve especificar `DO_NOTHING`, `ROLLBACK` ou `DELETE`.
Condicional: é possível especificar o parâmetro `OnFailure` ou `DisableRollback`, mas não ambos.
Padrão: `ROLLBACK`
Tipo: string
Valores válidos:` DO_NOTHING | ROLLBACK | DELETE`
Obrigatório: não
Parâmetros
Uma lista de estruturas `Parameter` que especificam parâmetros de entrada para a pilha. Para obter mais informações, consulte o tipo de dados [Parameter](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_Parameter.html).
Tipo: matriz de objetos [Parameter](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_Parameter.html)
Obrigatório: não
ResourceTypes
Os tipos de recursos de modelo com os quais você tem permissões para trabalhar para essa ação de criação de pilha. Por exemplo: `AWS::EC2::Instance`, `AWS::EC2::*` ou `Custom::MyCustomInstance`. Use a seguinte sintaxe para descrever tipos de recursos de modelo.
+ Para todos os recursos da AWS:
```
AWS::*
```
+ Para todos os recursos personalizados:
```
Custom::*
```
+ Para um recurso personalizado específico:
```
Custom::logical_ID
```
+ Para todos os recursos de um AWS service (Serviço da AWS) específico:
```
AWS::service_name::*
```
+ Para um recurso da AWS específico:
```
AWS::service_name::resource_logical_ID
```
Se a lista de tipos de recursos não incluir um recurso que você está criando, a criação da pilha falhará. Por padrão, o CloudFormation concede permissões a todos os tipos de recursos. O IAM usa esse parâmetro para chaves de condição específicas do CloudFormation nas políticas do IAM. Para obter mais informações, consulte [Controlar o acesso com o AWS Identity and Access Management](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html).
Tipo: matriz de strings
Restrições de tamanho: tamanho mínimo 1. O comprimento máximo é 256.
Obrigatório: não
RoleARN
O nome do recurso da Amazon (ARN) de uma função do IAM assumida pelo CloudFormation para criar a pilha. O CloudFormation usa as credenciais da função para fazer chamadas em seu nome. O CloudFormation sempre usará essa função para todas as futuras operações na pilha. Desde que os usuários tenham permissão para operar na pilha, o CloudFormation usará essa função mesmo que os usuários não tenham permissão para transmiti-la. Certifique-se de que a função conceda a menor quantidade de privilégios.
Se você não especificar um valor, o CloudFormation usará a função anteriormente associada à pilha. Se nenhuma função estiver disponível, o CloudFormation usará uma sessão temporária gerada a partir das suas credenciais de usuário.
Tipo: string
Restrições de tamanho: tamanho mínimo 20. O comprimento máximo é 2.048.
Obrigatório: não
StackName
O nome que está associado à pilha. O nome deve ser exclusivo na região na qual você estiver criando a pilha.
Um nome de pilha pode conter apenas caracteres alfanuméricos (sensíveis a maiúsculas e minúsculas) e hífens. Ele deve começar com um caractere alfabético e não pode ter mais de 128 caracteres.
Tipo: String
Exigido: sim
StackPolicyBody
Estrutura que contém o corpo da política de pilha. Para obter mais informações, consulte o tópico sobre como [Prevenir atualizações para recursos de pilha](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/protect-stack-resources.html).
Condicional: é possível especificar o parâmetro `StackPolicyBody` ou `StackPolicyURL`, mas não ambos.
Tipo: string
Restrições de comprimento: tamanho mínimo de 1. Tamanho máximo de 16384.
Obrigatório: não
StackPolicyURL
Localização de um arquivo contendo a política de pilha. O URL deve apontar para uma política localizada em um bucket do S3 na mesma região que a pilha. O tamanho do arquivo máximo permitido para a política de pilha é de 16 KB.
Condicional: é possível especificar o parâmetro `StackPolicyBody` ou `StackPolicyURL`, mas não ambos.
Tipo: string
Restrições de comprimento: tamanho mínimo de 1. Tamanho máximo de 1350.
Obrigatório: não
Tags
Pares de chave/valor para associar a essa pilha. O CloudFormation também propaga essas tags para os recursos criados na pilha. Você pode especificar um número máximo de 10 tags.
Tipo: matriz de objetos [Tag](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_Tag.html)
Obrigatório: não
TemplateBody
Estrutura que contém o corpo do modelo com um comprimento mínimo de 1 byte e um comprimento máximo de 51.200 bytes. Para obter mais informações, consulte [Anatomia do modelo](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-anatomy.html).
Condicional: é possível especificar o parâmetro `TemplateBody` ou `TemplateURL`, mas não ambos.
Tipo: string
Restrições de comprimento: tamanho mínimo de 1.
Obrigatório: não
TemplateURL
Localização de um arquivo contendo o corpo do modelo. O URL deve apontar para um modelo que esteja localizado em um bucket do S3. O tamanho máximo permitido para o modelo é 460.800 bytes. Para obter mais informações, consulte [Anatomia do modelo](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-anatomy.html).
Condicional: é possível especificar o parâmetro `TemplateBody` ou `TemplateURL`, mas não ambos.
Tipo: string
Restrições de tamanho: tamanho mínimo 1. Tamanho máximo de 1.024.
Obrigatório: não
TimeoutInMinutes
O tempo permitido antes que o status da pilha se torne `CREATE_FAILED`. Se `DisableRollback` não estiver definido ou estiver definido como `false`, a pilha será revertida.
Tipo: inteiro
Intervalo válido: valor mínimo de 1.
Obrigatório: não
## Saídas
StackId
Identificador exclusivo da pilha.
Tipo: string
StackStatus
Status atual da pilha.
Tipo: string
Valores válidos: `CREATE_IN_PROGRESS | CREATE_FAILED | CREATE_COMPLETE | ROLLBACK_IN_PROGRESS | ROLLBACK_FAILED | ROLLBACK_COMPLETE | DELETE_IN_PROGRESS | DELETE_FAILED | DELETE_COMPLETE | UPDATE_IN_PROGRESS | UPDATE_COMPLETE_CLEANUP_IN_PROGRESS | UPDATE_COMPLETE | UPDATE_ROLLBACK_IN_PROGRESS | UPDATE_ROLLBACK_FAILED | UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS | UPDATE_ROLLBACK_COMPLETE | REVIEW_IN_PROGRESS`
Obrigatório: Sim
StackStatusReason
Mensagem de sucesso ou falha associada ao status da pilha.
Tipo: string
Obrigatório: não
Para obter mais informações, consulte [CreateStack](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html).
## Considerações sobre segurança
Antes de poder usar a ação `aws:createStack`, você deve atribuir a seguinte política à função assumida do Automation para IAM. Para obter mais informações sobre a função de admissão, consulte [Tarefa 1: Criar uma função de serviço para a automação](automation-setup-iam.md#create-service-role).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"sqs:*",
"cloudformation:CreateStack",
"cloudformation:DescribeStacks"
],
"Resource":"*"
}
]
}
```
------
# `aws:createTags`: cria tags para os recursos da AWS
Cria novas tags para instâncias do Amazon Elastic Compute Cloud (Amazon EC2) ou instâncias gerenciadas do AWS Systems Manager.
**nota**
A ação `aws:createTags` suporta uma nova tentativa automática de controle de utilização. Para obter mais informações, consulte [Configurar a repetição automática para operações com controle de utilização](automation-throttling-retry.md).
**Input**
Essa ação oferece suporte para a maioria dos parâmetros `CreateTags` do Amazon EC2 e `AddTagsToResource` do Systems Manager. Para obter mais informações, consulte [CreateTags](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/api_createtags.html) e [AddTagsToResource](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/api_addtagstoresource.html).
O exemplo a seguir mostra como marcar uma Amazon Machine Image (AMI) e uma instância como recursos de produção para um departamento específico.
------
#### [ YAML ]
```
name: createTags
action: aws:createTags
maxAttempts: 3
onFailure: Abort
inputs:
ResourceType: EC2
ResourceIds:
- ami-9a3768fa
- i-02951acd5111a8169
Tags:
- Key: production
Value: ''
- Key: department
Value: devops
```
------
#### [ JSON ]
```
{
"name": "createTags",
"action": "aws:createTags",
"maxAttempts": 3,
"onFailure": "Abort",
"inputs": {
"ResourceType": "EC2",
"ResourceIds": [
"ami-9a3768fa",
"i-02951acd5111a8169"
],
"Tags": [
{
"Key": "production",
"Value": ""
},
{
"Key": "department",
"Value": "devops"
}
]
}
}
```
------
ResourceIds
Os IDs dos recursos a serem marcados. Se o tipo de recurso não for "EC2", esse campo poderá conter apenas um item.
Tipo: String List
Obrigatório: Sim
Tags
As tags a serem associadas aos recursos.
Tipo: lista de mapas
Obrigatório: Sim
ResourceType
Os tipos de recursos a serem marcados. Se não for fornecido, o valor padrão de "EC2" será usado.
Tipo: string
Obrigatório: não
Valores válidos: `EC2` \$1 `ManagedInstance` \$1 `MaintenanceWindow` \$1 `Parameter`
**Output**
Nenhum
# `aws:deleteImage`: exclui uma Imagem de máquina da Amazon
Exclua a Amazon Machine Image (AMI) especificada e todos os snapshots relacionados.
**nota**
A ação `aws:deleteImage` suporta uma nova tentativa automática de controle de utilização. Para obter mais informações, consulte [Configurar a repetição automática para operações com controle de utilização](automation-throttling-retry.md).
**Input**
Esta ação oferece suporte para apenas um parâmetro. Para obter mais informações, consulte a documentação de [DeregisterImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DeregisterImage.html) e [DeleteSnapshot](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DeleteSnapshot.html).
------
#### [ YAML ]
```
name: deleteMyImage
action: aws:deleteImage
maxAttempts: 3
timeoutSeconds: 180
onFailure: Abort
inputs:
ImageId: ami-12345678
```
------
#### [ JSON ]
```
{
"name": "deleteMyImage",
"action": "aws:deleteImage",
"maxAttempts": 3,
"timeoutSeconds": 180,
"onFailure": "Abort",
"inputs": {
"ImageId": "ami-12345678"
}
}
```
------
ImageId
O ID da imagem a ser excluída.
Tipo: String
Exigido: sim
**Output**
Nenhum
# `aws:deleteStack`: exclui uma pilha do CloudFormation
Exclui uma pilha do AWS CloudFormation.
**nota**
A ação `aws:deleteStack` suporta uma nova tentativa automática de controle de utilização. Para obter mais informações, consulte [Configurar a repetição automática para operações com controle de utilização](automation-throttling-retry.md).
**Entrada**
------
#### [ YAML ]
```
name: deleteStack
action: aws:deleteStack
maxAttempts: 1
onFailure: Abort
inputs:
StackName: "{{stackName}}"
```
------
#### [ JSON ]
```
{
"name":"deleteStack",
"action":"aws:deleteStack",
"maxAttempts":1,
"onFailure":"Abort",
"inputs":{
"StackName":"{{stackName}}"
}
}
```
------
ClientRequestToken
Um identificador exclusivo para essa solicitação de `DeleteStack`. Especifique esse token se você planeja repetir solicitações, para que o CloudFormation saiba que você não está tentando excluir uma pilha com o mesmo nome. Você pode repetir as solicitações `DeleteStack` para verificar se o CloudFormation as recebeu.
Tipo: string
Restrições de tamanho: tamanho mínimo 1. O comprimento máximo é 128.
Padrão: [a-zA-Z][-a-zA-Z0-9]\$1
Obrigatório: não
RetainResources.member.N
Essa entrada aplica-se apenas a pilhas que estão em um estado `DELETE_FAILED`. Uma lista de IDs de recursos lógicos para os recursos que você deseja manter. Durante a exclusão, o CloudFormation exclui a pilha, mas não exclui os recursos mantidos.
A retenção de recursos é útil quando você não pode excluir um recurso, como um bucket do S3 não vazio, mas deseja excluir a pilha.
Tipo: matriz de strings
Obrigatório: Não
RoleARN
O nome do recurso da Amazon (ARN) de uma função do AWS Identity and Access Management (IAM) assumida pelo CloudFormation para criar a pilha. O CloudFormation usa as credenciais da função para fazer chamadas em seu nome. O CloudFormation sempre usará essa função para todas as futuras operações na pilha. Desde que os usuários tenham permissão para operar na pilha, o CloudFormation usará essa função mesmo que os usuários não tenham permissão para transmiti-la. Certifique-se de que a função conceda a menor quantidade de privilégios.
Se você não especificar um valor, o CloudFormation usará a função anteriormente associada à pilha. Se nenhuma função estiver disponível, o CloudFormation usará uma sessão temporária gerada a partir das suas credenciais de usuário.
Tipo: string
Restrições de tamanho: tamanho mínimo 20. O comprimento máximo é 2.048.
Obrigatório: não
StackName
O nome ou o ID de pilha exclusivo que está associado à pilha.
Tipo: String
Exigido: sim
## Considerações sobre segurança
Antes de poder usar a ação `aws:deleteStack`, você deve atribuir a seguinte política à função assumida do Automation para IAM. Para obter mais informações sobre a função de admissão, consulte [Tarefa 1: Criar uma função de serviço para a automação](automation-setup-iam.md#create-service-role).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"sqs:*",
"cloudformation:DeleteStack",
"cloudformation:DescribeStacks"
],
"Resource":"*"
}
]
}
```
------
# `aws:executeAutomation` – Executa outra automação
Executa uma automação secundária chamando um runbook secundário. Com essa ação, você pode criar runbooks para suas operações mais comuns e fazer referência a esses runbooks durante uma automação. Essa ação pode simplificar seus runbooks, removendo a necessidade de duplicar etapas em runbooks semelhantes.
A automação secundária é executada no contexto do usuário que iniciou a automação primária. Isso significa que a automação secundária usa o mesmo usuário ou perfil do AWS Identity and Access Management (IAM) usado pelo usuário que iniciou a primeira automação.
**Importante**
Se você especificar parâmetros em uma automação secundária que usa uma função assumida (uma função que usa a política iam:passRole), o usuário ou a função que iniciou a automação primária deverá ter permissão para transmitir a função assumida especificada na automação secundária. Para obter mais informações sobre como configurar uma função assumida para o Automation, consulte [Criar perfis de serviço para o Automation usando o console](automation-setup-iam.md).
**Entrada**
------
#### [ YAML ]
```
name: Secondary_Automation
action: aws:executeAutomation
maxAttempts: 3
timeoutSeconds: 3600
onFailure: Abort
inputs:
DocumentName: secondaryAutomation
RuntimeParameters:
instanceIds:
- i-1234567890abcdef0
```
------
#### [ JSON ]
```
{
"name":"Secondary_Automation",
"action":"aws:executeAutomation",
"maxAttempts":3,
"timeoutSeconds":3600,
"onFailure":"Abort",
"inputs":{
"DocumentName":"secondaryAutomation",
"RuntimeParameters":{
"instanceIds":[
"i-1234567890abcdef0"
]
}
}
}
```
------
DocumentName
O nome do runbook secundário a ser executado durante a etapa. Para runbooks na mesma Conta da AWS, especifique o nome do runbook. Para runbooks compartilhados de uma Conta da AWS diferente, especifique o nome do recurso da Amazon (ARN) do runbook. Para obter informações sobre como usar runbooks compartilhados, consulte [Usar documentos compartilhados do](documents-ssm-sharing.md#using-shared-documents).
Tipo: String
Exigido: sim
DocumentVersion
A versão do runbook secundário a ser executada. Se não for especificada, o Automation executará a versão padrão do runbook.
Tipo: string
Obrigatório: não
MaxConcurrency
O número máximo de destinos que podem executar essa tarefa em paralelo. Você pode especificar um número, como 10, ou uma porcentagem, como 10%.
Tipo: string
Obrigatório: não
MaxErrors
O número de erros permitidos antes que o sistema interrompa a execução de automações em outros destinos. Você pode especificar um número absoluto de erros, como 10, ou uma porcentagem do conjunto de destino, como 10%. Se você especificar 3, por exemplo, o sistema deixará de executar a automação quando o quarto erro for recebido. Se você especificar 0, o sistema deixará de executar a automação em destinos adicionais depois que o primeiro resultado do erro for retornado. Se você executar uma automação em 50 recursos e definir `MaxErrors` para 10%, o sistema interromperá a execução da automação em destinos adicionais quando o sexto erro for recebido.
As automações que já estiverem em execução quando o limite de `MaxErrors` for atingido poderão ser concluídas, mas algumas dessas automações também poderão falhar. Se você precisar garantir que não haverá mais automações com falhas do que o especificado em `MaxErrors`, defina `MaxConcurrency` para 1, para que as automações prossigam uma de cada vez.
Tipo: string
Obrigatório: não
RuntimeParameters
Parâmetros necessários para o runbook secundário. O mapeamento usa o seguinte formato: \$1"parameter1" : "value1", "parameter2" : "value2" \$1
Tipo: mapa
Obrigatório: não
Tags
Metadados opcional que você atribui a um recurso. É possível especificar um máximo de cinco tags para uma automação.
Tipo: MapList
Obrigatório: não
TargetLocations
Um local é uma combinação de Regiões da AWS e/ou Contas da AWS onde você deseja executar a automação. Um número mínimo de 1 item deve ser especificado e um número máximo de 100 itens pode ser especificado. Ao especificar um valor para esse parâmetro, as saídas não são retornadas para a automação pai. Se necessário, você deve fazer chamadas subsequentes às operações da API para recuperar a saída das automações filhas.
Tipo: MapList
Obrigatório: não
TargetMaps
Uma lista de mapeamentos de valor-chave de parâmetros do documento para recursos de destino. Ambos `Targets` e `TargetMaps` não podem ser especificados juntos.
Tipo: MapList
Obrigatório: não
TargetParameterName
O nome do parâmetro usado como recurso de destino para a automação controlada por taxa. Obrigatório se você especificar `Targets`.
Tipo: string
Obrigatório: não
Destinos
Uma lista de mapeamentos de valor-chave para recursos de destino. Obrigatório se você especificar `TargetParameterName`.
Tipo: MapList
Obrigatório: nãoOutput
Output
O resultado gerado pela automação secundária. Você pode fazer referência à saída usando o seguinte formato: *Secondary\$1Automation\$1Step\$1Name*.Output
Tipo: StringList
Aqui está um exemplo:
```
- name: launchNewWindowsInstance
action: 'aws:executeAutomation'
onFailure: Abort
inputs:
DocumentName: launchWindowsInstance
nextStep: getNewInstanceRootVolume
- name: getNewInstanceRootVolume
action: 'aws:executeAwsApi'
onFailure: Abort
inputs:
Service: ec2
Api: DescribeVolumes
Filters:
- Name: attachment.device
Values:
- /dev/sda1
- Name: attachment.instance-id
Values:
- '{{launchNewWindowsInstance.Output}}'
outputs:
- Name: rootVolumeId
Selector: '$.Volumes[0].VolumeId'
Type: String
nextStep: snapshotRootVolume
- name: snapshotRootVolume
action: 'aws:executeAutomation'
onFailure: Abort
inputs:
DocumentName: AWS-CreateSnapshot
RuntimeParameters:
VolumeId:
- '{{getNewInstanceRootVolume.rootVolumeId}}'
Description:
- 'Initial root snapshot for {{launchNewWindowsInstance.Output}}'
```
ExecutionId
O ID da automação secundária.
Tipo: string
Status
O status da automação secundária.
Tipo: string
# `aws:executeAwsApi`: chama e executa as operações de API do AWS
Chama e executa as operações de API da AWS. A maioria das operações de API são suportadas, embora nem todas elas tenham sido testadas. Operações de API por transmissão, como a operação [Get Object](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGET.html), não são compatíveis. Se você não tiver certeza se uma operação de API que deseja usar é uma operação de transmissão, revise a documentação do [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html) do serviço para determinar se uma API requer entradas ou saídas de transmissão. Atualizamos regularmente a versão do Boto3 que essa ação usa. No entanto, após o lançamento de uma nova versão do Boto3, poderá levar algumas semanas para que as alterações sejam refletidas na ação. A execução de cada ação `aws:executeAwsApi` pode durar, no máximo, 25 segundos. Para obter mais exemplos de como usar essa ação, consulte [Exemplos adicionais de runbook](automation-document-examples.md).
**nota**
A ação `aws:executeAwsApi` suporta uma nova tentativa automática de controle de utilização. Para obter mais informações, consulte [Configurar a repetição automática para operações com controle de utilização](automation-throttling-retry.md).
**Entradas**
As entradas são definidas pela operação de API que você escolher.
------
#### [ YAML ]
```
action: aws:executeAwsApi
inputs:
Service: The official namespace of the service
Api: The API operation or method name
API operation inputs or parameters: A value
outputs: # These are user-specified outputs
- Name: The name for a user-specified output key
Selector: A response object specified by using jsonpath format
Type: The data type
```
------
#### [ JSON ]
```
{
"action":"aws:executeAwsApi",
"inputs":{
"Service":"The official namespace of the service",
"Api":"The API operation or method name",
"API operation inputs or parameters":"A value"
},
"outputs":[ These are user-specified outputs
{
"Name":"The name for a user-specified output key",
"Selector":"A response object specified by using JSONPath format",
"Type":"The data type"
}
]
}
```
------
Serviço
O namespace do AWS service (Serviço da AWS) que contém a operação de API que você deseja executar. Você pode visualizar uma lista de namespaces de AWS service (Serviço da AWS) compatíveis em [Available services](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html) (Serviços disponíveis) no AWS SDK para Python (Boto3). O namespace pode ser encontrado na seção **Cliente**. Por exemplo, o namespace para o Systems Manager é `ssm`. O namespace do Amazon Elastic Compute Cloud (Amazon EC2) é `ec2`.
Tipo: String
Exigido: sim
API
O nome da operação de API que você deseja executar. Você pode visualizar as operações de API (também chamadas de métodos), escolhendo um serviço na navegação à esquerda na seguinte página de [Referência de serviços](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html): Escolha um método na seção **Client (Cliente)** para o serviço que você deseja invocar. Por exemplo, todas as operações de API (métodos) do Amazon Relational Database Service (Amazon RDS) estão listadas na seguinte página: [Amazon RDS methods](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html) (Métodos do Amazon RDS).
Tipo: String
Exigido: sim
Entradas de operação da API
Uma ou mais entradas de operação da API. Você pode visualizar as entradas disponíveis (também chamadas de parâmetros), escolhendo um serviço na navegação à esquerda na seguinte página de [Referência de serviços](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html). Escolha um método na seção **Client (Cliente)** para o serviço que você deseja invocar. Por exemplo, todos os métodos de API estão listados na página a seguir: [Métodos do Amazon RDS](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html). Escolha o método [describe\$1db\$1instances](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html#RDS.Client.describe_db_instances) e role para baixo para ver os parâmetros disponíveis, como **DBInstanceIdentifier**, **Name (Nome)** e **Values (Valores)**.
```
inputs:
Service: The official namespace of the service
Api: The API operation name
API input 1: A value
API Input 2: A value
API Input 3: A value
```
```
"inputs":{
"Service":"The official namespace of the service",
"Api":"The API operation name",
"API input 1":"A value",
"API Input 2":"A value",
"API Input 3":"A value"
}
```
Tipo: determinado pela ação de API escolhida
Obrigatório: Sim
**Saídas**
As saídas são especificadas pelo usuário com base na resposta da operação da API escolhida.
Nome
Um nome para a saída.
Tipo: String
Exigido: sim
Seletor
O JSONPath para um determinado atributo no objeto de resposta. Você pode visualizar os objetos de resposta escolhendo um serviço na navegação à esquerda na seguinte página de [Referência de serviços](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html). Escolha um método na seção **Client (Cliente)** para o serviço que você deseja invocar. Por exemplo, todos os métodos de API estão listados na página a seguir: [Métodos do Amazon RDS](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html). Escolha o método [describe\$1db\$1instances](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html#RDS.Client.describe_db_instances) e role para baixo até a seção **Response Structure (Estrutura de resposta)**. **DBInstances** é listado como um objeto de resposta.
Tipo: inteiro, booliano, String, StringList, StringMap ou MapList
Obrigatório: Sim
Tipo
O tipo de dados para o elemento de resposta.
Tipo: Varia
Obrigatório: Sim
# `aws:executeScript` – Executa um script
Executa o script do Python ou PowerShell fornecido, usando o runtime e o handler especificados. Cada ação `aws:executeScript` pode ser executada por uma duração máxima de dez minutos (600 segundos). Você pode limitar o tempo limite especificando o parâmetro `timeoutSeconds` para uma etapa `aws:executeScript`.
Use instruções de retorno em sua função para adicionar saídas à carga útil da saída. Para obter exemplos de definição de saídas para sua ação `aws:executeScript`, consulte [Exemplo 2: Runbook com script](automation-authoring-runbooks-scripted-example.md). Também é possível enviar o resultado das ações do `aws:executeScript` nos runbooks para o grupo de logs do Amazon CloudWatch Logs especificado. Para obter mais informações, consulte [Registro de saída de ações do Automation em log com o CloudWatch Logs](automation-action-logging.md).
Se quiser enviar a saída de ações `aws:executeScript` ao CloudWatch Logs ou se os scripts que você especificar para ações `aws:executeScript` chamarem opções de API da AWS, um perfil de serviço do AWS Identity and Access Management (IAM) (ou uma função de recepção) sempre será necessário para executar o runbook.
**nota**
A ação `aws:executeScript` não suporta uma nova tentativa automática de controle de utilização. Se o seu script fizer chamadas de API AWS que possam ser limitadas, você deve implementar a sua própria lógica de repetição no código do script.
A ação `aws:executeScript` contém os módulos pré-instalados do PowerShell Core a seguir.
+ Microsoft.PowerShell.Host
+ Microsoft.PowerShell.Management
+ Microsoft.PowerShell.Security
+ Microsoft.PowerShell.Utility
+ PackageManagement
+ PowerShellGet
Para usar módulos do PowerShell Core que não estão pré-instalados, o script deve instalar o módulo com o sinalizador `-Force`, conforme mostrado no comando a seguir. Não há suporte ao módulo `AWSPowerShell.NetCore`. Substitua *ModuleName* pelo nome do módulo que deseja instalar.
```
Install-Module ModuleName -Force
```
Para usar cmdlets do PowerShell Core em seu script, recomendamos o uso dos módulos `AWS.Tools`, conforme mostrado nos comandos a seguir. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
+ Cmdlets do Amazon S3.
```
Install-Module AWS.Tools.S3 -Force
Get-S3Bucket -BucketName amzn-s3-demo-bucket
```
+ cmdlets do Amazon EC2
```
Install-Module AWS.Tools.EC2 -Force
Get-EC2InstanceStatus -InstanceId instance-id
```
+ cmdlets do AWS Tools for Windows PowerShell comuns ou independentes de serviço.
```
Install-Module AWS.Tools.Common -Force
Get-AWSRegion
```
Se o script inicializar novos objetos além de usar cmdlets do PowerShell Core, você também deverá importar o módulo conforme mostrado no comando a seguir.
```
Install-Module AWS.Tools.EC2 -Force
Import-Module AWS.Tools.EC2
$tag = New-Object Amazon.EC2.Model.Tag
$tag.Key = "Tag"
$tag.Value = "TagValue"
New-EC2Tag -Resource i-02573cafcfEXAMPLE -Tag $tag
```
Para obter exemplos de instalação e importação dos módulos `AWS.Tools` e do uso de cmdlets do PowerShell Core em runbooks, consulte [Experiência de design visual para runbooks de automação](automation-visual-designer.md).
**Input**
Forneça as informações necessárias para executar o script. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
**nota**
O anexo de um script Python pode ser um arquivo .py ou um arquivo .zip contendo o script. É necessário armazenar os scripts do PowerShell em arquivos .zip.
------
#### [ YAML ]
```
action: "aws:executeScript"
inputs:
Runtime: runtime
Handler: "functionName"
InputPayload:
scriptInput: '{{parameterValue}}'
Script: |-
def functionName(events, context):
...
Attachment: "scriptAttachment.zip"
```
------
#### [ JSON ]
```
{
"action": "aws:executeScript",
"inputs": {
"Runtime": "runtime",
"Handler": "functionName",
"InputPayload": {
"scriptInput": "{{parameterValue}}"
},
"Attachment": "scriptAttachment.zip"
}
}
```
------
Runtime
A linguagem do runtime a ser usada para executar o script fornecido. O `aws:executeScript` suporta runtimes na tabela a seguir.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/automation-action-executeScript.html)
Tipo: String
Exigido: sim
Para runtimes Python, o ambiente fornece 512 MB de memória e 512 MB de espaço em disco. Para runtimes PowerShell, o ambiente fornece 1024 MB de memória e 512 MB de espaço em disco.
Manipulador
Escolha o nome da função. É necessário garantir que a função definida no manipulador tenha dois parâmetros, `events` e `context`. O runtime do PowerShell não oferece suporte a este parâmetro.
Tipo: string
Obrigatório: sim (Python) \$1 sem suporte (PowerShell)
InputPayload
Um objeto JSON ou YAML que será passado para o primeiro parâmetro do manipulador. Isso pode ser usado para passar dados de entrada para o script.
Tipo: string
Obrigatório: não
```
description: Tag an instance
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: '(Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.'
InstanceId:
type: String
description: (Required) The ID of the EC2 instance you want to tag.
mainSteps:
- name: tagInstance
action: 'aws:executeScript'
inputs:
Runtime: "python3.11"
Handler: tagInstance
InputPayload:
instanceId: '{{InstanceId}}'
Script: |-
def tagInstance(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceId = events['instanceId']
tag = {
"Key": "Env",
"Value": "ExamplePython"
}
print(f"Adding tag {tag} to instance id {instanceId}")
ec2.create_tags(
Resources=[instanceId],
Tags=[tag]
)
return tag
outputs:
- Type: String
Name: TagKey
Selector: $.Payload.Key
outputs:
- tagInstance.TagKey
```
```
description: Tag an instance
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: (Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.
InstanceId:
type: String
description: (Required) The ID of the EC2 instance you want to tag.
mainSteps:
- name: tagInstance
action: aws:executeScript
isEnd: true
inputs:
Runtime: PowerShell 7.4
InputPayload:
instanceId: '{{InstanceId}}'
Script: |-
Install-Module AWS.Tools.EC2 -Force
Import-Module AWS.Tools.EC2
$input = $env:InputPayload | ConvertFrom-Json
$tag = New-Object Amazon.EC2.Model.Tag
$tag.Key = "Env"
$tag.Value = "ExamplePowerShell"
Write-Information "Adding tag key: $($tag.Key) and value: $($tag.Value) to instance id $($input.instanceId)"
New-EC2Tag -Resource $input.instanceId -Tag $tag
return $tag
outputs:
- Type: String
Name: TagKey
Selector: $.Payload.Key
outputs:
- tagInstance.TagKey
```
Script
Um script incorporado que você precisa executar durante a execução da automação.
Tipo: string
Obrigatório: não (Python) \$1 sim (PowerShell)
Attachment
O nome de um arquivo de script autônomo ou arquivo .zip que pode ser invocado pela ação. Especifique o mesmo valor do `Name` do arquivo de anexo de documento especificado no parâmetro de solicitação de `Attachments`. Para obter mais informações, consulte [Anexos](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateDocument.html#systemsmanager-CreateDocument-request-Attachments) na *Referência de API do AWS Systems Manager*. Se você estiver fornecendo um script usando um anexo, você deverá definir uma seção `files` nos elementos de nível superior do seu runbook. Para obter mais informações, consulte [Versão 0.3 do esquema](documents-schemas-features.md#automation-doc-syntax-examples).
Para invocar um arquivo para Python, use o formato `filename.method_name` no `Handler`.
O anexo de um script Python pode ser um arquivo .py ou um arquivo .zip contendo o script. É necessário armazenar os scripts do PowerShell em arquivos .zip.
Ao incluir bibliotecas Python em seu anexo, recomendamos adicionar um arquivo `__init__.py` em cada diretório do módulo. Isso permite que você importe os módulos da biblioteca em seu anexo dentro do conteúdo do script. Por exemplo: `from library import module`
Tipo: string
Obrigatório: nãoOutput
Carga útil
A representação JSON do objeto retornado pela função. Até 100 KB é retornado. Se você gerar uma lista, haverá o retorno de no máximo de 100 itens.
## Usar anexos com aws:executeScript
Os anexos fornecem uma maneira poderosa de empacotar e reutilizar scripts complexos, vários módulos e dependências externas com suas ações `aws:executeScript`. Use anexos quando precisar:
+ Empacotar vários módulos Python ou scripts PowerShell juntos.
+ Reutilizar a mesma lógica de script em vários runbooks.
+ Incluir bibliotecas ou dependências externas em seus scripts.
+ Manter a definição do seu runbook limpa separando a lógica complexa do script.
+ Compartilhar pacotes de scripts entre equipes ou fluxos de trabalho de automação.
### Estrutura e empacotamento de anexos
Você pode anexar arquivos únicos ou pacotes zip contendo vários arquivos. A estrutura depende do seu caso de uso:
**Anexos de arquivo único**
Para scripts simples, você pode anexar um único arquivo `.py` (Python) ou um arquivo `.zip` contendo um único script PowerShell.
**Pacotes de vários módulos**
Para automação complexa que requer vários módulos, crie um pacote zip com a seguinte estrutura recomendada:
```
my-automation-package.zip
├── main.py # Entry point script
├── utils/
│ ├── __init__.py # Required for Python module imports
│ ├── helper_functions.py # Utility functions
│ └── aws_operations.py # AWS-specific operations
├── config/
│ ├── __init__.py
│ └── settings.py # Configuration settings
└── requirements.txt # Optional: document dependencies
```
**Importante**
Para pacotes Python, você deve incluir um arquivo `__init__.py` vazio em cada diretório que contém módulos Python. Isso permite importar módulos usando a sintaxe de importação padrão do Python, como `from utils import helper_functions`.
**Estrutura do pacote PowerShell**
Os anexos PowerShell devem ser empacotados em arquivos zip com a seguinte estrutura:
```
my-powershell-package.zip
├── Main.ps1 # Entry point script
├── Modules/
│ ├── HelperFunctions.ps1 # Utility functions
│ └── AWSOperations.ps1 # AWS-specific operations
└── Config/
└── Settings.ps1 # Configuration settings
```
### Criar runbooks com anexos
Siga estas etapas para criar runbooks que usam anexos:
1. **Faça o upload do seu anexo para o Amazon S3**
Carregue seu arquivo de script ou pacote zip em um bucket do S3 que possa ser acessado por seu perfil de automação. Anote o URI do S3 para uso na próxima etapa.
```
aws s3 cp my-automation-package.zip s3://my-automation-bucket/scripts/
```
1. **Calcule a soma de verificação do anexo**
Calcule a soma de verificação SHA-256 do arquivo de anexo para verificação de segurança:
```
# Linux/macOS
shasum -a 256 my-automation-package.zip
# Windows PowerShell
Get-FileHash -Algorithm SHA256 my-automation-package.zip
```
1. **Defina a seção de arquivos em seu runbook**
Adicione uma seção `files` no nível superior do seu runbook para fazer referência ao seu anexo:
```
files:
my-automation-package.zip:
checksums:
sha256: "your-calculated-checksum-here"
```
1. **Faça referência ao anexo em sua etapa executeScript**
Use o parâmetro `Attachment` para fazer referência ao seu arquivo enviado:
```
- name: runMyScript
action: aws:executeScript
inputs:
Runtime: python3.11
Handler: main.process_data
Attachment: my-automation-package.zip
InputPayload:
inputData: "{{InputParameter}}"
```
## Exemplos de anexos aws:executeScript
Os exemplos a seguir demonstram maneiras diferentes de usar anexos com a ação `aws:executeScript`.
### Exemplo 1: anexo de arquivo único
Este exemplo mostra como usar um único arquivo Python como anexo para processar dados da instância do EC2.
**Arquivo do anexo: process\$1instance.py**
Crie um arquivo Python com o seguinte conteúdo:
```
import boto3
import json
def process_instance_data(events, context):
"""Process EC2 instance data and return formatted results."""
try:
instance_id = events.get('instanceId')
if not instance_id:
raise ValueError("instanceId is required")
ec2 = boto3.client('ec2')
# Get instance details
response = ec2.describe_instances(InstanceIds=[instance_id])
instance = response['Reservations'][0]['Instances'][0]
# Format the response
result = {
'instanceId': instance_id,
'instanceType': instance['InstanceType'],
'state': instance['State']['Name'],
'availabilityZone': instance['Placement']['AvailabilityZone'],
'tags': {tag['Key']: tag['Value'] for tag in instance.get('Tags', [])}
}
print(f"Successfully processed instance {instance_id}")
return result
except Exception as e:
print(f"Error processing instance: {str(e)}")
raise
```
**Runbook completo**
Aqui está o runbook completo que usa o anexo de arquivo único:
```
description: Process EC2 instance data using single file attachment
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: (Required) IAM role for automation execution
InstanceId:
type: String
description: (Required) EC2 instance ID to process
files:
process_instance.py:
checksums:
sha256: "abc123def456..."
mainSteps:
- name: processInstance
action: aws:executeScript
inputs:
Runtime: python3.11
Handler: process_instance.process_instance_data
Attachment: process_instance.py
InputPayload:
instanceId: '{{InstanceId}}'
outputs:
- Type: StringMap
Name: InstanceData
Selector: $.Payload
outputs:
- processInstance.InstanceData
```
### Exemplo 2: pacote de vários módulos
Este exemplo demonstra o uso de um pacote zip contendo vários módulos Python para operações complexas de bucket do S3.
**Estrutura do pacote**
Crie um pacote zip com a seguinte estrutura:
```
s3-operations.zip
├── main.py
├── utils/
│ ├── __init__.py
│ ├── s3_helper.py
│ └── validation.py
└── config/
├── __init__.py
└── settings.py
```
**main.py (ponto de entrada)**
O script principal que orquestra as operações:
```
from utils.s3_helper import S3Operations
from utils.validation import validate_bucket_name
from config.settings import get_default_settings
def cleanup_s3_bucket(events, context):
"""Clean up S3 bucket based on specified criteria."""
try:
bucket_name = events.get('bucketName')
max_age_days = events.get('maxAgeDays', 30)
# Validate inputs
if not validate_bucket_name(bucket_name):
raise ValueError(f"Invalid bucket name: {bucket_name}")
# Initialize S3 operations
s3_ops = S3Operations()
settings = get_default_settings()
# Perform cleanup
deleted_objects = s3_ops.delete_old_objects(
bucket_name,
max_age_days,
settings['dry_run']
)
result = {
'bucketName': bucket_name,
'deletedCount': len(deleted_objects),
'deletedObjects': deleted_objects[:10], # Return first 10 for brevity
'dryRun': settings['dry_run']
}
print(f"Cleanup completed for bucket {bucket_name}")
return result
except Exception as e:
print(f"Error during S3 cleanup: {str(e)}")
raise
```
## Solução de problemas de anexos aws:executeScript
Use as diretrizes a seguir para resolver problemas comuns com anexos `aws:executeScript`:
**Erros de importação de módulos**
Se você receber erros de importação ao usar pacotes com vários módulos:
+ Certifique-se de ter incluído um arquivo `__init__.py` vazio em cada diretório contendo módulos Python.
+ Verifique se suas instruções de importação correspondem à estrutura real de arquivos e diretórios em seu pacote zip.
+ Use importações relativas (por exemplo, `from .utils import helper`) ou importações absolutas (por exemplo, `from utils import helper`) de forma consistente.
**Erros de anexo não encontrado**
Se sua automação não conseguir encontrar o anexo:
+ Verifique se o valor do parâmetro `Attachment` corresponde exatamente à chave em sua seção `files`.
+ Verifique se o caminho e o nome do arquivo do bucket do S3 estão corretos na seção `files`.
+ Certifique-se de que seu perfil de automação tenha permissão `s3:GetObject` para a localização do anexo do S3.
+ Verifique se a soma de verificação em seu runbook corresponde à soma de verificação real do arquivo.
**Erros de função do manipulador**
Se você receber erros relacionados ao manipulador:
+ Em Python: use o formato `filename.function_name` no parâmetro `Handler` (por exemplo, `main.process_data`).
+ Certifique-se de que sua função de manipulador aceite exatamente dois parâmetros: `events` e `context`.
+ Em PowerShell: não especifique um parâmetro `Handler`; o script é executado diretamente.
**Falhas de execução de script**
Se o script falhar durante a execução:
+ Verifique o histórico de execução da automação para mensagens de erro detalhadas e rastreamentos de pilha.
+ Use instruções `print()` (Python) ou `Write-Information` (PowerShell) para adicionar a saída de depuração.
+ Verifique se todas as permissões AWS necessárias foram concedidas à sua função de automação.
+ Teste a lógica do seu script localmente antes de empacotá-lo como um anexo.
**Tratamento de erros e códigos de saída**
Para lidar adequadamente com erros e códigos de saída de retorno:
+ Em Python: use `raise Exception("error message")` para indicar falha no script.
+ Em PowerShell: use `throw "error message"` ou `Write-Error` para indicar falha.
+ Retorne dados estruturados de suas funções para fornecer informações detalhadas de êxito/falha.
+ Use blocos try-catch para lidar com exceções de forma elegante e fornecer mensagens de erro significativas.
# `aws:executeStateMachine` – Executa uma máquina de estado do AWS Step Functions
Executa uma máquina de estado do AWS Step Functions.
**nota**
A ação `aws:executeStateMachine` suporta uma nova tentativa automática de controle de utilização. Para obter mais informações, consulte [Configurar a repetição automática para operações com controle de utilização](automation-throttling-retry.md).
**Entrada**
Essa ação oferece suporte para a maioria dos parâmetros da operação da API [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) do Step Functions.
**Permissões obrigatórias do AWS Identity and Access Management (IAM)**
+ `states:DescribeExecution`
+ `states:StartExecution`
+ `states:StopExecution`
------
#### [ YAML ]
```
name: executeTheStateMachine
action: aws:executeStateMachine
inputs:
stateMachineArn: StateMachine_ARN
input: '{"parameters":"values"}'
name: name
```
------
#### [ JSON ]
```
{
"name": "executeTheStateMachine",
"action": "aws:executeStateMachine",
"inputs": {
"stateMachineArn": "StateMachine_ARN",
"input": "{\"parameters\":\"values\"}",
"name": "name"
}
}
```
------
stateMachineArn
O nome do recurso da Amazon (ARN) da máquina de estado do Step Functions.
Tipo: String
Exigido: sim
name
O nome da execução.
Tipo: string
Obrigatório: não
input
Uma string que contém os dados de entrada JSON da execução.
Tipo: string
Obrigatório: não
**Saídas**
As saídas a seguir são predefinidas para essa ação.
executionArn
O ARN da execução.
Tipo: string
input
A string que contém os dados de entrada JSON da execução. As restrições de comprimento se aplicam ao tamanho da carga útil e são expressas como bytes na codificação UTF-8.
Tipo: string
name
O nome da execução.
Tipo: string
saída
Os dados de saída JSON da execução. As restrições de comprimento se aplicam ao tamanho da carga útil e são expressas como bytes na codificação UTF-8.
Tipo: string
startDate
A data em que a execução é iniciada.
Tipo: string
stateMachineArn
O ARN da máquina de estado executada.
Tipo: string
status
O status atual da execução.
Tipo: string
stopDate
Se a execução já tiver terminado, a data em que a execução foi interrompida.
Tipo: string
# `aws:invokeWebhook` — Invoque uma integração de webhook do Automation
Invoca a integração de webhook do Automation especificada. Para obter informações sobre como criar integrações do Automation, consulte [Criação de integrações de webhooks para o Automation](creating-webhook-integrations.md).
**nota**
A ação `aws:invokeWebhook` suporta uma nova tentativa automática de controle de utilização. Para obter mais informações, consulte [Configurar a repetição automática para operações com controle de utilização](automation-throttling-retry.md).
**nota**
Para usar a ação `aws:invokeWebhook`, seu usuário ou perfil de serviço deve permitir as ações a seguir:
ssm:GetParameter
kms:Decrypt
A permissão para a operação AWS Key Management Service (AWS KMS) `Decrypt` só é necessária se você usar uma chave gerenciada pelo cliente para criptografar o parâmetro para sua integração.
**Input**
Forneça as informações para a integração do Automation que você deseja invocar.
------
#### [ YAML ]
```
action: "aws:invokeWebhook"
inputs:
IntegrationName: "exampleIntegration"
Body: "Request body"
```
------
#### [ JSON ]
```
{
"action": "aws:invokeWebhook",
"inputs": {
"IntegrationName": "exampleIntegration",
"Body": "Request body"
}
}
```
------
IntegrationName
O nome da integração do Automation. Por exemplo, `exampleIntegration`. A integração que você especificar já deve existir.
Tipo: String
Exigido: sim
Corpo
A carga útil que você deseja enviar quando a integração do webhook for invocada.
Tipo: string
Obrigatório: nãoOutput
Resposta
O texto recebido da resposta do provedor de webhook.
ResponseCode
O código de status de HTTP recebido da resposta do provedor de webhook.
# `aws:invokeLambdaFunction` – Invoca uma função do AWS Lambda
Chama a função do AWS Lambda especificada.
**nota**
Cada ação `aws:invokeLambdaFunction` pode ser executada por uma duração máxima de cinco minutos (300 segundos). Você pode limitar o tempo limite especificando o parâmetro `timeoutSeconds` para uma etapa `aws:invokeLambdaFunction`.
**nota**
A ação `aws:invokeLambdaFunction` suporta uma nova tentativa automática de controle de utilização. Para obter mais informações, consulte [Configurar a repetição automática para operações com controle de utilização](automation-throttling-retry.md).
**Input**
Essa ação oferece suporte para a maioria dos parâmetros invocados do serviço Lambda. Para obter mais informações, consulte [Invoke](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html).
------
#### [ YAML ]
```
name: invokeMyLambdaFunction
action: aws:invokeLambdaFunction
maxAttempts: 3
timeoutSeconds: 120
onFailure: Abort
inputs:
FunctionName: MyLambdaFunction
```
------
#### [ JSON ]
```
{
"name": "invokeMyLambdaFunction",
"action": "aws:invokeLambdaFunction",
"maxAttempts": 3,
"timeoutSeconds": 120,
"onFailure": "Abort",
"inputs": {
"FunctionName": "MyLambdaFunction"
}
}
```
------
FunctionName
O nome da função do Lambda. Essa função deve existir.
Tipo: String
Exigido: sim
Qualifier
A versão da função ou nome do alias.
Tipo: string
Obrigatório: não
InvocationType
O tipo de invocação. O valor padrão é `RequestResponse`.
Tipo: string
Valores válidos: `Event` \$1 `RequestResponse` \$1 `DryRun`
Obrigatório: não
LogType
Se o valor padrão for `Tail`, o tipo de invocação deverá ser `RequestResponse`. O Lambda retorna os últimos 4 KB de dados de log produzidos pela sua função Lambda, codificados em base64.
Tipo: string
Valores válidos: `None` \$1 `Tail`
Obrigatório: não
ClientContext
As informações específicas do cliente.
Obrigatório: não
InputPayload
Um objeto JSON ou YAML que será transmitido para o primeiro parâmetro do manipulador. É possível usar essa entrada a fim de transmitir dados para a função. Essa entrada fornece mais flexibilidade e suporte do que a entrada `Payload` legada. Se você definir `InputPayload` e `Payload` para a ação, `InputPayload` tem precedência e o valor `Payload` não será usado.
Tipo: StringMap
Obrigatório: não
Carga útil
Uma string JSON que é transmitida para o primeiro parâmetro do manipulador. É possível usá-la a fim de transmitir dados de entrada para a função. Recomendamos usar a entrada `InputPayload` para funcionalidade adicional.
Tipo: string
Obrigatório: nãoOutput
StatusCode
Código de status do HTTP
FunctionError
Se presente, ele indica que ocorreu um erro durante a execução da função. Os detalhes do erro estão incluídos na carga útil da resposta.
LogResult
Os logs codificados pelo base64 para a invocação da função Lambda. Os logs estarão presentes apenas se o tipo de invocação for `RequestResponse` e se tiverem sido solicitados.
Carga útil
A representação JSON do objeto retornado pela função Lambda. A carga útil estará presente apenas se o tipo de invocação for `RequestResponse`.
A seguir é mostrada uma parte do runbook `AWS-PatchInstanceWithRollback` que demonstra como fazer referência a saídas da ação `aws:invokeLambdaFunction`.
------
#### [ YAML ]
```
- name: IdentifyRootVolume
action: aws:invokeLambdaFunction
inputs:
FunctionName: "IdentifyRootVolumeLambda-{{automation:EXECUTION_ID}}"
Payload: '{"InstanceId": "{{InstanceId}}"}'
- name: PrePatchSnapshot
action: aws:executeAutomation
inputs:
DocumentName: "AWS-CreateSnapshot"
RuntimeParameters:
VolumeId: "{{IdentifyRootVolume.Payload}}"
Description: "ApplyPatchBaseline restoration case contingency"
```
------
#### [ JSON ]
```
{
"name": "IdentifyRootVolume",
"action": "aws:invokeLambdaFunction",
"inputs": {
"FunctionName": "IdentifyRootVolumeLambda-{{automation:EXECUTION_ID}}",
"Payload": "{\"InstanceId\": \"{{InstanceId}}\"}"
}
},
{
"name": "PrePatchSnapshot",
"action": "aws:executeAutomation",
"inputs": {
"DocumentName": "AWS-CreateSnapshot",
"RuntimeParameters": {
"VolumeId": "{{IdentifyRootVolume.Payload}}",
"Description": "ApplyPatchBaseline restoration case contingency"
}
}
}
```
------
# `aws:loop`: itera nas etapas de uma automação
Essa ação itera em um subconjunto de etapas em um runbook de automação. Você pode escolher um loop de estilo `do while` ou `for each`. Para construir um loop `do while`, use o parâmetro de entrada `LoopCondition`. Para construir um loop `for each`, use os parâmetros de entrada `Iterators` e `IteratorDataType`. Ao usar uma ação `aws:loop`, especifique somente o parâmetro de entrada `Iterators` ou `LoopCondition`. O número máximo de iterações é 100.
A propriedade `onCancel` só pode ser usada para etapas definidas em um loop. A propriedade `onCancel` não é compatível com a ação `aws:loop`. A propriedade `onFailure` pode ser usada para uma ação `aws:loop`, mas ela só será usada se ocorrer um erro inesperado causando a falha da etapa. Se você definir propriedades `onFailure` para as etapas em um loop, a ação `aws:loop` herdará essas propriedades e reagirá adequadamente quando ocorrer uma falha.
**Exemplos**
Veja a seguir exemplos de como criar os diferentes tipos de ações de loop.
------
#### [ do while ]
```
name: RepeatMyLambdaFunctionUntilOutputIsReturned
action: aws:loop
inputs:
Steps:
- name: invokeMyLambda
action: aws:invokeLambdaFunction
inputs:
FunctionName: LambdaFunctionName
outputs:
- Name: ShouldRetry
Selector: $.Retry
Type: Boolean
LoopCondition:
Variable: "{{ invokeMyLambda.ShouldRetry }}"
BooleanEquals: true
MaxIterations: 3
```
------
#### [ for each ]
```
name: stopAllInstancesWithWaitTime
action: aws:loop
inputs:
Iterators: "{{ DescribeInstancesStep.InstanceIds }}"
IteratorDataType: "String"
Steps:
- name: stopOneInstance
action: aws:changeInstanceState
inputs:
InstanceIds:
- "{{stopAllInstancesWithWaitTime.CurrentIteratorValue}}"
CheckStateOnly: false
DesiredState: stopped
- name: wait10Seconds
action: aws:sleep
inputs:
Duration: PT10S
```
------
**Input**
Veja a entrada a seguir.
Iteradores
A lista de itens sobre os quais as etapas devem ser iteradas. O número máximo de iteradores é 100.
Tipo: StringList
Obrigatório: não
IteratorDataType
Um parâmetro opcional para especificar o tipo de dados dos `Iterators`. Um valor para esse parâmetro pode ser fornecido junto com o parâmetro de entrada `Iterators`. Se você não especificar um valor para esse parâmetro e `Iterators`, deverá especificar um valor para o parâmetro `LoopCondition`.
Tipo: string
Valores válidos: Boolean \$1 Integer \$1 String \$1 StringMap
Padrão: String
Obrigatório: não
LoopCondition
Consiste em uma `Variable` e uma condição do operador a ser avaliada. Se você não especificar um valor para esse parâmetro, deverá especificar um valor para os parâmetros `Iterators` e `IteratorDataType`. Você pode usar avaliações complexas de operadores usando uma combinação dos operadores `And`, `Not` e `Or`. A condição é avaliada após a conclusão das etapas do loop. Se a condição for `true` e o valor `MaxIterations` não tiver sido atingido, as etapas do loop serão executadas novamente. As condições do operador são as seguintes:
**Operações de string**
+ StringEquals
+ EqualsIgnoreCase
+ StartsWith
+ EndsWith
+ Contém
**Operações numéricas**
+ NumericEquals
+ NumericGreater
+ NumericLesser
+ NumericGreaterOrEquals
+ NumericLesser
+ NumericLesserOrEquals
**Operação booleana**
+ BooleanEquals
Tipo: StringMap
Obrigatório: não
MaxIterations
O número máximo de vezes que as etapas do loop são executadas. Quando o valor especificado para essa entrada é atingido, o loop para de ser executado mesmo se `LoopCondition` ainda for `true` ou se houver objetos restantes no parâmetro `Iterators`.
Tipo: inteiro
Valores válidos: 1 a 100
Obrigatório: não
Etapas
A lista de etapas a serem executadas no loop. Elas funcionam como um runbook aninhado. Nessas etapas, você pode acessar o valor atual do iterador de um loop `for each` usando a sintaxe `{{loopStepName.CurrentIteratorValue}}`. Você também pode acessar um valor inteiro da iteração atual para os dois tipos de loop usando a sintaxe `{{loopStepName.CurrentIteration}}`.
Type: Lista de etapas
Obrigatório: SimOutput
CurrentIteration
A iteração atual do loop como um número inteiro. Os valores de iteração começam em 1.
Tipo: inteiro
CurrentIteratorValue
O valor do iterador atual como uma string. Essa saída só está presente em loops `for each`.
Tipo: string
# `aws:pause` – Pausa uma automação
Essa ação pausa a automação. Depois de pausada, o status da automação é *Waiting* (Em espera). Para continuar a automação, use a operação da API [SendAutomationSignal](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_SendAutomationSignal.html) com o tipo de sinal `Resume`. Recomendamos usar a ação `aws:sleep` ou `aws:approve` para um controle mais granular de seus fluxos de trabalho.
**nota**
O tempo limite padrão para essa ação é de 7 dias (604.800 segundos) e o valor máximo é de 30 dias (2.592.000 segundos). Você pode limitar ou prolongar o tempo limite especificando o parâmetro `timeoutSeconds` para uma etapa `aws:pause`.
**Input**
Veja a entrada a seguir.
------
#### [ YAML ]
```
name: pauseThis
action: aws:pause
timeoutSeconds: 1209600
inputs: {}
```
------
#### [ JSON ]
```
{
"name": "pauseThis",
"action": "aws:pause",
"timeoutSeconds": "1209600",
"inputs": {}
}
```
------Output
Nenhum
# `aws:runCommand` – Executa um comando em uma instância gerenciada
Executa os comandos especificados.
**nota**
A automação comporta apenas a *output* de uma ação do AWS Systems Manager Run Command. Um runbook pode incluir várias ações do Run Command, mas apenas uma ação de cada vez pode gerar um output.
**Input**
Essa ação oferece suporte para a maioria dos parâmetros de comando de envio. Para obter mais informações, consulte [SendCommand](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_SendCommand.html).
------
#### [ YAML ]
```
- name: checkMembership
action: 'aws:runCommand'
inputs:
DocumentName: AWS-RunPowerShellScript
InstanceIds:
- '{{InstanceIds}}'
Parameters:
commands:
- (Get-WmiObject -Class Win32_ComputerSystem).PartOfDomain
```
------
#### [ JSON ]
```
{
"name": "checkMembership",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"InstanceIds": [
"{{InstanceIds}}"
],
"Parameters": {
"commands": [
"(Get-WmiObject -Class Win32_ComputerSystem).PartOfDomain"
]
}
}
}
```
------
DocumentName
Se o documento do tipo Comando for de sua propriedade ou da AWS, especifique o nome do documento. Se você estiver usando um documento compartilhado com você por uma Conta da AWSdiferente, especifique o nome do recurso da Amazon (ARN) do documento. Para obter mais informações sobre o uso de documentos compartilhados, consulte [Usar documentos compartilhados do](documents-ssm-sharing.md#using-shared-documents).
Tipo: String
Exigido: sim
InstanceIds
Os IDs de instâncias em que deseja que o comando seja executado. Você pode especificar um máximo de 50 IDs.
Você também pode usar o pseudoparâmetro `{{RESOURCE_ID}}` no lugar de IDs de instância para executar o comando em todas as instâncias no grupo de destino. Para obter mais informações sobre pseudoparâmetros, consulte [Usar pseudoparâmetros ao registrar tarefas da janela de manutenção](maintenance-window-tasks-pseudo-parameters.md).
Outra alternativa é enviar comandos para uma frota de instâncias usando o parâmetro `Targets`.. O parâmetro `Targets` aceita tags do Amazon Elastic Compute Cloud (Amazon EC2). Para obter mais informações sobre como usar o parâmetro `Targets`, consulte [Execução de comandos em escala](send-commands-multiple.md).
Tipo: StringList
Obrigatório: não (Se não especificar InstanceIds ou usar o pseudoparâmetro `{{RESOURCE_ID}}`, você deverá especificar o parâmetro `Targets`.)
Targets
Vários critérios de pesquisa que apontam para instâncias usando uma combinação de chave-valor especificada. As `Targets` serão necessárias se você não fornecer um ou mais IDs de instância na chamada. Para obter mais informações sobre como usar o parâmetro `Targets`, consulte [Execução de comandos em escala](send-commands-multiple.md).
Tipo: MapList (o esquema do mapa na lista deve corresponder ao objeto). Para obter informações, consulte [Target](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_Target.html) na *Referência de API do AWS Systems Manager*.
Obrigatório: não (Se não especificar `Targets`, você deverá especificar os IDs da instância ou usar o pseudoparâmetro `{{RESOURCE_ID}}`.)
Veja um exemplo a seguir.
```
- name: checkMembership
action: aws:runCommand
inputs:
DocumentName: AWS-RunPowerShellScript
Targets:
- Key: tag:Stage
Values:
- Gamma
- Beta
- Key: tag-key
Values:
- Suite
Parameters:
commands:
- (Get-WmiObject -Class Win32_ComputerSystem).PartOfDomain
```
```
{
"name": "checkMembership",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"Targets": [
{
"Key": "tag:Stage",
"Values": [
"Gamma", "Beta"
]
},
{
"Key": "tag:Application",
"Values": [
"Suite"
]
}
],
"Parameters": {
"commands": [
"(Get-WmiObject -Class Win32_ComputerSystem).PartOfDomain"
]
}
}
}
```
Parameters
Os parâmetros necessários e opcionais especificados no documento.
Tipo: mapa
Obrigatório: não
CloudWatchOutputConfig
Opções de configuração para enviar o output do comando para o Amazon CloudWatch Logs. Para obter mais informações sobre o envio do output do comando para o CloudWatch Logs, consulte [Configurar o Amazon CloudWatch Logs para Run Command](sysman-rc-setting-up-cwlogs.md).
Tipo: StringMap (O esquema do mapa deve corresponder ao objeto. Para obter mais informações, consulte [CloudWatchOutputConfig](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CloudWatchOutputConfig.html) na *Referência de API do AWS Systems Manager*).
Obrigatório: não
Veja um exemplo a seguir.
```
- name: checkMembership
action: aws:runCommand
inputs:
DocumentName: AWS-RunPowerShellScript
InstanceIds:
- "{{InstanceIds}}"
Parameters:
commands:
- "(Get-WmiObject -Class Win32_ComputerSystem).PartOfDomain"
CloudWatchOutputConfig:
CloudWatchLogGroupName: CloudWatchGroupForSSMAutomationService
CloudWatchOutputEnabled: true
```
```
{
"name": "checkMembership",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"InstanceIds": [
"{{InstanceIds}}"
],
"Parameters": {
"commands": [
"(Get-WmiObject -Class Win32_ComputerSystem).PartOfDomain"
]
},
"CloudWatchOutputConfig" : {
"CloudWatchLogGroupName": "CloudWatchGroupForSSMAutomationService",
"CloudWatchOutputEnabled": true
}
}
}
```
Comment
Informações definidas pelo usuário sobre o comando.
Tipo: string
Obrigatório: não
DocumentHash
O hash do documento.
Tipo: string
Obrigatório: não
DocumentHashType
O tipo de hash.
Tipo: string
Valores válidos: `Sha256` \$1 `Sha1`
Obrigatório: não
NotificationConfig
As configurações para enviar notificações.
Obrigatório: não
OutputS3BucketName
O nome do bucket do S3 para as respostas do output dos comandos. Seu nó gerenciado deve ter permissões para o bucket do S3 para registrar o output com êxito.
Tipo: string
Obrigatório: não
OutputS3KeyPrefix
O prefixo.
Tipo: string
Obrigatório: não
ServiceRoleArn
O ARN da função do AWS Identity and Access Management (IAM).
Tipo: string
Obrigatório: não
TimeoutSeconds
O tempo, em segundos, para esperar que um comando seja entregue ao AWS Systems Manager SSM Agent em uma instância. Se o comando não for recebido pelo SSM Agent na instância antes que o valor especificado seja atingido, o status do comando mudará para `Delivery Timed Out`.
Tipo: inteiro
Obrigatório: não
Valores válidos: 30 a 2592000Output
CommandId
O ID do comando.
Status
O status do comando.
ResponseCode
O código de resposta do comando. Se o documento executado tiver mais de uma etapa, nenhum valor será retornado para essa saída.
Output
O output do comando. Se você segmentar uma tag ou várias instâncias com seu comando, nenhum valor de output será retornado. Você pode usar as operações `GetCommandInvocation` e `ListCommandInvocations` da API para recuperar o output de instâncias individuais.
# `aws:runInstances` – Executa uma instância do Amazon EC2
Inicia uma nova instância do Amazon Elastic Compute Cloud (Amazon EC2).
**nota**
A ação `aws:runInstances` suporta uma nova tentativa automática de controle de utilização. Para obter mais informações, consulte [Configurar a repetição automática para operações com controle de utilização](automation-throttling-retry.md).
**Input**
A ação oferece suporte para a maioria dos parâmetros de API. Para obter mais informações, consulte a documentação da API [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html).
------
#### [ YAML ]
```
name: launchInstance
action: aws:runInstances
maxAttempts: 3
timeoutSeconds: 1200
onFailure: Abort
inputs:
ImageId: ami-12345678
InstanceType: t2.micro
MinInstanceCount: 1
MaxInstanceCount: 1
IamInstanceProfileName: myRunCmdRole
TagSpecifications:
- ResourceType: instance
Tags:
- Key: LaunchedBy
Value: SSMAutomation
- Key: Category
Value: HighAvailabilityFleetHost
```
------
#### [ JSON ]
```
{
"name":"launchInstance",
"action":"aws:runInstances",
"maxAttempts":3,
"timeoutSeconds":1200,
"onFailure":"Abort",
"inputs":{
"ImageId":"ami-12345678",
"InstanceType":"t2.micro",
"MinInstanceCount":1,
"MaxInstanceCount":1,
"IamInstanceProfileName":"myRunCmdRole",
"TagSpecifications":[
{
"ResourceType":"instance",
"Tags":[
{
"Key":"LaunchedBy",
"Value":"SSMAutomation"
},
{
"Key":"Category",
"Value":"HighAvailabilityFleetHost"
}
]
}
]
}
}
```
------
AdditionalInfo
Reservado.
Tipo: string
Obrigatório: não
BlockDeviceMappings
Os dispositivos de bloco para a instância.
Tipo: MapList
Obrigatório: não
ClientToken
O identificador para garantir a idempotência da solicitação.
Tipo: string
Obrigatório: não
DisableApiTermination
Ativa ou desativa o encerramento da API da instância.
Tipo: booliano
Obrigatório: não
EbsOptimized
Ativa ou desativa a otimização do Amazon Elastic Block Store (Amazon EBS).
Tipo: booliano
Obrigatório: não
IamInstanceProfileArn
O nome do recurso da Amazon (ARN) do perfil da instância do AWS Identity and Access Management (IAM) a ser associado às instâncias.
Tipo: string
Obrigatório: não
IamInstanceProfileName
O nome do perfil de instância do IAM para a instância.
Tipo: string
Obrigatório: não
ImageId
O ID da Amazon Machine Image (AMI).
Tipo: String
Exigido: sim
InstanceInitiatedShutdownBehavior
Indica se a instância é interrompida ou encerrada no desligamento do sistema.
Tipo: string
Obrigatório: não
InstanceType
O tipo de instância.
Se o valor de um tipo de instância não for fornecido, o tipo de instância m1.small será usado.
Tipo: string
Obrigatório: não
KernelId
O ID do kernel.
Tipo: string
Obrigatório: não
KeyName
O nome do par de chaves.
Tipo: string
Obrigatório: não
MaxInstanceCount
O número máximo de instâncias a serem executadas.
Tipo: string
Obrigatório: não
MetadataOptions
As opções de metadados da instância. Para obter mais informações, consulte [InstanceMetadataOptionsRequest](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_InstanceMetadataOptionsRequest.html).
Tipo: StringMap
Obrigatório: não
MinInstanceCount
O número mínimo de instâncias a serem executadas.
Tipo: string
Obrigatório: não
Monitoramento
Ativa ou desativa o monitoramento detalhado.
Tipo: booliano
Obrigatório: não
NetworkInterfaces
As interfaces de rede.
Tipo: MapList
Obrigatório: não
Posicionamento
O posicionamento da instância.
Tipo: StringMap
Obrigatório: não
PrivateIpAddress
O endereço IPv4 primário.
Tipo: string
Obrigatório: não
RamdiskId
O ID do disco RAM.
Tipo: string
Obrigatório: não
SecurityGroupIds
Os IDs dos security groups da instância.
Tipo: StringList
Obrigatório: não
SecurityGroups
Os nomes dos security groups da instância.
Tipo: StringList
Obrigatório: não
SubnetId
O ID da sub-rede.
Tipo: string
Obrigatório: não
TagSpecifications
As tags a serem aplicadas aos recursos durante a execução. Você só pode marcar instâncias e volumes na inicialização. As tags especificadas são aplicadas a todas as instâncias ou volumes que são criados durante a execução. Para marcar uma instância depois que ela tiver sido iniciada, use a ação [`aws:createTags`: cria tags para os recursos da AWS](automation-action-createtag.md).
Tipo: MapList (Para obter mais informações, consulte [TagSpecification](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_TagSpecification.html).)
Obrigatório: não
UserData
Um script fornecido como um valor literal de string. Se um valor literal for inserido, ele deverá ser codificado em Base64.
Tipo: string
Obrigatório: nãoOutput
InstanceIds
Os IDs das instâncias.
InstanceStates
O estado atual da instância.
# `aws:sleep`: atrasa uma automação
Atrasa a execução da Automação por um período de tempo especificado. Essa ação usa o formato de data e hora da Organização Internacional de Normalização (ISO) 8601. Para obter mais informações sobre esse formato de data e hora, consulte [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html).
**Input**
É possível atrasar uma automação para uma duração especificada.
------
#### [ YAML ]
```
name: sleep
action: aws:sleep
inputs:
Duration: PT10M
```
------
#### [ JSON ]
```
{
"name":"sleep",
"action":"aws:sleep",
"inputs":{
"Duration":"PT10M"
}
}
```
------
Você também pode atrasar a automação até uma data e hora especificadas. Se a data e a hora especificadas tiverem passado, a ação prosseguirá imediatamente.
------
#### [ YAML ]
```
name: sleep
action: aws:sleep
inputs:
Timestamp: '2020-01-01T01:00:00Z'
```
------
#### [ JSON ]
```
{
"name": "sleep",
"action": "aws:sleep",
"inputs": {
"Timestamp": "2020-01-01T01:00:00Z"
}
}
```
------
**nota**
A automação permite um atraso máximo de 604.799 segundos (7 dias).
Duração
Uma duração ISO 8601. Não é possível especificar uma duração negativa.
Tipo: string
Obrigatório: não
Timestamp
Um timestamp ISO 8601. Se você não especificar um valor para esse parâmetro, deverá especificar um valor para o parâmetro `Duration`.
Tipo: string
Obrigatório: nãoOutput
Nenhum
# `aws:updateVariable`: atualiza um valor para uma variável do runbook
Essa ação atualiza um valor para uma variável do runbook. O tipo de dados do valor deve corresponder ao tipo de dados da variável que você deseja atualizar. Não há suporte a conversões de tipo de dados. A propriedade `onCancel` não é compatível com a ação `aws:updateVariable`.
**Input**
Veja a entrada a seguir.
------
#### [ YAML ]
```
name: updateStringList
action: aws:updateVariable
inputs:
Name: variable:variable name
Value:
- "1"
- "2"
```
------
#### [ JSON ]
```
{
"name": "updateStringList",
"action": "aws:updateVariable",
"inputs": {
"Name": "variable:variable name",
"Value": ["1","2"]
}
}
```
------
Nome
O nome da variável cujo valor você deseja atualizar. É necessário usar o formato `variable:variable name`
Tipo: String
Exigido: sim
Valor
O novo valor a ser atribuído à variável. O valor deve corresponder ao tipo de dados da variável. Não há suporte a conversões de tipo de dados.
Tipo: Boolean \$1 Integer \$1 MapList \$1 String \$1 StringList \$1 StringMap
Obrigatório: Sim
Restrições:
+ O MapList pode conter um número máximo de 200 itens.
+ Os comprimentos de chave podem ter um comprimento mínimo de 1 e um máximo de 50.
+ StringList pode ter um número mínimo de 0 itens e um número máximo de 50 itens.
+ Os comprimentos de string podem ter um comprimento mínimo de 1 e um máximo de 512.Output
Nenhum
# `aws:waitForAwsResourceProperty`: aguarde uma propriedade de recurso da AWS
A ação `aws:waitForAwsResourceProperty` permite que a automação espere por um estado específico do recurso ou um estado do evento antes de continuar a automação. Para obter mais exemplos de como usar essa ação, consulte [Exemplos adicionais de runbook](automation-document-examples.md).
**nota**
O valor de tempo limite padrão para esta ação é 3600 segundos (uma hora). Você pode limitar ou prolongar o tempo limite especificando o parâmetro `timeoutSeconds` para uma etapa `aws:waitForAwsResourceProperty`. Para obter mais informações e exemplos de como usar essa ação, consulte [Gerenciar tempos limite em runbooks](automation-handling-timeouts.md).
**nota**
A ação `aws:waitForAwsResourceProperty` suporta uma nova tentativa automática de controle de utilização. Para obter mais informações, consulte [Configurar a repetição automática para operações com controle de utilização](automation-throttling-retry.md).
**Input**
As entradas são definidas pela operação de API que você escolher.
------
#### [ YAML ]
```
action: aws:waitForAwsResourceProperty
inputs:
Service: The official namespace of the service
Api: The API operation or method name
API operation inputs or parameters: A value
PropertySelector: Response object
DesiredValues:
- Desired property value
```
------
#### [ JSON ]
```
{
"action": "aws:waitForAwsResourceProperty",
"inputs": {
"Service":"The official namespace of the service",
"Api":"The API operation or method name",
"API operation inputs or parameters":"A value",
"PropertySelector": "Response object",
"DesiredValues": [
"Desired property value"
]
}
}
```
------
Serviço
O namespace do AWS service (Serviço da AWS) que contém a operação de API que você deseja executar. Por exemplo, o namespace para AWS Systems Manager é `ssm`. O namespace do Amazon Elastic Compute Cloud (Amazon EC2) é `ec2`. Você pode visualizar uma lista de namespaces de AWS service (Serviço da AWS) compatíveis na seção [Available Services](https://docs.aws.amazon.com/cli/latest/reference/#available-services) (Serviços disponíveis) da *Referência de comandos da AWS CLI*.
Tipo: String
Exigido: sim
API
O nome da operação de API que você deseja executar. Você pode visualizar as operações de API (também chamadas de métodos), escolhendo um serviço na navegação à esquerda na seguinte página de [Referência de serviços](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html): Escolha um método na seção **Client (Cliente)** para o serviço que você deseja invocar. Por exemplo, todas as operações de API (métodos) do Amazon Relational Database Service (Amazon RDS) estão listadas na seguinte página: [Amazon RDS methods](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html) (Métodos do Amazon RDS).
Tipo: String
Exigido: sim
Entradas de operação da API
Uma ou mais entradas de operação da API. Você pode visualizar as entradas disponíveis (também chamadas de parâmetros), escolhendo um serviço na navegação à esquerda na seguinte página de [Referência de serviços](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html). Escolha um método na seção **Client (Cliente)** para o serviço que você deseja invocar. Por exemplo, todos os métodos de API estão listados na página a seguir: [Métodos do Amazon RDS](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html). Escolha o método [describe\$1db\$1instances](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html#RDS.Client.describe_db_instances) e role para baixo para ver os parâmetros disponíveis, como **DBInstanceIdentifier**, **Name (Nome)** e **Values (Valores)**.
```
inputs:
Service: The official namespace of the service
Api: The API operation name
API input 1: A value
API Input 2: A value
API Input 3: A value
```
```
"inputs":{
"Service":"The official namespace of the service",
"Api":"The API operation name",
"API input 1":"A value",
"API Input 2":"A value",
"API Input 3":"A value"
}
```
Tipo: determinado pela ação de API escolhida
Obrigatório: Sim
PropertySelector
O JSONPath para um determinado atributo no objeto de resposta. Você pode visualizar os objetos de resposta escolhendo um serviço na navegação à esquerda na seguinte página de [Referência de serviços](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html). Escolha um método na seção **Client (Cliente)** para o serviço que você deseja invocar. Por exemplo, todos os métodos de API estão listados na página a seguir: [Métodos do Amazon RDS](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html). Escolha o método [describe\$1db\$1instances](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html#RDS.Client.describe_db_instances) e role para baixo até a seção **Response Structure (Estrutura de resposta)**. **DBInstances** é listado como um objeto de resposta.
Tipo: String
Exigido: sim
DesiredValues
O status ou estado esperado no qual a automação deve continuar.
Tipo: MapList, StringList
Obrigatório: Sim
# Variáveis de sistema de automação
Os runbooks do AWS Systems Manager Automation usam as variáveis a seguir. Para obter um exemplo de como essas variáveis são usadas, visualize a origem JSON do runbook `AWS-UpdateWindowsAmi`.
**Para visualizar a origem JSON do runbook `AWS-UpdateWindowsAmi`**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Documents**.
1. Na lista de documentos, use a barra de pesquisa ou os números à direita da barra de pesquisa para escolher o runbook `AWS-UpdateWindowsAmi`.
1. Escolha a guia **Conteúdo**.
**Variáveis do sistema**
Runbooks do Automation oferecem suporte para as seguintes variáveis de sistema:
****
| Variável | Detalhes |
| --- | --- |
| `global:ACCOUNT_ID` | O ID da Conta da AWS do usuário ou do perfil no qual o Automation é executado. |
| `global:DATE` | A data (no runtime), no formato aaaa-MM-dd. |
| `global:DATE_TIME` | A data e a hora (no runtime), no formato aaaa-MM-dd\$1HH.mm.ss. |
| `global:AWS_PARTITION` | A partição na qual o recurso está. Para Regiões da AWS padrão, a partição é `aws`. Para obter recursos em outras partições, a partição é `aws-partitionname`. Por exemplo, a partição para recursos na região da AWS GovCloud (Oeste dos EUA) é `aws-us-gov`. |
| `global:REGION` | A região em que o runbook é executado. Por exemplo, us-east-2. |
**Variáveis de automação**
Runbooks do Automation oferecem suporte para as seguintes variáveis de automação:
****
| Variável | Detalhes |
| --- | --- |
| `automation:EXECUTION_ID` | O identificador exclusivo atribuído à automação atual. Por exemplo, `1a2b3c-1a2b3c-1a2b3c-1a2b3c1a2b3c1a2b3c`. |
**Topics**
+ [Terminologia](#automation-terms)
+ [Cenários compatíveis](#automation-variables-support)
+ [Cenários não compatíveis](#automation-variables-unsupported)
## Terminologia
Os termos a seguir descrevem como as variáveis e os parâmetros são resolvidos.
****
| Prazo | Definição | Exemplo |
| --- | --- | --- |
| ARN constante | Um nome do recurso da Amazon (ARN) válido sem variáveis. | `arn:aws:iam::123456789012:role/roleName` |
| Parâmetro do runbook | Um parâmetro definido no nível do runbook (por exemplo, `instanceId`). O parâmetro é usado em uma substituição de string básica. Seu valor é fornecido na ocasião de início da execução. |
|
| Parâmetro do Systems Manager | Uma variável definida no AWS Systems Manager Parameter Store. Ele não pode ser referenciado diretamente na entrada da etapa. Podem ser necessárias permissões para acessar o parâmetro. |
description: Launch new Windows test instance schemaVersion: '0.3' assumeRole: '{{AutomationAssumeRole}}' parameters: AutomationAssumeRole: type: String default: '' description: >- (Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to run this runbook. LatestAmi: type: String default: >- {{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}} description: The latest Windows Server 2016 AMI queried from the public parameter. mainSteps: - name: launchInstance action: 'aws:runInstances' maxAttempts: 3 timeoutSeconds: 1200 onFailure: Abort inputs: ImageId: '{{LatestAmi}}' ...
|
## Cenários compatíveis
****
| Cenário | Comentários | Exemplo |
| --- | --- | --- |
| `assumeRole` de ARN constante na criação. | Uma verificação de autorização é realizada para verificar se o usuário de chamada tem permissão para transmitir a `assumeRole` especificada. |
|
| Valor fornecido para o parâmetro do runbook no início. | O cliente fornece o valor a ser usado para um parâmetro. Quaisquer entradas fornecidas na inicialização precisam ser definidas na lista de parâmetros do runbook. |
... "parameters": { "amiId": { "type": "String", "default": "ami-12345678", "description": "list of commands to run as part of first step" }, ...
As entradas para iniciar a execução da automação incluem: `{"amiId" : ["ami-12345678"] }` |
| Parâmetro do Systems Manager referenciado no conteúdo do runbook. | A variável existe na conta do cliente ou é um parâmetro acessível publicamente, e o `AssumeRole` do runbook tem acesso à variável. Uma verificação é realizada na ocasião da criação para confirmar se `AssumeRole` tem acesso. O parâmetro não pode ser referenciado diretamente na entrada da etapa. |
... parameters: LatestAmi: type: String default: >- {{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}} description: The latest Windows Server 2016 AMI queried from the public parameter. mainSteps: - name: launchInstance action: 'aws:runInstances' maxAttempts: 3 timeoutSeconds: 1200 onFailure: Abort inputs: ImageId: '{{LatestAmi}}' ...
|
| Variável de sistema referenciada na definição de etapa | Uma variável de sistema é substituída no runbook quando a automação é iniciada. O valor injetado no runbook é relativo a quando ocorre a substituição. Ou seja, o valor de uma variável de tempo injetado na etapa 1 é diferente do valor injetado na etapa 3 devido ao tempo necessário para executar as etapas intermediárias. As variáveis do sistema não precisam ser definidas na lista de parâmetros do runbook. |
|
| Variável de automação referenciada na definição de etapa. | As variáveis de automação não precisam ser definidas na lista de parâmetros do runbook. A única variável de Automação com suporte é **automation:EXECUTION\$1ID**. |
|
| Consulte a saída da etapa anterior na próxima definição de etapa. | Este é o redirecionamento de parâmetros. A saída de uma etapa anterior é referenciada usando a sintaxe `{{stepName.OutputName}}`. Essa sintaxe não pode ser usada pelo cliente para parâmetros do runbook. Isso é resolvido quando a etapa de referência é executada. O parâmetro não está listado nos parâmetros do runbook. |
|
## Cenários não compatíveis
****
| Cenário | Comentário | Exemplo |
| --- | --- | --- |
| Parâmetro do Systems Manager fornecido para o `assumeRole` na criação | Sem suporte. |
User supplies input : { "attemptModel" : "minAttempts" }
|
| Referência cruzada de parâmetros do runbook | O usuário fornece um parâmetro de entrada na hora de início, que é uma referência a outro parâmetro no runbook. |
... "parameters": { "amiId": { "type": "String", "default": "ami-7f2e6015", "description": "list of commands to run as part of first step" }, "alternateAmiId": { "type": "String", "description": "The alternate AMI to try if this first fails".
"default" : "{{amiId}}" },
...
|
| Expansão de vários níveis | O runbook define uma variável que é avaliada como o nome de uma variável. Ela fica dentro dos delimitadores de variáveis (ou seja, *\$1\$1 \$1\$1*) e é expandida para o valor dessa variável/parâmetro. |
Note: The customer intention here would be to run a command of "echo {Hello world}"
|
| Referenciar a saída de uma etapa do runbook que é um tipo de variável diferente | O usuário faz referência à saída de uma etapa do runbook anterior em uma etapa subsequente. A saída é um tipo de variável que não atende aos requisitos da ação na etapa subsequente. |
... mainSteps: - name: getImageId action: aws:executeAwsApi inputs: Service: ec2 Api: DescribeImages Filters: - Name: "name" Values: - "{{ImageName}}" outputs: - Name: ImageIdList Selector: "$.Images" Type: "StringList" - name: copyMyImages action: aws:copyImage maxAttempts: 3 onFailure: Abort inputs: SourceImageId: {{getImageId.ImageIdList}} SourceRegion: ap-northeast-2 ImageName: Encrypted Copies of LAMP base AMI in ap-northeast-2 Encrypted: true ... Note: You must provide the type required by the Automation action. In this case, aws:copyImage requires a "String" type variable but the preceding step outputs a "StringList" type variable.
|
# Criação dos seus próprios runbooks
Um runbook do Automation define as *ações* que o Systems Manager realizará nas instâncias gerenciadas e outros recursos da AWS quando uma automação for executada. O Automation é uma ferramenta do AWS Systems Manager. Um runbook contém uma ou mais etapas que são executadas em ordem sequencial. Cada etapa se baseia em uma única ação. A saída de uma etapa pode ser usada como entrada de uma etapa posterior.
O processo de execução dessas ações e suas etapas é chamado de *automação*.
Os tipos de ação compatíveis com runbooks permitem automatizar uma ampla variedade de operações em seu ambiente da AWS. Por exemplo, usando o tipo de ação `executeScript`, você pode incorporar um script do Python ou PowerShell diretamente em seu runbook. (Ao criar um runbook personalizado, você pode adicionar seu script em linha ou anexá-lo de um bucket do S3 ou de sua máquina local.) Você pode automatizar o gerenciamento de seus recursos do AWS CloudFormation usando os tipos de ação `createStack` e `deleteStack`. Além disso, usando o tipo de ação `executeAwsApi`, uma etapa pode executar *qualquer* operação de API em qualquer AWS service (Serviço da AWS), incluindo criar ou excluir recursos da AWS, iniciar outros processos, acionar notificações e muito mais.
Para obter uma lista de todos os 20 tipos de ação compatíveis com o Automation, consulte [Referência de ações do Systems Manager Automation](automation-actions.md).
O AWS Systems Manager Automation inclui vários runbooks com etapas predefinidas que você pode usar para executar tarefas comuns, como reiniciar uma ou mais instâncias do Amazon Elastic Compute Cloud (Amazon EC2) ou criar uma Amazon Machine Image (AMI). Você também pode criar seus próprios runbooks de automação e compartilhá-los com outras contas da Contas da AWS ou torná-los públicos para todos os usuários do Automation.
Os runbooks são escritos em YAML ou JSON. No entanto, usando o **Document Builder** no console do Systems Manager Automation, você pode criar um runbook sem precisar criar em JSON ou YAML nativo.
**Importante**
Se você executar um fluxo de trabalho de automação que chama outros serviços usando uma função de serviço do AWS Identity and Access Management (IAM), esteja ciente de que esta função deve ser configurada com permissão para chamar esses serviços. Esse requisito aplica-se a todos os runbooks do Automation da AWS (runbooks da `AWS-*`), como os runbooks `AWS-ConfigureS3BucketLogging`, `AWS-CreateDynamoDBBackup` e `AWS-RestartEC2Instance`, entre outros. Esse requisito também se aplica a todos os runbooks personalizados do Automation criados que invoquem outros Serviços da AWS, usando ações que chamam outros serviços. Por exemplo, se você usar as ações `aws:executeAwsApi`, `aws:createStack` ou `aws:copyImage`, configure a função de serviço com permissão para invocar esses serviços. É possível habilitar permissões para outros Serviços da AWS, adicionando uma política em linha do IAM à função. Para obter mais informações, consulte [(Opcional) Adicione uma política em linha ou uma política gerenciada pelo cliente para invocar outros Serviços da AWS](automation-setup-iam.md#add-inline-policy).
Para obter informações sobre as ações que podem ser especificadas em um runbook, consulte [Referência de ações do Systems Manager Automation](automation-actions.md).
Para obter informações sobre como usar o AWS Toolkit for Visual Studio Code para criar runbooks, consulte[Trabalhar com documentos do Systems Manager Automation](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/systems-manager-automation-docs.html) no *Manual do usuário do AWS Toolkit for Visual Studio Code*.
Para obter informações sobre como usar o designer visual para criar um runbook personalizado, consulte [Experiência de design visual para runbooks de automação](automation-visual-designer.md).
**Contents**
+ [Experiência de design visual para runbooks de automação](automation-visual-designer.md)
+ [Visão geral da interface de experiência de design visual](visual-designer-interface-overview.md)
+ [Navegador Ações](visual-designer-interface-overview.md#visual-designer-actions)
+ [Canvas](visual-designer-interface-overview.md#visual-designer-canvas)
+ [Formulário](visual-designer-interface-overview.md#visual-designer-form)
+ [Atalhos de teclado](visual-designer-interface-overview.md#visual-designer-keyboard-shortcuts)
+ [Usar a experiência de design visual](visual-designer-use.md)
+ [Criar um runbook](visual-designer-use.md#visual-designer-create-runbook-workflow)
+ [Desenvolver um runbook](visual-designer-use.md#visual-designer-build)
+ [Atualizar seu runbook](visual-designer-use.md#visual-designer-update-runbook)
+ [Exportar seu runbook](visual-designer-use.md#visual-designer-export-runbook)
+ [Configurar entradas e saídas para suas ações](visual-designer-action-inputs-outputs.md)
+ [Forneça dados de entrada para uma ação](visual-designer-action-inputs-outputs.md#providing-input)
+ [Definir dados de saída para uma ação](visual-designer-action-inputs-outputs.md#defining-output)
+ [Tratamento de erros com a experiência de design visual](visual-designer-error-handling.md)
+ [Repetir a ação em caso de erro](visual-designer-error-handling.md#retry-actions)
+ [Tempo limite](visual-designer-error-handling.md#timeout-seconds)
+ [Ações com falha](visual-designer-error-handling.md#failure-actions)
+ [Ações canceladas](visual-designer-error-handling.md#cancel-actions)
+ [Ações críticas](visual-designer-error-handling.md#critical-actions)
+ [Enceramento de ações](visual-designer-error-handling.md#end-actions)
+ [Tutorial: criar um runbook usando a experiência de design visual](visual-designer-tutorial.md)
+ [Etapa 1: navegue até a experiência de design visual](visual-designer-tutorial.md#navigate-console)
+ [Etapa 2: criar um fluxo de trabalho](visual-designer-tutorial.md#create-workflow)
+ [Etapa 3: analisar o código gerado automaticamente](visual-designer-tutorial.md#view-generated-code)
+ [Etapa 4: executar seu novo runbook](visual-designer-tutorial.md#use-tutorial-runbook)
+ [Etapa 5: limpar](visual-designer-tutorial.md#cleanup-tutorial-runbook)
+ [Criar runbooks do Automation](automation-authoring-runbooks.md)
+ [Identifique seu caso de uso](automation-authoring-runbooks.md#automation-authoring-runbooks-use-case)
+ [Configuração do ambiente de desenvolvimento](automation-authoring-runbooks.md#automation-authoring-runbooks-environment)
+ [Desenvolva conteúdo do runbook](automation-authoring-runbooks.md#automation-authoring-runbooks-developing-content)
+ [Exemplo 1: criação de runbooks pai-filho](automation-authoring-runbooks-parent-child-example.md)
+ [Crie o runbook filho](automation-authoring-runbooks-parent-child-example.md#automation-authoring-runbooks-child-runbook)
+ [Crie o runbook pai](automation-authoring-runbooks-parent-child-example.md#automation-authoring-runbooks-parent-runbook)
+ [Exemplo 2: Runbook com script](automation-authoring-runbooks-scripted-example.md)
+ [Exemplos adicionais de runbook](automation-document-examples.md)
+ [Implantar a arquitetura da VPC e os controles de domínio do Microsoft Active Directory](automation-document-architecture-deployment-example.md)
+ [Restaurar um volume raiz do snapshot mais recente](automation-document-instance-recovery-example.md)
+ [Crie uma AMI e uma cópia entre regiões](automation-document-backup-maintenance-example.md)
+ [Criar parâmetros de entrada que preenchem os recursos da AWS](populating-input-parameters.md)
+ [Uso do Document Builder para criar runbooks](automation-document-builder.md)
+ [Criação de um runbook usando o Document Builder](automation-document-builder.md#create-runbook)
+ [Crie um runbook que execute scripts](automation-document-builder.md#create-runbook-scripts)
+ [Uso de scripts em runbooks](automation-document-script-considerations.md)
+ [Permissões para usar runbooks](automation-document-script-considerations.md#script-permissions)
+ [Adicionar scripts a runbooks](automation-document-script-considerations.md#adding-scripts)
+ [Restrições de script para runbooks](automation-document-script-considerations.md#script-constraints)
+ [Uso de instruções condicionais em runbooks](automation-branch-condition.md)
+ [Trabalhar com a ação `aws:branch`](automation-branch-condition.md#branch-action-explained)
+ [Criar uma etapa `aws:branch` em um runbook](automation-branch-condition.md#create-branch-action)
+ [Sobre a criação de variáveis de saída](automation-branch-condition.md#branch-action-output)
+ [Runbooks `aws:branch` de exemplo](automation-branch-condition.md#branch-runbook-examples)
+ [Criar automações de ramificação complexas com operadores](automation-branch-condition.md#branch-operators)
+ [Exemplos de como usar opções condicionais](automation-branch-condition.md#conditional-examples)
+ [Uso de saídas de ações como entradas](automation-action-outputs-inputs.md)
+ [Uso de JSONPath em runbooks](automation-action-outputs-inputs.md#automation-action-json-path)
+ [Criação de integrações de webhooks para o Automation](creating-webhook-integrations.md)
+ [Criação de integrações (console)](creating-webhook-integrations.md#creating-integrations-console)
+ [Criação de integrações (linha de comando)](creating-webhook-integrations.md#creating-integrations-commandline)
+ [Criação de webhooks para integrações](creating-webhook-integrations.md#creating-webhooks)
+ [Gerenciar tempos limite em runbooks](automation-handling-timeouts.md)
# Experiência de design visual para runbooks de automação
O AWS Systems Manager Automation fornece uma experiência de design visual de baixo código que ajuda você a criar runbooks de automação. A experiência de design visual fornece uma interface simples de arrastar e soltar com a opção de adição do seu próprio código para que você possa criar e editar runbooks mais facilmente. Com a experiência de design visual, você pode fazer o seguinte:
+ Controlar instruções condicionais.
+ Controlar como a entrada e a saída são filtradas ou transformadas para cada ação.
+ Configurar o tratamento de erros.
+ Criar protótipos de novos runbooks.
+ Usar seus protótipos de runbooks como ponto de partida para o desenvolvimento local com o AWS Toolkit for Visual Studio Code.
Ao criar ou editar um runbook, você pode acessar a experiência de design visual no [console do Automation](https://console.aws.amazon.com/systems-manager/automation/home?region=us-east-1#/). À medida que você cria um runbook, a experiência de design visual valida seu trabalho e gera código automaticamente. Você pode revisar o código gerado ou exportá-lo para desenvolvimento local. Ao terminar, você pode salvar seu runbook, executá-lo e examinar os resultados no console do Systems Manager Automation.
**Topics**
+ [Visão geral da interface](visual-designer-interface-overview.md)
+ [Usar a experiência de design visual](visual-designer-use.md)
+ [Configurar entradas e saídas](visual-designer-action-inputs-outputs.md)
+ [Tratamento de erros com a experiência de design visual](visual-designer-error-handling.md)
+ [Tutorial: criar um runbook usando a experiência de design visual](visual-designer-tutorial.md)
# Visão geral da interface de experiência de design visual
A experiência de design visual do Systems Manager Automation é um designer de fluxo de trabalho visual de baixo código que ajuda você a criar runbooks de automação.
Conheça a experiência de design visual com uma visão geral dos componentes da interface:
![\[Componentes da experiência de design visual\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/visual_designer_overview.png)
+ O navegador **Ações** contém as guias **Ações**, **APIs da AWS** e **Runbooks**.
+ A *tela* é onde você arrasta e solta ações no gráfico do fluxo de trabalho, altera a ordem das ações e seleciona ações para configurar ou visualizar.
+ O painel **Formulário** é onde você pode visualizar e editar as propriedades de qualquer ação selecionada na tela. Selecione a opção **Conteúdo** para visualizar o YAML ou o JSON do seu runbook, com a ação atualmente selecionada destacada.
Os links de **Informações** abrem um painel com informações contextuais quando você precisa de ajuda. Esses painéis também incluem links para tópicos relacionados na documentação do Systems Manager Automation.
## Navegador Ações
No navegador **Ações**, é possível selecionar ações para arrastar e soltar no gráfico do fluxo de trabalho. Você pode pesquisar todas as ações usando o campo de pesquisa na parte superior do navegador **Ações**. O navegador **Ações** contém as seguintes guias:
+ A guia **Ações** fornece uma lista de ações de automação que você pode arrastar e soltar no gráfico do fluxo de trabalho do seu runbook na tela.
+ A guia **APIs da AWS** fornece uma lista de APIs da AWS que você pode arrastar e soltar no gráfico do fluxo de trabalho do seu runbook na tela.
+ A guia **Runbooks** fornece vários runbooks prontos para uso e reutilizáveis como blocos de construção que você pode usar em uma variedade de casos de uso. Por exemplo, você pode usar runbooks para realizar tarefas comuns de remediação em instâncias do Amazon EC2 em seu fluxo de trabalho sem precisar recriar as mesmas ações.
![\[Experiência de design visual: navegador Ações\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/visual_designer_actions_multi_view.png)
## Canvas
Depois de escolher uma ação para adicionar à sua automação, arraste-a para a tela e solte-a no gráfico do fluxo de trabalho. Você também pode arrastar e soltar ações para movê-las para lugares diferentes no fluxo de trabalho do seu runbook. Se o seu fluxo de trabalho for complexo, talvez não seja possível visualizar tudo no painel da tela. Use os controles na parte superior da tela para aumentar ou diminuir o zoom. Para visualizar diferentes partes de um fluxo de trabalho, é possível arrastar o gráfico do fluxo de trabalho na tela.
Arraste uma ação do navegador **Ações** e solte-a no gráfico do fluxo de trabalho do seu runbook. Uma linha mostra onde ela será colocada no fluxo de trabalho. Para alterar a ordem de uma ação, é possível arrastá-la para um local diferente no seu fluxo de trabalho. A nova ação foi adicionada ao seu fluxo de trabalho e seu código é gerado automaticamente.
![\[Experiência de design visual: Tela\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/visual_designer_canvas.png)
## Formulário
Após adicionar uma ação ao seu fluxo de trabalho do runbook, você pode configurá-la para atender ao seu caso de uso. Escolha a ação que você deseja configurar e você verá seus parâmetros e opções no painel **Formulário**. Você também pode ver o código YAML ou JSON escolhendo a opção **Conteúdo**. O código associado à ação que você selecionou é destacado.
![\[Experiência de design visual: painel Formulário\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/visual_designer_form.png)
![\[Experiência de design visual: painel Conteúdo\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/visual_designer_content.png)
## Atalhos de teclado
A experiência de design visual é compatível com os atalhos de teclado mostrados na tabela a seguir.
| Atalho de teclado | Função |
| --- | --- |
| Ctrl\$1Z | Desfazer a operação mais recente. |
| Ctrl\$1Shift\$1Z | Refazer a operação mais recente. |
| Alt\$1C | Centralizar o fluxo de trabalho na tela. |
| Backspace | Remover todos os estados selecionados. |
| Delete | Remover todos os estados selecionados. |
| Ctrl\$1D | Duplicar o estado selecionado. |
# Usar a experiência de design visual
Aprenda a criar, editar e executar fluxos de trabalho do runbook usando a experiência de design visual. Depois que seu fluxo de trabalho estiver pronto, você poderá salvá-lo ou exportá-lo. Você também pode usar a experiência de design visual para prototipagem rápida.
## Criar um runbook
1. Faça login no [console do Systems Manager Automation](https://console.aws.amazon.com/systems-manager/automation/home?region=us-east-1#/).
1. Escolha **Criar runbook**.
1. Na caixa **Nome**, insira um nome para o runbook, por exemplo, `MyNewRunbook`.
1. Ao lado do botão **Design** e **Código**, selecione o ícone de lápis e insira um nome para o seu runbook.
Agora você pode criar um fluxo de trabalho para seu novo runbook.
## Desenvolver um runbook
Para criar um fluxo de trabalho de runbook usando a experiência de design visual, arraste uma ação de automação do navegador **Ações** para a tela, colocando-a onde desejar no fluxo de trabalho do seu runbook. Você também pode reordenar as ações em seu fluxo de trabalho arrastando-as para um local diferente. Quando você arrasta uma ação para a tela, uma linha aparece nos locais em que é possível soltar a ação no fluxo de trabalho. Após uma ação ser colocada na tela, seu código é gerado automaticamente e adicionado ao conteúdo do seu runbook.
Se você souber o nome da ação que deseja adicionar, use a caixa de pesquisa na parte superior do navegador **Ações** para encontrá-la.
Depois de soltar uma ação na tela, configure-a usando o painel **Formulário** à direita. Esse painel contém as guias **Geral**, **Entradas**, **Saídas** e **Configuração** para cada ação de automação ou ação de API que você coloca na tela. Por exemplo, a guia **Geral** consiste nas seguintes seções:
+ O **Nome da etapa** identifica a etapa. Especifique um valor exclusivo para o nome da etapa.
+ A **Descrição** ajuda você a descrever o que a ação está fazendo no fluxo de trabalho do seu runbook.
A guia **Entradas** contém campos que variam com base na ação. Por exemplo, a ação de automação `aws:executeScript` consiste nas seguintes seções:
+ O **Runtime** é a linguagem que será usada para executar o script fornecido.
+ O **Manipulador** é o nome da sua função. É necessário garantir que a função definida no manipulador tenha dois parâmetros: `events` e `context`. O runtime do PowerShell não é compatível com este parâmetro.
+ O **Script** é um script incorporado que você deseja executar durante o fluxo de trabalho.
+ (Opcional) O **Anexo** é para scripts autônomos ou arquivos.zip que podem ser invocados pela ação. Esse parâmetro é obrigatório para runbooks JSON.
A guia **Saídas** ajuda a especificar os valores que você deseja gerar de uma ação. Você pode referenciar valores de saída em ações posteriores do seu fluxo de trabalho ou gerar resultados de ações para fins de registro. Nem todas as ações terão uma guia **Saídas** porque nem todas as ações oferecem suporte a saídas. Por exemplo, a ação `aws:pause` não aceita saídas. Para ações que oferecem suporte a saídas, a guia **Saídas** consiste nas seguintes seções:
+ O **Nome** é o nome a ser usado para o valor de saída. Você pode referenciar saídas em ações posteriores do seu fluxo de trabalho.
+ O **Seletor** é uma string de expressão JSONPath que começa com `"$."` e é usada para selecionar um ou mais componentes em um elemento JSON.
+ O **Tipo** é o tipo de dados para o valor de saída. Por exemplo, o tipo de dados `String` ou `Integer`.
A guia **Configuração** contém propriedades e opções que todas as ações de automação podem usar. A ação consiste nas seguintes seções:
+ A propriedade **Máximo de tentativas** é o número tentativas de executar uma ação em caso de falha.
+ A propriedade **Tempo limite em segundos** especifica o valor do tempo limite para uma ação.
+ A propriedade **É crítica** determina se a falha na ação interrompe toda a automação.
+ A propriedade **Próxima etapa** determina qual ação a automação executará em seguida no runbook.
+ A propriedade **Em falha** determina qual ação a automação executará em seguida no runbook se a ação falhar.
+ A propriedade **Em cancelamento** determina qual ação a automação executará em seguida no runbook se a ação for cancelada por um usuário.
Para excluir uma ação, você pode usar o backspace, a barra de ferramentas acima da tela ou clicar com o botão direito do mouse e escolher **Excluir ação**.
À medida que seu fluxo de trabalho cresce, ele pode não caber na tela. Para ajudar a ajustar o fluxo de trabalho à tela, tente uma das opções a seguir:
+ Use os controles nos painéis laterais para redimensionar ou fechar os painéis.
+ Use a barra de ferramentas na parte superior da tela para ampliar ou reduzir o gráfico do fluxo de trabalho.
## Atualizar seu runbook
Você pode atualizar um fluxo de trabalho de runbook existente criando uma nova versão do seu runbook. As atualizações em seus runbooks podem ser feitas usando a experiência de design visual ou editando o código diretamente. Para atualizar um runbook existente, use o procedimento a seguir:
1. Faça login no [console do Systems Manager Automation](https://console.aws.amazon.com/systems-manager/automation/home?region=us-east-1#/).
1. Escolha o runbook que deseja atualizar.
1. Escolha **Create new version (Criar nova versão)**.
1. A experiência de design visual tem dois painéis: um painel de código e um painel de fluxo de trabalho visual. Escolha **Design** no painel de fluxo de trabalho visual para editar seu fluxo de trabalho com a experiência de design visual. Ao concluir, escolha **Criar nova versão** para salvar as alterações e sair.
1. (Opcional) Use o painel de código para editar o conteúdo do runbook em YAML ou JSON.
## Exportar seu runbook
Para exportar o código YAML ou JSON do fluxo de trabalho do seu runbook e também um gráfico do seu fluxo de trabalho, use o procedimento a seguir:
1. Escolha seu runbook no console **Documentos**.
1. Escolha **Create new version (Criar nova versão)**.
1. No menu suspenso **Ações**, escolha se você deseja exportar o gráfico ou o runbook, além do formato preferido.
# Configurar entradas e saídas para suas ações
Cada ação de automação responde com base na entrada recebida. Na maioria dos casos, você envia a saída para as ações subsequentes. Na experiência de design visual, é possível configurar os dados de entrada e saída de uma ação nas guias **Entradas** e **Saídas** do painel **Formulário**.
Para obter informações detalhadas sobre como definir e usar a saída para ações de automação, consulte [Uso de saídas de ações como entradas](automation-action-outputs-inputs.md).
## Forneça dados de entrada para uma ação
Cada ação de automação tem uma ou mais entradas para as quais você deve fornecer um valor. O valor que você fornece para a entrada de uma ação é determinado pelo tipo e formato de dados aceitos pela ação. Por exemplo, as ações `aws:sleep` exigem um valor de string formatado em ISO 8601 para a entrada `Duration`.
Geralmente, você usa ações no fluxo de trabalho do seu runbook que retornam a saída que você deseja usar em ações subsequentes. É importante garantir que seus valores de entrada estejam corretos para evitar erros no fluxo de trabalho do seu runbook. Os valores de entrada também são importantes porque determinam se a ação retorna a saída esperada. Por exemplo, ao usar a ação `aws:executeAwsApi`, você quer ter certeza de que está fornecendo o valor certo para a operação da API.
## Definir dados de saída para uma ação
Algumas ações de automação retornam a saída após realizar suas operações definidas. As ações que retornam uma saída têm saídas predefinidas ou permitem que você mesmo as defina. Por exemplo, a ação `aws:createImage` tem saídas predefinidas que retornam um `ImageId` e `ImageState`. Comparativamente, com a ação `aws:executeAwsApi`, você pode definir as saídas que deseja da operação de API especificada. Como resultado, você pode retornar um ou mais valores de uma única operação de API para usar em ações subsequentes.
Definir suas próprias saídas para uma ação de automação exige que você especifique um nome da saída, o tipo de dados e o valor da saída. Para continuar usando a ação `aws:executeAwsApi` como exemplo, digamos que você esteja chamando a operação da API `DescribeInstances` do Amazon EC2. Neste exemplo, você deseja retornar, ou gerar como saída, o `State` de uma instância do Amazon EC2 e ramificar o fluxo de trabalho do seu runbook com base na saída. Você escolhe nomear a saída **InstanceState** e usar o tipo de dados **String**.
O processo para definir o valor real da saída é diferente dependendo da ação. Por exemplo, se você estiver usando a ação `aws:executeScript`, deverá usar instruções `return` em suas funções para fornecer dados às saídas. Com outras ações como `aws:executeAwsApi`, `aws:waitForAwsResourceProperty` e `aws:assertAwsResourceProperty`, um `Selector` é necessário. O `Selector`, ou `PropertySelector` como algumas ações se referem a ele, é uma string JSONPath usada para processar a resposta JSON de uma operação de API. É importante entender como o objeto de resposta JSON de uma operação de API é estruturado para que você possa selecionar o valor correto para sua saída. Usando a operação de API `DescribeInstances` mencionada anteriormente, veja o exemplo de resposta JSON a seguir:
```
{
"reservationSet": {
"item": {
"reservationId": "r-1234567890abcdef0",
"ownerId": 123456789012,
"groupSet": "",
"instancesSet": {
"item": {
"instanceId": "i-1234567890abcdef0",
"imageId": "ami-bff32ccc",
"instanceState": {
"code": 16,
"name": "running"
},
"privateDnsName": "ip-192-168-1-88.eu-west-1.compute.internal",
"dnsName": "ec2-54-194-252-215.eu-west-1.compute.amazonaws.com",
"reason": "",
"keyName": "my_keypair",
"amiLaunchIndex": 0,
"productCodes": "",
"instanceType": "t2.micro",
"launchTime": "2018-05-08T16:46:19.000Z",
"placement": {
"availabilityZone": "eu-west-1c",
"groupName": "",
"tenancy": "default"
},
"monitoring": {
"state": "disabled"
},
"subnetId": "subnet-56f5f000",
"vpcId": "vpc-11112222",
"privateIpAddress": "192.168.1.88",
"ipAddress": "54.194.252.215",
"sourceDestCheck": true,
"groupSet": {
"item": {
"groupId": "sg-e4076000",
"groupName": "SecurityGroup1"
}
},
"architecture": "x86_64",
"rootDeviceType": "ebs",
"rootDeviceName": "/dev/xvda",
"blockDeviceMapping": {
"item": {
"deviceName": "/dev/xvda",
"ebs": {
"volumeId": "vol-1234567890abcdef0",
"status": "attached",
"attachTime": "2015-12-22T10:44:09.000Z",
"deleteOnTermination": true
}
}
},
"virtualizationType": "hvm",
"clientToken": "xMcwG14507example",
"tagSet": {
"item": {
"key": "Name",
"value": "Server_1"
}
},
"hypervisor": "xen",
"networkInterfaceSet": {
"item": {
"networkInterfaceId": "eni-551ba000",
"subnetId": "subnet-56f5f000",
"vpcId": "vpc-11112222",
"description": "Primary network interface",
"ownerId": 123456789012,
"status": "in-use",
"macAddress": "02:dd:2c:5e:01:69",
"privateIpAddress": "192.168.1.88",
"privateDnsName": "ip-192-168-1-88.eu-west-1.compute.internal",
"sourceDestCheck": true,
"groupSet": {
"item": {
"groupId": "sg-e4076000",
"groupName": "SecurityGroup1"
}
},
"attachment": {
"attachmentId": "eni-attach-39697adc",
"deviceIndex": 0,
"status": "attached",
"attachTime": "2018-05-08T16:46:19.000Z",
"deleteOnTermination": true
},
"association": {
"publicIp": "54.194.252.215",
"publicDnsName": "ec2-54-194-252-215.eu-west-1.compute.amazonaws.com",
"ipOwnerId": "amazon"
},
"privateIpAddressesSet": {
"item": {
"privateIpAddress": "192.168.1.88",
"privateDnsName": "ip-192-168-1-88.eu-west-1.compute.internal",
"primary": true,
"association": {
"publicIp": "54.194.252.215",
"publicDnsName": "ec2-54-194-252-215.eu-west-1.compute.amazonaws.com",
"ipOwnerId": "amazon"
}
}
},
"ipv6AddressesSet": {
"item": {
"ipv6Address": "2001:db8:1234:1a2b::123"
}
}
}
},
"iamInstanceProfile": {
"arn": "arn:aws:iam::123456789012:instance-profile/AdminRole",
"id": "ABCAJEDNCAA64SSD123AB"
},
"ebsOptimized": false,
"cpuOptions": {
"coreCount": 1,
"threadsPerCore": 1
}
}
}
}
}
}
```
No objeto de resposta JSON, a instância `State` está aninhada em um objeto `Instances` que está aninhado no objeto `Reservations`. Para retornar o valor da instância `State`, use a seguinte string para `Selector` para que o valor possa ser usado em nossa saída: **\$1.Reservations[0].Instances[0].State.Name**.
Para referenciar um valor de saída em ações subsequentes do fluxo de trabalho do seu runbook, o seguinte formato é usado: `{{ StepName.NameOfOutput }}`. Por exemplo, **\$1\$1 GetInstanceState.InstanceState \$1\$1**. Na experiência de design visual, é possível escolher valores de saída para usar em ações subsequentes utilizando o menu suspenso para a entrada. Ao usar saídas em ações subsequentes, o tipo de dados da saída deve corresponder ao tipo de dados da entrada. Neste exemplo, a saída `InstanceState` é uma `String`. Portanto, para usar o valor na entrada de uma ação subsequente, a entrada deve aceitar uma `String`.
# Tratamento de erros com a experiência de design visual
Por padrão, quando uma ação relata um erro, o Automation interrompe totalmente o fluxo de trabalho do runbook. Isso ocorre porque o valor padrão da propriedade `onFailure` em todas as ações é `Abort`. É possível configurar a forma como a automação lida com erros no fluxo de trabalho do seu runbook. Mesmo que você tenha configurado o tratamento de erros, alguns erros ainda podem causar uma falha na automação. Para obter mais informações, consulte [Solução de problemas do Systems Manager Automation](automation-troubleshooting.md). Na experiência de design visual, você configura o tratamento de erros no painel **Configuração**.
![\[Opções de tratamento de erros\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/visual_designer_error_handling.png)
## Repetir a ação em caso de erro
Para repetir uma ação em caso de erro, especifique um valor para a propriedade **Máximo de tentativas**. O valor padrão é 1. Se o valor for maior que 1, a etapa não será considerada como em falha até que todas as novas tentativas tenham falhado.
## Tempo limite
Você pode configurar um tempo limite para as ações para definir o número máximo de segundos que sua ação pode ser executada antes que ela falhe. Para configurar um tempo limite, insira o número de segundos que sua ação deve esperar antes que a ação falhe na propriedade **Tempo limite em segundos**. Se o tempo limite for atingido e o valor de `Max attempts` for maior que 1, a etapa não será considerada expirada até que todas as novas tentativas tenham sido feitas.
## Ações com falha
Por padrão, quando uma ação falha, o Automation interrompe totalmente o fluxo de trabalho do runbook. Você pode modificar esse comportamento especificando um valor alternativo para a propriedade **Em falha** das ações em seu runbook. Se desejar que o fluxo de trabalho continue na próxima etapa do runbook, escolha **Continuar**. Se desejar que o fluxo de trabalho pule para outra etapa subsequente no runbook, escolha **Etapa** e insira o nome da etapa.
## Ações canceladas
Por padrão, quando uma ação é cancelada por um usuário, o Automation interrompe totalmente o fluxo de trabalho do runbook. Você pode modificar esse comportamento especificando um valor alternativo para a propriedade **Em cancelamento** das ações em seu runbook. Se desejar que o fluxo de trabalho pule para outra etapa subsequente no runbook, escolha **Etapa** e insira o nome da etapa.
## Ações críticas
Você pode designar uma ação como *crítica*, o que significa que ela determina o status geral dos relatórios de sua automação. Se uma etapa com essa designação falhar, o Automation relatará o status final como `Failed`, independentemente do sucesso de outras ações. Para configurar uma ação como crítica, mantenha o valor padrão como **Verdadeiro** para a propriedade **É crítica**.
## Enceramento de ações
A propriedade **É o fim** interrompe automação no final de determinada ação. O valor padrão da propriedade é `false`. Se você configurar essa propriedade para uma ação, a automação será interrompida se a ação for bem-sucedida ou falhar. Essa propriedade é mais frequentemente usada com ações `aws:branch` para lidar com valores de entrada inesperados ou indefinidos. O exemplo a seguir mostra um runbook que espera um estado de instância de `running`, `stopping` ou `stopped`. Se uma instância estiver em um estado diferente, a automação será encerrada.
![\[A experiência de design visual é o exemplo final\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/visual_designer_is_end_example.png)
# Tutorial: criar um runbook usando a experiência de design visual
Neste tutorial, você aprenderá o básico de como trabalhar com a experiência de design visual fornecida pelo Systems Manager Automation. Na experiência de design visual, é possível criar um runbook que usa várias ações. Você usará o recurso de arrastar e soltar para organizar as ações na tela. Você também pesquisará, selecionará e configurará essas ações. Em seguida, você poderá visualizar o código YAML gerado automaticamente para o fluxo de trabalho do seu runbook, sair da experiência de design visual, executar o runbook e revisar os detalhes da execução.
Este tutorial também mostra como atualizar o runbook e visualizar a nova versão. No final do tutorial, você executa uma etapa de limpeza e exclui seu runbook.
Após concluir este tutorial, você saberá como usar a experiência de design visual para criar um runbook. Você também aprenderá a atualizar, executar e excluir seu runbook.
**nota**
Antes de começar este tutorial, certifique-se de concluir a [Configurar a automação](automation-setup.md).
**Topics**
+ [Etapa 1: navegue até a experiência de design visual](#navigate-console)
+ [Etapa 2: criar um fluxo de trabalho](#create-workflow)
+ [Etapa 3: analisar o código gerado automaticamente](#view-generated-code)
+ [Etapa 4: executar seu novo runbook](#use-tutorial-runbook)
+ [Etapa 5: limpar](#cleanup-tutorial-runbook)
## Etapa 1: navegue até a experiência de design visual
1. Faça login no [console do Systems Manager Automation](https://console.aws.amazon.com/systems-manager/automation/home?region=us-east-1#/).
1. Escolha **Criar runbook de automação**.
## Etapa 2: criar um fluxo de trabalho
Na experiência de design visual, um fluxo de trabalho é uma representação gráfica do seu runbook na tela. É possível usar a experiência de design visual para definir, configurar e examinar as ações individuais do seu runbook.
**Para criar um fluxo de trabalho**
1. Ao lado do botão **Design** e **Código**, selecione o ícone de lápis e insira um nome para o seu runbook. Para este tutorial, insira **VisualDesignExperienceTutorial**.
![\[Experiência de design visual: dê um nome ao seu runbook\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/visual_designer_tutorial_name.png)
1. Na seção **Atributos do documento** do painel **Formulário**, expanda a lista suspensa **Parâmetros de entrada** e selecione **Adicionar um parâmetro**.
1. No campo **Nome do parâmetro**, insira **InstanceId**.
1. No menu suspenso **Tipo**, escolha **AWS::EC2::Instance**.
1. Selecione o botão **Obrigatório**.
![\[Crie um parâmetro para seu runbook\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/visual_designer_actions_tutorial_parameter.png)
1. No navegador **APIs da AWS**, insira **DescribeInstances** na barra de pesquisa.
1. Arraste uma ação **Amazon EC2 – DescribeInstances** para a tela vazia.
1. Em **Nome da etapa**, insira um valor. Para este tutorial, use o nome **GetInstanceState**.
![\[Escolha uma ação de API de descrição de instâncias do Amazon EC2.\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/visual_designer_tutorial_api_action.png)
1. Expanda a lista suspensa **Entradas adicionais** e, no campo **Nome da entrada**, insira **InstanceIds**.
1. Escolha a guia **Entradas**.
1. No campo **Valor de entrada**, escolha a entrada do documento **InstanceId**. Isso faz referência ao valor do parâmetro de entrada criado por você no início do procedimento. Como a entrada **InstanceIDs** da ação `DescribeInstances` aceita valores `StringList`, é necessário colocar a entrada **InstanceID** entre colchetes. O YAML para o **Valor de entrada** deve corresponder ao seguinte: **['\$1\$1 InstanceId \$1\$1']**.
1. Na guia **Saídas**, selecione **Adicionar uma saída** e insira **InstanceState** no campo **Nome**.
1. No campo **Seletor**, insira **\$1.Reservations[0].Instances[0].State.Name**.
1. **No menu suspenso **Tipo**, escolha String**.
1. Arraste uma ação de **Ramificação** do navegador **Ações** e solte-a abaixo da etapa **`GetInstanceState`**.
1. Em **Nome da etapa**, insira um valor. Neste tutorial, use o nome `BranchOnInstanceState`.
Para definir a lógica de ramificação, faça o seguinte:
1. Escolha o estado **`Branch`** na tela. Em seguida, em **Entradas** e **Escolhas**, selecione o ícone de lápis para editar a **Regra \$11**.
1. Escolha **Adicionar condições**.
1. Na caixa de diálogo **Condições para a regra \$11**, escolha a saída da etapa **GetInstanceState.InstanceState** no menu suspenso **Variável**.
1. Em **Operador**, escolha **é igual a**.
1. Em **Valor**, escolha **String** na lista suspensa. Insira **stopped**.
![\[Defina uma condição para uma ação de ramificação.\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/visual_designer_tutorial_condition.png)
1. Selecione **Salvar condições**.
1. Escolha **Adicionar nova regra de escolha**.
1. Escolha **Adicionar condições** para a **Regra \$12**.
1. Na caixa de diálogo **Condições para a regra \$12**, escolha a saída da etapa **GetInstanceState.InstanceState** no menu suspenso **Variável**.
1. Em **Operador**, escolha **é igual a**.
1. Em **Valor**, escolha **String** na lista suspensa. Insira **stopping**.
1. Selecione **Salvar condições**.
1. Escolha **Adicionar nova regra de escolha**.
1. Para a **Regra \$13**, escolha **Adicionar condições**.
1. Na caixa de diálogo **Condições para a regra \$13**, escolha a saída da etapa **GetInstanceState.InstanceState** no menu suspenso **Variável**.
1. Em **Operador**, escolha **é igual a**.
1. Em **Valor**, escolha **String** na lista suspensa. Insira **running**.
1. Selecione **Salvar condições**.
1. Na **Regra padrão**, escolha **Ir para o final** em **Etapa padrão**.
1. Arraste a ação **Alterar um estado de instância** para a caixa vazia **Arraste a ação aqui** sob a condição **\$1\$1GetInstanceState.InstanceState\$1\$1 == "stopped"**.
1. Em **Nome da etapa**, insira **StartInstance**.
1. Na guia **Entradas**, em **IDs de instância**, escolha o valor de entrada do documento **InstanceId** no menu suspenso.
1. Para **Estado desejado**, especifique **`running`**.
1. Arraste a ação **Aguardar recurso da AWS** para a caixa vazia **Arraste a ação aqui** sob a condição **\$1\$1 GetInstanceState.InstanceState \$1\$1 == "stopping"**.
1. Em **Nome da etapa**, insira um valor. Neste tutorial, use o nome `WaitForInstanceStop`.
1. No campo **Serviço**, escolha **Amazon EC2**.
1. No campo **API**, escolha **DescribeInstances**.
1. No campo **Seletor de propriedades**, insira **\$1.Reservations[0].Instances[0].State.Name**.
1. Para o parâmetro **Valores desejados**, insira **`["stopped"]`**.
1. Na guia **Configuração** da ação **WaitForInstanceStop**, escolha **StartInstance** no menu suspenso **Próxima etapa**.
1. Arraste a ação **Executar comando em instâncias** para a caixa vazia **Arraste a ação aqui** sob a condição **\$1\$1GetInstanceState.InstanceState\$1\$1 == "running"**.
1. Em **Nome da etapa**, insira **SayHello**.
1. Na guia **Entradas**, insira **AWS-RunShellScript** para o parâmetro **Nome do documento**.
1. Para **InstanceIds**, escolha o valor de entrada do documento **InstanceId** no menu suspenso.
1. Expanda o menu suspenso **Entradas adicionais** e, no menu suspenso **Nome da entrada**, escolha **Parâmetros**.
1. No campo **Valore de entrada**, insira **`{"commands": "echo 'Hello World'"}`**.
1. Revise o runbook concluído na tela e selecione **Criar runbook** para salvar o runbook do tutorial.
![\[Analisar e criar o runbook.\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/visual_designer_tutorial_complete.png)
## Etapa 3: analisar o código gerado automaticamente
Conforme você arrasta e solta ações do navegador **Ações** na tela, a experiência de design visual compõe automaticamente o conteúdo YAML ou JSON do seu runbook em tempo real. Você pode visualizar e editar esse código. Para visualizar o código gerado automaticamente, selecione **Código** na opção **Design** e **Código**.
## Etapa 4: executar seu novo runbook
Após criar seu runbook, você poderá executar a automação.
**Para executar seu novo runbook de automação**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, selecione **Automation** e **Execute automation (Executar automação)**.
1. Na lista **Automation document** (Documento do Automation), escolha um runbook. Escolha uma ou mais opções no painel **Document categories** (Categorias de documentos) para filtrar documentos SSM de acordo com sua finalidade. Para visualizar um runbook que você tenha, escolha a guia **Owned by me** (De minha propriedade). Para visualizar um runbook compartilhado com sua conta, escolha a guia **Shared with me** (Compartilhado comigo). Para visualizar todos os runbooks, escolha a guia **All documents** (Todos os documentos).
**nota**
Você pode visualizar informações sobre um runbook, selecionando o nome dele.
1. Na seção **Document details** (Detalhes do documento), verifique se **Document version** (Versão do documento) está definida como a versão que você quer executar. O sistema inclui as seguintes opções de versão:
+ **Versão padrão no runtime**: escolha essa opção se o runbook do Automation for atualizado periodicamente e uma nova versão padrão for atribuída.
+ **Versão mais recente no runtime**: escolha essa opção se o runbook do Automation for atualizado periodicamente e se você quiser executar a versão mais recente.
+ **1 (padrão):** escolha esta opção para executar a primeira versão do documento, que é a versão padrão.
1. Escolha **Próximo**.
1. Na página **Executar runbook de automação**, escolha **Execução simples**.
1. Na seção **Input parameters (Parâmetros de entrada)**, especifique as entradas necessárias. Opcionalmente, você pode escolher uma função de serviço do IAM na lista **AutomationAssumeRole**.
1. (Opcional) Escolha um alarme do Amazon CloudWatch a fim de aplicar à sua automação para monitoramento. Para anexar um alarme do CloudWatch à sua automação, a entidade principal do IAM que inicia a automação deve ter permissão para a ação `iam:createServiceLinkedRole`. Para obter mais informações sobre alarmes do CloudWatch, consulte [Usar alarmes do Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html). A automação será interrompida se o alarme for ativado. Se você usar o AWS CloudTrail, você verá a chamada de API em sua trilha.
1. Clique em **Executar**.
## Etapa 5: limpar
**Para excluir seu runbook**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Documents**.
1. Selecione a guia **Pertencente a mim**.
1. Localize o runbook **VisualDesignExperienceTutorial**.
1. Selecione o botão na página do cartão do documento e escolha **Excluir documento** no menu suspenso **Ações**.
# Criar runbooks do Automation
Cada runbook no Automation, uma ferramenta do AWS Systems Manager, define uma automação. Os runbooks do Automation definem as ações que são executadas durante uma automação. No conteúdo do runbook, você define os parâmetros de entrada, saídas e ações que o Systems Manager realiza nas suas instâncias gerenciadas e os recursos da AWS.
A Automação inclui vários runbooks predefinidos que você pode usar para executar tarefas comuns, como reiniciar uma ou mais instâncias do Amazon Elastic Compute Cloud (Amazon EC2) ou criar uma Amazon Machine Image (AMI). No entanto, seus casos de uso podem se estender além dos recursos dos runbooks predefinidos. Se esse for o caso, você pode criar seus próprios runbooks e modificá-los de acordo com suas necessidades.
Um runbook consiste em ações de automação, parâmetros para essas ações e parâmetros de entrada especificados. O conteúdo de um runbook é escrito em YAML ou JSON. Se você não estiver familiarizado com YAML ou JSON, recomendamos usar o designer visual ou aprender mais sobre qualquer linguagem de marcação antes de tentar criar seu próprio runbook. Para obter mais informações sobre o designer visual, consulte [Experiência de design visual para runbooks de automação](automation-visual-designer.md).
As seções a seguir ajudarão você a criar seu primeiro runbook.
## Identifique seu caso de uso
A primeira etapa na criação de um runbook é identificar o caso de uso. Por exemplo, você agendou o runbook `AWS-CreateImage` para ser executado diariamente em todas as instâncias do Amazon EC2 de produção. No final do mês, você percebe que tem mais imagens do que são necessárias para obter pontos de recuperação. No futuro, você precisará excluir automaticamente a AMI mais antiga de uma instância do Amazon EC2, quando uma nova AMI for criada. Para fazer isso, você cria um novo runbook que faz o seguinte:
1. Executa a ação `aws:createImage` e especifica o ID da instância na descrição da imagem.
1. Executa a ação `aws:waitForAwsResourceProperty` para sondar o estado da imagem até que ela esteja `available`.
1. Depois que o estado da imagem estiver `available`, o `aws:executeScript` executa um script Python personalizado que reúne os IDs de todas as imagens associadas à sua instância do Amazon EC2. O script faz isso filtrando, usando o ID da instância na descrição da imagem que você especificou na criação. Em seguida, o script classifica a lista de IDs de imagem com base no `creationDate` da imagem e emite o ID da AMI mais antiga.
1. Por último, a ação `aws:deleteImage` é executada para excluir a AMI mais antiga, usando o ID do resultado da etapa anterior.
Nesse cenário, você já estava usando o runbook `AWS-CreateImage`, mas descobriu que seu caso de uso exigia maior flexibilidade. Esta é uma situação comum porque pode haver sobreposição entre runbooks e ações de automação. Como resultado, talvez seja necessário ajustar quais runbooks ou ações você deve usar para resolver seu caso de uso.
Por exemplo, as ações `aws:executeScript` e `aws:invokeLambdaFunction` permitem que você execute scripts personalizados como parte de sua automação. Para escolher entre eles, você pode preferir o `aws:invokeLambdaFunction` devido às linguagens do runtime adicionais suportadas. No entanto, você pode preferir o `aws:executeScript`, porque permite criar conteúdo de script diretamente em runbooks YAML e fornecer conteúdo de script como anexos para runbooks JSON. Você também pode considerar o `aws:executeScript` para ser mais simples em termos de configuração do AWS Identity and Access Management (IAM). Como ele usa as permissões fornecidas no `AutomationAssumeRole`, o `aws:executeScript` não requer uma função do AWS Lambda de execução da função.
Em qualquer cenário específico, uma ação pode fornecer mais flexibilidade, ou funcionalidade adicional, sobre outra. Portanto, recomendamos que você revise os parâmetros de entrada disponíveis para o runbook ou ação que quiser usar, para determinar qual melhor se adapta ao seu caso de uso e preferências.
## Configuração do ambiente de desenvolvimento
Depois de identificar seu caso de uso e os runbooks predefinidos ou ações de automação que deseja usar no runbook, é hora de configurar seu ambiente de desenvolvimento para o conteúdo do runbook. Para desenvolver o conteúdo do runbook, recomendamos usar o AWS Toolkit for Visual Studio Code em vez do console de documentos do Systems Manager.
O Toolkit for VS Code é uma extensão de código aberto para o Visual Studio Code (VS Code) que oferece mais recursos do que o console Systems Manager Documents. Os recursos úteis incluem validação de esquema para YAML e JSON, trechos para tipos de ação de automação e suporte de preenchimento automático para várias opções em YAML e JSON.
Para obter mais informações sobre como instalar o Toolkit for VS Code, consulte [Instalar o AWS Toolkit for Visual Studio Code](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/setup-toolkit.html). Para obter mais informações sobre como usar o Toolkit for VS Code para desenvolver runbooks, consulte [Trabalhar com documentos do Systems Manager Automation](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/systems-manager-automation-docs.html) no *Manual do usuário do AWS Toolkit for Visual Studio Code*.
## Desenvolva conteúdo do runbook
Com o caso de uso identificado e o ambiente configurado, você está pronto para desenvolver o conteúdo do runbook. Seu caso de uso e suas preferências ditarão em grande parte as ações de automação ou os runbooks que você usa no conteúdo do runbook. Algumas ações suportam apenas um subconjunto de parâmetros de entrada quando comparadas a outra ação que permite realizar uma tarefa semelhante. Outras ações têm resultados específicos, como `aws:createImage`, onde algumas ações permitem que você defina suas próprias saídas, como `aws:executeAwsApi`.
Se você não tiver certeza de como usar uma ação específica em seu runbook, recomendamos analisar a entrada correspondente para a ação na seção [Referência de ações do Systems Manager Automation](automation-actions.md). Recomendamos também examinar o conteúdo de runbooks predefinidos para ver exemplos reais de como essas ações são usadas. Para obter mais exemplos de aplicações reais de runbooks, consulte [Exemplos adicionais de runbook](automation-document-examples.md).
Para demonstrar as diferenças de simplicidade e flexibilidade que o conteúdo do runbook fornece, os tutoriais a seguir fornecem um exemplo de como aplicar patches a grupos de instâncias do Amazon EC2 em etapas:
+ [Exemplo 1: criação de runbooks pai-filho](automation-authoring-runbooks-parent-child-example.md): neste exemplo, dois runbooks são usados em um relacionamento pai-filho. O runbook pai inicia uma automação de controle de taxa do runbook filho.
+ [Exemplo 2: Runbook com script](automation-authoring-runbooks-scripted-example.md): este exemplo demonstra como você pode realizar as mesmas tarefas do Exemplo 1 condensando o conteúdo em um único runbook e usando scripts em seu runbook.
# Exemplo 1: criação de runbooks pai-filho
O exemplo a seguir demonstra como criar dois runbooks que corrigem grupos marcados de instâncias do Amazon Elastic Compute Cloud (Amazon EC2) em estágios. Esses runbooks são usados em um relacionamento pai-filho com o runbook pai usado para iniciar uma automação de controle de taxa do runbook filho. Para obter mais informações sobre automações de controle de taxas, consulte [Executar operações automatizadas em escala](running-automations-scale.md). Para obter mais informações sobre as ações de automação usadas neste exemplo, consulte a [Referência de ações do Systems Manager Automation](automation-actions.md).
## Crie o runbook filho
Este exemplo de runbook aborda o seguinte cenário. Emily é engenheira de sistemas na AnyCompany Consultants, LLC. Ela precisa configurar patches para grupos de instâncias do Amazon Elastic Compute Cloud (Amazon EC2) que hospedam bancos de dados primários e secundários. As aplicações acessam esses bancos de dados 24 horas por dia, portanto, uma das instâncias do banco de dados deve estar sempre disponível.
Ela decide que a aplicação de patches nas instâncias em etapas é a melhor abordagem. O grupo principal de instâncias de banco de dados receberão o patch primeiro, seguido pelo grupo secundário de instâncias de banco de dados. Além disso, para evitar custos adicionais, deixando instâncias em execução que foram interrompidas anteriormente, Emily quer que as instâncias corrigidas sejam retornadas ao seu estado original, antes da aplicação de patches.
Emily identifica os grupos primário e secundário de instâncias de banco de dados pelas tags associadas às instâncias. Ela decide criar um runbook pai que inicia uma automação de controle de taxa de um runbook filho. Ao fazer isso, ela pode direcionar as tags associadas aos grupos primário e secundário de instâncias do banco de dados e gerenciar a simultaneidade das automações filho. Depois de analisar os documentos do Systems Manager (SSM) disponíveis para aplicação de patches, ela escolhe o documento `AWS-RunPatchBaseline`. Usando este documento do SSM, seus colegas podem revisar as informações de conformidade de patch associadas após a conclusão da operação de patch.
Para começar a criar o conteúdo do runbook, Emily analisa as ações de automação disponíveis e começa a criar o conteúdo para o runbook filho da seguinte maneira:
1. Primeiro, ela fornece valores para o esquema e a descrição do runbook e define os parâmetros de entrada para o runbook filho.
Utilizando o parâmetro `AutomationAssumeRole`, Emily e seus colegas podem usar uma função do IAM existente que permite que o Automation realize ações no runbook em seu nome. Emily usa o parâmetro `InstanceId` para determinar a instância que deve ser corrigida. Opcionalmente, os parâmetros `Operation`, `RebootOption` e `SnapshotId` podem ser usados para fornecer valores para documentar os parâmetros para `AWS-RunPatchBaseline`. Para evitar que valores inválidos sejam fornecidos a esses parâmetros do documento, ela define a propriedade `allowedValues` conforme necessário.
------
#### [ YAML ]
```
schemaVersion: '0.3'
description: 'An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: >-
'(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the
actions on your behalf. If no role is specified, Systems Manager
Automation uses your IAM permissions to operate this runbook.'
default: ''
InstanceId:
type: String
description: >-
'(Required) The instance you want to patch.'
SnapshotId:
type: String
description: '(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.'
default: ''
RebootOption:
type: String
description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.'
allowedValues:
- NoReboot
- RebootIfNeeded
default: RebootIfNeeded
Operation:
type: String
description: '(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.'
allowedValues:
- Install
- Scan
default: Install
```
------
#### [ JSON ]
```
{
"schemaVersion":"0.3",
"description":"An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.",
"assumeRole":"{{AutomationAssumeRole}}",
"parameters":{
"AutomationAssumeRole":{
"type":"String",
"description":"(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.",
"default":""
},
"InstanceId":{
"type":"String",
"description":"(Required) The instance you want to patch."
},
"SnapshotId":{
"type":"String",
"description":"(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.",
"default":""
},
"RebootOption":{
"type":"String",
"description":"(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.",
"allowedValues":[
"NoReboot",
"RebootIfNeeded"
],
"default":"RebootIfNeeded"
},
"Operation":{
"type":"String",
"description":"(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.",
"allowedValues":[
"Install",
"Scan"
],
"default":"Install"
}
}
},
```
------
1. Com os elementos de nível superior definidos, Emily prossegue com a criação das ações que compõem as `mainSteps` do runbook. A primeira etapa gera o estado atual da instância de destino especificada no parâmetro de entrada `InstanceId` usando a ação `aws:executeAwsApi`. A saída desta ação é usada em ações posteriores.
------
#### [ YAML ]
```
mainSteps:
- name: getInstanceState
action: 'aws:executeAwsApi'
onFailure: Abort
inputs:
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- '{{InstanceId}}'
outputs:
- Name: instanceState
Selector: '$.Reservations[0].Instances[0].State.Name'
Type: String
nextStep: branchOnInstanceState
```
------
#### [ JSON ]
```
"mainSteps":[
{
"name":"getInstanceState",
"action":"aws:executeAwsApi",
"onFailure":"Abort",
"inputs":{
"inputs":null,
"Service":"ec2",
"Api":"DescribeInstances",
"InstanceIds":[
"{{InstanceId}}"
]
},
"outputs":[
{
"Name":"instanceState",
"Selector":"$.Reservations[0].Instances[0].State.Name",
"Type":"String"
}
],
"nextStep":"branchOnInstanceState"
},
```
------
1. Em vez de iniciar manualmente e manter o controle do estado original de cada instância que precisa ser corrigida, Emily usa a saída da ação anterior para ramificar a automação com base no estado da instância de destino. Isso permite que a automação execute etapas diferentes dependendo das condições definidas na ação `aws:branch` e melhora a eficiência geral da automação sem intervenção manual.
Se o estado da instância já for `running`, a automação prossegue com o patch da instância com o documento `AWS-RunPatchBaseline` usando a ação `aws:runCommand`.
Se o estado da instância for `stopping`, as pesquisas de automação sondam para a instância alcançar o estado `stopped`, usando a `aws:waitForAwsResourceProperty`, inicia a instância usando a ação `executeAwsApi`, e sonda a instância para alcançar um estado `running` antes de aplicar os patches nela.
Se o estado da instância for `stopped`, as pesquisas de automação iniciam a instância e a sonda para alcançar o estado `running`, antes de aplicar os patches na instância, usando as mesmas ações.
------
#### [ YAML ]
```
- name: branchOnInstanceState
action: 'aws:branch'
onFailure: Abort
inputs:
Choices:
- NextStep: startInstance
Variable: '{{getInstanceState.instanceState}}'
StringEquals: stopped
- NextStep: verifyInstanceStopped
Variable: '{{getInstanceState.instanceState}}'
StringEquals: stopping
- NextStep: patchInstance
Variable: '{{getInstanceState.instanceState}}'
StringEquals: running
isEnd: true
- name: startInstance
action: 'aws:executeAwsApi'
onFailure: Abort
inputs:
Service: ec2
Api: StartInstances
InstanceIds:
- '{{InstanceId}}'
nextStep: verifyInstanceRunning
- name: verifyInstanceRunning
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 120
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- '{{InstanceId}}'
PropertySelector: '$.Reservations[0].Instances[0].State.Name'
DesiredValues:
- running
nextStep: patchInstance
- name: verifyInstanceStopped
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 120
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- '{{InstanceId}}'
PropertySelector: '$.Reservations[0].Instances[0].State.Name'
DesiredValues:
- stopped
nextStep: startInstance
- name: patchInstance
action: 'aws:runCommand'
onFailure: Abort
timeoutSeconds: 5400
inputs:
DocumentName: 'AWS-RunPatchBaseline'
InstanceIds:
- '{{InstanceId}}'
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
```
------
#### [ JSON ]
```
{
"name":"branchOnInstanceState",
"action":"aws:branch",
"onFailure":"Abort",
"inputs":{
"Choices":[
{
"NextStep":"startInstance",
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"stopped"
},
{
"Or":[
{
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"stopping"
}
],
"NextStep":"verifyInstanceStopped"
},
{
"NextStep":"patchInstance",
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"running"
}
]
},
"isEnd":true
},
{
"name":"startInstance",
"action":"aws:executeAwsApi",
"onFailure":"Abort",
"inputs":{
"Service":"ec2",
"Api":"StartInstances",
"InstanceIds":[
"{{InstanceId}}"
]
},
"nextStep":"verifyInstanceRunning"
},
{
"name":"verifyInstanceRunning",
"action":"aws:waitForAwsResourceProperty",
"timeoutSeconds":120,
"inputs":{
"Service":"ec2",
"Api":"DescribeInstances",
"InstanceIds":[
"{{InstanceId}}"
],
"PropertySelector":"$.Reservations[0].Instances[0].State.Name",
"DesiredValues":[
"running"
]
},
"nextStep":"patchInstance"
},
{
"name":"verifyInstanceStopped",
"action":"aws:waitForAwsResourceProperty",
"timeoutSeconds":120,
"inputs":{
"Service":"ec2",
"Api":"DescribeInstances",
"InstanceIds":[
"{{InstanceId}}"
],
"PropertySelector":"$.Reservations[0].Instances[0].State.Name",
"DesiredValues":[
"stopped"
],
"nextStep":"startInstance"
}
},
{
"name":"patchInstance",
"action":"aws:runCommand",
"onFailure":"Abort",
"timeoutSeconds":5400,
"inputs":{
"DocumentName":"AWS-RunPatchBaseline",
"InstanceIds":[
"{{InstanceId}}"
],
"Parameters":{
"SnapshotId":"{{SnapshotId}}",
"RebootOption":"{{RebootOption}}",
"Operation":"{{Operation}}"
}
}
},
```
------
1. Após a conclusão da operação de patch, Emily deseja que a automação retorne a instância de destino ao mesmo estado em que estava antes da automação ser iniciada. Ela faz isso usando novamente a saída da primeira ação. As ramificações de automação com base no estado original da instância de destino usando a ação `aws:branch`. Se a instância estava anteriormente em outro estado diferente de `running`, ela será interrompida. Caso contrário, se o estado da instância for `running`, a automação é encerrada.
------
#### [ YAML ]
```
- name: branchOnOriginalInstanceState
action: 'aws:branch'
onFailure: Abort
inputs:
Choices:
- NextStep: stopInstance
Not:
Variable: '{{getInstanceState.instanceState}}'
StringEquals: running
isEnd: true
- name: stopInstance
action: 'aws:executeAwsApi'
onFailure: Abort
inputs:
Service: ec2
Api: StopInstances
InstanceIds:
- '{{InstanceId}}'
```
------
#### [ JSON ]
```
{
"name":"branchOnOriginalInstanceState",
"action":"aws:branch",
"onFailure":"Abort",
"inputs":{
"Choices":[
{
"NextStep":"stopInstance",
"Not":{
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"running"
}
}
]
},
"isEnd":true
},
{
"name":"stopInstance",
"action":"aws:executeAwsApi",
"onFailure":"Abort",
"inputs":{
"Service":"ec2",
"Api":"StopInstances",
"InstanceIds":[
"{{InstanceId}}"
]
}
}
]
}
```
------
1. Emily analisa o conteúdo do runbook filho concluído e cria o runbook na mesma Conta da AWS e Região da AWS das instâncias de destino. Agora ela está pronta para continuar com a criação do conteúdo do runbook pai. Abaixo está o conteúdo do runbook filho concluído.
------
#### [ YAML ]
```
schemaVersion: '0.3'
description: 'An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: >-
'(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the
actions on your behalf. If no role is specified, Systems Manager
Automation uses your IAM permissions to operate this runbook.'
default: ''
InstanceId:
type: String
description: >-
'(Required) The instance you want to patch.'
SnapshotId:
type: String
description: '(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.'
default: ''
RebootOption:
type: String
description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.'
allowedValues:
- NoReboot
- RebootIfNeeded
default: RebootIfNeeded
Operation:
type: String
description: '(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.'
allowedValues:
- Install
- Scan
default: Install
mainSteps:
- name: getInstanceState
action: 'aws:executeAwsApi'
onFailure: Abort
inputs:
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- '{{InstanceId}}'
outputs:
- Name: instanceState
Selector: '$.Reservations[0].Instances[0].State.Name'
Type: String
nextStep: branchOnInstanceState
- name: branchOnInstanceState
action: 'aws:branch'
onFailure: Abort
inputs:
Choices:
- NextStep: startInstance
Variable: '{{getInstanceState.instanceState}}'
StringEquals: stopped
- Or:
- Variable: '{{getInstanceState.instanceState}}'
StringEquals: stopping
NextStep: verifyInstanceStopped
- NextStep: patchInstance
Variable: '{{getInstanceState.instanceState}}'
StringEquals: running
isEnd: true
- name: startInstance
action: 'aws:executeAwsApi'
onFailure: Abort
inputs:
Service: ec2
Api: StartInstances
InstanceIds:
- '{{InstanceId}}'
nextStep: verifyInstanceRunning
- name: verifyInstanceRunning
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 120
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- '{{InstanceId}}'
PropertySelector: '$.Reservations[0].Instances[0].State.Name'
DesiredValues:
- running
nextStep: patchInstance
- name: verifyInstanceStopped
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 120
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- '{{InstanceId}}'
PropertySelector: '$.Reservations[0].Instances[0].State.Name'
DesiredValues:
- stopped
nextStep: startInstance
- name: patchInstance
action: 'aws:runCommand'
onFailure: Abort
timeoutSeconds: 5400
inputs:
DocumentName: 'AWS-RunPatchBaseline'
InstanceIds:
- '{{InstanceId}}'
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
- name: branchOnOriginalInstanceState
action: 'aws:branch'
onFailure: Abort
inputs:
Choices:
- NextStep: stopInstance
Not:
Variable: '{{getInstanceState.instanceState}}'
StringEquals: running
isEnd: true
- name: stopInstance
action: 'aws:executeAwsApi'
onFailure: Abort
inputs:
Service: ec2
Api: StopInstances
InstanceIds:
- '{{InstanceId}}'
```
------
#### [ JSON ]
```
{
"schemaVersion":"0.3",
"description":"An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.",
"assumeRole":"{{AutomationAssumeRole}}",
"parameters":{
"AutomationAssumeRole":{
"type":"String",
"description":"'(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.'",
"default":""
},
"InstanceId":{
"type":"String",
"description":"'(Required) The instance you want to patch.'"
},
"SnapshotId":{
"type":"String",
"description":"(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.",
"default":""
},
"RebootOption":{
"type":"String",
"description":"(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.",
"allowedValues":[
"NoReboot",
"RebootIfNeeded"
],
"default":"RebootIfNeeded"
},
"Operation":{
"type":"String",
"description":"(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.",
"allowedValues":[
"Install",
"Scan"
],
"default":"Install"
}
},
"mainSteps":[
{
"name":"getInstanceState",
"action":"aws:executeAwsApi",
"onFailure":"Abort",
"inputs":{
"inputs":null,
"Service":"ec2",
"Api":"DescribeInstances",
"InstanceIds":[
"{{InstanceId}}"
]
},
"outputs":[
{
"Name":"instanceState",
"Selector":"$.Reservations[0].Instances[0].State.Name",
"Type":"String"
}
],
"nextStep":"branchOnInstanceState"
},
{
"name":"branchOnInstanceState",
"action":"aws:branch",
"onFailure":"Abort",
"inputs":{
"Choices":[
{
"NextStep":"startInstance",
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"stopped"
},
{
"Or":[
{
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"stopping"
}
],
"NextStep":"verifyInstanceStopped"
},
{
"NextStep":"patchInstance",
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"running"
}
]
},
"isEnd":true
},
{
"name":"startInstance",
"action":"aws:executeAwsApi",
"onFailure":"Abort",
"inputs":{
"Service":"ec2",
"Api":"StartInstances",
"InstanceIds":[
"{{InstanceId}}"
]
},
"nextStep":"verifyInstanceRunning"
},
{
"name":"verifyInstanceRunning",
"action":"aws:waitForAwsResourceProperty",
"timeoutSeconds":120,
"inputs":{
"Service":"ec2",
"Api":"DescribeInstances",
"InstanceIds":[
"{{InstanceId}}"
],
"PropertySelector":"$.Reservations[0].Instances[0].State.Name",
"DesiredValues":[
"running"
]
},
"nextStep":"patchInstance"
},
{
"name":"verifyInstanceStopped",
"action":"aws:waitForAwsResourceProperty",
"timeoutSeconds":120,
"inputs":{
"Service":"ec2",
"Api":"DescribeInstances",
"InstanceIds":[
"{{InstanceId}}"
],
"PropertySelector":"$.Reservations[0].Instances[0].State.Name",
"DesiredValues":[
"stopped"
],
"nextStep":"startInstance"
}
},
{
"name":"patchInstance",
"action":"aws:runCommand",
"onFailure":"Abort",
"timeoutSeconds":5400,
"inputs":{
"DocumentName":"AWS-RunPatchBaseline",
"InstanceIds":[
"{{InstanceId}}"
],
"Parameters":{
"SnapshotId":"{{SnapshotId}}",
"RebootOption":"{{RebootOption}}",
"Operation":"{{Operation}}"
}
}
},
{
"name":"branchOnOriginalInstanceState",
"action":"aws:branch",
"onFailure":"Abort",
"inputs":{
"Choices":[
{
"NextStep":"stopInstance",
"Not":{
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"running"
}
}
]
},
"isEnd":true
},
{
"name":"stopInstance",
"action":"aws:executeAwsApi",
"onFailure":"Abort",
"inputs":{
"Service":"ec2",
"Api":"StopInstances",
"InstanceIds":[
"{{InstanceId}}"
]
}
}
]
}
```
------
Para obter mais informações sobre as ações de automação usadas neste exemplo, consulte a [Referência de ações do Systems Manager Automation](automation-actions.md).
## Crie o runbook pai
Esse exemplo de runbook continua o cenário descrito na seção anterior. Agora que Emily criou o runbook filho, ela começa a criar o conteúdo para o runbook pai da seguinte maneira:
1. Primeiro, ela fornece valores para o esquema e a descrição do runbook e define os parâmetros de entrada para o runbook pai.
Utilizando o parâmetro `AutomationAssumeRole`, Emily e seus colegas podem usar uma função do IAM existente que permite que o Automation realize ações no runbook em seu nome. Emily usa os parâmetros `PatchGroupPrimaryKey` e `PatchGroupPrimaryValue` para especificar a tag associada ao grupo primário de instâncias de banco de dados que será corrigido. Ela usa os parâmetros `PatchGroupSecondaryKey` e `PatchGroupSecondaryValue` para especificar as tags associadas ao grupo secundário de instâncias de banco de dados nos quais os patches serão aplicados.
------
#### [ YAML ]
```
description: 'An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.'
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: '(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.'
default: ''
PatchGroupPrimaryKey:
type: String
description: '(Required) The key of the tag for the primary group of instances you want to patch.''
PatchGroupPrimaryValue:
type: String
description: '(Required) The value of the tag for the primary group of instances you want to patch.'
PatchGroupSecondaryKey:
type: String
description: '(Required) The key of the tag for the secondary group of instances you want to patch.'
PatchGroupSecondaryValue:
type: String
description: '(Required) The value of the tag for the secondary group of instances you want to patch.'
```
------
#### [ JSON ]
```
{
"schemaVersion": "0.3",
"description": "An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.",
"assumeRole": "{{AutomationAssumeRole}}",
"parameters": {
"AutomationAssumeRole": {
"type": "String",
"description": "(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.",
"default": ""
},
"PatchGroupPrimaryKey": {
"type": "String",
"description": "(Required) The key of the tag for the primary group of instances you want to patch."
},
"PatchGroupPrimaryValue": {
"type": "String",
"description": "(Required) The value of the tag for the primary group of instances you want to patch."
},
"PatchGroupSecondaryKey": {
"type": "String",
"description": "(Required) The key of the tag for the secondary group of instances you want to patch."
},
"PatchGroupSecondaryValue": {
"type": "String",
"description": "(Required) The value of the tag for the secondary group of instances you want to patch."
}
}
},
```
------
1. Com os elementos de nível superior definidos, Emily prossegue com a criação das ações que compõem as `mainSteps` do runbook.
A primeira ação inicia uma automação de controle de taxa usando o runbook filho recém-criado, direcionado a instâncias associadas à tag especificada no `PatchGroupPrimaryKey` e nos parâmetros de entrada `PatchGroupPrimaryValue`. Ela usa os valores fornecidos aos parâmetros de entrada para especificar a chave e o valor da tag associada ao grupo primário de instâncias de banco de dados nos quais deseja aplicar o patch.
Depois que a primeira automação for concluída, a segunda ação inicia outra automação de controle de taxa usando o runbook filho direcionado a instâncias associadas à tag especificada no `PatchGroupSecondaryKey` e no parâmetros de entrada do `PatchGroupSecondaryValue`. Ela usa os valores fornecidos aos parâmetros de entrada para especificar a chave e o valor da tag associada ao grupo secundário de instâncias de banco de dados nos quais deseja aplicar o patch.
------
#### [ YAML ]
```
mainSteps:
- name: patchPrimaryTargets
action: 'aws:executeAutomation'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: RunbookTutorialChildAutomation
Targets:
- Key: 'tag:{{PatchGroupPrimaryKey}}'
Values:
- '{{PatchGroupPrimaryValue}}'
TargetParameterName: 'InstanceId'
- name: patchSecondaryTargets
action: 'aws:executeAutomation'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: RunbookTutorialChildAutomation
Targets:
- Key: 'tag:{{PatchGroupSecondaryKey}}'
Values:
- '{{PatchGroupSecondaryValue}}'
TargetParameterName: 'InstanceId'
```
------
#### [ JSON ]
```
"mainSteps":[
{
"name":"patchPrimaryTargets",
"action":"aws:executeAutomation",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"RunbookTutorialChildAutomation",
"Targets":[
{
"Key":"tag:{{PatchGroupPrimaryKey}}",
"Values":[
"{{PatchGroupPrimaryValue}}"
]
}
],
"TargetParameterName":"InstanceId"
}
},
{
"name":"patchSecondaryTargets",
"action":"aws:executeAutomation",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"RunbookTutorialChildAutomation",
"Targets":[
{
"Key":"tag:{{PatchGroupSecondaryKey}}",
"Values":[
"{{PatchGroupSecondaryValue}}"
]
}
],
"TargetParameterName":"InstanceId"
}
}
]
}
```
------
1. Emily analisa o conteúdo do runbook pai concluído e cria o runbook na mesma Conta da AWS e Região da AWS das instâncias de destino. Agora ela está pronta para testar seus runbooks para garantir que a automação funcione conforme desejado antes de implementá-la em seu ambiente de produção. Abaixo está o conteúdo do runbook pai concluído.
------
#### [ YAML ]
```
description: An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: '(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.'
default: ''
PatchGroupPrimaryKey:
type: String
description: (Required) The key of the tag for the primary group of instances you want to patch.
PatchGroupPrimaryValue:
type: String
description: '(Required) The value of the tag for the primary group of instances you want to patch. '
PatchGroupSecondaryKey:
type: String
description: (Required) The key of the tag for the secondary group of instances you want to patch.
PatchGroupSecondaryValue:
type: String
description: '(Required) The value of the tag for the secondary group of instances you want to patch. '
mainSteps:
- name: patchPrimaryTargets
action: 'aws:executeAutomation'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: RunbookTutorialChildAutomation
Targets:
- Key: 'tag:{{PatchGroupPrimaryKey}}'
Values:
- '{{PatchGroupPrimaryValue}}'
TargetParameterName: 'InstanceId'
- name: patchSecondaryTargets
action: 'aws:executeAutomation'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: RunbookTutorialChildAutomation
Targets:
- Key: 'tag:{{PatchGroupSecondaryKey}}'
Values:
- '{{PatchGroupSecondaryValue}}'
TargetParameterName: 'InstanceId'
```
------
#### [ JSON ]
```
{
"description":"An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.",
"schemaVersion":"0.3",
"assumeRole":"{{AutomationAssumeRole}}",
"parameters":{
"AutomationAssumeRole":{
"type":"String",
"description":"(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.",
"default":""
},
"PatchGroupPrimaryKey":{
"type":"String",
"description":"(Required) The key of the tag for the primary group of instances you want to patch."
},
"PatchGroupPrimaryValue":{
"type":"String",
"description":"(Required) The value of the tag for the primary group of instances you want to patch. "
},
"PatchGroupSecondaryKey":{
"type":"String",
"description":"(Required) The key of the tag for the secondary group of instances you want to patch."
},
"PatchGroupSecondaryValue":{
"type":"String",
"description":"(Required) The value of the tag for the secondary group of instances you want to patch. "
}
},
"mainSteps":[
{
"name":"patchPrimaryTargets",
"action":"aws:executeAutomation",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"RunbookTutorialChildAutomation",
"Targets":[
{
"Key":"tag:{{PatchGroupPrimaryKey}}",
"Values":[
"{{PatchGroupPrimaryValue}}"
]
}
],
"TargetParameterName":"InstanceId"
}
},
{
"name":"patchSecondaryTargets",
"action":"aws:executeAutomation",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"RunbookTutorialChildAutomation",
"Targets":[
{
"Key":"tag:{{PatchGroupSecondaryKey}}",
"Values":[
"{{PatchGroupSecondaryValue}}"
]
}
],
"TargetParameterName":"InstanceId"
}
}
]
}
```
------
Para obter mais informações sobre as ações de automação usadas neste exemplo, consulte a [Referência de ações do Systems Manager Automation](automation-actions.md).
# Exemplo 2: Runbook com script
Este exemplo de runbook aborda o seguinte cenário. Emily é engenheira de sistemas na AnyCompany Consultants, LLC. Ela criou anteriormente dois runbooks que são usados em um relacionamento pai-filho para grupos de patches de instâncias do Amazon Elastic Compute Cloud (Amazon EC2) que hospedam bancos de dados primários e secundários. As aplicações acessam esses bancos de dados 24 horas por dia, portanto, uma das instâncias do banco de dados deve estar sempre disponível.
Com base nesse requisito, ela criou uma solução que corrige as instâncias em etapas usando o documento do Systems Manager (SSM) `AWS-RunPatchBaseline`. Usando este documento do SSM, seus colegas podem revisar as informações de conformidade de patch associadas após a conclusão da operação de patch.
O grupo principal de instâncias de banco de dados recebem o patch primeiro, seguido pelo grupo secundário de instâncias de banco de dados. Além disso, para evitar custos adicionais, deixando instâncias em execução que foram interrompidas anteriormente, Emily garantiu que a automação retornasse as instâncias corrigidas ao seu estado original antes da aplicação de patches ocorrer. Emily usou tags associadas aos grupos primário e secundário de instâncias de banco de dados para identificar quais instâncias devem ser corrigidas na ordem desejada.
A solução automatizada existente funciona, mas ela quer melhorar a solução, se possível. Para ajudar na manutenção do conteúdo do runbook e facilitar a solução de problemas, ela gostaria de condensar a automação em um único runbook e simplificar o número de parâmetros de entrada. Além disso, ela gostaria de evitar a criação de várias automações filho.
Depois que Emily revisar as ações de automação disponíveis, ela determinará que pode melhorar sua solução usando o `aws:executeScript` para executar seus scripts Python personalizados. Ela agora começa a criar o conteúdo para o runbook da seguinte forma:
1. Primeiro, ela fornece valores para o esquema e a descrição do runbook e define os parâmetros de entrada para o runbook pai.
Utilizando o parâmetro `AutomationAssumeRole`, Emily e seus colegas podem usar uma função do IAM existente que permite que o Automation realize ações no runbook em seu nome. Ao contrário do [Exemplo 1](automation-authoring-runbooks-parent-child-example.md), o parâmetro `AutomationAssumeRole` agora é necessário e não opcional. Como este runbook inclui ações `aws:executeScript`, uma função de serviço (IAM) AWS Identity and Access Management (ou função assumida) será sempre necessária. Este requisito é necessário porque alguns dos scripts Python especificados para as ações chamam as operações de API da AWS.
Emily usa os parâmetros `PrimaryPatchGroupTag` e `SecondaryPatchGroupTag` para especificar as tags associadas ao grupo secundário de instâncias de banco de dados que será corrigido. Para simplificar os parâmetros de entrada necessários, ela decide usar os parâmetros `StringMap` em vez de usar vários parâmetros `String` como ela usou no runbook de Exemplo 1. Opcionalmente, os parâmetros `Operation`, `RebootOption` e `SnapshotId` podem ser usados para fornecer valores para documentar os parâmetros para `AWS-RunPatchBaseline`. Para evitar que valores inválidos sejam fornecidos a esses parâmetros do documento, ela define a propriedade `allowedValues` conforme necessário.
------
#### [ YAML ]
```
description: 'An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.'
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: '(Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.'
PrimaryPatchGroupTag:
type: StringMap
description: '(Required) The tag for the primary group of instances you want to patch. Specify a key-value pair. Example: {"key" : "value"}'
SecondaryPatchGroupTag:
type: StringMap
description: '(Required) The tag for the secondary group of instances you want to patch. Specify a key-value pair. Example: {"key" : "value"}'
SnapshotId:
type: String
description: '(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.'
default: ''
RebootOption:
type: String
description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.'
allowedValues:
- NoReboot
- RebootIfNeeded
default: RebootIfNeeded
Operation:
type: String
description: '(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.'
allowedValues:
- Install
- Scan
default: Install
```
------
#### [ JSON ]
```
{
"description":"An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.",
"schemaVersion":"0.3",
"assumeRole":"{{AutomationAssumeRole}}",
"parameters":{
"AutomationAssumeRole":{
"type":"String",
"description":"(Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook."
},
"PrimaryPatchGroupTag":{
"type":"StringMap",
"description":"(Required) The tag for the primary group of instances you want to patch. Specify a key-value pair. Example: {\"key\" : \"value\"}"
},
"SecondaryPatchGroupTag":{
"type":"StringMap",
"description":"(Required) The tag for the secondary group of instances you want to patch. Specify a key-value pair. Example: {\"key\" : \"value\"}"
},
"SnapshotId":{
"type":"String",
"description":"(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.",
"default":""
},
"RebootOption":{
"type":"String",
"description":"(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.",
"allowedValues":[
"NoReboot",
"RebootIfNeeded"
],
"default":"RebootIfNeeded"
},
"Operation":{
"type":"String",
"description":"(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.",
"allowedValues":[
"Install",
"Scan"
],
"default":"Install"
}
}
},
```
------
1. Com os elementos de nível superior definidos, Emily prossegue com a criação das ações que compõem as `mainSteps` do runbook. A primeira etapa reúne os IDs de todas as instâncias associadas à tag especificada no parâmetro `PrimaryPatchGroupTag` e resulta em um parâmetro `StringMap` que contém o ID de instância e o estado atual da instância. A saída desta ação é usada em ações posteriores.
Observe que o parâmetro de entrada do `script` é compatível com runbooks JSON. Os runbooks JSON devem fornecer conteúdo de script usando o parâmetro de entrada do `attachment`.
------
#### [ YAML ]
```
mainSteps:
- name: getPrimaryInstanceState
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: getInstanceStates
InputPayload:
primaryTag: '{{PrimaryPatchGroupTag}}'
Script: |-
def getInstanceStates(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
tag = events['primaryTag']
tagKey, tagValue = list(tag.items())[0]
instanceQuery = ec2.describe_instances(
Filters=[
{
"Name": "tag:" + tagKey,
"Values": [tagValue]
}]
)
if not instanceQuery['Reservations']:
noInstancesForTagString = "No instances found for specified tag."
return({ 'noInstancesFound' : noInstancesForTagString })
else:
queryResponse = instanceQuery['Reservations']
originalInstanceStates = {}
for results in queryResponse:
instanceSet = results['Instances']
for instance in instanceSet:
instanceId = instance['InstanceId']
originalInstanceStates[instanceId] = instance['State']['Name']
return originalInstanceStates
outputs:
- Name: originalInstanceStates
Selector: $.Payload
Type: StringMap
nextStep: verifyPrimaryInstancesRunning
```
------
#### [ JSON ]
```
"mainSteps":[
{
"name":"getPrimaryInstanceState",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"getInstanceStates",
"InputPayload":{
"primaryTag":"{{PrimaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"originalInstanceStates",
"Selector":"$.Payload",
"Type":"StringMap"
}
],
"nextStep":"verifyPrimaryInstancesRunning"
},
```
------
1. Emily usa o resultado da ação anterior em outra ação do `aws:executeScript` para verificar se todas as ocorrências associadas à tag especificada no parâmetro `PrimaryPatchGroupTag` estão em um estado `running`.
Se o estado da instância já for `running` ou `shutting-down`, o script continua a percorrer as instâncias restantes.
Se o estado da instância for `stopping`, o script sonda para que a instância atinja o estado `stopped` e inicie a instância.
Se o estado da instância for `stopped`, o script inicia a instância.
------
#### [ YAML ]
```
- name: verifyPrimaryInstancesRunning
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: verifyInstancesRunning
InputPayload:
targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}'
Script: |-
def verifyInstancesRunning(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped':
print("The target instance " + instance + " is stopped. The instance will now be started.")
ec2.start_instances(
InstanceIds=[instance]
)
elif instanceDict[instance] == 'stopping':
print("The target instance " + instance + " is stopping. Polling for instance to reach stopped state.")
while instanceDict[instance] != 'stopped':
poll = ec2.get_waiter('instance_stopped')
poll.wait(
InstanceIds=[instance]
)
ec2.start_instances(
InstanceIds=[instance]
)
else:
pass
nextStep: waitForPrimaryRunningInstances
```
------
#### [ JSON ]
```
{
"name":"verifyPrimaryInstancesRunning",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"verifyInstancesRunning",
"InputPayload":{
"targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"waitForPrimaryRunningInstances"
},
```
------
1. Emily verifica se todas as instâncias associadas com a tag especificada no parâmetro `PrimaryPatchGroupTag` foram iniciadas ou já estão em um estado `running`. Ele então usa outro script para verificar se todas as instâncias, incluindo aquelas que foram iniciadas na ação anterior, atingiram o estado `running`.
------
#### [ YAML ]
```
- name: waitForPrimaryRunningInstances
action: 'aws:executeScript'
timeoutSeconds: 300
onFailure: Abort
inputs:
Runtime: python3.11
Handler: waitForRunningInstances
InputPayload:
targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}'
Script: |-
def waitForRunningInstances(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
poll = ec2.get_waiter('instance_running')
poll.wait(
InstanceIds=[instance]
)
nextStep: returnPrimaryTagKey
```
------
#### [ JSON ]
```
{
"name":"waitForPrimaryRunningInstances",
"action":"aws:executeScript",
"timeoutSeconds":300,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"waitForRunningInstances",
"InputPayload":{
"targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"returnPrimaryTagKey"
},
```
------
1. Emily usa mais dois scripts para retornar valores `String` individuais da chave e valor da tag especificada no parâmetro `PrimaryPatchGroupTag`. Os valores retornados por essas ações permitem que ela forneça valores diretamente ao parâmetro `Targets` do documento `AWS-RunPatchBaseline`. A automação prossegue então com a aplicação do patch na instância com o documento `AWS-RunPatchBaseline` usando a ação `aws:runCommand`.
------
#### [ YAML ]
```
- name: returnPrimaryTagKey
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
primaryTag: '{{PrimaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['primaryTag']
tagKey = list(tag)[0]
stringKey = "tag:" + tagKey
return {'tagKey' : stringKey}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: primaryPatchGroupKey
Selector: $.Payload.tagKey
Type: String
nextStep: returnPrimaryTagValue
- name: returnPrimaryTagValue
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
primaryTag: '{{PrimaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['primaryTag']
tagKey = list(tag)[0]
tagValue = tag[tagKey]
return {'tagValue' : tagValue}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: primaryPatchGroupValue
Selector: $.Payload.tagValue
Type: String
nextStep: patchPrimaryInstances
- name: patchPrimaryInstances
action: 'aws:runCommand'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: AWS-RunPatchBaseline
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
Targets:
- Key: '{{returnPrimaryTagKey.primaryPatchGroupKey}}'
Values:
- '{{returnPrimaryTagValue.primaryPatchGroupValue}}'
MaxConcurrency: 10%
MaxErrors: 10%
nextStep: returnPrimaryToOriginalState
```
------
#### [ JSON ]
```
{
"name":"returnPrimaryTagKey",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"primaryTag":"{{PrimaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"primaryPatchGroupKey",
"Selector":"$.Payload.tagKey",
"Type":"String"
}
],
"nextStep":"returnPrimaryTagValue"
},
{
"name":"returnPrimaryTagValue",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"primaryTag":"{{PrimaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"primaryPatchGroupValue",
"Selector":"$.Payload.tagValue",
"Type":"String"
}
],
"nextStep":"patchPrimaryInstances"
},
{
"name":"patchPrimaryInstances",
"action":"aws:runCommand",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"AWS-RunPatchBaseline",
"Parameters":{
"SnapshotId":"{{SnapshotId}}",
"RebootOption":"{{RebootOption}}",
"Operation":"{{Operation}}"
},
"Targets":[
{
"Key":"{{returnPrimaryTagKey.primaryPatchGroupKey}}",
"Values":[
"{{returnPrimaryTagValue.primaryPatchGroupValue}}"
]
}
],
"MaxConcurrency":"10%",
"MaxErrors":"10%"
},
"nextStep":"returnPrimaryToOriginalState"
},
```
------
1. Após a conclusão da operação de patch, Emily deseja que a automação retorne as instâncias de destino associadas à tag especificada no parâmetro `PrimaryPatchGroupTag` para o mesmo estado em que estavam antes da automação ser iniciada. Ela faz isso usando novamente a saída da primeira ação em um script. Com base no estado original da instância de destino, se a instância estava anteriormente em qualquer estado diferente de `running`, ela é interrompida. Caso contrário, se o estado da instância for `running` o script continuará a percorrer as instâncias restantes.
------
#### [ YAML ]
```
- name: returnPrimaryToOriginalState
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnToOriginalState
InputPayload:
targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}'
Script: |-
def returnToOriginalState(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped' or instanceDict[instance] == 'stopping':
ec2.stop_instances(
InstanceIds=[instance]
)
else:
pass
nextStep: getSecondaryInstanceState
```
------
#### [ JSON ]
```
{
"name":"returnPrimaryToOriginalState",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnToOriginalState",
"InputPayload":{
"targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"getSecondaryInstanceState"
},
```
------
1. A operação de patch é concluída para as instâncias associadas à tag especificada no parâmetro `PrimaryPatchGroupTag`. Agora, Emily duplica todas as ações anteriores em seu conteúdo do runbook para direcionar as instâncias associadas à tag especificada no parâmetro `SecondaryPatchGroupTag`.
------
#### [ YAML ]
```
- name: getSecondaryInstanceState
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: getInstanceStates
InputPayload:
secondaryTag: '{{SecondaryPatchGroupTag}}'
Script: |-
def getInstanceStates(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
tag = events['secondaryTag']
tagKey, tagValue = list(tag.items())[0]
instanceQuery = ec2.describe_instances(
Filters=[
{
"Name": "tag:" + tagKey,
"Values": [tagValue]
}]
)
if not instanceQuery['Reservations']:
noInstancesForTagString = "No instances found for specified tag."
return({ 'noInstancesFound' : noInstancesForTagString })
else:
queryResponse = instanceQuery['Reservations']
originalInstanceStates = {}
for results in queryResponse:
instanceSet = results['Instances']
for instance in instanceSet:
instanceId = instance['InstanceId']
originalInstanceStates[instanceId] = instance['State']['Name']
return originalInstanceStates
outputs:
- Name: originalInstanceStates
Selector: $.Payload
Type: StringMap
nextStep: verifySecondaryInstancesRunning
- name: verifySecondaryInstancesRunning
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: verifyInstancesRunning
InputPayload:
targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}'
Script: |-
def verifyInstancesRunning(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped':
print("The target instance " + instance + " is stopped. The instance will now be started.")
ec2.start_instances(
InstanceIds=[instance]
)
elif instanceDict[instance] == 'stopping':
print("The target instance " + instance + " is stopping. Polling for instance to reach stopped state.")
while instanceDict[instance] != 'stopped':
poll = ec2.get_waiter('instance_stopped')
poll.wait(
InstanceIds=[instance]
)
ec2.start_instances(
InstanceIds=[instance]
)
else:
pass
nextStep: waitForSecondaryRunningInstances
- name: waitForSecondaryRunningInstances
action: 'aws:executeScript'
timeoutSeconds: 300
onFailure: Abort
inputs:
Runtime: python3.11
Handler: waitForRunningInstances
InputPayload:
targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}'
Script: |-
def waitForRunningInstances(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
poll = ec2.get_waiter('instance_running')
poll.wait(
InstanceIds=[instance]
)
nextStep: returnSecondaryTagKey
- name: returnSecondaryTagKey
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
secondaryTag: '{{SecondaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['secondaryTag']
tagKey = list(tag)[0]
stringKey = "tag:" + tagKey
return {'tagKey' : stringKey}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: secondaryPatchGroupKey
Selector: $.Payload.tagKey
Type: String
nextStep: returnSecondaryTagValue
- name: returnSecondaryTagValue
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
secondaryTag: '{{SecondaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['secondaryTag']
tagKey = list(tag)[0]
tagValue = tag[tagKey]
return {'tagValue' : tagValue}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: secondaryPatchGroupValue
Selector: $.Payload.tagValue
Type: String
nextStep: patchSecondaryInstances
- name: patchSecondaryInstances
action: 'aws:runCommand'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: AWS-RunPatchBaseline
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
Targets:
- Key: '{{returnSecondaryTagKey.secondaryPatchGroupKey}}'
Values:
- '{{returnSecondaryTagValue.secondaryPatchGroupValue}}'
MaxConcurrency: 10%
MaxErrors: 10%
nextStep: returnSecondaryToOriginalState
- name: returnSecondaryToOriginalState
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnToOriginalState
InputPayload:
targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}'
Script: |-
def returnToOriginalState(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped' or instanceDict[instance] == 'stopping':
ec2.stop_instances(
InstanceIds=[instance]
)
else:
pass
```
------
#### [ JSON ]
```
{
"name":"getSecondaryInstanceState",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"getInstanceStates",
"InputPayload":{
"secondaryTag":"{{SecondaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"originalInstanceStates",
"Selector":"$.Payload",
"Type":"StringMap"
}
],
"nextStep":"verifySecondaryInstancesRunning"
},
{
"name":"verifySecondaryInstancesRunning",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"verifyInstancesRunning",
"InputPayload":{
"targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"waitForSecondaryRunningInstances"
},
{
"name":"waitForSecondaryRunningInstances",
"action":"aws:executeScript",
"timeoutSeconds":300,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"waitForRunningInstances",
"InputPayload":{
"targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"returnSecondaryTagKey"
},
{
"name":"returnSecondaryTagKey",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"secondaryTag":"{{SecondaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"secondaryPatchGroupKey",
"Selector":"$.Payload.tagKey",
"Type":"String"
}
],
"nextStep":"returnSecondaryTagValue"
},
{
"name":"returnSecondaryTagValue",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"secondaryTag":"{{SecondaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"secondaryPatchGroupValue",
"Selector":"$.Payload.tagValue",
"Type":"String"
}
],
"nextStep":"patchSecondaryInstances"
},
{
"name":"patchSecondaryInstances",
"action":"aws:runCommand",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"AWS-RunPatchBaseline",
"Parameters":{
"SnapshotId":"{{SnapshotId}}",
"RebootOption":"{{RebootOption}}",
"Operation":"{{Operation}}"
},
"Targets":[
{
"Key":"{{returnSecondaryTagKey.secondaryPatchGroupKey}}",
"Values":[
"{{returnSecondaryTagValue.secondaryPatchGroupValue}}"
]
}
],
"MaxConcurrency":"10%",
"MaxErrors":"10%"
},
"nextStep":"returnSecondaryToOriginalState"
},
{
"name":"returnSecondaryToOriginalState",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnToOriginalState",
"InputPayload":{
"targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
}
}
]
}
```
------
1. Emily analisa o conteúdo do runbook com script concluído e cria o runbook na mesma Conta da AWS e Região da AWS das instâncias de destino. Agora ela está pronta para testar seu runbook para garantir que a automação funcione conforme desejado antes de implementá-la em seu ambiente de produção. Abaixo está o conteúdo do runbook com script concluído.
------
#### [ YAML ]
```
description: An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: '(Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.'
PrimaryPatchGroupTag:
type: StringMap
description: '(Required) The tag for the primary group of instances you want to patch. Specify a key-value pair. Example: {"key" : "value"}'
SecondaryPatchGroupTag:
type: StringMap
description: '(Required) The tag for the secondary group of instances you want to patch. Specify a key-value pair. Example: {"key" : "value"}'
SnapshotId:
type: String
description: '(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.'
default: ''
RebootOption:
type: String
description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.'
allowedValues:
- NoReboot
- RebootIfNeeded
default: RebootIfNeeded
Operation:
type: String
description: '(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.'
allowedValues:
- Install
- Scan
default: Install
mainSteps:
- name: getPrimaryInstanceState
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: getInstanceStates
InputPayload:
primaryTag: '{{PrimaryPatchGroupTag}}'
Script: |-
def getInstanceStates(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
tag = events['primaryTag']
tagKey, tagValue = list(tag.items())[0]
instanceQuery = ec2.describe_instances(
Filters=[
{
"Name": "tag:" + tagKey,
"Values": [tagValue]
}]
)
if not instanceQuery['Reservations']:
noInstancesForTagString = "No instances found for specified tag."
return({ 'noInstancesFound' : noInstancesForTagString })
else:
queryResponse = instanceQuery['Reservations']
originalInstanceStates = {}
for results in queryResponse:
instanceSet = results['Instances']
for instance in instanceSet:
instanceId = instance['InstanceId']
originalInstanceStates[instanceId] = instance['State']['Name']
return originalInstanceStates
outputs:
- Name: originalInstanceStates
Selector: $.Payload
Type: StringMap
nextStep: verifyPrimaryInstancesRunning
- name: verifyPrimaryInstancesRunning
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: verifyInstancesRunning
InputPayload:
targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}'
Script: |-
def verifyInstancesRunning(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped':
print("The target instance " + instance + " is stopped. The instance will now be started.")
ec2.start_instances(
InstanceIds=[instance]
)
elif instanceDict[instance] == 'stopping':
print("The target instance " + instance + " is stopping. Polling for instance to reach stopped state.")
while instanceDict[instance] != 'stopped':
poll = ec2.get_waiter('instance_stopped')
poll.wait(
InstanceIds=[instance]
)
ec2.start_instances(
InstanceIds=[instance]
)
else:
pass
nextStep: waitForPrimaryRunningInstances
- name: waitForPrimaryRunningInstances
action: 'aws:executeScript'
timeoutSeconds: 300
onFailure: Abort
inputs:
Runtime: python3.11
Handler: waitForRunningInstances
InputPayload:
targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}'
Script: |-
def waitForRunningInstances(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
poll = ec2.get_waiter('instance_running')
poll.wait(
InstanceIds=[instance]
)
nextStep: returnPrimaryTagKey
- name: returnPrimaryTagKey
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
primaryTag: '{{PrimaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['primaryTag']
tagKey = list(tag)[0]
stringKey = "tag:" + tagKey
return {'tagKey' : stringKey}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: primaryPatchGroupKey
Selector: $.Payload.tagKey
Type: String
nextStep: returnPrimaryTagValue
- name: returnPrimaryTagValue
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
primaryTag: '{{PrimaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['primaryTag']
tagKey = list(tag)[0]
tagValue = tag[tagKey]
return {'tagValue' : tagValue}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: primaryPatchGroupValue
Selector: $.Payload.tagValue
Type: String
nextStep: patchPrimaryInstances
- name: patchPrimaryInstances
action: 'aws:runCommand'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: AWS-RunPatchBaseline
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
Targets:
- Key: '{{returnPrimaryTagKey.primaryPatchGroupKey}}'
Values:
- '{{returnPrimaryTagValue.primaryPatchGroupValue}}'
MaxConcurrency: 10%
MaxErrors: 10%
nextStep: returnPrimaryToOriginalState
- name: returnPrimaryToOriginalState
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnToOriginalState
InputPayload:
targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}'
Script: |-
def returnToOriginalState(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped' or instanceDict[instance] == 'stopping':
ec2.stop_instances(
InstanceIds=[instance]
)
else:
pass
nextStep: getSecondaryInstanceState
- name: getSecondaryInstanceState
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: getInstanceStates
InputPayload:
secondaryTag: '{{SecondaryPatchGroupTag}}'
Script: |-
def getInstanceStates(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
tag = events['secondaryTag']
tagKey, tagValue = list(tag.items())[0]
instanceQuery = ec2.describe_instances(
Filters=[
{
"Name": "tag:" + tagKey,
"Values": [tagValue]
}]
)
if not instanceQuery['Reservations']:
noInstancesForTagString = "No instances found for specified tag."
return({ 'noInstancesFound' : noInstancesForTagString })
else:
queryResponse = instanceQuery['Reservations']
originalInstanceStates = {}
for results in queryResponse:
instanceSet = results['Instances']
for instance in instanceSet:
instanceId = instance['InstanceId']
originalInstanceStates[instanceId] = instance['State']['Name']
return originalInstanceStates
outputs:
- Name: originalInstanceStates
Selector: $.Payload
Type: StringMap
nextStep: verifySecondaryInstancesRunning
- name: verifySecondaryInstancesRunning
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: verifyInstancesRunning
InputPayload:
targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}'
Script: |-
def verifyInstancesRunning(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped':
print("The target instance " + instance + " is stopped. The instance will now be started.")
ec2.start_instances(
InstanceIds=[instance]
)
elif instanceDict[instance] == 'stopping':
print("The target instance " + instance + " is stopping. Polling for instance to reach stopped state.")
while instanceDict[instance] != 'stopped':
poll = ec2.get_waiter('instance_stopped')
poll.wait(
InstanceIds=[instance]
)
ec2.start_instances(
InstanceIds=[instance]
)
else:
pass
nextStep: waitForSecondaryRunningInstances
- name: waitForSecondaryRunningInstances
action: 'aws:executeScript'
timeoutSeconds: 300
onFailure: Abort
inputs:
Runtime: python3.11
Handler: waitForRunningInstances
InputPayload:
targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}'
Script: |-
def waitForRunningInstances(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
poll = ec2.get_waiter('instance_running')
poll.wait(
InstanceIds=[instance]
)
nextStep: returnSecondaryTagKey
- name: returnSecondaryTagKey
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
secondaryTag: '{{SecondaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['secondaryTag']
tagKey = list(tag)[0]
stringKey = "tag:" + tagKey
return {'tagKey' : stringKey}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: secondaryPatchGroupKey
Selector: $.Payload.tagKey
Type: String
nextStep: returnSecondaryTagValue
- name: returnSecondaryTagValue
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
secondaryTag: '{{SecondaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['secondaryTag']
tagKey = list(tag)[0]
tagValue = tag[tagKey]
return {'tagValue' : tagValue}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: secondaryPatchGroupValue
Selector: $.Payload.tagValue
Type: String
nextStep: patchSecondaryInstances
- name: patchSecondaryInstances
action: 'aws:runCommand'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: AWS-RunPatchBaseline
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
Targets:
- Key: '{{returnSecondaryTagKey.secondaryPatchGroupKey}}'
Values:
- '{{returnSecondaryTagValue.secondaryPatchGroupValue}}'
MaxConcurrency: 10%
MaxErrors: 10%
nextStep: returnSecondaryToOriginalState
- name: returnSecondaryToOriginalState
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnToOriginalState
InputPayload:
targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}'
Script: |-
def returnToOriginalState(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped' or instanceDict[instance] == 'stopping':
ec2.stop_instances(
InstanceIds=[instance]
)
else:
pass
```
------
#### [ JSON ]
```
{
"description":"An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.",
"schemaVersion":"0.3",
"assumeRole":"{{AutomationAssumeRole}}",
"parameters":{
"AutomationAssumeRole":{
"type":"String",
"description":"(Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook."
},
"PrimaryPatchGroupTag":{
"type":"StringMap",
"description":"(Required) The tag for the primary group of instances you want to patch. Specify a key-value pair. Example: {\"key\" : \"value\"}"
},
"SecondaryPatchGroupTag":{
"type":"StringMap",
"description":"(Required) The tag for the secondary group of instances you want to patch. Specify a key-value pair. Example: {\"key\" : \"value\"}"
},
"SnapshotId":{
"type":"String",
"description":"(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.",
"default":""
},
"RebootOption":{
"type":"String",
"description":"(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.",
"allowedValues":[
"NoReboot",
"RebootIfNeeded"
],
"default":"RebootIfNeeded"
},
"Operation":{
"type":"String",
"description":"(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.",
"allowedValues":[
"Install",
"Scan"
],
"default":"Install"
}
},
"mainSteps":[
{
"name":"getPrimaryInstanceState",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"getInstanceStates",
"InputPayload":{
"primaryTag":"{{PrimaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"originalInstanceStates",
"Selector":"$.Payload",
"Type":"StringMap"
}
],
"nextStep":"verifyPrimaryInstancesRunning"
},
{
"name":"verifyPrimaryInstancesRunning",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"verifyInstancesRunning",
"InputPayload":{
"targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"waitForPrimaryRunningInstances"
},
{
"name":"waitForPrimaryRunningInstances",
"action":"aws:executeScript",
"timeoutSeconds":300,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"waitForRunningInstances",
"InputPayload":{
"targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"returnPrimaryTagKey"
},
{
"name":"returnPrimaryTagKey",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"primaryTag":"{{PrimaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"primaryPatchGroupKey",
"Selector":"$.Payload.tagKey",
"Type":"String"
}
],
"nextStep":"returnPrimaryTagValue"
},
{
"name":"returnPrimaryTagValue",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"primaryTag":"{{PrimaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"primaryPatchGroupValue",
"Selector":"$.Payload.tagValue",
"Type":"String"
}
],
"nextStep":"patchPrimaryInstances"
},
{
"name":"patchPrimaryInstances",
"action":"aws:runCommand",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"AWS-RunPatchBaseline",
"Parameters":{
"SnapshotId":"{{SnapshotId}}",
"RebootOption":"{{RebootOption}}",
"Operation":"{{Operation}}"
},
"Targets":[
{
"Key":"{{returnPrimaryTagKey.primaryPatchGroupKey}}",
"Values":[
"{{returnPrimaryTagValue.primaryPatchGroupValue}}"
]
}
],
"MaxConcurrency":"10%",
"MaxErrors":"10%"
},
"nextStep":"returnPrimaryToOriginalState"
},
{
"name":"returnPrimaryToOriginalState",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnToOriginalState",
"InputPayload":{
"targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"getSecondaryInstanceState"
},
{
"name":"getSecondaryInstanceState",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"getInstanceStates",
"InputPayload":{
"secondaryTag":"{{SecondaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"originalInstanceStates",
"Selector":"$.Payload",
"Type":"StringMap"
}
],
"nextStep":"verifySecondaryInstancesRunning"
},
{
"name":"verifySecondaryInstancesRunning",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"verifyInstancesRunning",
"InputPayload":{
"targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"waitForSecondaryRunningInstances"
},
{
"name":"waitForSecondaryRunningInstances",
"action":"aws:executeScript",
"timeoutSeconds":300,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"waitForRunningInstances",
"InputPayload":{
"targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"returnSecondaryTagKey"
},
{
"name":"returnSecondaryTagKey",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"secondaryTag":"{{SecondaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"secondaryPatchGroupKey",
"Selector":"$.Payload.tagKey",
"Type":"String"
}
],
"nextStep":"returnSecondaryTagValue"
},
{
"name":"returnSecondaryTagValue",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"secondaryTag":"{{SecondaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"secondaryPatchGroupValue",
"Selector":"$.Payload.tagValue",
"Type":"String"
}
],
"nextStep":"patchSecondaryInstances"
},
{
"name":"patchSecondaryInstances",
"action":"aws:runCommand",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"AWS-RunPatchBaseline",
"Parameters":{
"SnapshotId":"{{SnapshotId}}",
"RebootOption":"{{RebootOption}}",
"Operation":"{{Operation}}"
},
"Targets":[
{
"Key":"{{returnSecondaryTagKey.secondaryPatchGroupKey}}",
"Values":[
"{{returnSecondaryTagValue.secondaryPatchGroupValue}}"
]
}
],
"MaxConcurrency":"10%",
"MaxErrors":"10%"
},
"nextStep":"returnSecondaryToOriginalState"
},
{
"name":"returnSecondaryToOriginalState",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnToOriginalState",
"InputPayload":{
"targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
}
}
]
}
```
------
Para obter mais informações sobre as ações de automação usadas neste exemplo, consulte a [Referência de ações do Systems Manager Automation](automation-actions.md).
# Exemplos adicionais de runbook
Os runbooks de exemplo a seguir demonstram como é possível usar as ações de automação do AWS Systems Manager para automatizar tarefas comuns de implantação, solução de problemas e manutenção.
**nota**
Os exemplos de runbooks nesta seção são fornecidos para demonstrar como é possível criar runbooks personalizados para oferecer suporte às suas necessidades operacionais específicas. Esses documentos não se destinam ao uso em ambientes de produção como estão. No entanto, você pode personalizá-los para seu próprio uso.
**Topics**
+ [Implantar a arquitetura da VPC e os controles de domínio do Microsoft Active Directory](automation-document-architecture-deployment-example.md)
+ [Restaurar um volume raiz do snapshot mais recente](automation-document-instance-recovery-example.md)
+ [Crie uma AMI e uma cópia entre regiões](automation-document-backup-maintenance-example.md)
# Implantar a arquitetura da VPC e os controles de domínio do Microsoft Active Directory
Para aumentar a eficiência e padronizar tarefas comuns, é possível optar por automatizar implantações. Isso é útil se você implantar regularmente a mesma arquitetura em várias contas e Regiões da AWS. A automatização de implantações de arquitetura também pode reduzir o potencial de erro humano que pode ocorrer ao implantar a arquitetura manualmente. AWS Systems Manager As ações do Automation podem ajudar você a fazer isso. O Automation é uma ferramenta do AWS Systems Manager.
O runbook AWS Systems Manager do exemplo a seguir realiza estas ações:
+ Recupera a Amazon Machine Image (AMI) mais recente do Windows Server 2016 usando o Parameter Store do Systems Manager para usar ao executar as instâncias do EC2 que serão configuradas como controladores de domínio. O Parameter Store é uma ferramenta do AWS Systems Manager.
+ Usa a ação de automação `aws:executeAwsApi` para chamar várias operações da API da AWS para criar a arquitetura da VPC. As instâncias do controlador de domínio são executadas em sub-redes privadas e se conectam à Internet usando um gateway NAT. Isso permite que o SSM Agent nas instâncias acessem os endpoints do Systems Manager necessários.
+ Usa a ação de automação `aws:waitForAwsResourceProperty` para confirmar se as instâncias executadas pela ação anterior estão `Online` para o AWS Systems Manager.
+ Usa a ação de automação `aws:runCommand` para configurar as instâncias executadas como controles de domínio do Microsoft Active Directory.
------
#### [ YAML ]
```
---
description: Custom Automation Deployment Example
schemaVersion: '0.3'
parameters:
AutomationAssumeRole:
type: String
default: ''
description: >-
(Optional) The ARN of the role that allows Automation to perform the
actions on your behalf. If no role is specified, Systems Manager
Automation uses your IAM permissions to run this runbook.
mainSteps:
- name: getLatestWindowsAmi
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ssm
Api: GetParameter
Name: >-
/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base
outputs:
- Name: amiId
Selector: $.Parameter.Value
Type: String
nextStep: createSSMInstanceRole
- name: createSSMInstanceRole
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: iam
Api: CreateRole
AssumeRolePolicyDocument: >-
{"Version": "2012-10-17", "Statement":[{"Effect":"Allow","Principal":{"Service":["ec2.amazonaws.com"]},"Action":["sts:AssumeRole"]}]}
RoleName: sampleSSMInstanceRole
nextStep: attachManagedSSMPolicy
- name: attachManagedSSMPolicy
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: iam
Api: AttachRolePolicy
PolicyArn: 'arn:aws:iam::aws:policy/service-role/AmazonSSMManagedInstanceCore'
RoleName: sampleSSMInstanceRole
nextStep: createSSMInstanceProfile
- name: createSSMInstanceProfile
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: iam
Api: CreateInstanceProfile
InstanceProfileName: sampleSSMInstanceRole
outputs:
- Name: instanceProfileArn
Selector: $.InstanceProfile.Arn
Type: String
nextStep: addSSMInstanceRoleToProfile
- name: addSSMInstanceRoleToProfile
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: iam
Api: AddRoleToInstanceProfile
InstanceProfileName: sampleSSMInstanceRole
RoleName: sampleSSMInstanceRole
nextStep: createVpc
- name: createVpc
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateVpc
CidrBlock: 10.0.100.0/22
outputs:
- Name: vpcId
Selector: $.Vpc.VpcId
Type: String
nextStep: getMainRtb
- name: getMainRtb
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: DescribeRouteTables
Filters:
- Name: vpc-id
Values:
- '{{ createVpc.vpcId }}'
outputs:
- Name: mainRtbId
Selector: '$.RouteTables[0].RouteTableId'
Type: String
nextStep: verifyMainRtb
- name: verifyMainRtb
action: aws:assertAwsResourceProperty
onFailure: Abort
inputs:
Service: ec2
Api: DescribeRouteTables
RouteTableIds:
- '{{ getMainRtb.mainRtbId }}'
PropertySelector: '$.RouteTables[0].Associations[0].Main'
DesiredValues:
- 'True'
nextStep: createPubSubnet
- name: createPubSubnet
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateSubnet
CidrBlock: 10.0.103.0/24
AvailabilityZone: us-west-2c
VpcId: '{{ createVpc.vpcId }}'
outputs:
- Name: pubSubnetId
Selector: $.Subnet.SubnetId
Type: String
nextStep: createPubRtb
- name: createPubRtb
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateRouteTable
VpcId: '{{ createVpc.vpcId }}'
outputs:
- Name: pubRtbId
Selector: $.RouteTable.RouteTableId
Type: String
nextStep: createIgw
- name: createIgw
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateInternetGateway
outputs:
- Name: igwId
Selector: $.InternetGateway.InternetGatewayId
Type: String
nextStep: attachIgw
- name: attachIgw
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: AttachInternetGateway
InternetGatewayId: '{{ createIgw.igwId }}'
VpcId: '{{ createVpc.vpcId }}'
nextStep: allocateEip
- name: allocateEip
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: AllocateAddress
Domain: vpc
outputs:
- Name: eipAllocationId
Selector: $.AllocationId
Type: String
nextStep: createNatGw
- name: createNatGw
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateNatGateway
AllocationId: '{{ allocateEip.eipAllocationId }}'
SubnetId: '{{ createPubSubnet.pubSubnetId }}'
outputs:
- Name: natGwId
Selector: $.NatGateway.NatGatewayId
Type: String
nextStep: verifyNatGwAvailable
- name: verifyNatGwAvailable
action: aws:waitForAwsResourceProperty
timeoutSeconds: 150
inputs:
Service: ec2
Api: DescribeNatGateways
NatGatewayIds:
- '{{ createNatGw.natGwId }}'
PropertySelector: '$.NatGateways[0].State'
DesiredValues:
- available
nextStep: createNatRoute
- name: createNatRoute
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateRoute
DestinationCidrBlock: 0.0.0.0/0
NatGatewayId: '{{ createNatGw.natGwId }}'
RouteTableId: '{{ getMainRtb.mainRtbId }}'
nextStep: createPubRoute
- name: createPubRoute
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateRoute
DestinationCidrBlock: 0.0.0.0/0
GatewayId: '{{ createIgw.igwId }}'
RouteTableId: '{{ createPubRtb.pubRtbId }}'
nextStep: setPubSubAssoc
- name: setPubSubAssoc
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: AssociateRouteTable
RouteTableId: '{{ createPubRtb.pubRtbId }}'
SubnetId: '{{ createPubSubnet.pubSubnetId }}'
- name: createDhcpOptions
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateDhcpOptions
DhcpConfigurations:
- Key: domain-name-servers
Values:
- '10.0.100.50,10.0.101.50'
- Key: domain-name
Values:
- sample.com
outputs:
- Name: dhcpOptionsId
Selector: $.DhcpOptions.DhcpOptionsId
Type: String
nextStep: createDCSubnet1
- name: createDCSubnet1
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateSubnet
CidrBlock: 10.0.100.0/24
AvailabilityZone: us-west-2a
VpcId: '{{ createVpc.vpcId }}'
outputs:
- Name: firstSubnetId
Selector: $.Subnet.SubnetId
Type: String
nextStep: createDCSubnet2
- name: createDCSubnet2
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateSubnet
CidrBlock: 10.0.101.0/24
AvailabilityZone: us-west-2b
VpcId: '{{ createVpc.vpcId }}'
outputs:
- Name: secondSubnetId
Selector: $.Subnet.SubnetId
Type: String
nextStep: createDCSecGroup
- name: createDCSecGroup
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateSecurityGroup
GroupName: SampleDCSecGroup
Description: Security Group for Sample Domain Controllers
VpcId: '{{ createVpc.vpcId }}'
outputs:
- Name: dcSecGroupId
Selector: $.GroupId
Type: String
nextStep: authIngressDCTraffic
- name: authIngressDCTraffic
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: AuthorizeSecurityGroupIngress
GroupId: '{{ createDCSecGroup.dcSecGroupId }}'
IpPermissions:
- FromPort: -1
IpProtocol: '-1'
IpRanges:
- CidrIp: 0.0.0.0/0
Description: Allow all traffic between Domain Controllers
nextStep: verifyInstanceProfile
- name: verifyInstanceProfile
action: aws:waitForAwsResourceProperty
maxAttempts: 5
onFailure: Abort
inputs:
Service: iam
Api: ListInstanceProfilesForRole
RoleName: sampleSSMInstanceRole
PropertySelector: '$.InstanceProfiles[0].Arn'
DesiredValues:
- '{{ createSSMInstanceProfile.instanceProfileArn }}'
nextStep: iamEventualConsistency
- name: iamEventualConsistency
action: aws:sleep
inputs:
Duration: PT2M
nextStep: launchDC1
- name: launchDC1
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: RunInstances
BlockDeviceMappings:
- DeviceName: /dev/sda1
Ebs:
DeleteOnTermination: true
VolumeSize: 50
VolumeType: gp2
- DeviceName: xvdf
Ebs:
DeleteOnTermination: true
VolumeSize: 100
VolumeType: gp2
IamInstanceProfile:
Arn: '{{ createSSMInstanceProfile.instanceProfileArn }}'
ImageId: '{{ getLatestWindowsAmi.amiId }}'
InstanceType: t2.micro
MaxCount: 1
MinCount: 1
PrivateIpAddress: 10.0.100.50
SecurityGroupIds:
- '{{ createDCSecGroup.dcSecGroupId }}'
SubnetId: '{{ createDCSubnet1.firstSubnetId }}'
TagSpecifications:
- ResourceType: instance
Tags:
- Key: Name
Value: SampleDC1
outputs:
- Name: pdcInstanceId
Selector: '$.Instances[0].InstanceId'
Type: String
nextStep: launchDC2
- name: launchDC2
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: RunInstances
BlockDeviceMappings:
- DeviceName: /dev/sda1
Ebs:
DeleteOnTermination: true
VolumeSize: 50
VolumeType: gp2
- DeviceName: xvdf
Ebs:
DeleteOnTermination: true
VolumeSize: 100
VolumeType: gp2
IamInstanceProfile:
Arn: '{{ createSSMInstanceProfile.instanceProfileArn }}'
ImageId: '{{ getLatestWindowsAmi.amiId }}'
InstanceType: t2.micro
MaxCount: 1
MinCount: 1
PrivateIpAddress: 10.0.101.50
SecurityGroupIds:
- '{{ createDCSecGroup.dcSecGroupId }}'
SubnetId: '{{ createDCSubnet2.secondSubnetId }}'
TagSpecifications:
- ResourceType: instance
Tags:
- Key: Name
Value: SampleDC2
outputs:
- Name: adcInstanceId
Selector: '$.Instances[0].InstanceId'
Type: String
nextStep: verifyDCInstanceState
- name: verifyDCInstanceState
action: aws:waitForAwsResourceProperty
inputs:
Service: ec2
Api: DescribeInstanceStatus
IncludeAllInstances: true
InstanceIds:
- '{{ launchDC1.pdcInstanceId }}'
- '{{ launchDC2.adcInstanceId }}'
PropertySelector: '$.InstanceStatuses..InstanceState.Name'
DesiredValues:
- running
nextStep: verifyInstancesOnlineSSM
- name: verifyInstancesOnlineSSM
action: aws:waitForAwsResourceProperty
timeoutSeconds: 600
inputs:
Service: ssm
Api: DescribeInstanceInformation
InstanceInformationFilterList:
- key: InstanceIds
valueSet:
- '{{ launchDC1.pdcInstanceId }}'
- '{{ launchDC2.adcInstanceId }}'
PropertySelector: '$.InstanceInformationList..PingStatus'
DesiredValues:
- Online
nextStep: installADRoles
- name: installADRoles
action: aws:runCommand
inputs:
DocumentName: AWS-RunPowerShellScript
InstanceIds:
- '{{ launchDC1.pdcInstanceId }}'
- '{{ launchDC2.adcInstanceId }}'
Parameters:
commands: |-
try {
Install-WindowsFeature -Name AD-Domain-Services -IncludeManagementTools
}
catch {
Write-Error "Failed to install ADDS Role."
}
nextStep: setAdminPassword
- name: setAdminPassword
action: aws:runCommand
inputs:
DocumentName: AWS-RunPowerShellScript
InstanceIds:
- '{{ launchDC1.pdcInstanceId }}'
Parameters:
commands:
- net user Administrator "sampleAdminPass123!"
nextStep: createForest
- name: createForest
action: aws:runCommand
inputs:
DocumentName: AWS-RunPowerShellScript
InstanceIds:
- '{{ launchDC1.pdcInstanceId }}'
Parameters:
commands: |-
$dsrmPass = 'sample123!' | ConvertTo-SecureString -asPlainText -Force
try {
Install-ADDSForest -DomainName "sample.com" -DomainMode 6 -ForestMode 6 -InstallDNS -DatabasePath "D:\NTDS" -SysvolPath "D:\SYSVOL" -SafeModeAdministratorPassword $dsrmPass -Force
}
catch {
Write-Error $_
}
try {
Add-DnsServerForwarder -IPAddress "10.0.100.2"
}
catch {
Write-Error $_
}
nextStep: associateDhcpOptions
- name: associateDhcpOptions
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: AssociateDhcpOptions
DhcpOptionsId: '{{ createDhcpOptions.dhcpOptionsId }}'
VpcId: '{{ createVpc.vpcId }}'
nextStep: waitForADServices
- name: waitForADServices
action: aws:sleep
inputs:
Duration: PT1M
nextStep: promoteADC
- name: promoteADC
action: aws:runCommand
inputs:
DocumentName: AWS-RunPowerShellScript
InstanceIds:
- '{{ launchDC2.adcInstanceId }}'
Parameters:
commands: |-
ipconfig /renew
$dsrmPass = 'sample123!' | ConvertTo-SecureString -asPlainText -Force
$domAdminUser = "sample\Administrator"
$domAdminPass = "sampleAdminPass123!" | ConvertTo-SecureString -asPlainText -Force
$domAdminCred = New-Object System.Management.Automation.PSCredential($domAdminUser,$domAdminPass)
try {
Install-ADDSDomainController -DomainName "sample.com" -InstallDNS -DatabasePath "D:\NTDS" -SysvolPath "D:\SYSVOL" -SafeModeAdministratorPassword $dsrmPass -Credential $domAdminCred -Force
}
catch {
Write-Error $_
}
```
------
#### [ JSON ]
```
{
"description": "Custom Automation Deployment Example",
"schemaVersion": "0.3",
"assumeRole": "{{ AutomationAssumeRole }}",
"parameters": {
"AutomationAssumeRole": {
"type": "String",
"description": "(Optional) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to run this runbook.",
"default": ""
}
},
"mainSteps": [
{
"name": "getLatestWindowsAmi",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ssm",
"Api": "GetParameter",
"Name": "/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base"
},
"outputs": [
{
"Name": "amiId",
"Selector": "$.Parameter.Value",
"Type": "String"
}
],
"nextStep": "createSSMInstanceRole"
},
{
"name": "createSSMInstanceRole",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "iam",
"Api": "CreateRole",
"AssumeRolePolicyDocument": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":[\"ec2.amazonaws.com\"]},\"Action\":[\"sts:AssumeRole\"]}]}",
"RoleName": "sampleSSMInstanceRole"
},
"nextStep": "attachManagedSSMPolicy"
},
{
"name": "attachManagedSSMPolicy",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "iam",
"Api": "AttachRolePolicy",
"PolicyArn": "arn:aws:iam::aws:policy/service-role/AmazonSSMManagedInstanceCore",
"RoleName": "sampleSSMInstanceRole"
},
"nextStep": "createSSMInstanceProfile"
},
{
"name": "createSSMInstanceProfile",
"action":"aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "iam",
"Api": "CreateInstanceProfile",
"InstanceProfileName": "sampleSSMInstanceRole"
},
"outputs": [
{
"Name": "instanceProfileArn",
"Selector": "$.InstanceProfile.Arn",
"Type": "String"
}
],
"nextStep": "addSSMInstanceRoleToProfile"
},
{
"name": "addSSMInstanceRoleToProfile",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "iam",
"Api": "AddRoleToInstanceProfile",
"InstanceProfileName": "sampleSSMInstanceRole",
"RoleName": "sampleSSMInstanceRole"
},
"nextStep": "createVpc"
},
{
"name": "createVpc",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateVpc",
"CidrBlock": "10.0.100.0/22"
},
"outputs": [
{
"Name": "vpcId",
"Selector": "$.Vpc.VpcId",
"Type": "String"
}
],
"nextStep": "getMainRtb"
},
{
"name": "getMainRtb",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "DescribeRouteTables",
"Filters": [
{
"Name": "vpc-id",
"Values": ["{{ createVpc.vpcId }}"]
}
]
},
"outputs": [
{
"Name": "mainRtbId",
"Selector": "$.RouteTables[0].RouteTableId",
"Type": "String"
}
],
"nextStep": "verifyMainRtb"
},
{
"name": "verifyMainRtb",
"action": "aws:assertAwsResourceProperty",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "DescribeRouteTables",
"RouteTableIds": ["{{ getMainRtb.mainRtbId }}"],
"PropertySelector": "$.RouteTables[0].Associations[0].Main",
"DesiredValues": ["True"]
},
"nextStep": "createPubSubnet"
},
{
"name": "createPubSubnet",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateSubnet",
"CidrBlock": "10.0.103.0/24",
"AvailabilityZone": "us-west-2c",
"VpcId": "{{ createVpc.vpcId }}"
},
"outputs":[
{
"Name": "pubSubnetId",
"Selector": "$.Subnet.SubnetId",
"Type": "String"
}
],
"nextStep": "createPubRtb"
},
{
"name": "createPubRtb",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateRouteTable",
"VpcId": "{{ createVpc.vpcId }}"
},
"outputs": [
{
"Name": "pubRtbId",
"Selector": "$.RouteTable.RouteTableId",
"Type": "String"
}
],
"nextStep": "createIgw"
},
{
"name": "createIgw",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateInternetGateway"
},
"outputs": [
{
"Name": "igwId",
"Selector": "$.InternetGateway.InternetGatewayId",
"Type": "String"
}
],
"nextStep": "attachIgw"
},
{
"name": "attachIgw",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "AttachInternetGateway",
"InternetGatewayId": "{{ createIgw.igwId }}",
"VpcId": "{{ createVpc.vpcId }}"
},
"nextStep": "allocateEip"
},
{
"name": "allocateEip",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "AllocateAddress",
"Domain": "vpc"
},
"outputs": [
{
"Name": "eipAllocationId",
"Selector": "$.AllocationId",
"Type": "String"
}
],
"nextStep": "createNatGw"
},
{
"name": "createNatGw",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateNatGateway",
"AllocationId": "{{ allocateEip.eipAllocationId }}",
"SubnetId": "{{ createPubSubnet.pubSubnetId }}"
},
"outputs":[
{
"Name": "natGwId",
"Selector": "$.NatGateway.NatGatewayId",
"Type": "String"
}
],
"nextStep": "verifyNatGwAvailable"
},
{
"name": "verifyNatGwAvailable",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 150,
"inputs": {
"Service": "ec2",
"Api": "DescribeNatGateways",
"NatGatewayIds": [
"{{ createNatGw.natGwId }}"
],
"PropertySelector": "$.NatGateways[0].State",
"DesiredValues": [
"available"
]
},
"nextStep": "createNatRoute"
},
{
"name": "createNatRoute",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateRoute",
"DestinationCidrBlock": "0.0.0.0/0",
"NatGatewayId": "{{ createNatGw.natGwId }}",
"RouteTableId": "{{ getMainRtb.mainRtbId }}"
},
"nextStep": "createPubRoute"
},
{
"name": "createPubRoute",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateRoute",
"DestinationCidrBlock": "0.0.0.0/0",
"GatewayId": "{{ createIgw.igwId }}",
"RouteTableId": "{{ createPubRtb.pubRtbId }}"
},
"nextStep": "setPubSubAssoc"
},
{
"name": "setPubSubAssoc",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "AssociateRouteTable",
"RouteTableId": "{{ createPubRtb.pubRtbId }}",
"SubnetId": "{{ createPubSubnet.pubSubnetId }}"
}
},
{
"name": "createDhcpOptions",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateDhcpOptions",
"DhcpConfigurations": [
{
"Key": "domain-name-servers",
"Values": ["10.0.100.50,10.0.101.50"]
},
{
"Key": "domain-name",
"Values": ["sample.com"]
}
]
},
"outputs": [
{
"Name": "dhcpOptionsId",
"Selector": "$.DhcpOptions.DhcpOptionsId",
"Type": "String"
}
],
"nextStep": "createDCSubnet1"
},
{
"name": "createDCSubnet1",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateSubnet",
"CidrBlock": "10.0.100.0/24",
"AvailabilityZone": "us-west-2a",
"VpcId": "{{ createVpc.vpcId }}"
},
"outputs": [
{
"Name": "firstSubnetId",
"Selector": "$.Subnet.SubnetId",
"Type": "String"
}
],
"nextStep": "createDCSubnet2"
},
{
"name": "createDCSubnet2",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateSubnet",
"CidrBlock": "10.0.101.0/24",
"AvailabilityZone": "us-west-2b",
"VpcId": "{{ createVpc.vpcId }}"
},
"outputs": [
{
"Name": "secondSubnetId",
"Selector": "$.Subnet.SubnetId",
"Type": "String"
}
],
"nextStep": "createDCSecGroup"
},
{
"name": "createDCSecGroup",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateSecurityGroup",
"GroupName": "SampleDCSecGroup",
"Description": "Security Group for Example Domain Controllers",
"VpcId": "{{ createVpc.vpcId }}"
},
"outputs": [
{
"Name": "dcSecGroupId",
"Selector": "$.GroupId",
"Type": "String"
}
],
"nextStep": "authIngressDCTraffic"
},
{
"name": "authIngressDCTraffic",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "AuthorizeSecurityGroupIngress",
"GroupId": "{{ createDCSecGroup.dcSecGroupId }}",
"IpPermissions": [
{
"FromPort": -1,
"IpProtocol": "-1",
"IpRanges": [
{
"CidrIp": "0.0.0.0/0",
"Description": "Allow all traffic between Domain Controllers"
}
]
}
]
},
"nextStep": "verifyInstanceProfile"
},
{
"name": "verifyInstanceProfile",
"action": "aws:waitForAwsResourceProperty",
"maxAttempts": 5,
"onFailure": "Abort",
"inputs": {
"Service": "iam",
"Api": "ListInstanceProfilesForRole",
"RoleName": "sampleSSMInstanceRole",
"PropertySelector": "$.InstanceProfiles[0].Arn",
"DesiredValues": [
"{{ createSSMInstanceProfile.instanceProfileArn }}"
]
},
"nextStep": "iamEventualConsistency"
},
{
"name": "iamEventualConsistency",
"action": "aws:sleep",
"inputs": {
"Duration": "PT2M"
},
"nextStep": "launchDC1"
},
{
"name": "launchDC1",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "RunInstances",
"BlockDeviceMappings": [
{
"DeviceName": "/dev/sda1",
"Ebs": {
"DeleteOnTermination": true,
"VolumeSize": 50,
"VolumeType": "gp2"
}
},
{
"DeviceName": "xvdf",
"Ebs": {
"DeleteOnTermination": true,
"VolumeSize": 100,
"VolumeType": "gp2"
}
}
],
"IamInstanceProfile": {
"Arn": "{{ createSSMInstanceProfile.instanceProfileArn }}"
},
"ImageId": "{{ getLatestWindowsAmi.amiId }}",
"InstanceType": "t2.micro",
"MaxCount": 1,
"MinCount": 1,
"PrivateIpAddress": "10.0.100.50",
"SecurityGroupIds": [
"{{ createDCSecGroup.dcSecGroupId }}"
],
"SubnetId": "{{ createDCSubnet1.firstSubnetId }}",
"TagSpecifications": [
{
"ResourceType": "instance",
"Tags": [
{
"Key": "Name",
"Value": "SampleDC1"
}
]
}
]
},
"outputs": [
{
"Name": "pdcInstanceId",
"Selector": "$.Instances[0].InstanceId",
"Type": "String"
}
],
"nextStep": "launchDC2"
},
{
"name": "launchDC2",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "RunInstances",
"BlockDeviceMappings": [
{
"DeviceName": "/dev/sda1",
"Ebs": {
"DeleteOnTermination": true,
"VolumeSize": 50,
"VolumeType": "gp2"
}
},
{
"DeviceName": "xvdf",
"Ebs": {
"DeleteOnTermination": true,
"VolumeSize": 100,
"VolumeType": "gp2"
}
}
],
"IamInstanceProfile": {
"Arn": "{{ createSSMInstanceProfile.instanceProfileArn }}"
},
"ImageId": "{{ getLatestWindowsAmi.amiId }}",
"InstanceType": "t2.micro",
"MaxCount": 1,
"MinCount": 1,
"PrivateIpAddress": "10.0.101.50",
"SecurityGroupIds": [
"{{ createDCSecGroup.dcSecGroupId }}"
],
"SubnetId": "{{ createDCSubnet2.secondSubnetId }}",
"TagSpecifications": [
{
"ResourceType": "instance",
"Tags": [
{
"Key": "Name",
"Value": "SampleDC2"
}
]
}
]
},
"outputs": [
{
"Name": "adcInstanceId",
"Selector": "$.Instances[0].InstanceId",
"Type": "String"
}
],
"nextStep": "verifyDCInstanceState"
},
{
"name": "verifyDCInstanceState",
"action": "aws:waitForAwsResourceProperty",
"inputs": {
"Service": "ec2",
"Api": "DescribeInstanceStatus",
"IncludeAllInstances": true,
"InstanceIds": [
"{{ launchDC1.pdcInstanceId }}",
"{{ launchDC2.adcInstanceId }}"
],
"PropertySelector": "$.InstanceStatuses[0].InstanceState.Name",
"DesiredValues": [
"running"
]
},
"nextStep": "verifyInstancesOnlineSSM"
},
{
"name": "verifyInstancesOnlineSSM",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 600,
"inputs": {
"Service": "ssm",
"Api": "DescribeInstanceInformation",
"InstanceInformationFilterList": [
{
"key": "InstanceIds",
"valueSet": [
"{{ launchDC1.pdcInstanceId }}",
"{{ launchDC2.adcInstanceId }}"
]
}
],
"PropertySelector": "$.InstanceInformationList[0].PingStatus",
"DesiredValues": [
"Online"
]
},
"nextStep": "installADRoles"
},
{
"name": "installADRoles",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"InstanceIds": [
"{{ launchDC1.pdcInstanceId }}",
"{{ launchDC2.adcInstanceId }}"
],
"Parameters": {
"commands": [
"try {",
" Install-WindowsFeature -Name AD-Domain-Services -IncludeManagementTools",
"}",
"catch {",
" Write-Error \"Failed to install ADDS Role.\"",
"}"
]
}
},
"nextStep": "setAdminPassword"
},
{
"name": "setAdminPassword",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"InstanceIds": [
"{{ launchDC1.pdcInstanceId }}"
],
"Parameters": {
"commands": [
"net user Administrator \"sampleAdminPass123!\""
]
}
},
"nextStep": "createForest"
},
{
"name": "createForest",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"InstanceIds": [
"{{ launchDC1.pdcInstanceId }}"
],
"Parameters": {
"commands": [
"$dsrmPass = 'sample123!' | ConvertTo-SecureString -asPlainText -Force",
"try {",
" Install-ADDSForest -DomainName \"sample.com\" -DomainMode 6 -ForestMode 6 -InstallDNS -DatabasePath \"D:\\NTDS\" -SysvolPath \"D:\\SYSVOL\" -SafeModeAdministratorPassword $dsrmPass -Force",
"}",
"catch {",
" Write-Error $_",
"}",
"try {",
" Add-DnsServerForwarder -IPAddress \"10.0.100.2\"",
"}",
"catch {",
" Write-Error $_",
"}"
]
}
},
"nextStep": "associateDhcpOptions"
},
{
"name": "associateDhcpOptions",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "AssociateDhcpOptions",
"DhcpOptionsId": "{{ createDhcpOptions.dhcpOptionsId }}",
"VpcId": "{{ createVpc.vpcId }}"
},
"nextStep": "waitForADServices"
},
{
"name": "waitForADServices",
"action": "aws:sleep",
"inputs": {
"Duration": "PT1M"
},
"nextStep": "promoteADC"
},
{
"name": "promoteADC",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"InstanceIds": [
"{{ launchDC2.adcInstanceId }}"
],
"Parameters": {
"commands": [
"ipconfig /renew",
"$dsrmPass = 'sample123!' | ConvertTo-SecureString -asPlainText -Force",
"$domAdminUser = \"sample\\Administrator\"",
"$domAdminPass = \"sampleAdminPass123!\" | ConvertTo-SecureString -asPlainText -Force",
"$domAdminCred = New-Object System.Management.Automation.PSCredential($domAdminUser,$domAdminPass)",
"try {",
" Install-ADDSDomainController -DomainName \"sample.com\" -InstallDNS -DatabasePath \"D:\\NTDS\" -SysvolPath \"D:\\SYSVOL\" -SafeModeAdministratorPassword $dsrmPass -Credential $domAdminCred -Force",
"}",
"catch {",
" Write-Error $_",
"}"
]
}
}
}
]
}
```
------
# Restaurar um volume raiz do snapshot mais recente
O sistema operacional em um volume raiz pode ser corrompido por vários motivos. Por exemplo, após uma operação de patch, as instâncias podem não inicializar com êxito, devido a um kernel ou registro corrompido. A automatização de tarefas comuns de solução de problemas, como restaurar um volume raiz do snapshot mais recente feito antes da operação de patch, pode reduzir o tempo de inatividade e agilizar seus esforços de solução de problemas. AWS Systems Manager As ações do Automation podem ajudar você a fazer isso. O Automation é uma ferramenta do AWS Systems Manager.
O runbook AWS Systems Manager do exemplo a seguir realiza estas ações:
+ Usa a ação de automação `aws:executeAwsApi` para recuperar detalhes do volume raiz da instância.
+ Usa a ação de automação `aws:executeScript` para recuperar o snapshot mais recente do volume raiz.
+ Usa a ação de automação `aws:branch` para continuar a automação, se um snapshot for encontrado para o volume raiz.
------
#### [ YAML ]
```
---
description: Custom Automation Troubleshooting Example
schemaVersion: '0.3'
assumeRole: "{{ AutomationAssumeRole }}"
parameters:
AutomationAssumeRole:
type: String
description: "(Required) The ARN of the role that allows Automation to perform
the actions on your behalf. If no role is specified, Systems Manager Automation
uses your IAM permissions to use this runbook."
default: ''
InstanceId:
type: String
description: "(Required) The Instance Id whose root EBS volume you want to restore the latest Snapshot."
default: ''
mainSteps:
- name: getInstanceDetails
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- "{{ InstanceId }}"
outputs:
- Name: availabilityZone
Selector: "$.Reservations[0].Instances[0].Placement.AvailabilityZone"
Type: String
- Name: rootDeviceName
Selector: "$.Reservations[0].Instances[0].RootDeviceName"
Type: String
nextStep: getRootVolumeId
- name: getRootVolumeId
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: DescribeVolumes
Filters:
- Name: attachment.device
Values: ["{{ getInstanceDetails.rootDeviceName }}"]
- Name: attachment.instance-id
Values: ["{{ InstanceId }}"]
outputs:
- Name: rootVolumeId
Selector: "$.Volumes[0].VolumeId"
Type: String
nextStep: getSnapshotsByStartTime
- name: getSnapshotsByStartTime
action: aws:executeScript
timeoutSeconds: 45
onFailure: Abort
inputs:
Runtime: python3.11
Handler: getSnapshotsByStartTime
InputPayload:
rootVolumeId : "{{ getRootVolumeId.rootVolumeId }}"
Script: |-
def getSnapshotsByStartTime(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
rootVolumeId = events['rootVolumeId']
snapshotsQuery = ec2.describe_snapshots(
Filters=[
{
"Name": "volume-id",
"Values": [rootVolumeId]
}
]
)
if not snapshotsQuery['Snapshots']:
noSnapshotFoundString = "NoSnapshotFound"
return { 'noSnapshotFound' : noSnapshotFoundString }
else:
jsonSnapshots = snapshotsQuery['Snapshots']
sortedSnapshots = sorted(jsonSnapshots, key=lambda k: k['StartTime'], reverse=True)
latestSortedSnapshotId = sortedSnapshots[0]['SnapshotId']
return { 'latestSnapshotId' : latestSortedSnapshotId }
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: latestSnapshotId
Selector: $.Payload.latestSnapshotId
Type: String
- Name: noSnapshotFound
Selector: $.Payload.noSnapshotFound
Type: String
nextStep: branchFromResults
- name: branchFromResults
action: aws:branch
onFailure: Abort
inputs:
Choices:
- NextStep: createNewRootVolumeFromSnapshot
Not:
Variable: "{{ getSnapshotsByStartTime.noSnapshotFound }}"
StringEquals: "NoSnapshotFound"
isEnd: true
- name: createNewRootVolumeFromSnapshot
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateVolume
AvailabilityZone: "{{ getInstanceDetails.availabilityZone }}"
SnapshotId: "{{ getSnapshotsByStartTime.latestSnapshotId }}"
outputs:
- Name: newRootVolumeId
Selector: "$.VolumeId"
Type: String
nextStep: stopInstance
- name: stopInstance
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: StopInstances
InstanceIds:
- "{{ InstanceId }}"
nextStep: verifyVolumeAvailability
- name: verifyVolumeAvailability
action: aws:waitForAwsResourceProperty
timeoutSeconds: 120
inputs:
Service: ec2
Api: DescribeVolumes
VolumeIds:
- "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
PropertySelector: "$.Volumes[0].State"
DesiredValues:
- "available"
nextStep: verifyInstanceStopped
- name: verifyInstanceStopped
action: aws:waitForAwsResourceProperty
timeoutSeconds: 120
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- "{{ InstanceId }}"
PropertySelector: "$.Reservations[0].Instances[0].State.Name"
DesiredValues:
- "stopped"
nextStep: detachRootVolume
- name: detachRootVolume
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: DetachVolume
VolumeId: "{{ getRootVolumeId.rootVolumeId }}"
nextStep: verifyRootVolumeDetached
- name: verifyRootVolumeDetached
action: aws:waitForAwsResourceProperty
timeoutSeconds: 30
inputs:
Service: ec2
Api: DescribeVolumes
VolumeIds:
- "{{ getRootVolumeId.rootVolumeId }}"
PropertySelector: "$.Volumes[0].State"
DesiredValues:
- "available"
nextStep: attachNewRootVolume
- name: attachNewRootVolume
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: AttachVolume
Device: "{{ getInstanceDetails.rootDeviceName }}"
InstanceId: "{{ InstanceId }}"
VolumeId: "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
nextStep: verifyNewRootVolumeAttached
- name: verifyNewRootVolumeAttached
action: aws:waitForAwsResourceProperty
timeoutSeconds: 30
inputs:
Service: ec2
Api: DescribeVolumes
VolumeIds:
- "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
PropertySelector: "$.Volumes[0].Attachments[0].State"
DesiredValues:
- "attached"
nextStep: startInstance
- name: startInstance
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: StartInstances
InstanceIds:
- "{{ InstanceId }}"
```
------
#### [ JSON ]
```
{
"description": "Custom Automation Troubleshooting Example",
"schemaVersion": "0.3",
"assumeRole": "{{ AutomationAssumeRole }}",
"parameters": {
"AutomationAssumeRole": {
"type": "String",
"description": "(Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to run this runbook.",
"default": ""
},
"InstanceId": {
"type": "String",
"description": "(Required) The Instance Id whose root EBS volume you want to restore the latest Snapshot.",
"default": ""
}
},
"mainSteps": [
{
"name": "getInstanceDetails",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "DescribeInstances",
"InstanceIds": [
"{{ InstanceId }}"
]
},
"outputs": [
{
"Name": "availabilityZone",
"Selector": "$.Reservations[0].Instances[0].Placement.AvailabilityZone",
"Type": "String"
},
{
"Name": "rootDeviceName",
"Selector": "$.Reservations[0].Instances[0].RootDeviceName",
"Type": "String"
}
],
"nextStep": "getRootVolumeId"
},
{
"name": "getRootVolumeId",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "DescribeVolumes",
"Filters": [
{
"Name": "attachment.device",
"Values": [
"{{ getInstanceDetails.rootDeviceName }}"
]
},
{
"Name": "attachment.instance-id",
"Values": [
"{{ InstanceId }}"
]
}
]
},
"outputs": [
{
"Name": "rootVolumeId",
"Selector": "$.Volumes[0].VolumeId",
"Type": "String"
}
],
"nextStep": "getSnapshotsByStartTime"
},
{
"name": "getSnapshotsByStartTime",
"action": "aws:executeScript",
"timeoutSeconds": 45,
"onFailure": "Continue",
"inputs": {
"Runtime": "python3.11",
"Handler": "getSnapshotsByStartTime",
"InputPayload": {
"rootVolumeId": "{{ getRootVolumeId.rootVolumeId }}"
},
"Attachment": "getSnapshotsByStartTime.py"
},
"outputs": [
{
"Name": "Payload",
"Selector": "$.Payload",
"Type": "StringMap"
},
{
"Name": "latestSnapshotId",
"Selector": "$.Payload.latestSnapshotId",
"Type": "String"
},
{
"Name": "noSnapshotFound",
"Selector": "$.Payload.noSnapshotFound",
"Type": "String"
}
],
"nextStep": "branchFromResults"
},
{
"name": "branchFromResults",
"action": "aws:branch",
"onFailure": "Abort",
"inputs": {
"Choices": [
{
"NextStep": "createNewRootVolumeFromSnapshot",
"Not": {
"Variable": "{{ getSnapshotsByStartTime.noSnapshotFound }}",
"StringEquals": "NoSnapshotFound"
}
}
]
},
"isEnd": true
},
{
"name": "createNewRootVolumeFromSnapshot",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateVolume",
"AvailabilityZone": "{{ getInstanceDetails.availabilityZone }}",
"SnapshotId": "{{ getSnapshotsByStartTime.latestSnapshotId }}"
},
"outputs": [
{
"Name": "newRootVolumeId",
"Selector": "$.VolumeId",
"Type": "String"
}
],
"nextStep": "stopInstance"
},
{
"name": "stopInstance",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "StopInstances",
"InstanceIds": [
"{{ InstanceId }}"
]
},
"nextStep": "verifyVolumeAvailability"
},
{
"name": "verifyVolumeAvailability",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 120,
"inputs": {
"Service": "ec2",
"Api": "DescribeVolumes",
"VolumeIds": [
"{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
],
"PropertySelector": "$.Volumes[0].State",
"DesiredValues": [
"available"
]
},
"nextStep": "verifyInstanceStopped"
},
{
"name": "verifyInstanceStopped",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 120,
"inputs": {
"Service": "ec2",
"Api": "DescribeInstances",
"InstanceIds": [
"{{ InstanceId }}"
],
"PropertySelector": "$.Reservations[0].Instances[0].State.Name",
"DesiredValues": [
"stopped"
]
},
"nextStep": "detachRootVolume"
},
{
"name": "detachRootVolume",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "DetachVolume",
"VolumeId": "{{ getRootVolumeId.rootVolumeId }}"
},
"nextStep": "verifyRootVolumeDetached"
},
{
"name": "verifyRootVolumeDetached",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 30,
"inputs": {
"Service": "ec2",
"Api": "DescribeVolumes",
"VolumeIds": [
"{{ getRootVolumeId.rootVolumeId }}"
],
"PropertySelector": "$.Volumes[0].State",
"DesiredValues": [
"available"
]
},
"nextStep": "attachNewRootVolume"
},
{
"name": "attachNewRootVolume",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "AttachVolume",
"Device": "{{ getInstanceDetails.rootDeviceName }}",
"InstanceId": "{{ InstanceId }}",
"VolumeId": "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
},
"nextStep": "verifyNewRootVolumeAttached"
},
{
"name": "verifyNewRootVolumeAttached",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 30,
"inputs": {
"Service": "ec2",
"Api": "DescribeVolumes",
"VolumeIds": [
"{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
],
"PropertySelector": "$.Volumes[0].Attachments[0].State",
"DesiredValues": [
"attached"
]
},
"nextStep": "startInstance"
},
{
"name": "startInstance",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "StartInstances",
"InstanceIds": [
"{{ InstanceId }}"
]
}
}
],
"files": {
"getSnapshotsByStartTime.py": {
"checksums": {
"sha256": "sampleETagValue"
}
}
}
}
```
------
# Crie uma AMI e uma cópia entre regiões
Criar uma Amazon Machine Image (AMI) de uma instância é um processo comum usado em backup e recuperação. Também é possível optar por copiar uma AMI em outra Região da AWS como parte de uma arquitetura de recuperação de desastres. A automação de tarefas de manutenção comuns poderá reduzir o tempo de inatividade se um problema exigir failover. AWS Systems Manager As ações do Automation podem ajudar você a fazer isso. O Automation é uma ferramenta do AWS Systems Manager.
O runbook AWS Systems Manager de exemplo a seguir realiza estas ações:
+ Usa a ação de automação `aws:executeAwsApi` para criar uma AMI.
+ Usa a ação de automação `aws:waitForAwsResourceProperty` para confirmar a disponibilidade da AMI.
+ Usa a ação de automação `aws:executeScript` para copiar a AMI na região de destino.
------
#### [ YAML ]
```
---
description: Custom Automation Backup and Recovery Example
schemaVersion: '0.3'
assumeRole: "{{ AutomationAssumeRole }}"
parameters:
AutomationAssumeRole:
type: String
description: "(Required) The ARN of the role that allows Automation to perform
the actions on your behalf. If no role is specified, Systems Manager Automation
uses your IAM permissions to use this runbook."
default: ''
InstanceId:
type: String
description: "(Required) The ID of the EC2 instance."
default: ''
mainSteps:
- name: createImage
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateImage
InstanceId: "{{ InstanceId }}"
Name: "Automation Image for {{ InstanceId }}"
NoReboot: false
outputs:
- Name: newImageId
Selector: "$.ImageId"
Type: String
nextStep: verifyImageAvailability
- name: verifyImageAvailability
action: aws:waitForAwsResourceProperty
timeoutSeconds: 600
inputs:
Service: ec2
Api: DescribeImages
ImageIds:
- "{{ createImage.newImageId }}"
PropertySelector: "$.Images[0].State"
DesiredValues:
- available
nextStep: copyImage
- name: copyImage
action: aws:executeScript
timeoutSeconds: 45
onFailure: Abort
inputs:
Runtime: python3.11
Handler: crossRegionImageCopy
InputPayload:
newImageId : "{{ createImage.newImageId }}"
Script: |-
def crossRegionImageCopy(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2', region_name='us-east-1')
newImageId = events['newImageId']
ec2.copy_image(
Name='DR Copy for ' + newImageId,
SourceImageId=newImageId,
SourceRegion='us-west-2'
)
```
------
#### [ JSON ]
```
{
"description": "Custom Automation Backup and Recovery Example",
"schemaVersion": "0.3",
"assumeRole": "{{ AutomationAssumeRole }}",
"parameters": {
"AutomationAssumeRole": {
"type": "String",
"description": "(Required) The ARN of the role that allows Automation to perform\nthe actions on your behalf. If no role is specified, Systems Manager Automation\nuses your IAM permissions to run this runbook.",
"default": ""
},
"InstanceId": {
"type": "String",
"description": "(Required) The ID of the EC2 instance.",
"default": ""
}
},
"mainSteps": [
{
"name": "createImage",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateImage",
"InstanceId": "{{ InstanceId }}",
"Name": "Automation Image for {{ InstanceId }}",
"NoReboot": false
},
"outputs": [
{
"Name": "newImageId",
"Selector": "$.ImageId",
"Type": "String"
}
],
"nextStep": "verifyImageAvailability"
},
{
"name": "verifyImageAvailability",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 600,
"inputs": {
"Service": "ec2",
"Api": "DescribeImages",
"ImageIds": [
"{{ createImage.newImageId }}"
],
"PropertySelector": "$.Images[0].State",
"DesiredValues": [
"available"
]
},
"nextStep": "copyImage"
},
{
"name": "copyImage",
"action": "aws:executeScript",
"timeoutSeconds": 45,
"onFailure": "Abort",
"inputs": {
"Runtime": "python3.11",
"Handler": "crossRegionImageCopy",
"InputPayload": {
"newImageId": "{{ createImage.newImageId }}"
},
"Attachment": "crossRegionImageCopy.py"
}
}
],
"files": {
"crossRegionImageCopy.py": {
"checksums": {
"sha256": "sampleETagValue"
}
}
}
}
```
------
# Criar parâmetros de entrada que preenchem os recursos da AWS
O Automation, uma ferramenta do Systems Manager, preenche recursos da AWS no Console de gerenciamento da AWS que correspondem ao tipo de recurso definido para um parâmetro de entrada. Recursos na sua Conta da AWS, que correspondem ao tipo de recurso, são exibidos em uma lista suspensa para você escolher. Você pode definir tipos de parâmetros de entrada para instâncias do Amazon Elastic Compute Cloud (Amazon EC2), buckets do Amazon Simple Storage Service (Amazon S3) e funções do AWS Identity and Access Management (IAM). As definições de tipo suportadas e as expressões regulares usadas para localizar recursos correspondentes são as seguintes:
+ `AWS::EC2::Instance::Id` - `^m?i-([a-z0-9]{8}|[a-z0-9]{17})$`
+ `List` - `^m?i-([a-z0-9]{8}|[a-z0-9]{17})$`
+ `AWS::S3::Bucket::Name` - `^[0-9a-z][a-z0-9\\-\\.]{3,63}$`
+ `List` - `^[0-9a-z][a-z0-9\\-\\.]{3,63}$`
+ `AWS::IAM::Role::Arn` - `^arn:(aws|aws-cn|aws-us-gov|aws-iso|aws-iso-b):iam::[0-9]{12}:role/.*$`
+ `List` - `^arn:(aws|aws-cn|aws-us-gov|aws-iso|aws-iso-b):iam::[0-9]{12}:role/.*$`
O exemplo a seguir são tipos de parâmetros de entrada definidos no conteúdo do runbook.
------
#### [ YAML ]
```
description: Enables encryption on an Amazon S3 bucket
schemaVersion: '0.3'
assumeRole: '{{ AutomationAssumeRole }}'
parameters:
BucketName:
type: 'AWS::S3::Bucket::Name'
description: (Required) The name of the Amazon S3 bucket you want to encrypt.
SSEAlgorithm:
type: String
description: (Optional) The server-side encryption algorithm to use for the default encryption.
default: AES256
AutomationAssumeRole:
type: 'AWS::IAM::Role::Arn'
description: (Optional) The Amazon Resource Name (ARN) of the role that allows Automation to perform the actions on your behalf.
default: ''
mainSteps:
- name: enableBucketEncryption
action: 'aws:executeAwsApi'
inputs:
Service: s3
Api: PutBucketEncryption
Bucket: '{{BucketName}}'
ServerSideEncryptionConfiguration:
Rules:
- ApplyServerSideEncryptionByDefault:
SSEAlgorithm: '{{SSEAlgorithm}}'
isEnd: true
```
------
#### [ JSON ]
```
{
"description": "Enables encryption on an Amazon S3 bucket",
"schemaVersion": "0.3",
"assumeRole": "{{ AutomationAssumeRole }}",
"parameters": {
"BucketName": {
"type": "AWS::S3::Bucket::Name",
"description": "(Required) The name of the Amazon S3 bucket you want to encrypt."
},
"SSEAlgorithm": {
"type": "String",
"description": "(Optional) The server-side encryption algorithm to use for the default encryption.",
"default": "AES256"
},
"AutomationAssumeRole": {
"type": "AWS::IAM::Role::Arn",
"description": "(Optional) The Amazon Resource Name (ARN) of the role that allows Automation to perform the actions on your behalf.",
"default": ""
}
},
"mainSteps": [
{
"name": "enableBucketEncryption",
"action": "aws:executeAwsApi",
"inputs": {
"Service": "s3",
"Api": "PutBucketEncryption",
"Bucket": "{{BucketName}}",
"ServerSideEncryptionConfiguration": {
"Rules": [
{
"ApplyServerSideEncryptionByDefault": {
"SSEAlgorithm": "{{SSEAlgorithm}}"
}
}
]
}
},
"isEnd": true
}
]
}
```
------
# Uso do Document Builder para criar runbooks
Se os runbooks públicos do AWS Systems Manager, não forem compatíveis com todas as ações que você quiser executar em seus recursos da AWS, você poderá criar seus próprios runbooks. Para criar um runbook personalizado, é possível criar manualmente um arquivo local em formato YAML ou JSON com as ações de automação apropriadas. Como alternativa, é possível usar o Document Builder no console do Systems Manager Automation para criar um runbook personalizado.
Usando o Document Builder, é possível adicionar etapas de ação de automação ao runbook personalizado e fornecer os parâmetros necessários sem precisar usar sintaxes JSON ou YAML. Depois de adicionar etapas e criar o runbook, o sistema converterá as ações adicionadas para o formato YAML que o Systems Manager poderá usar para executar a automação.
Runbooks são compatíveis com o uso de Markdown, uma linguagem de marcação que permite adicionar descrições do estilo wiki a runbooks e etapas individuais dentro do runbook. Para obter mais informações sobre como usar Markdown, consulte [Usar Markdown na AWS](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html).
## Criação de um runbook usando o Document Builder
**Antes de começar**
Recomendamos que você leia sobre as diferentes ações que podem ser usadas em um runbook. Para obter mais informações, consulte [Referência de ações do Systems Manager Automation](automation-actions.md).
**Para criar um runbook usando o Document Builder**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Documents**.
1. Escolha **Criar automação**.
1. Em **Name** (Nome), insira um nome descritivo para o runbook.
1. Em **Document description (Descrição do documento)**, forneça a descrição de estilo markdown para o runbook. Você pode fornecer instruções para usar o runbook, as etapas numeradas ou qualquer outro tipo de informação para descrever o runbook. Consulte o texto padrão para obter informações sobre como formatar o conteúdo.
**dica**
Alterne entre **Hide preview (Ocultar visualização)** e **Show preview (Exibir visualização)** para ver a aparência do conteúdo de descrição à medida que redige.
1. (Opcional) Em **Assume role (Função assumida)**, insira o nome ou ARN de uma função de serviço para executar ações em seu nome. Se você não especificar uma função, o Automation usará as permissões de acesso do usuário que executar a automação.
**Importante**
Para runbooks não pertencentes à Amazon que usam a ação `aws:executeScript`, uma função deverá ser especificada. Para mais informações, consulte [Permissões para usar runbooks](automation-document-script-considerations.md#script-permissions).
1. (Opcional) Em **Outputs (Saídas)**, insira saídas para a automação desse runbook a serem disponibilizadas para outros processos.
Por exemplo, se o runbook criar uma nova AMI, você poderá especificar ["CreateImage.ImageId"] e usar essa saída para criar novas instâncias em uma automação subsequente.
1. (Opcional) Expanda a seção **Input parameters (Parâmetros de entrada)** e faça o seguinte.
1. Em **Parameter name** (Nome do parâmetro), insira um nome descritivo para o parâmetro do runbook que estiver criando.
1. Em **Type (Tipo)**, escolha um tipo para o parâmetro, como `String` ou `MapList`.
1. Em **Required (Obrigatório)**, siga um destes procedimentos:
+ Escolha **Yes** (Sim) se um valor para esse parâmetro de runbook precisar ser fornecido no runtime.
+ Selecione **No** (Não) se o parâmetro não for obrigatório e insira um valor de parâmetro padrão (opcional) em **Default value** (Valor padrão).
1. Em **Description** (Descrição), insira uma descrição para o parâmetro do runbook.
**nota**
Para adicionar mais parâmetros do runbook, escolha **Add a parameter** (Adicionar um parâmetro). Para remover um parâmetro do runbook, escolha o botão **X** (Remover).
1. (Opcional) Expanda a seção **Target type** (Tipo de destino) e escolha um tipo de destino para definir os tipos de recursos nos quais a automação pode ser executada. Por exemplo, para executar um runbook em instâncias do EC2, escolha `/AWS::EC2::Instance`.
**nota**
Se você especificar um valor de “`/`”, o runbook poderá ser executado em todos os tipos de recursos. Para obter uma lista dos tipos de recursos válidos, consulte [Referência de tipos de recursos da AWS](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html) no *Manual do usuário do AWS CloudFormation*.
1. (Opcional) Expanda a seção **Document tags** (Tags de documento) e insira um ou mais pares de chave-valor para aplicar ao runbook. As tags facilitam a identificação, organização e pesquisa de recursos.
1. Na seção **Step 1 (Etapa 1)**, forneça as seguintes informações.
+ Em **Step name** (Nome da etapa), insira um nome descritivo para a primeira etapa da automação.
+ Para **Action type (Tipo de ação)**, selecione o tipo de ação a ser usado para esta etapa.
Para obter uma lista e informações sobre os tipos de ação disponíveis, consulte [Referência de ações do Systems Manager Automation](automation-actions.md).
+ Em **Description (Descrição)**, insira uma descrição para a etapa de automação. Você pode usar Markdown para formatar o texto.
+ Dependendo do **Action type (Tipo de ação)** selecionado, insira as entradas necessárias para o tipo de ação na seção **Step inputs (Entradas da etapa)**. Por exemplo, se você selecionou a ação `aws:approve`, deverá especificar um valor para a propriedade `Approvers`.
Para obter informações sobre os campos de entrada de etapa, consulte a entrada em [Referência de ações do Systems Manager Automation](automation-actions.md) para o tipo de ação selecionado. Por exemplo: [`aws:executeStateMachine` – Executa uma máquina de estado do AWS Step Functions](automation-action-executeStateMachine.md).
+ (Opcional) Em **Additional inputs** (Entradas adicionais), forneça os valores de entrada adicionais necessários para o runbook. Os tipos de entrada disponíveis dependem do tipo de ação selecionado para a etapa. (Observe que alguns tipos de ação exigem valores de entrada.)
**nota**
Para adicionar mais entradas, escolha **Add optional input (Adicionar entrada opcional)**. Para remover uma entrada, escolha o botão **X** (Remover).
+ (Opcional) Em **Outputs (Saídas)**, insira saídas para essa etapa a serem disponibilizadas para outros processos.
**nota**
**Outputs (Saídas)** não está disponível para todos os tipos de ação.
+ (Opcional) Expanda a seção **Common properties** (Propriedades comuns) e especifique as propriedades para as ações comuns a todas as ações de automação. Por exemplo, em **Timeout seconds** (Segundos de tempo limite), você pode fornecer um valor em segundos para especificar quanto tempo a etapa pode ser executada antes de ser interrompida.
Para obter mais informações, consulte [Propriedades compartilhadas por todas as ações](automation-actions.md#automation-common).
**nota**
Para adicionar mais etapas, selecione **Add step** (Adicionar etapa) e repita o procedimento de criação de uma etapa. Para remover uma etapa, escolha **Remove step** (Remover etapa).
1. Escolha **Create automation** (Criar automação) para salvar o runbook.
## Crie um runbook que execute scripts
O procedimento a seguir mostra como usar o Document Builder no console do AWS Systems Manager Automation para criar um runbook personalizado que execute um script.
A primeira etapa do runbook criado executa um script para executar uma instância do Amazon Elastic Compute Cloud (Amazon EC2). A segunda etapa executa outro script para monitorar para que a verificação de status da instância seja alterada `ok`. Depois, um status geral de `Success` é relatado para a automação.
**Antes de começar**
Você deve ter concluído as etapas a seguir:
+ Verifique se você tem privilégios de administrador ou se recebeu as permissões adequadas para acessar o Systems Manager no AWS Identity and Access Management (IAM).
Para mais informações, consulte [Verificar o acesso do usuário aos runbooks](automation-setup.md#automation-setup-user-access).
+ Verifique se você tem uma função de serviço do IAM para o Automation (também conhecida como uma *função assumida*) em sua Conta da AWS. A função é necessária pois essa demonstração usa a ação `aws:executeScript`.
Para obter informações sobre como criar essa função, consulte [Configurar o acesso a uma função de serviço (função assumida) para automações](automation-setup.md#automation-setup-configure-role).
Para obter informações sobre o requisito de função de serviço do IAM para a execução do `aws:executeScript`, consulte [Permissões para usar runbooks](automation-document-script-considerations.md#script-permissions).
+ Verifique se você tem permissão para executar instâncias do EC2.
Para obter informações, consulte [IAM e Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/UsingIAM.html#intro-to-iam) no *Guia do usuário do Amazon EC2*.
**Para criar um runbook personalizado usando o Document Builder**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Documents**.
1. Escolha **Criar automação**.
1. Em **Name (Nome)**, digite este nome descritivo para o runbook: **LaunchInstanceAndCheckStatus**.
1. (Opcional) Em **Document description** (Descrição do documento), substitua o texto padrão por uma descrição desse runbook, usando Markdown (Marcação). Veja um exemplo a seguir.
```
##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 2023 AMI ID available. | {{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64 }}
```
1. Em **Assume role** (Função assumida) insira o ARN da função de serviço do IAM para o Automation (função assumida) para a execução de automação, no formato **arn:aws:iam::111122223333:role/AutomationServiceRole**. Substitua o ID da Conta da AWS por 111122223333.
A função especificada é usada para fornecer as permissões necessárias para iniciar a automação.
**Importante**
Para runbooks não pertencentes à Amazon que usam a ação `aws:executeScript`, uma função deverá ser especificada. Para mais informações, consulte [Permissões para usar runbooks](automation-document-script-considerations.md#script-permissions).
1. Expanda **Input parameters (Parâmetros de entrada)** e faça o seguinte.
1. Em **Parameter name (Nome do parâmetro)**, insira **imageId**.
1. Em **Type (Tipo)**, escolha **String**.
1. Em **Required (Obrigatório)**, escolha `No`.
1. Em **Default value (Valor padrão)**, insira o seguinte.
```
{{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64 }}
```
**nota**
Esse valor executa uma instância do Amazon EC2 usando o ID da Amazon Machine Image (AMI) do Amazon Linux 2023 mais recente. Se você quiser usar uma AMI diferente, substitua o valor pelo ID da sua AMI.
1. Em **Description (Descrição)**, insira o seguinte.
```
(Optional) The AMI ID to use for launching the instance. The default value uses the latest released Amazon Linux 2023 AMI ID.
```
1. Escolha **Add a parameter (Adicionar um parâmetro)** para criar o segundo parâmetro, **tagValue**, e insira o seguinte.
1. Em **Parameter name (Nome do parâmetro)**, insira **tagValue**.
1. Em **Type (Tipo)**, escolha **String**.
1. Em **Required (Obrigatório)**, escolha `No`.
1. Em **Default value (Valor padrão)**, insira **LaunchedBySsmAutomation**. Isso adiciona o valor `Name:LaunchedBySsmAutomation` do par de chaves da tag à instância.
1. Em **Description (Descrição)**, insira o seguinte.
```
(Optional) The tag value to add to the instance. The default value is LaunchedBySsmAutomation.
```
1. Escolha **Add a parameter (Adicionar um parâmetro)** para criar o terceiro parâmetro, **instanceType**, e insira as informações a seguir.
1. Em **Parameter name (Nome do parâmetro)**, insira **instanceType**.
1. Em **Type (Tipo)**, escolha **String**.
1. Em **Required (Obrigatório)**, escolha `No`.
1. Em **Default value (Valor padrão)**, insira **t2.micro**.
1. Em **Parameter description (Descrição do parâmetro)**, insira o seguinte.
```
(Optional) The instance type to use for the instance. The default value is t2.micro.
```
1. Expanda **Target type (Tipo de destino)** e escolha **"/"**.
1. (Opcional) Expanda **Document tags** (Tags do documento) para aplicar tags de recurso ao runbook. Em **Tag key (Chave de tag)**, insira **Purpose** e, em **Tag value (Valor da tag)**, insira **LaunchInstanceAndCheckState**.
1. Na seção **Step 1 (Etapa 1)**, conclua as etapas a seguir.
1. Em **Step name (Nome da etapa)**, insira este nome descritivo para a primeira etapa da automação: **LaunchEc2Instance**.
1. Em **Action type (Tipo de ação)**, escolha **Run a script (Executar um script)** (**aws:executeScript**).
1. Em **Description (Descrição)**, insira uma descrição para a etapa de automação, como a seguinte.
```
**About This Step**
This step first launches an EC2 instance using the ```aws:executeScript``` action and the provided script.
```
1. Expanda **Inputs (Entradas)**.
1. Em **Runtime**, escolha a linguagem do runtime a ser usada para executar o script fornecido.
1. Em **Handler (Manipulador)**, insira **launch\$1instance**. Esse é o nome da função declarado no script a seguir.
**nota**
Isso não é necessário para o PowerShell.
1. Em **Script**, substitua o conteúdo padrão pelo seguinte. Certifique-se de corresponder o script com o valor de runtime correspondente.
------
#### [ 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}
```
------
1. Expanda **Additional inputs (Entradas adicionais)**.
1. Em **Input name (Nome da entrada)**, escolha **InputPayload**. Em **Input value (Valor de entrada)**, insira os dados YAML a seguir.
```
image_id: "{{ imageId }}"
tag_value: "{{ tagValue }}"
instance_type: "{{ instanceType }}"
```
1. Expanda **Outputs (Saídas)** e faça o seguinte:
+ Em **Nome**, digite **payload**.
+ Em **Selector (Seletor)**, insira **\$1.Payload**.
+ Em **Type (Tipo)**, escolha `StringMap`.
1. Selecione **Add step** (Adicionar etapa) para adicionar uma segunda etapa ao runbook. A segunda etapa consulta o status da instância executada na Etapa 1 e aguarda até que o status retornado seja `ok`.
1. Na seção **Step 2 (Etapa 2)**, faça o seguinte.
1. Em **Step name** (Nome da etapa), insira este nome descritivo para a segunda etapa da automação: **WaitForInstanceStatusOk**.
1. Em **Action type (Tipo de ação)**, escolha **Run a script (Executar um script)** (**aws:executeScript**).
1. Em **Description (Descrição)**, insira uma descrição para a etapa de automação, como a seguinte.
```
**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.
```
1. Em **Runtime**, escolha a linguagem do runtime a ser usada para executar o script fornecido.
1. Em **Handler (Manipulador)**, insira **poll\$1instance**. Esse é o nome da função declarado no script a seguir.
**nota**
Isso não é necessário para o PowerShell.
1. Em **Script**, substitua o conteúdo padrão pelo seguinte. Certifique-se de corresponder o script com o valor de runtime correspondente.
------
#### [ 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}
```
------
1. Expanda **Additional inputs (Entradas adicionais)**.
1. Em **Input name (Nome da entrada)**, escolha **InputPayload**. Em **Input value (Valor de entrada)**, insira o seguinte:
```
{{ LaunchEc2Instance.payload }}
```
1. Escolha **Create automation** (Criar automação) para salvar o runbook.
# Uso de scripts em runbooks
Runbooks do Automation oferecem suporte à execução de scripts como parte da automação. O Automation é uma ferramenta do AWS Systems Manager. Usando runbooks, você pode executar scripts diretamente na AWS sem precisar criar um ambiente de computação separado para executar os scripts. Como os documentos de automação podem executar etapas de script junto com outros tipos de etapas de automação, como aprovações, você pode intervir manualmente em situações críticas ou ambíguas. Você pode enviar o resultados das ações do `aws:executeScript` nos runbooks para o Amazon CloudWatch Logs. Para obter mais informações, consulte [Registro de saída de ações do Automation em log com o CloudWatch Logs](automation-action-logging.md).
## Permissões para usar runbooks
Para usar um runbook, o Systems Manager deve usar as permissões de uma função do AWS Identity and Access Management (IAM). O método usado pelo Automation para determinar quais permissões da função usar depende de alguns fatores e se uma etapa usa a ação `aws:executeScript`.
Para runbooks que não usam o `aws:executeScript`, o Automation usa uma das duas fontes de permissões:
+ As permissões de uma função de serviço do IAM, ou função assumida, que é especificada no runbook ou transmitida como um parâmetro.
+ Se nenhum perfil de serviço do IAM estiver especificado, as permissões do usuário que iniciou a automação.
Quando uma etapa em um documento do runbook incluir a ação `aws:executeScript`, uma função de serviço do IAM (função assumida) sempre será necessária se o script do Python ou PowerShell especificado para a ação estiver chamando quaisquer ações da API da AWS. A automação verifica a existência dessa função na seguinte ordem:
+ As permissões de uma função de serviço do IAM, ou função assumida, que é especificada no runbook ou transmitida como um parâmetro.
+ Se nenhuma função for encontrada, o Automation tentará executar o script do Python ou PowerShell especificado para `aws:executeScript` sem permissões. Se o script estiver chamando uma operação de API da AWS (por exemplo, a operação Amazon EC2 `CreateImage`), ou tentando agir em um recurso da AWS (como uma instância do EC2), a etapa que contém o script falhará e o Systems Manager retornará uma mensagem de erro relatando a falha.
## Adicionar scripts a runbooks
Você pode adicionar scripts aos runbooks, incluindo o script em linha como parte de uma etapa no runbook. Também é possível anexar scripts ao runbook fazendo upload dos scripts de sua máquina local ou especificando um bucket do Amazon Simple Storage Service (Amazon S3) onde os scripts estão localizados. Após a conclusão de uma etapa que executa um script, o resultado do script estará disponível como um objeto JSON, que poderá ser usado como entrada para etapas subsequentes no runbook. Para obter mais informações sobre a ação `aws:executeScript` e como usar anexos para scripts, consulte [`aws:executeScript` – Executa um script](automation-action-executeScript.md).
## Restrições de script para runbooks
Runbooks impõem um limite de cinco anexos do arquivo. Os scripts podem ser na forma de um script do Python (.py), um script do PowerShell Core (.ps1) ou anexados como conteúdo em um arquivo .zip.
# Uso de instruções condicionais em runbooks
Por padrão, as etapas que você define na seção `mainSteps` de um runbook são executadas em ordem sequencial. Depois que uma ação é concluída, a próxima ação especificada na seção `mainSteps` começa. Além disso, se uma ação falhar, todo a automação falhará (por padrão). Você pode usar a ação de automação `aws:branch` e as opções do runbook descritas nesta seção para criar automações que executam *ramificações condicionais*. Isso significa que você pode criar fluxos automações que vão para outra etapa após avaliar diferentes escolhas ou que dinamicamente respondem a alterações quando uma etapa é concluída. Veja a seguir uma lista de opções que você pode usar para criar fluxos de trabalho de automação dinâmicos:
+ **`aws:branch`**: esta ação de automação permite que você crie a automação dinâmica que avalia várias opções em uma única etapa e, em seguida, salta para outra etapa no runbook com base nos resultados da avaliação.
+ **`nextStep`**: esta opção especifica qual etapa de uma automação deve ser processada imediatamente após a conclusão bem-sucedida de uma etapa.
+ **`isEnd`**: esta opção interrompe a execução de uma automação no final de determinada etapa. O valor padrão desta opção é falso.
+ **`isCritical`**: esta opção designa uma etapa como essencial para a conclusão bem-sucedida da automação. Se uma etapa com essa designação falhar, o Automation relatará o status final da automação como `Failed`. O valor padrão desta opção é `true`.
+ **`onFailure`**: esta opção indica se a automação deve ser anulada, deve continuar ou seguir para outra etapa, em caso de falha. O valor padrão desta opção é anular.
A seção a seguir descreve a ação de automação `aws:branch`. Para obter mais informações sobre as opções do `nextStep`, `isEnd`, `isCritical` e `onFailure`, consulte [Runbooks `aws:branch` de exemplo](#branch-runbook-examples).
## Trabalhar com a ação `aws:branch`
A ação `aws:branch` oferece as opções de ramificação condicional mais dinâmicas para automações. Como mencionado anteriormente, essa ação permite que a automação avalie várias condições em uma única etapa e depois vá para uma nova etapa com base nos resultados da avaliação. A ação `aws:branch` funciona como uma instrução `IF-ELIF-ELSE` na programação.
Veja a seguir um exemplo de YAML de uma etapa `aws:branch`:
```
- name: ChooseOSforCommands
action: aws:branch
inputs:
Choices:
- NextStep: runPowerShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Windows
- NextStep: runShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Linux
Default:
PostProcessing
```
Quando você especifica a ação `aws:branch` para uma etapa, você especifica as `Choices` que a automação deve avaliar. A automação pode avaliar as `Choices` com base no valor de um parâmetro especificado na seção `Parameters` do runbook. A automação também pode avaliar as `Choices` com base no resultado de uma etapa anterior.
A automação avalia cada opção usando uma expressão booleana. Se a avaliação determinar que a primeira opção é `true`, a automação pulará para a etapa designada para essa opção. Se a avaliação determinar que a primeira opção é `false`, a automação avaliará a próxima opção. Se a sua etapa inclui três `Choices` ou mais, a automação avaliará cada opção em ordem sequencial até avaliar uma opção que seja `true`. A automação pula para a etapa designada para a opção `true`.
Se nenhuma das `Choices` for `true`, a automação verificará se a etapa contém um valor `Default`. Um valor `Default` define uma etapa para a qual a automação deve saltar, se nenhuma das opções for `true`. Se nenhum valor `Default` for especificado para a etapa, a automação processará a próxima etapa no runbook.
Aqui está uma etapa `aws:branch` em YAML chamada **chooseOSfromParameter**. A etapa inclui duas `Choices`: (`NextStep: runWindowsCommand`) e (`NextStep: runLinuxCommand`). A automação avalia essas `Choices` para determinar qual comando deve ser executado para o sistema operacional apropriado. A `Variable` para cada opção usa `{{OSName}}`, que é um parâmetro que o autor do runbook definiu na seção `Parameters` do runbook.
```
mainSteps:
- name: chooseOSfromParameter
action: aws:branch
inputs:
Choices:
- NextStep: runWindowsCommand
Variable: "{{OSName}}"
StringEquals: Windows
- NextStep: runLinuxCommand
Variable: "{{OSName}}"
StringEquals: Linux
```
Aqui está uma etapa `aws:branch` em YAML chamada **chooseOSfromOutput**. A etapa inclui duas `Choices`: (`NextStep: runPowerShellCommand`) e (`NextStep: runShellCommand`). A automação avalia essas `Choices` para determinar qual comando deve ser executado para o sistema operacional apropriado. A `Variable` para cada opção usa `{{GetInstance.platform}}`, que é o resultado de uma etapa anterior no runbook. Este exemplo também inclui uma opção chamada `Default`. Se a automação avaliar as duas `Choices`, e nenhuma opção for `true`, a automação pulará para uma etapa chamada `PostProcessing`.
```
mainSteps:
- name: chooseOSfromOutput
action: aws:branch
inputs:
Choices:
- NextStep: runPowerShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Windows
- NextStep: runShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Linux
Default:
PostProcessing
```
### Criar uma etapa `aws:branch` em um runbook
Quando você cria uma etapa `aws:branch` em um runbook, você define as `Choices` que a automação deve avaliar para determinar a etapa que a automação deve passar em seguida. Como mencionado anteriormente, `Choices` são avaliadas usando uma expressão booliana. Cada opção deve definir as seguintes opções:
+ **NextStep**: a próxima etapa no runbook para processar se a opção designada é `true`.
+ **Variável**: especifique o nome de um parâmetro definido na seção `Parameters` do runbook, uma variável definida na seção `Variables` ou especifique um objeto de saída de uma etapa anterior.
Especifique valores de variáveis usando o formato a seguir.
`Variable: "{{variable name}}"`
Especifique valores de parâmetros usando o formato a seguir.
`Variable: "{{parameter name}}"`
Especifique variáveis de objetos de saída usando o seguinte formato:
`Variable: "{{previousStepName.outputName}}"`
**nota**
A criação da variável de saída é descrita em mais detalhes na próxima seção, [Sobre a criação de variáveis de saída](#branch-action-output).
+ **Operação**: os critérios usados para avaliar a escolha, como `StringEquals: Linux`. A ação `aws:branch` oferece suporte às seguintes operações:
**Operações de string**
+ StringEquals
+ EqualsIgnoreCase
+ StartsWith
+ EndsWith
+ Contém
**Operações numéricas**
+ NumericEquals
+ NumericGreater
+ NumericLesser
+ NumericGreaterOrEquals
+ NumericLesser
+ NumericLesserOrEquals
**Operação booleana**
+ BooleanEquals
**Importante**
Quando você cria um runbook, o sistema valida cada operação dele. Se uma operação não for suportada, o sistema retornará um erro ao tentar criar o runbook.
+ **Padrão**: especifique uma etapa de contingência para a qual a automação deve ir se nenhuma das `Choices` for `true`.
**nota**
Se você não quiser especificar um valor `Default`, especifique a opção `isEnd`. Se nenhuma das `Choices` for `true` e nenhum valor `Default` for especificado, a automação será interrompida no final da etapa.
Use os modelos a seguir para ajudar a construir a etapa `aws:branch` no runbook. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
------
#### [ YAML ]
```
mainSteps:
- name: step name
action: aws:branch
inputs:
Choices:
- NextStep: step to jump to if evaluation for this choice is true
Variable: "{{parameter name or output from previous step}}"
Operation type: Operation value
- NextStep: step to jump to if evaluation for this choice is true
Variable: "{{parameter name or output from previous step}}"
Operation type: Operation value
Default:
step to jump to if all choices are false
```
------
#### [ JSON ]
```
{
"mainSteps":[
{
"name":"a name for the step",
"action":"aws:branch",
"inputs":{
"Choices":[
{
"NextStep":"step to jump to if evaluation for this choice is true",
"Variable":"{{parameter name or output from previous step}}",
"Operation type":"Operation value"
},
{
"NextStep":"step to jump to if evaluation for this choice is true",
"Variable":"{{parameter name or output from previous step}}",
"Operation type":"Operation value"
}
],
"Default":"step to jump to if all choices are false"
}
}
]
}
```
------
#### Sobre a criação de variáveis de saída
Para criar uma opção `aws:branch` que faz referência à saída de uma etapa anterior, você precisa identificar o nome da etapa anterior e o nome do campo de saída. Você então combina os nomes da etapa e o campo usando o seguinte formato:
`Variable: "{{previousStepName.outputName}}"`
Por exemplo, a primeira etapa do exemplo a seguir é chamada de `GetInstance`. Depois, em `outputs`, há um campo chamado `platform`. Na segunda etapa (`ChooseOSforCommands`), o autor deseja fazer referência à saída do campo de plataforma como uma variável. Para criar a variável, basta combinar o nome da etapa (GetInstance) e o nome do campo de saída (plataforma) para criar `Variable: "{{GetInstance.platform}}"`.
```
mainSteps:
- Name: GetInstance
action: aws:executeAwsApi
inputs:
Service: ssm
Api: DescribeInstanceInformation
Filters:
- Key: InstanceIds
Values: ["{{ InstanceId }}"]
outputs:
- Name: myInstance
Selector: "$.InstanceInformationList[0].InstanceId"
Type: String
- Name: platform
Selector: "$.InstanceInformationList[0].PlatformType"
Type: String
- name: ChooseOSforCommands
action: aws:branch
inputs:
Choices:
- NextStep: runPowerShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Windows
- NextStep: runShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Linux
Default:
Sleep
```
Aqui está um exemplo que mostra como *"Variable": "\$1\$1describeInstance.Platform\$1\$1"* é criado na etapa anterior e na saída.
```
- name: describeInstance
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- "{{ InstanceId }}"
outputs:
- Name: Platform
Selector: "$.Reservations[0].Instances[0].Platform"
Type: String
nextStep: branchOnInstancePlatform
- name: branchOnInstancePlatform
action: aws:branch
inputs:
Choices:
- NextStep: runEC2RescueForWindows
Variable: "{{ describeInstance.Platform }}"
StringEquals: windows
Default: runEC2RescueForLinux
```
### Runbooks `aws:branch` de exemplo
Aqui estão alguns exemplos de runbooks que usam o `aws:branch`.
**Exemplo 1: usar `aws:branch` com uma variável de saída para executar comandos com base no tipo de sistema operacional**
Na primeira etapa deste exemplo (`GetInstance`), o autor do runbook usa a ação `aws:executeAwsApi` para chamar a operação de API `ssm` `DescribeInstanceInformation`. O autor usa essa ação para determinar o tipo de sistema operacional que está sendo usado por uma instância. A ação `aws:executeAwsApi` emite o ID da instância e o tipo de plataforma.
Na segunda etapa (`ChooseOSforCommands`), o autor usa a ação `aws:branch` com duas `Choices` (`NextStep: runPowerShellCommand`) e (`NextStep: runShellCommand`). A automação avalia o sistema operacional da instância usando o resultado da etapa anterior (`Variable: "{{GetInstance.platform}}"`). A automação pula para uma etapa do sistema operacional designado.
```
---
schemaVersion: '0.3'
assumeRole: "{{AutomationAssumeRole}}"
parameters:
AutomationAssumeRole:
default: ""
type: String
mainSteps:
- name: GetInstance
action: aws:executeAwsApi
inputs:
Service: ssm
Api: DescribeInstanceInformation
outputs:
- Name: myInstance
Selector: "$.InstanceInformationList[0].InstanceId"
Type: String
- Name: platform
Selector: "$.InstanceInformationList[0].PlatformType"
Type: String
- name: ChooseOSforCommands
action: aws:branch
inputs:
Choices:
- NextStep: runPowerShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Windows
- NextStep: runShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Linux
Default:
Sleep
- name: runShellCommand
action: aws:runCommand
inputs:
DocumentName: AWS-RunShellScript
InstanceIds:
- "{{GetInstance.myInstance}}"
Parameters:
commands:
- ls
isEnd: true
- name: runPowerShellCommand
action: aws:runCommand
inputs:
DocumentName: AWS-RunPowerShellScript
InstanceIds:
- "{{GetInstance.myInstance}}"
Parameters:
commands:
- ls
isEnd: true
- name: Sleep
action: aws:sleep
inputs:
Duration: PT3S
```
**Exemplo 2: usar `aws:branch` com uma variável de parâmetro para executar comandos com base no tipo de sistema operacional**
O autor do runbook define várias opções de parâmetro no início do runbook, na seção `parameters`. Um parâmetro é chamado de `OperatingSystemName`. Na primeira etapa (`ChooseOS`), o autor usa a ação `aws:branch` com duas `Choices` (`NextStep: runWindowsCommand`) e (`NextStep: runLinuxCommand`). A variável para essas `Choices` faz referência à opção de parâmetro especificada na seção de parâmetros (`Variable: "{{OperatingSystemName}}"`). Quando o usuário executa esse runbook, ele especifica um valor em runtime para `OperatingSystemName`. A automação usa o parâmetro de runtime durante a avaliação das `Choices`. A automação pula para uma etapa do sistema operacional designado com base no parâmetro do runtime para `OperatingSystemName`.
```
---
schemaVersion: '0.3'
assumeRole: "{{AutomationAssumeRole}}"
parameters:
AutomationAssumeRole:
default: ""
type: String
OperatingSystemName:
type: String
LinuxInstanceId:
type: String
WindowsInstanceId:
type: String
mainSteps:
- name: ChooseOS
action: aws:branch
inputs:
Choices:
- NextStep: runWindowsCommand
Variable: "{{OperatingSystemName}}"
StringEquals: windows
- NextStep: runLinuxCommand
Variable: "{{OperatingSystemName}}"
StringEquals: linux
Default:
Sleep
- name: runLinuxCommand
action: aws:runCommand
inputs:
DocumentName: "AWS-RunShellScript"
InstanceIds:
- "{{LinuxInstanceId}}"
Parameters:
commands:
- ls
isEnd: true
- name: runWindowsCommand
action: aws:runCommand
inputs:
DocumentName: "AWS-RunPowerShellScript"
InstanceIds:
- "{{WindowsInstanceId}}"
Parameters:
commands:
- date
isEnd: true
- name: Sleep
action: aws:sleep
inputs:
Duration: PT3S
```
### Criar automações de ramificação complexas com operadores
Você pode criar automações de ramificação complexas usando os operadores `And`, `Or`, e `Not` em suas etapas `aws:branch`.
**O operador 'And' (‘E’)**
Use o operador `And` quando você quiser que muitas variáveis sejam `true` para uma opção. No exemplo a seguir, a primeira opção avalia se uma instância está `running` e usa o sistema operacional `Windows`. Se a avaliação de *ambas* as variáveis for verdadeira, a automação pulará para a etapa `runPowerShellCommand`. Se uma ou mais das variáveis for `false`, a automação avaliará as variáveis para a segunda opção.
```
mainSteps:
- name: switch2
action: aws:branch
inputs:
Choices:
- And:
- Variable: "{{GetInstance.pingStatus}}"
StringEquals: running
- Variable: "{{GetInstance.platform}}"
StringEquals: Windows
NextStep: runPowerShellCommand
- And:
- Variable: "{{GetInstance.pingStatus}}"
StringEquals: running
- Variable: "{{GetInstance.platform}}"
StringEquals: Linux
NextStep: runShellCommand
Default:
sleep3
```
**O operador 'Or' (‘Ou’)**
Use o operador `Or` quando você quiser que *qualquer* de diversas variáveis sejam verdadeiras para uma opção. No exemplo a seguir, a primeira opção avalia se uma string de parâmetro é `Windows` e se a saída de uma etapa AWS Lambda é verdadeira. Se a avaliação determinar que *qualquer uma* das variáveis é verdadeira, a automação pulará para a etapa `RunPowerShellCommand`. Se as duas variáveis forem falsas, a automação avaliará as variáveis para a segunda opção.
```
- Or:
- Variable: "{{parameter1}}"
StringEquals: Windows
- Variable: "{{BooleanParam1}}"
BooleanEquals: true
NextStep: RunPowershellCommand
- Or:
- Variable: "{{parameter2}}"
StringEquals: Linux
- Variable: "{{BooleanParam2}}"
BooleanEquals: true
NextStep: RunShellScript
```
**O operador 'Not' (‘Não’)**
Use o operador `Not` quando você desejar pular para uma etapa definida quando uma variável *não* for verdadeira. No exemplo a seguir, a primeira opção avalia se uma string de parâmetro é `Not Linux`. Se a avaliação determinar que a variável não é Linux, a automação pulará para a etapa `sleep2`. Se a avaliação da primeira opção determinar que ela *é* Linux, a automação avaliará a próxima opção.
```
mainSteps:
- name: switch
action: aws:branch
inputs:
Choices:
- NextStep: sleep2
Not:
Variable: "{{testParam}}"
StringEquals: Linux
- NextStep: sleep1
Variable: "{{testParam}}"
StringEquals: Windows
Default:
sleep3
```
## Exemplos de como usar opções condicionais
Esta seção inclui vários exemplos de como usar as opções dinâmicas em um runbook. Cada exemplo nesta seção estende o seguinte runbook: Este runbook tem duas ações. A primeira ação é chamada de `InstallMsiPackage`. Ela usa a ação `aws:runCommand` para instalar um aplicativo em uma instância do Windows Server. A segunda ação é chamada de `TestInstall`. Ela usa a ação `aws:invokeLambdaFunction` para executar um teste do aplicativo instalado, se o aplicativo foi instalado com êxito. A etapa um especifica `onFailure: Abort`. Isso significa que, se a instalação da aplicação não foi bem-sucedida, a automação será interrompida antes da segunda etapa.
**Exemplo 1: runbook com duas ações lineares**
```
---
schemaVersion: '0.3'
description: Install MSI package and run validation.
assumeRole: "{{automationAssumeRole}}"
parameters:
automationAssumeRole:
type: String
description: "(Required) Assume role."
packageName:
type: String
description: "(Required) MSI package to be installed."
instanceIds:
type: String
description: "(Required) Comma separated list of instances."
mainSteps:
- name: InstallMsiPackage
action: aws:runCommand
maxAttempts: 2
onFailure: Abort
inputs:
InstanceIds:
- "{{instanceIds}}"
DocumentName: AWS-RunPowerShellScript
Parameters:
commands:
- msiexec /i {{packageName}}
- name: TestInstall
action: aws:invokeLambdaFunction
maxAttempts: 1
timeoutSeconds: 500
inputs:
FunctionName: TestLambdaFunction
...
```
**Criar uma automação dinâmica que pula para etapas diferentes usando a opção `onFailure`**
O exemplo a seguir usa as opções `onFailure: step:step name`, `nextStep` e `isEnd` para criar uma automação dinâmica. Nesse exemplo, se a ação `InstallMsiPackage` falhar, a automação saltará para uma ação chamada *PostFailure* (`onFailure: step:PostFailure`) para executar uma função do AWS Lambda, a fim de realizar alguma ação no evento em que a instalação falhou. Se a instalação for bem-sucedida, o processo de automação pulará para a ação TestInstall (`nextStep: TestInstall`). Ambas as etapas `TestInstall` e `PostFailure` usam a opção `isEnd` (`isEnd: true`) para que a automação termine quando uma dessas etapas for concluída.
**nota**
O uso da opção `isEnd` na última etapa da seção `mainSteps` é opcional. Se a última etapa não pular para outras etapas, a automação será interrompida depois de executar a ação na última etapa.
**Exemplo 2: automação dinâmica que salta para diferentes etapas**
```
mainSteps
- name: InstallMsiPackage
action: aws:runCommand
onFailure: step:PostFailure
maxAttempts: 2
inputs:
InstanceIds:
- "{{instanceIds}}"
DocumentName: AWS-RunPowerShellScript
Parameters:
commands:
- msiexec /i {{packageName}}
nextStep: TestInstall
- name: TestInstall
action: aws:invokeLambdaFunction
maxAttempts: 1
timeoutSeconds: 500
inputs:
FunctionName: TestLambdaFunction
isEnd: true
- name: PostFailure
action: aws:invokeLambdaFunction
maxAttempts: 1
timeoutSeconds: 500
inputs:
FunctionName: PostFailureRecoveryLambdaFunction
isEnd: true
...
```
**nota**
Antes de processar um runbook, o sistema verifica se o runbook não cria um loop infinito. Se um loop infinito for detectado, a automação retornará um erro e um círculo de rastreamento mostrando as etapas que criam o loop.
**Criar uma automação dinâmica que define etapas essenciais**
Você pode especificar que uma etapa é essencial para o sucesso geral da automação. Se uma etapa essencial falhar, o Automation informará o status da automação como `Failed`, mesmo se uma ou mais etapas forem executadas com êxito. No exemplo a seguir, o usuário identifica a etapa *VerifyDependencies* se a etapa *InstallMsiPackage* falhar (`onFailure: step:VerifyDependencies`). O usuário especifica que a etapa `InstallMsiPackage` não é essencial (`isCritical: false`). Neste exemplo, se o aplicativo falhar ao instalar, a automação processará a etapa `VerifyDependencies` para determinar se uma ou mais dependências estão ausentes, o que deve ter causado a falha na instalação do aplicativo.
**Exemplo 3: definir as etapas essenciais para a automação **
```
---
name: InstallMsiPackage
action: aws:runCommand
onFailure: step:VerifyDependencies
isCritical: false
maxAttempts: 2
inputs:
InstanceIds:
- "{{instanceIds}}"
DocumentName: AWS-RunPowerShellScript
Parameters:
commands:
- msiexec /i {{packageName}}
nextStep: TestPackage
...
```
# Uso de saídas de ações como entradas
Várias ações de automação retornam saídas predefinidas. Você pode passar essas saídas como entradas para etapas posteriores em seu runbook usando o formato `{{stepName.outputName}}`. Também é possível definir saídas personalizadas para várias ações de automação em seus runbooks. Isso permite que você execute scripts ou invoque operações de API para outros Serviços da AWS uma vez, para que você possa reutilizar os valores como entradas em ações posteriores. Os tipos de parâmetro em runbooks são estáticos. Isso significa que o tipo de parâmetro não pode ser alterado depois de definido. Para definir uma saída de etapa, forneça os seguintes campos:
+ Nome (obrigatório): o nome da saída usado para referenciar o valor de saída em etapas posteriores.
+ Seletor (obrigatório): a expressão JSONPath usada para determinar o valor de saída.
+ Tipo (opcional): o tipo de dados do valor retornado pelo campo seletor. Os valores de tipo válidos são `String`, `Integer`, `Boolean`, `StringList` ,`StringMap`, `MapList`. O valor padrão é `String`.
Se o valor de uma saída não corresponder ao tipo de dados que você especificou, o Automation tentará converter o tipo de dados. Por exemplo, se o valor retornado for um `Integer`, mas o `Type` especificado for `String`, o valor final da saída será um valor `String`. As seguintes conversões de tipos são permitidas:
+ Valores `String` podem ser convertidos em `StringList`, `Integer` e `Boolean`.
+ Valores `Integer` podem ser convertidos em `String` e `StringList`.
+ Valores `Boolean` podem ser convertidos em `String` e `StringList`.
+ Valores `StringList`, `IntegerList` ou `BooleanList` contendo um elemento podem ser convertidos em `String`, `Integer` ou `Boolean`.
Ao usar parâmetros ou saídas com ações de automação, o tipo de dados não pode ser alterado dinamicamente na entrada de uma ação.
Aqui está um exemplo de runbook que demonstra como definir saídas de ações e como referenciar o valor como entrada para uma ação posterior. Os runbooks fazem o seguinte:
+ Usa a ação `aws:executeAwsApi` para chamar a operação de API do Amazon EC2 DescribeImages para obter o nome de uma determinada AMI do Windows Server 2016. Ela gera o ID de imagem como `ImageId`.
+ Usa a ação `aws:executeAwsApi` para chamar a operação de API do Amazon EC2 RunInstances para iniciar uma instância que usa o `ImageId` da etapa anterior. Ela gera o ID de instância como `InstanceId`.
+ Usa a ação ` aws:waitForAwsResourceProperty` para sondar a operação de API do Amazon EC2 DescribeInstanceStatus para aguardar que a instância alcance o estado `running`. A ação atinge o tempo limite em 60 segundos. A etapa atinge o limite de tempo se o estado da instância não chegar a `running` após 60 segundos de sondagem.
+ Usa a ação `aws:assertAwsResourceProperty` para chamar a operação da API `DescribeInstanceStatus` do Amazon EC2 para afirmar que a instância está no estado `running`. A etapa falhará se o estado da instância não for `running`.
```
---
description: Sample runbook using AWS API operations
schemaVersion: '0.3'
assumeRole: "{{ AutomationAssumeRole }}"
parameters:
AutomationAssumeRole:
type: String
description: "(Optional) The ARN of the role that allows Automation to perform the actions on your behalf."
default: ''
ImageName:
type: String
description: "(Optional) Image Name to launch EC2 instance with."
default: "Windows_Server-2022-English-Full-Base*"
mainSteps:
- name: getImageId
action: aws:executeAwsApi
inputs:
Service: ec2
Api: DescribeImages
Filters:
- Name: "name"
Values:
- "{{ ImageName }}"
outputs:
- Name: ImageId
Selector: "$.Images[0].ImageId"
Type: "String"
- name: launchOneInstance
action: aws:executeAwsApi
inputs:
Service: ec2
Api: RunInstances
ImageId: "{{ getImageId.ImageId }}"
MaxCount: 1
MinCount: 1
outputs:
- Name: InstanceId
Selector: "$.Instances[0].InstanceId"
Type: "String"
- name: waitUntilInstanceStateRunning
action: aws:waitForAwsResourceProperty
timeoutSeconds: 60
inputs:
Service: ec2
Api: DescribeInstanceStatus
InstanceIds:
- "{{ launchOneInstance.InstanceId }}"
PropertySelector: "$.InstanceStatuses[0].InstanceState.Name"
DesiredValues:
- running
- name: assertInstanceStateRunning
action: aws:assertAwsResourceProperty
inputs:
Service: ec2
Api: DescribeInstanceStatus
InstanceIds:
- "{{ launchOneInstance.InstanceId }}"
PropertySelector: "$.InstanceStatuses[0].InstanceState.Name"
DesiredValues:
- running
outputs:
- "launchOneInstance.InstanceId"
...
```
Cada uma das ações de automação descritas anteriormente permite que você chame uma operação de API específica, determinando o namespace do serviço, o nome da operação de API, os parâmetros de entrada e os parâmetros de saída. As entradas são definidas pela operação de API que você escolher. Você pode visualizar as operações de API (também chamadas de métodos), escolhendo um serviço na navegação à esquerda na seguinte página de [Referência de serviços](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html): Escolha um método na seção **Client (Cliente)** para o serviço que você deseja invocar. Por exemplo, todas as operações de API (métodos) do Amazon Relational Database Service (Amazon RDS) estão listadas na seguinte página: [Amazon RDS methods](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html) (Métodos do Amazon RDS).
Você pode visualizar o esquema para cada ação de automação nos seguintes locais:
+ [`aws:assertAwsResourceProperty`: define um estado do recurso da AWS ou o estado do evento](automation-action-assertAwsResourceProperty.md)
+ [`aws:executeAwsApi`: chama e executa as operações de API do AWS](automation-action-executeAwsApi.md)
+ [`aws:waitForAwsResourceProperty`: aguarde uma propriedade de recurso da AWS](automation-action-waitForAwsResourceProperty.md)
Os esquemas incluem as descrições dos campos obrigatórios para o uso de cada ação.
**Usar os campos Selector/PropertySelector (Seletor/Seletor de propriedades)**
Cada ação do Automation exige que você especifique uma saída `Selector` (para`aws:executeAwsApi`) ou um `PropertySelector` (para `aws:assertAwsResourceProperty` e `aws:waitForAwsResourceProperty`). Esses campos são usados para processar a resposta do JSON de uma operação de API da AWS. Esses campos usam a sintaxe JSONPath.
Este é um exemplo para ajudar a ilustrar esse conceito para a ação `aws:executeAwsAPi`:
```
---
mainSteps:
- name: getImageId
action: aws:executeAwsApi
inputs:
Service: ec2
Api: DescribeImages
Filters:
- Name: "name"
Values:
- "{{ ImageName }}"
outputs:
- Name: ImageId
Selector: "$.Images[0].ImageId"
Type: "String"
...
```
Na etapa `aws:executeAwsApi` do `getImageId`, a automação invoca a operação da API `DescribeImages` e recebe uma resposta do `ec2`. A automação então aplica `Selector - "$.Images[0].ImageId"` à resposta da API e atribui o valor selecionado à variável `ImageId` do resultado. Outras etapas na mesma automação podem usar o valor de `ImageId` especificando `"{{ getImageId.ImageId }}"`.
Este é um exemplo para ajudar a ilustrar esse conceito para a ação `aws:waitForAwsResourceProperty`:
```
---
- name: waitUntilInstanceStateRunning
action: aws:waitForAwsResourceProperty
# timeout is strongly encouraged for action - aws:waitForAwsResourceProperty
timeoutSeconds: 60
inputs:
Service: ec2
Api: DescribeInstanceStatus
InstanceIds:
- "{{ launchOneInstance.InstanceId }}"
PropertySelector: "$.InstanceStatuses[0].InstanceState.Name"
DesiredValues:
- running
...
```
Na etapa `aws:waitForAwsResourceProperty` do `waitUntilInstanceStateRunning`, a automação invoca a operação da API `DescribeInstanceStatus` e recebe uma resposta do `ec2`. Depois, a automação aplica `PropertySelector - "$.InstanceStatuses[0].InstanceState.Name"` à resposta e verifica se o valor retornado corresponde a um valor na lista `DesiredValues` (neste caso, `running`). A etapa repetirá o processo até que a resposta retorne um estado de instância de `running`.
## Uso de JSONPath em runbooks
Uma expressão JSONPath é uma string que começa com “\$1”. que é usado para selecionar um ou mais componentes em um elemento JSON. A lista a seguir inclui informações sobre operadores JSONPath que são compatíveis com o Systems Manager Automation:
+ **Filho com notação de pontos (.)**: use com um objeto JSON. Esse operador seleciona o valor de uma chave específica.
+ **Varredura profunda (..)**: use com um elemento JSON. Esse operador examina o elemento JSON nível por nível e seleciona uma lista de valores com a chave específica. O tipo de retorno desse operador é sempre uma matriz JSON. No contexto de um tipo de saída da etapa de automação, o operador pode ser StringList ou MapList.
+ **Índice de matriz ([ ])**: use com uma matriz JSON. Esse operador obtém o valor de um índice específico.
+ **Filtro ([?(*expression*)])**: use com uma matriz JSON. Esse operador filtra os valores da matriz JSON que correspondem aos critérios definidos na expressão do filtro. As expressões de filtro só podem usar os seguintes operadores: ==, \$1=, >, <, >= ou <=. A combinação de várias expressões de filtro com AND (&&) ou OR (\$1\$1) não é possível. O tipo de retorno desse operador é sempre uma matriz JSON.
Para compreender melhor os operadores JSONPath, revise a seguinte resposta do JSON da operação de API `DescribeInstances` do ec2. Abaixo dessa resposta estão vários exemplos que mostram resultados diferentes aplicando diferentes expressões JSONPath à com base na operação da API `DescribeInstances`.
```
{
"NextToken": "abcdefg",
"Reservations": [
{
"OwnerId": "123456789012",
"ReservationId": "r-abcd12345678910",
"Instances": [
{
"ImageId": "ami-12345678",
"BlockDeviceMappings": [
{
"Ebs": {
"DeleteOnTermination": true,
"Status": "attached",
"VolumeId": "vol-000000000000"
},
"DeviceName": "/dev/xvda"
}
],
"State": {
"Code": 16,
"Name": "running"
}
}
],
"Groups": []
},
{
"OwnerId": "123456789012",
"ReservationId": "r-12345678910abcd",
"Instances": [
{
"ImageId": "ami-12345678",
"BlockDeviceMappings": [
{
"Ebs": {
"DeleteOnTermination": true,
"Status": "attached",
"VolumeId": "vol-111111111111"
},
"DeviceName": "/dev/xvda"
}
],
"State": {
"Code": 80,
"Name": "stopped"
}
}
],
"Groups": []
}
]
}
```
**Exemplo 1 do JSONPath: obtenha uma string específica de uma resposta JSON**
```
JSONPath:
$.Reservations[0].Instances[0].ImageId
Returns:
"ami-12345678"
Type: String
```
**Exemplo 2 do JSONPath: obtenha um booliano específico de uma resposta JSON**
```
JSONPath:
$.Reservations[0].Instances[0].BlockDeviceMappings[0].Ebs.DeleteOnTermination
Returns:
true
Type: Boolean
```
**Exemplo 3 do JSONPath: obtenha um número inteiro específico de uma resposta JSON**
```
JSONPath:
$.Reservations[0].Instances[0].State.Code
Returns:
16
Type: Integer
```
**Exemplo 4 do JSONPath: faça uma verificação detalhada de uma resposta JSON e, em seguida, obtenha todos os valores para VolumeId como uma StringList**
```
JSONPath:
$.Reservations..BlockDeviceMappings..VolumeId
Returns:
[
"vol-000000000000",
"vol-111111111111"
]
Type: StringList
```
**Exemplo 5 do JSONPath: obter um objeto específico BlockDeviceMappings como um StringMap**
```
JSONPath:
$.Reservations[0].Instances[0].BlockDeviceMappings[0]
Returns:
{
"Ebs" : {
"DeleteOnTermination" : true,
"Status" : "attached",
"VolumeId" : "vol-000000000000"
},
"DeviceName" : "/dev/xvda"
}
Type: StringMap
```
**Exemplo 6 do JSONPath: faça uma verificação detalhada de uma resposta JSON e, em seguida, obtenha todos os objetos de estado como uma MapList**
```
JSONPath:
$.Reservations..Instances..State
Returns:
[
{
"Code" : 16,
"Name" : "running"
},
{
"Code" : 80,
"Name" : "stopped"
}
]
Type: MapList
```
**Exemplo 7 do JSONPath: filtro para instâncias no estado `running`**
```
JSONPath:
$.Reservations..Instances[?(@.State.Name == 'running')]
Returns:
[
{
"ImageId": "ami-12345678",
"BlockDeviceMappings": [
{
"Ebs": {
"DeleteOnTermination": true,
"Status": "attached",
"VolumeId": "vol-000000000000"
},
"DeviceName": "/dev/xvda"
}
],
"State": {
"Code": 16,
"Name": "running"
}
}
]
Type: MapList
```
**Exemplo 8 do JSONPath: retornar o `ImageId` de instâncias que não estão no estado `running`**
```
JSONPath:
$.Reservations..Instances[?(@.State.Name != 'running')].ImageId
Returns:
[
"ami-12345678"
]
Type: StringList | String
```
# Criação de integrações de webhooks para o Automation
Para enviar mensagens usando webhooks durante uma automação, crie uma integração. As integrações podem ser invocadas durante uma automação usando a ação `aws:invokeWebhook` em seu runbook. Se você ainda não criou um webhook, consulte [Criação de webhooks para integrações](#creating-webhooks). Para saber mais a respeito da ação `aws:invokeWebhook`, consulte [`aws:invokeWebhook` — Invoque uma integração de webhook do Automation](invoke-webhook.md).
Conforme mostrado nos procedimentos a seguir, você pode criar uma integração usando o console do Automation do Systems Manager ou sua ferramenta da linha de comando preferida.
## Criação de integrações (console)
**Para criar uma integração para o Automation (console)**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação à esquerda, escolha **Automation** (Automação).
1. Escolha a guia **Integrations** (Integrações).
1. Selecione **Add integration** (Adicionar integração), e escolha **Webhook**.
1. Insira os valores necessários e todos os valores opcionais que você deseja incluir para a integração.
1. Selecione **Add** (Adicionar) para criar a integração.
## Criação de integrações (linha de comando)
Para criar uma integração usando ferramentas da linha de comando, você deve criar o parâmetro `SecureString` necessário para uma integração. O Automation usa um namespace reservado no Parameter Store, uma ferramenta do Systems Manager, para armazenar informações sobre sua integração. Se você criar uma integração usando o Console de gerenciamento da AWS, o Automation lida com esse processo para você. Seguindo o namespace, você deve especificar o tipo de integração que deseja criar e, em seguida, o nome da sua integração. Atualmente, o Automation oferece suporte a Integrações do tipo `webhook`.
Os campos com suporte a integrações do tipo `webhook` são os seguintes:
+ Descrição
+ headers
+ payload
+ URL
**Antes de começar**
Caso ainda não tenha feito isso, instale e configure a AWS Command Line Interface (AWS CLI) ou o Ferramentas da AWS para PowerShell. Para obter informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) e [Instalar o Ferramentas da AWS para PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
**Para criar uma integração para o Automation (linha de comando)**
+ Execute os seguintes comandos para criar o parâmetro `SecureString` necessário para uma integração. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações. O namespace `/d9d01087-4a3f-49e0-b0b4-d568d7826553/ssm/integrations/webhook/` é reservado no Parameter Store para integrações. O nome do parâmetro deve usar esse namespace seguido do nome da sua integração. Por exemplo, . `/d9d01087-4a3f-49e0-b0b4-d568d7826553/ssm/integrations/webhook/myWebhookIntegration`.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name "/d9d01087-4a3f-49e0-b0b4-d568d7826553/ssm/integrations/webhook/myWebhookIntegration" \
--type "SecureString" \
--data-type "aws:ssm:integration" \
--value '{"description": "My first webhook integration for Automation.", "url": "myWebHookURL"}'
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name "/d9d01087-4a3f-49e0-b0b4-d568d7826553/ssm/integrations/webhook/myWebhookIntegration" ^
--type "SecureString" ^
--data-type "aws:ssm:integration" ^
--value "{\"description\":\"My first webhook integration for Automation.\",\"url\":\"myWebHookURL\"}"
```
------
#### [ PowerShell ]
```
Write-SSMParameter `
-Name "/d9d01087-4a3f-49e0-b0b4-d568d7826553/ssm/integrations/webhook/myWebhookIntegration" `
-Type "SecureString"
-DataType "aws:ssm:integration"
-Value '{"description": "My first webhook integration for Automation.", "url": "myWebHookURL"}'
```
------
## Criação de webhooks para integrações
Ao criar webhooks com seu provedor, observe o seguinte:
+ O protocolo deve ser o HTTPS.
+ Há suporte para os cabeçalhos de solicitação personalizados.
+ Um corpo da solicitação padrão pode ser especificado.
+ O corpo da solicitação padrão pode ser substituído quando uma integração for invocada usando a ação `aws:invokeWebhook`.
# Gerenciar tempos limite em runbooks
A propriedade `timeoutSeconds` é compartilhada por todas as ações de automação. Você pode usar essa propriedade para especificar o valor do tempo limite de execução de uma ação. Além disso, você pode alterar como um tempo limite de ação afeta a automação e o status geral da execução. Você pode fazer isso definindo também as propriedades compartilhadas `onFailure` e `isCritical` para uma ação.
Por exemplo, dependendo do caso de uso, quando uma ação atinge o tempo limite, você poderá preferir que a automação continue com uma ação diferente e não afete o status geral da automação. Neste exemplo, você especifica o tempo de espera antes que o tempo limite da ação seja esgotado usando a propriedade `timeoutSeconds`. Especifique então a ação ou etapa que a automação deve executar no caso do tempo limite expirar. Especifique um valor usando o formato `step:step name` da propriedade `onFailure`, em vez do valor padrão de `Abort`. Por padrão, se o tempo limite de uma ação expirar, o status de execução da automação será `Timed Out`. Para evitar que um tempo limite afete o status da execução da automação, especifique `false` para a propriedade `isCritical`.
O exemplo a seguir mostra como definir as propriedades compartilhadas para uma ação descrita nesse cenário.
------
#### [ YAML ]
```
- name: verifyImageAvailability
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 600
isCritical: false
onFailure: 'step:getCurrentImageState'
inputs:
Service: ec2
Api: DescribeImages
ImageIds:
- '{{ createImage.newImageId }}'
PropertySelector: '$.Images[0].State'
DesiredValues:
- available
nextStep: copyImage
```
------
#### [ JSON ]
```
{
"name": "verifyImageAvailability",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 600,
"isCritical": false,
"onFailure": "step:getCurrentImageState",
"inputs": {
"Service": "ec2",
"Api": "DescribeImages",
"ImageIds": [
"{{ createImage.newImageId }}"
],
"PropertySelector": "$.Images[0].State",
"DesiredValues": [
"available"
]
},
"nextStep": "copyImage"
}
```
------
Para obter mais informações sobre propriedades compartilhadas por todas as ações de automação, consulte [Propriedades compartilhadas por todas as ações](automation-actions.md#automation-common).
# Referência de runbooks do Systems Manager Automation
Para ajudar você a começar rapidamente, o AWS Systems Manager fornece runbooks predefinidos. Esses runbooks são mantidos pela Amazon Web Services, AWS Support e AWS Config. A referência de runbooks descreve cada um dos runbooks predefinidos fornecidos pelo Systems Manager, Suporte e AWS Config. Para obter mais informações, consulte [Referência de runbooks do Systems Manager Automation](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide).
# Tutoriais
Os tutoriais a seguir ajudam você a usar o AWS Systems Manager Automation para lidar com casos de uso comuns. Esses tutoriais demonstram como usar seus próprios runbooks, runbooks predefinidos fornecidos pelo Automation e outras ferramentas do Systems Manager com outros Serviços da AWS.
**Contents**
+ [Atualizar o AMIs](automation-tutorial-update-ami.md)
+ [Atualizar uma AMI Linux](automation-tutorial-update-patch-linux-ami.md)
+ [Atualizar uma AMI (AWS CLI) Linux](automation-tutorial-update-ami.md#update-patch-linux-ami-cli)
+ [Atualizar uma AMI Windows Server](automation-tutorial-update-patch-windows-ami.md)
+ [Atualize uma AMI dourada usando Automation, AWS Lambda e Parameter Store](automation-tutorial-update-patch-golden-ami.md)
+ [Tarefa 1: Criar um parâmetro no Systems Manager () Parameter Store](automation-tutorial-update-patch-golden-ami.md#create-parameter-ami)
+ [Tarefa 2: Criar uma função do IAM para o AWS Lambda](automation-tutorial-update-patch-golden-ami.md#create-lambda-role)
+ [Tarefa 3: Criar uma função do AWS Lambda](automation-tutorial-update-patch-golden-ami.md#create-lambda-function)
+ [Tarefa 4: Criar um runbook e aplicar patches à AMI](automation-tutorial-update-patch-golden-ami.md#create-custom-ami-update-runbook)
+ [Atualizar AMIs usando o Automation e Jenkins](automation-tutorial-update-patch-ami-jenkins-integration.md)
+ [Atualização de AMIs para grupos do Auto Scaling](automation-tutorial-update-patch-windows-ami-autoscaling.md)
+ [Criar o runbook **PatchAMIAndUpdateASG**](automation-tutorial-update-patch-windows-ami-autoscaling.md#create-autoscaling-update-runbook)
+ [Uso de runbooks de autoatendimento do AWS Support](automation-tutorial-support-runbooks.md)
+ [Executar a ferramenta EC2Rescue em instâncias inacessíveis](automation-ec2rescue.md)
+ [Como funciona](automation-ec2rescue.md#automation-ec2rescue-how)
+ [Antes de começar](automation-ec2rescue.md#automation-ec2rescue-begin)
+ [Conceder permissões ao `AWSSupport-EC2Rescue` para realizar ações nas instâncias](automation-ec2rescue.md#automation-ec2rescue-access)
+ [Conceder permissões usando políticas do IAM](automation-ec2rescue.md#automation-ec2rescue-access-iam)
+ [Conceder permissões usando um modelo do CloudFormation](automation-ec2rescue.md#automation-ec2rescue-access-cfn)
+ [Executar a Automação](automation-ec2rescue.md#automation-ec2rescue-executing)
+ [Redefinir senhas e chaves SSH em instâncias do EC2](automation-ec2reset.md)
+ [Como funciona](automation-ec2reset.md#automation-ec2reset-how)
+ [Antes de começar](automation-ec2reset.md#automation-ec2reset-begin)
+ [Conceder a AWSSupport-EC2Rescue permissões para realizar ações em suas instâncias](automation-ec2reset.md#automation-ec2reset-access)
+ [Conceder permissões usando políticas do IAM](automation-ec2reset.md#automation-ec2reset-access-iam)
+ [Conceder permissões usando um modelo do CloudFormation](automation-ec2reset.md#automation-ec2reset-access-cfn)
+ [Executar a Automação](automation-ec2reset.md#automation-ec2reset-executing)
+ [Transferência de dados para o Automation usando transformadores de entrada](automation-tutorial-eventbridge-input-transformers.md)
# Atualizar o AMIs
Os tutoriais a seguir explicam como atualizar as Amazon Machine Image (AMIs) para incluir os patches mais recentes.
**Topics**
+ [Atualizar uma AMI Linux](automation-tutorial-update-patch-linux-ami.md)
+ [Atualizar uma AMI (AWS CLI) Linux](#update-patch-linux-ami-cli)
+ [Atualizar uma AMI Windows Server](automation-tutorial-update-patch-windows-ami.md)
+ [Atualize uma AMI dourada usando Automation, AWS Lambda e Parameter Store](automation-tutorial-update-patch-golden-ami.md)
+ [Atualizar AMIs usando o Automation e Jenkins](automation-tutorial-update-patch-ami-jenkins-integration.md)
+ [Atualização de AMIs para grupos do Auto Scaling](automation-tutorial-update-patch-windows-ami-autoscaling.md)
# Atualizar uma AMI Linux
Esta demonstração do Systems Manager Automation mostra como usar o console ou a AWS CLI e o runbook `AWS-UpdateLinuxAmi` para atualizar uma AMI Linux com as versões mais atualizadas dos pacotes especificados. O Automation é uma ferramenta do AWS Systems Manager. O runbook `AWS-UpdateLinuxAmi` também automatiza a instalação de pacotes e configurações adicionais específicos de sites. Você pode atualizar várias distribuições do Linux usando esta demonstração, incluindo Ubuntu Server, Red Hat Enterprise Linux (RHEL) ou Amazon Linux AMIs. Para obter uma lista completa das versões compatíveis do Linux, consulte [Pré-requisitos do Patch Manager](patch-manager-prerequisites.md).
O runbook `AWS-UpdateLinuxAmi` permite automatizar tarefas de manutenção de imagens sem precisar criar o runbook em JSON ou YAML. Você pode usar o runbook `AWS-UpdateLinuxAmi` para realizar os seguintes tipos de tarefas:
+ Atualize todos os pacotes de distribuição e software da Amazon em um Amazon Linux, Red Hat Enterprise Linux ou Ubuntu Server Amazon Machine Image (AMI). Esse é o comportamento padrão do runbook.
+ Instale o AWS Systems Manager SSM Agent em uma imagem existente para habilitar ferramentas do Systems Manager, como a execução remota de comandos usando o AWS Systems Manager Run Command ou a coleta de inventário de software usando o Inventory.
+ Instalar pacotes de software adicionais.
**Antes de começar**
Antes de começar a trabalhar com runbooks, configure funções e, opcionalmente, o EventBridge para o Automation. Para obter mais informações, consulte [Configurar a automação](automation-setup.md). Esta demonstração também requer que você especifique o nome de um perfil de instância do AWS Identity and Access Management (IAM). Para obter mais informações sobre como criar um perfil de instância do IAM, consulte [Configurar permissões de instância obrigatórias para o Systems Manager](setup-instance-permissions.md).
O runbook `AWS-UpdateLinuxAmi` aceita os seguintes parâmetros de entrada:
****
| Parâmetro | Tipo | Descrição |
| --- | --- | --- |
| SourceAmiId | String | (Obrigatório) O ID da AMI de origem. |
| IamInstanceProfileName | String | (Obrigatório) O nome do perfil para o perfil de instância do IAM criado em [Configurar permissões de instância obrigatórias para o Systems Manager](setup-instance-permissions.md). A função de perfil de instância concede ao Automation permissão para realizar ações em suas instâncias, como executar comandos ou iniciar e interromper serviços. O runbook usa apenas o nome da função de perfil da instância. Se você especificar o nome do recurso da Amazon (ARN), a automação falhará. |
| AutomationAssumeRole | String | (Obrigatório) O nome da função de serviço do IAM que você criou em [Configurar a automação](automation-setup.md). A função de serviço (também chamada de função assumida) concede ao Automation permissão para assumir sua função do IAM e realizar ações em seu nome. Por exemplo, a função de serviço permite que o Automation crie uma nova AMI ao executar a ação `aws:createImage` em um runbook. Para esse parâmetro, o ARN completo deve ser especificado. |
| TargetAmiName | String | (Opcional) O nome da nova AMI após a sua criação. O nome padrão é uma string gerada pelo sistema que inclui o ID da AMI de origem, bem como a data e a hora de criação. |
| InstanceType | String | (Opcional) O tipo de instância a ser executada como o host do espaço de trabalho. Os tipos de instância variam de acordo com a região. O tipo padrão é t2.micro. |
| PreUpdateScript | String | (Opcional) URL de um script a ser executado antes de as atualizações serem aplicadas. O padrão (\$1"none\$1") é não executar um script. |
| PostUpdateScript | String | (Opcional) URL de um script a ser executado depois de as atualizações de pacote serem aplicadas. O padrão (\$1"none\$1") é não executar um script. |
| IncludePackages | String | (Opcional) Somente atualiza esses pacotes nomeados. Por padrão (\$1"all\$1"), todas as atualizações disponíveis são aplicadas. |
| ExcludePackages | String | (Opcional) Nomes de pacotes para evitar atualizações, em todas as condições. Por padrão (\$1"none\$1"), nenhum pacote é excluído. |
**Etapas da Automação**
O runbook `AWS-UpdateLinuxAmi` inclui as seguintes ações de automação, por padrão.
**Etapa 1: launchInstance (ação `aws:runInstances`) **
Esta etapa executa uma instância usando dados de usuário do Amazon Elastic Compute Cloud (Amazon EC2) e uma função de perfil de instância do IAM. Os dados de usuário instalam o SSM Agent apropriado, com base no sistema operacional. Instalar o SSM Agent permite que você utilize ferramentas do Systems Manager como Run Command, State Manager e Inventory.
**Etapa 2: updateOSSoftware (ação `aws:runCommand`) **
Essa etapa executa os seguintes comandos na instância executada:
+ Baixa um script de atualização do Amazon S3.
+ Executa um script de pré-atualização opcional.
+ Atualiza pacotes de distribuição e softwares da Amazon.
+ Executa um script de pós-atualização opcional.
O log de execução é armazenado na pasta /tmp para que o usuário possa visualizá-lo mais tarde.
Se quiser atualizar um conjunto específico de pacotes, forneça a lista usando o parâmetro `IncludePackages`. Quando essa lista é fornecida, o sistema tenta atualizar somente esses pacotes e suas dependências. Nenhuma outra atualização é realizada. Por padrão, quando nenhum pacote de *inclusão* é especificado, o programa atualiza todos os pacotes disponíveis.
Se quiser excluir a atualização de um conjunto específico de pacotes, forneça a lista ao parâmetro `ExcludePackages`. Se essa lista for fornecida, os pacotes permanecerão na sua versão atual, independentemente de qualquer outra opção especificada. Por padrão, quando nenhum pacote de *exclusão* é especificado, nenhum pacote é excluído.
**Etapa 3: stopInstance (ação `aws:changeInstanceState`)**
Essa etapa interrompe a instância atualizada.
**Etapa 4: createImage (ação `aws:createImage`) **
Essa etapa cria uma nova AMI com um nome descritivo que a vincula ao ID de origem e ao horário de criação. Por exemplo: “AMI Gerado pelo EC2 Automation em \$1\$1global:DATE\$1TIME\$1\$1 do \$1\$1SourceAmiId\$1\$1” DATE\$1TIME e SourceID representam variáveis do Automation.
**Etapa 5: terminateInstance (ação `aws:changeInstanceState`) **
Essa etapa limpa a automação, encerrando a instância em execução.
**Output**
A automação retorna o novo ID da AMI como resultado.
**nota**
Por padrão, quando o Automation executa o runbook `AWS-UpdateLinuxAmi`, o sistema cria uma instância temporária na VPC padrão (172.30.0.0/16). Se tiver excluído a VPC padrão, você receberá o seguinte erro:
`VPC not defined 400`
Para resolver esse problema, você deve fazer uma cópia do runbook `AWS-UpdateLinuxAmi` e especificar um ID de sub-rede. Para obter mais informações, consulte [VPC não definida 400](automation-troubleshooting.md#automation-trbl-common-vpc).
**Para criar uma AMI com patch aplicado usando o Automation (AWS Systems Manager)**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação à esquerda, escolha **Automation** (Automação).
1. Escolha **Execute automation**.
1. Na lista **Automation document** (Documento de automação), escolha `AWS-UpdateLinuxAmi`.
1. Na seção **Detalhes do documento**, verifique se a **Versão do documento** está definida como **Versão padrão no runtime**.
1. Escolha **Próximo**.
1. Na seção **Execution mode (Modo de execução)**, escolha **Simple Execution (Execução simples)**.
1. Na seção **Input parameters** (Parâmetros de entrada), insira as informações coletadas na seção **Before you begin** (Antes de começar).
1. Escolha **Executar**. O console exibe o status de execução da Automação.
Após a conclusão da automação, execute uma instância de teste da AMI atualizada para verificar as alterações.
**nota**
Se alguma etapa da automação falhar, as informações sobre a falha serão listadas na página **Automation Executions** (Execuções do Automation). A automação foi concebida para terminar a instância temporária após a conclusão bem-sucedida de todas as tarefas. Se uma etapa falhar, o sistema talvez não encerre a instância. Então, se uma etapa falhar, encerre manualmente a instância temporária.
## Atualizar uma AMI (AWS CLI) Linux
Esta demonstração do AWS Systems Manager Automation mostra como usar a AWS Command Line Interface (AWS CLI) e o runbook `AWS-UpdateLinuxAmi` do Systems Manager para aplicar patches automaticamente a uma Amazon Machine Image (AMI) do Linux com as versões mais atualizadas dos pacotes especificados. O Automation é uma ferramenta do AWS Systems Manager. O runbook `AWS-UpdateLinuxAmi` também automatiza a instalação de pacotes e configurações adicionais específicos de sites. Você pode atualizar várias distribuições do Linux usando esta demonstração, incluindo Ubuntu Server, Red Hat Enterprise Linux (RHEL) ou Amazon Linux AMIs. Para obter uma lista completa das versões compatíveis do Linux, consulte [Pré-requisitos do Patch Manager](patch-manager-prerequisites.md).
O runbook `AWS-UpdateLinuxAmi` permite automatizar tarefas de manutenção de imagens sem precisar criar o runbook em JSON ou YAML. Você pode usar o runbook `AWS-UpdateLinuxAmi` para realizar os seguintes tipos de tarefas:
+ Atualize todos os pacotes de distribuição e software da Amazon em um Amazon Linux, RHEL ou Ubuntu Server Amazon Machine Image (AMI). Esse é o comportamento padrão do runbook.
+ Instale o AWS Systems Manager SSM Agent em uma imagem existente para habilitar os recursos do Systems Manager, como a execução remota de comandos usando o AWS Systems Manager Run Command ou a coleta de inventário de software usando o Inventory.
+ Instalar pacotes de software adicionais.
**Antes de começar**
Antes de começar a trabalhar com runbooks, configure funções e, opcionalmente, o EventBridge para o Automation. Para obter mais informações, consulte [Configurar a automação](automation-setup.md). Esta demonstração também requer que você especifique o nome de um perfil de instância do AWS Identity and Access Management (IAM). Para obter mais informações sobre como criar um perfil de instância do IAM, consulte [Configurar permissões de instância obrigatórias para o Systems Manager](setup-instance-permissions.md).
O runbook `AWS-UpdateLinuxAmi` aceita os seguintes parâmetros de entrada:
****
| Parameter | Tipo | Descrição |
| --- | --- | --- |
| SourceAmiId | String | (Obrigatório) O ID da AMI de origem. Você pode fazer referência automaticamente ao ID mais recente de uma AMI do Amazon EC2 para Linux usando um parâmetro *público* do AWS Systems Manager Parameter Store . Para obter mais informações, consulte [Consultar os IDs de AMI do Amazon Linux mais recentes usando o AWS Systems Manager Parameter Store](https://aws.amazon.com/blogs/compute/query-for-the-latest-amazon-linux-ami-ids-using-aws-systems-manager-parameter-store/). |
| IamInstanceProfileName | String | (Obrigatório) O nome do perfil para o perfil de instância do IAM criado em [Configurar permissões de instância obrigatórias para o Systems Manager](setup-instance-permissions.md). A função de perfil de instância concede ao Automation permissão para realizar ações em suas instâncias, como executar comandos ou iniciar e interromper serviços. O runbook usa apenas o nome da função de perfil da instância. |
| AutomationAssumeRole | String | (Obrigatório) O nome da função de serviço do IAM que você criou em [Configurar a automação](automation-setup.md). A função de serviço (também chamada de função assumida) concede ao Automation permissão para assumir sua função do IAM e realizar ações em seu nome. Por exemplo, a função de serviço permite que o Automation crie uma nova AMI ao executar a ação `aws:createImage` em um runbook. Para esse parâmetro, o ARN completo deve ser especificado. |
| TargetAmiName | String | (Opcional) O nome da nova AMI após a sua criação. O nome padrão é uma string gerada pelo sistema que inclui o ID da AMI de origem, bem como a data e a hora de criação. |
| InstanceType | String | (Opcional) O tipo de instância a ser executada como o host do espaço de trabalho. Os tipos de instância variam de acordo com a região. O tipo padrão é t2.micro. |
| PreUpdateScript | String | (Opcional) URL de um script a ser executado antes de as atualizações serem aplicadas. O padrão (\$1"none\$1") é não executar um script. |
| PostUpdateScript | String | (Opcional) URL de um script a ser executado depois de as atualizações de pacote serem aplicadas. O padrão (\$1"none\$1") é não executar um script. |
| IncludePackages | String | (Opcional) Somente atualiza esses pacotes nomeados. Por padrão (\$1"all\$1"), todas as atualizações disponíveis são aplicadas. |
| ExcludePackages | String | (Opcional) Nomes de pacotes para evitar atualizações, em todas as condições. Por padrão (\$1"none\$1"), nenhum pacote é excluído. |
**Etapas da Automação**
O runbook `AWS-UpdateLinuxAmi` inclui as seguintes etapas, por padrão.
**Etapa 1: launchInstance (ação `aws:runInstances`) **
Esta etapa executa uma instância usando dados de usuário do Amazon Elastic Compute Cloud (Amazon EC2) e uma função de perfil de instância do IAM. Os dados de usuário instalam o SSM Agent apropriado, com base no sistema operacional. Instalar o SSM Agent permite que você utilize ferramentas do Systems Manager como Run Command, State Manager e Inventory.
**Etapa 2: updateOSSoftware (ação `aws:runCommand`) **
Essa etapa executa os seguintes comandos na instância executada:
+ Baixe um script de atualização do Amazon Simple Storage Service (Amazon S3).
+ Executa um script de pré-atualização opcional.
+ Atualiza pacotes de distribuição e softwares da Amazon.
+ Executa um script de pós-atualização opcional.
O log de execução é armazenado na pasta /tmp para que o usuário possa visualizá-lo mais tarde.
Se quiser atualizar um conjunto específico de pacotes, forneça a lista usando o parâmetro `IncludePackages`. Quando essa lista é fornecida, o sistema tenta atualizar somente esses pacotes e suas dependências. Nenhuma outra atualização é realizada. Por padrão, quando nenhum pacote de *inclusão* é especificado, o programa atualiza todos os pacotes disponíveis.
Se quiser excluir a atualização de um conjunto específico de pacotes, forneça a lista ao parâmetro `ExcludePackages`. Se essa lista for fornecida, os pacotes permanecerão na sua versão atual, independentemente de qualquer outra opção especificada. Por padrão, quando nenhum pacote de *exclusão* é especificado, nenhum pacote é excluído.
**Etapa 3: stopInstance (ação `aws:changeInstanceState`)**
Essa etapa interrompe a instância atualizada.
**Etapa 4: createImage (ação `aws:createImage`) **
Essa etapa cria uma nova AMI com um nome descritivo que a vincula ao ID de origem e ao horário de criação. Por exemplo: “AMI Generated by EC2 Automation on \$1\$1global:DATE\$1TIME\$1\$1 from \$1\$1SourceAmiId\$1\$1” em que DATE\$1TIME e SourceID representam variáveis de Automação.
**Etapa 5: terminateInstance (ação `aws:changeInstanceState`) **
Essa etapa limpa a automação, encerrando a instância em execução.
**Saída**
A automação retorna o novo ID da AMI como resultado.
**nota**
Por padrão, quando o Automation executa o runbook `AWS-UpdateLinuxAmi`, o sistema cria uma instância temporária na VPC padrão (172.30.0.0/16). Se tiver excluído a VPC padrão, você receberá o seguinte erro:
`VPC not defined 400`
Para resolver esse problema, você deve fazer uma cópia do runbook `AWS-UpdateLinuxAmi` e especificar um ID de sub-rede. Para obter mais informações, consulte [VPC não definida 400](automation-troubleshooting.md#automation-trbl-common-vpc).
**Para criar uma AMI com patch aplicado usando o Automation**
1. Instale e configure a AWS Command Line Interface (AWS CLI), caso ainda não o tenha feito.
Para obter informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
1. Execute o comando a seguir para executar o runbook `AWS-UpdateLinuxAmi`. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
```
aws ssm start-automation-execution \
--document-name "AWS-UpdateLinuxAmi" \
--parameters \
SourceAmiId=AMI ID, \
IamInstanceProfileName=IAM instance profile, \
AutomationAssumeRole='arn:aws:iam::{{global:ACCOUNT_ID}}:role/AutomationServiceRole'
```
O comando retorna um ID de execução. Copie esse ID para a área de transferência. Você usará esse ID para visualizar o status da automação.
```
{
"AutomationExecutionId": "automation execution ID"
}
```
1. Para visualizar a automação usando a AWS CLI, execute o seguinte comando:
```
aws ssm describe-automation-executions
```
1. Para visualizar detalhes sobre o andamento da automação, execute o comando a seguir. Substitua *automation execution ID* (ID de execução da automação) por suas próprias informações.
```
aws ssm get-automation-execution --automation-execution-id automation execution ID
```
O processo de atualização pode demorar 30 minutos ou mais para ser concluído.
**nota**
Você pode também monitorar o status da automação no console. Na lista, escolha a automação que você acabou de processar e depois escolha a guia **Steps** (Etapas). Esta guia mostra o status das ações de automação.
Após a conclusão da automação, execute uma instância de teste da AMI atualizada para verificar as alterações.
**nota**
Se alguma etapa da automação falhar, as informações sobre a falha serão listadas na página **Automation Executions** (Execuções do Automation). A automação foi concebida para terminar a instância temporária após a conclusão bem-sucedida de todas as tarefas. Se uma etapa falhar, o sistema talvez não encerre a instância. Então, se uma etapa falhar, encerre manualmente a instância temporária.
# Atualizar uma AMI Windows Server
O runbook `AWS-UpdateWindowsAmi` permite automatizar tarefas de manutenção de imagens em Amazon Machine Image (AMI) do Amazon Windows, sem precisar criar o runbook em JSON ou YAML. Este runbook tem suporte para o Windows Server 2008 R2 ou posterior. Você pode usar o runbook `AWS-UpdateWindowsAmi` para realizar os seguintes tipos de tarefas:
+ Instalar todas as atualizações do Windows e atualizar softwares da Amazon (comportamento padrão).
+ Instalar atualizações específicas do Windows e atualizar softwares da Amazon.
+ Personalize uma AMI usando seus scripts.
**Antes de começar**
Antes de começar a trabalhar com runbooks, [configure funções para o Automation](automation-setup-iam.md) a fim de adicionar uma política `iam:PassRole` que referencia o ARN do perfil da instância ao qual você deseja conceder acesso. Opcionalmente, configure o Amazon EventBridge para o Automation, uma ferramenta do AWS Systems Manager. Para obter mais informações, consulte [Configurar a automação](automation-setup.md). Esta demonstração também requer que você especifique o nome de um perfil de instância do AWS Identity and Access Management (IAM). Para obter mais informações sobre como criar um perfil de instância do IAM, consulte [Configurar permissões de instância obrigatórias para o Systems Manager](setup-instance-permissions.md).
**nota**
As atualizações do AWS Systems Manager SSM Agent são normalmente implementadas em regiões diferentes e em momentos distintos. Quando você personalizar ou atualizar uma AMI, use apenas AMIs de origem publicadas para a região na qual você está trabalhando. Isso garante que você trabalhe com o SSM Agent mais recente lançado nessa região e evite problemas de compatibilidade.
O runbook `AWS-UpdateWindowsAmi` aceita os seguintes parâmetros de entrada:
****
| Parâmetro | Tipo | Descrição |
| --- | --- | --- |
| SourceAmiId | String | (Obrigatório) O ID da AMI de origem. Você pode fazer referência automaticamente ao ID de uma AMI do Windows Server mais recente, ID usando um parâmetro *público* Parameter Store do Systems Manager. Para obter mais informações, consulte [Consultar os mais recentes IDs da AMI do Windows usando o AWS Systems ManagerParameter Store](https://aws.amazon.com/blogs/mt/query-for-the-latest-windows-ami-using-systems-manager-parameter-store/). |
| SubnetId | String | (Opcional) A sub-rede na qual você deseja iniciar a instância temporária. Você deve especificar um valor para esse parâmetro se tiver excluído a VPC padrão. |
| IamInstanceProfileName | String | (Obrigatório) O nome do perfil para o perfil de instância do IAM criado em [Configurar permissões de instância obrigatórias para o Systems Manager](setup-instance-permissions.md). A função de perfil de instância concede ao Automation permissão para realizar ações em suas instâncias, como executar comandos ou iniciar e interromper serviços. O runbook usa apenas o nome da função de perfil da instância. |
| AutomationAssumeRole | String | (Obrigatório) O nome da função de serviço do IAM que você criou em [Configurar a automação](automation-setup.md). A função de serviço (também chamada de função assumida) concede ao Automation permissão para assumir sua função do IAM e realizar ações em seu nome. Por exemplo, a função de serviço permite que o Automation crie uma nova AMI ao executar a ação `aws:createImage` em um runbook. Para esse parâmetro, o ARN completo deve ser especificado. |
| TargetAmiName | String | (Opcional) O nome da nova AMI após a sua criação. O nome padrão é uma string gerada pelo sistema que inclui o ID da AMI de origem, bem como a data e a hora de criação. |
| InstanceType | String | (Opcional) O tipo de instância a ser executada como o host do espaço de trabalho. Os tipos de instância variam de acordo com a região. O tipo padrão é t2.medium. |
| PreUpdateScript | String | (Opcional) Um script a ser executado antes de atualizar a AMI. Insira um script no runbook ou no runtime como um parâmetro. |
| PostUpdateScript | String | (Opcional) Um script a ser executado depois de atualizar a AMI. Insira um script no runbook ou no runtime como um parâmetro. |
| IncludeKbs | String | (Opcional) Especifique um ou mais IDs de artigo da Base de Dados de Conhecimento Microsoft (KB) para incluir. Você pode instalar vários IDs usando valores separados por vírgulas. Formatos válidos: KB9876543 ou 9876543. |
| ExcludeKbs | String | (Opcional) Especifique um ou mais IDs de artigo da Base de Dados de Conhecimento Microsoft (KB) para excluir. Você pode excluir vários IDs usando valores separados por vírgulas. Formatos válidos: KB9876543 ou 9876543. |
| Categorias | String | (Opcional) Especifique uma ou mais categorias de atualização. Você pode filtrar categorias usando valores separados por vírgulas. Opções: Atualização crítica, Atualização de segurança, Atualização de definição, Pacote de atualizações, Pacote de serviços, Ferramenta, Atualização ou Driver. Os formatos válidos incluem uma única entrada, por exemplo: Atualização crítica. Como alternativa, você pode especificar uma lista separada por vírgulas: Atualização crítica, Atualização de segurança, Atualização de definição. |
| SeverityLevels | String | (Opcional) Especifique um ou mais níveis de gravidade MSRC associados a uma atualização. Você pode filtrar os níveis de gravidade usando valores separados por vírgulas. Opções: Crítica, Importante, Baixa, Moderada ou Não especificada. Os formatos válidos incluem uma única entrada, por exemplo: Crítica. Como alternativa, você pode especificar uma lista separada por vírgulas: Crítica, Importante, Baixa. |
**Etapas da Automação**
O runbook `AWS-UpdateWindowsAmi` inclui as seguintes etapas, por padrão.
**Etapa 1: launchInstance (ação `aws:runInstances`)**
Esta etapa executa uma instância com uma função de perfil da instância do IAM no especificado `SourceAmiID`.
**Etapa 2: runPreUpdateScript (ação `aws:runCommand`)**
Essa etapa permite especificar um script como uma string que é executada antes que as atualizações sejam instaladas.
**Etapa 3: updateEC2Config (ação `aws:runCommand`)**
Esta etapa usa o runbook `AWS-InstallPowerShellModule` para baixar um módulo PowerShell público da AWS. O Systems Manager verifica a integridade do módulo usando um hash SHA-256. Em seguida, o Systems Manager verifica o sistema operacional para determinar se deve atualizar EC2Config ou EC2Launch. EC2Config é executado no Windows Server 2008 R2 até o Windows Server 2012 R2. EC2Launch é executado no Windows Server 2016.
**Etapa 4: updateSSMAgent (ação `aws:runCommand`)**
Esta etapa atualiza o SSM Agent usando o runbook `AWS-UpdateSSMAgent`.
**Etapa 5: updateAWSPVDriver (ação `aws:runCommand`)**
Esta etapa atualiza os drivers de rede do AWS PV usando o runbook `AWS-ConfigureAWSPackage`.
**Etapa 6: updateAwsEnaNetworkDriver (ação `aws:runCommand`)**
Esta etapa atualiza os drivers de rede do AWS ENA usando o runbook `AWS-ConfigureAWSPackage`.
**Etapa 7: installWindowsUpdates (ação `aws:runCommand`) **
Essa etapa instala atualizações do Windows usando o runbook `AWS-InstallWindowsUpdates`. Por padrão, o Systems Manager procura e instala todas as atualizações ausentes. Você pode alterar o comportamento padrão especificando um dos seguintes parâmetros: `IncludeKbs`, `ExcludeKbs`, `Categories` ou `SeverityLevels`.
**Etapa 8: runPostUpdateScript (ação `aws:runCommand`)**
Essa etapa permite especificar um script como uma string que é executada após a instalação das atualizações.
**Etapa 9: runSysprepGeneralize (ação `aws:runCommand`) **
Esta etapa usa o runbook `AWS-InstallPowerShellModule` para baixar um módulo PowerShell público da AWS. O Systems Manager verifica a integridade do módulo usando um hash SHA-256. Em seguida, o Systems Manager executa o sysprep usando métodos com suporte da AWS para EC2Launch (Windows Server 2016) ou EC2Config (Windows Server 2008 R2 a 2012 R2).
**Etapa 10: stopInstance (ação `aws:changeInstanceState`) **
Essa etapa interrompe a instância atualizada.
**Etapa 11: createImage (ação `aws:createImage`) **
Essa etapa cria uma nova AMI com um nome descritivo que a vincula ao ID de origem e ao horário de criação. Por exemplo: “AMI Generated by EC2 Automation on \$1\$1global:DATE\$1TIME\$1\$1 from \$1\$1SourceAmiId\$1\$1” em que DATE\$1TIME e SourceID representam variáveis de Automação.
**Etapa 12: TerminateInstance (ação `aws:changeInstanceState`) **
Essa etapa limpa a automação, encerrando a instância em execução.
**Output**
Essa seção permite designar as saídas de várias etapas ou valores de qualquer parâmetro como saída da Automação. Por padrão, o resultado é o ID da AMI do Windows atualizada, criada pela automação.
**nota**
Por padrão, quando o Automation executa o runbook `AWS-UpdateWindowsAmi` e cria uma instância temporária, o sistema usa a VPC padrão (172.30.0.0/16). Se tiver excluído a VPC padrão, você receberá o seguinte erro:
VPC não definida 400
Para resolver esse problema, você deve fazer uma cópia do runbook `AWS-UpdateWindowsAmi` e especificar um ID de sub-rede. Para obter mais informações, consulte [VPC não definida 400](automation-troubleshooting.md#automation-trbl-common-vpc).
**Para criar uma AMI Windows com patch aplicado usando o Automation**
1. Instale e configure a AWS Command Line Interface (AWS CLI), caso ainda não o tenha feito.
Para obter informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
1. Execute o comando a seguir para executar o runbook `AWS-UpdateWindowsAmi`. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações. O exemplo de comando abaixo usa uma AMI recente do Amazon EC2 para minimizar o número de patches que precisam ser aplicados. Se você executar esse comando mais de uma vez, deverá especificar um valor exclusivo para `targetAMIname`. Os nomes da AMI deverão ser exclusivos.
```
aws ssm start-automation-execution \
--document-name="AWS-UpdateWindowsAmi" \
--parameters SourceAmiId='AMI ID',IamInstanceProfileName='IAM instance profile',AutomationAssumeRole='arn:aws:iam::{{global:ACCOUNT_ID}}:role/AutomationServiceRole'
```
O comando retorna um ID de execução. Copie esse ID para a área de transferência. Você usará esse ID para visualizar o status da automação.
```
{
"AutomationExecutionId": "automation execution ID"
}
```
1. Para visualizar a automação usando a AWS CLI, execute o seguinte comando:
```
aws ssm describe-automation-executions
```
1. Para visualizar detalhes sobre o andamento da automação, execute o comando a seguir.
```
aws ssm get-automation-execution
--automation-execution-id automation execution ID
```
**nota**
Dependendo do número de patches aplicados, o processo de aplicação de patches do Windows, executado nessa automação de amostra, poderá demorar 30 minutos ou mais para ser concluído.
# Atualize uma AMI dourada usando Automation, AWS Lambda e Parameter Store
O exemplo a seguir usa o modelo onde uma organização mantém suas próprias AMIs e aplica patches a elas periodicamente, em vez de se basear em AMIs do Amazon Elastic Compute Cloud (Amazon EC2).
O procedimento a seguir mostra como aplicar patches de sistema operacional (SO) automaticamente a uma AMI que já é considerada a AMI mais atualizada ou *mais recente*. No exemplo, o valor padrão do parâmetro `SourceAmiId` é definido por um parâmetro do AWS Systems Manager Parameter Store chamado `latestAmi`. O valor de `latestAmi` é atualizado por uma função AWS Lambda invocada no final da automação. Como resultado desse processo de automação, o tempo e o esforço gastos na aplicação de patches das AMIs são minimizados, pois o patch é sempre aplicado à AMI mais atualizada. O Parameter Store e o Automation são ferramentas do AWS Systems Manager.
**Antes de começar**
Configure as funções do Automation e, opcionalmente, o Amazon EventBridge para Automation. Para obter mais informações, consulte [Configurar a automação](automation-setup.md).
**Topics**
+ [Tarefa 1: Criar um parâmetro no Systems Manager () Parameter Store](#create-parameter-ami)
+ [Tarefa 2: Criar uma função do IAM para o AWS Lambda](#create-lambda-role)
+ [Tarefa 3: Criar uma função do AWS Lambda](#create-lambda-function)
+ [Tarefa 4: Criar um runbook e aplicar patches à AMI](#create-custom-ami-update-runbook)
## Tarefa 1: Criar um parâmetro no Systems Manager () Parameter Store
Crie um parâmetro de string no Parameter Store que use as seguintes informações:
+ **Nome**: `latestAmi`.
+ **Valor**: um ID de AMI. Por exemplo: .:` ami-188d6e0e`.
Para obter mais informações sobre como criar um parâmetro String usando o Parameter Store, consulte [Criar parâmetros do Parameter Store no Systems Manager](sysman-paramstore-su-create.md).
## Tarefa 2: Criar uma função do IAM para o AWS Lambda
Use o procedimento a seguir para criar uma função de serviço do IAM para o AWS Lambda. Essas políticas dão ao Lambda a permissão necessária para atualizar o valor do parâmetro `latestAmi` usando uma função do Lambda e do Systems Manager.
**Para criar uma função de serviço do IAM para o Lambda**
1. Faça login no Console de gerenciamento da AWS e abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. No painel de navegação, selecione **Políticas** e, em seguida, **Criar política**.
1. Selecione a guia **JSON**.
1. Substitua os conteúdos padrão pela política a seguir. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "logs:CreateLogGroup",
"Resource": "arn:aws:logs:us-east-1:111122223333:*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": [
"arn:aws:logs:us-east-1:111122223333:log-group:/aws/lambda/function name:*"
]
}
]
}
```
------
1. Escolha **Next: Tags**.
1. (Opcional) Adicione um ou mais pares de chave-valor de etiqueta para organizar, monitorar ou controlar acesso para essa política.
1. Selecione **Próximo: revisar**.
1. Na página **Revisar política**, em **Nome**, digite um nome para a política em linha, como **amiLambda**.
1. Escolha **Criar política**.
1. Repita as etapas 2 e 3.
1. Cole a política a seguir. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ssm:PutParameter",
"Resource": "arn:aws:ssm:us-east-1:111122223333:parameter/latestAmi"
},
{
"Effect": "Allow",
"Action": "ssm:DescribeParameters",
"Resource": "*"
}
]
}
```
------
1. Escolha **Próximo: tags**.
1. (Opcional) Adicione um ou mais pares de chave-valor de etiqueta para organizar, monitorar ou controlar acesso para essa política.
1. Escolha **Próximo: revisar**.
1. Na página **Revisar política**, em **Nome**, digite um nome para a política em linha, como **amiParameter**.
1. Escolha **Criar política**.
1. No painel de navegação, escolha **Perfis** e **Criar perfil**.
1. Em seguida, em **Caso de uso**, escolha **Lambda** e escolha **Próximo**.
1. Na página **Adicionar permissões**, use o campo **Pesquisar** para localizar as duas políticas criadas anteriormente.
1. Marque a caixa de seleção ao lado das políticas e, em seguida, escolha **Próximo**.
1. Em **Role name** (Nome da função), insira um nome para a nova função, como **lambda-ssm-role** ou outro nome que você preferir.
**nota**
Como várias entidades podem fazer referência à função, não é possível alterar o nome da função depois que ela é criada.
1. (Opcional) Adicione um ou mais pares chave-valor de etiquetas para organizar, acompanhar ou controlar o acesso a esse perfil e, em seguida, escolha **Criar perfil**.
## Tarefa 3: Criar uma função do AWS Lambda
Use o seguinte procedimento para criar uma função do Lambda que atualize automaticamente o valor do parâmetro `latestAmi`.
**Como criar uma função do Lambda**
1. Faça login no Console de gerenciamento da AWS e abra o console do AWS Lambda em [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/).
1. Escolha a opção **Criar função**.
1. Na página **Create function**, selecione **Author from scratch**.
1. Em **Function name** (Nome da função), insira **Automation-UpdateSsmParam**.
1. Em **Runtime**, selecione **Python 3.11**.
1. Em **Arquitetura**, selecione o tipo de processador de computador que o Lambda usará para executar a função, **x86\$164** ou **arm64**.
1. Na seção **Permissões**, expanda **Alterar perfil de execução padrão**.
1. Selecione **Use an existing role** (Usar uma função existente) e escolha a função de serviço do Lambda criada na Tarefa 2.
1. Escolha a opção **Criar função**.
1. Na área **Origem do código**, na guia **lambda\$1function**, exclua o código pré-preenchido no campo e cole a amostra de código a seguir.
```
from __future__ import print_function
import json
import boto3
print('Loading function')
#Updates an SSM parameter
#Expects parameterName, parameterValue
def lambda_handler(event, context):
print("Received event: " + json.dumps(event, indent=2))
# get SSM client
client = boto3.client('ssm')
#confirm parameter exists before updating it
response = client.describe_parameters(
Filters=[
{
'Key': 'Name',
'Values': [ event['parameterName'] ]
},
]
)
if not response['Parameters']:
print('No such parameter')
return 'SSM parameter not found.'
#if parameter has a Description field, update it PLUS the Value
if 'Description' in response['Parameters'][0]:
description = response['Parameters'][0]['Description']
response = client.put_parameter(
Name=event['parameterName'],
Value=event['parameterValue'],
Description=description,
Type='String',
Overwrite=True
)
#otherwise just update Value
else:
response = client.put_parameter(
Name=event['parameterName'],
Value=event['parameterValue'],
Type='String',
Overwrite=True
)
responseString = 'Updated parameter %s with value %s.' % (event['parameterName'], event['parameterValue'])
return responseString
```
1. Escolha **Arquivo, Salvar**.
1. Para testar a função do Lambda, no menu **Teste**, escolha **Configurar evento de teste**.
1. Em **Event name (Nome do evento)**, insira um nome para o evento de teste, como **MyTestEvent**.
1. Substitua o texto existente pelo seguinte JSON. Substitua *AMI ID* (ID da AMI) por suas próprias informações para definir o valor do parâmetro `latestAmi`.
```
{
"parameterName":"latestAmi",
"parameterValue":"AMI ID"
}
```
1. Escolha **Salvar**.
1. Selecione **Test (Testar)** para testar a função. Na guia **Resultado da execução**, o status deve ser informado como **Com êxito**, junto com outros detalhes sobre a atualização.
## Tarefa 4: Criar um runbook e aplicar patches à AMI
Use o procedimento a seguir para criar e executar um runbook que aplica patches à AMI especificada para o parâmetro **latestAmi**. Depois que a automação for concluída, o valor de **latestAmi** será atualizado com o ID da AMI que acabou de receber patch. As automações subsequentes usarão a AMI criada pela execução anterior.
**Para criar e executar o runbook**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Documents**.
1. Em **Criar documento**, escolha **Automation**.
1. Em **Nome**, digite **UpdateMyLatestWindowsAmi**.
1. Escolha a guia **Editor** e depois escolha **Edit (Editar)**.
1. Escolha **OK** quando solicitado.
1. No campo **Editor de documentos**, substitua o conteúdo padrão pelo conteúdo do runbook de amostra YAML apresentado a seguir.
```
---
description: Systems Manager Automation Demo - Patch AMI and Update ASG
schemaVersion: '0.3'
assumeRole: '{{ AutomationAssumeRole }}'
parameters:
AutomationAssumeRole:
type: String
description: '(Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to execute this document.'
default: ''
SourceAMI:
type: String
description: The ID of the AMI you want to patch.
default: '{{ ssm:latestAmi }}'
SubnetId:
type: String
description: The ID of the subnet where the instance from the SourceAMI parameter is launched.
SecurityGroupIds:
type: StringList
description: The IDs of the security groups to associate with the instance that's launched from the SourceAMI parameter.
NewAMI:
type: String
description: The name of of newly patched AMI.
default: 'patchedAMI-{{global:DATE_TIME}}'
InstanceProfile:
type: String
description: The name of the IAM instance profile you want the source instance to use.
SnapshotId:
type: String
description: (Optional) The snapshot ID to use to retrieve a patch baseline snapshot.
default: ''
RebootOption:
type: String
description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.'
allowedValues:
- NoReboot
- RebootIfNeeded
default: RebootIfNeeded
Operation:
type: String
description: (Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.
allowedValues:
- Install
- Scan
default: Install
mainSteps:
- name: startInstances
action: 'aws:runInstances'
timeoutSeconds: 1200
maxAttempts: 1
onFailure: Abort
inputs:
ImageId: '{{ SourceAMI }}'
InstanceType: m5.large
MinInstanceCount: 1
MaxInstanceCount: 1
IamInstanceProfileName: '{{ InstanceProfile }}'
SubnetId: '{{ SubnetId }}'
SecurityGroupIds: '{{ SecurityGroupIds }}'
- name: verifyInstanceManaged
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 600
inputs:
Service: ssm
Api: DescribeInstanceInformation
InstanceInformationFilterList:
- key: InstanceIds
valueSet:
- '{{ startInstances.InstanceIds }}'
PropertySelector: '$.InstanceInformationList[0].PingStatus'
DesiredValues:
- Online
onFailure: 'step:terminateInstance'
- name: installPatches
action: 'aws:runCommand'
timeoutSeconds: 7200
onFailure: Abort
inputs:
DocumentName: AWS-RunPatchBaseline
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
InstanceIds:
- '{{ startInstances.InstanceIds }}'
- name: stopInstance
action: 'aws:changeInstanceState'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceIds:
- '{{ startInstances.InstanceIds }}'
DesiredState: stopped
- name: createImage
action: 'aws:createImage'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceId: '{{ startInstances.InstanceIds }}'
ImageName: '{{ NewAMI }}'
NoReboot: false
ImageDescription: Patched AMI created by Automation
- name: terminateInstance
action: 'aws:changeInstanceState'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceIds:
- '{{ startInstances.InstanceIds }}'
DesiredState: terminated
- name: updateSsmParam
action: aws:invokeLambdaFunction
timeoutSeconds: 1200
maxAttempts: 1
onFailure: Abort
inputs:
FunctionName: Automation-UpdateSsmParam
Payload: '{"parameterName":"latestAmi", "parameterValue":"{{createImage.ImageId}}"}'
outputs:
- createImage.ImageId
```
1. Escolha **Criar automação**.
1. No painel de navegação, selecione **Automation** e **Execute automation (Executar automação)**.
1. Na página **Choose document** (Escolher documento), escolha a guia **Owned by me** (Pertencem a mim).
1. Procure o runbook **UpdateMyLatestWindowsAmi** e selecione o botão no cartão **UpdateMyLatestWindowsAmi**.
1. Escolha **Próximo**.
1. Escolha **Simple execution (Execução simples)**.
1. Especificar valores para os parâmetro de entrada.
1. Clique em **Executar**.
1. Após a conclusão da automação, escolha **Parameter Store** no painel de navegação e confirme se o novo valor para `latestAmi` corresponde ao valor retornado pela automação. Você também pode verificar se o novo ID da AMI corresponde à saída do Automation na seção **AMIs** do console do Amazon EC2.
# Atualizar AMIs usando o Automation e Jenkins
Se a sua organização usar o software Jenkins em um pipeline de CI/CD, você poderá adicionar o Automation como uma etapa de pós-compilação para pré-instalar as versões da aplicação na Amazon Machine Images (AMIs). O Automation é uma ferramenta do AWS Systems Manager. Você também pode usar o recurso de agendamento do Jenkins para chamar o Automation e criar sua própria cadência de aplicação de patches de sistema operacional (SO).
O exemplo abaixo mostra como invocar o Automation em um servidor Jenkins em execução on-premises ou no Amazon Elastic Compute Cloud (Amazon EC2). Para realizar a autenticação, o servidor Jenkins usa credenciais da AWS com base em uma política do IAM criada no exemplo e anexada ao seu perfil de instância.
**nota**
Certifique-se de seguir as práticas recomendadas de segurança do Jenkins ao configurar sua instância.
**Antes de começar**
Conclua as seguintes tarefas antes de configurar o Automation com o Jenkins:
+ Conclua o exemplo [Atualize uma AMI dourada usando Automation, AWS Lambda e Parameter Store](automation-tutorial-update-patch-golden-ami.md). O exemplo a seguir usa o runbook **UpdateMyLatestWindowsAmi** criado nesse exemplo.
+ Configure as funções do IAM para o Automation. O Systems Manager requer uma função de perfil da instância e um ARN da função de serviço para processar automações. Para obter mais informações, consulte [Configurar a automação](automation-setup.md).
**Como criar uma política do IAM para o servidor Jenkins**
1. Faça login no Console de gerenciamento da AWS e abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. No painel de navegação, selecione **Políticas** e, em seguida, **Criar política**.
1. Selecione a guia **JSON**.
1. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ssm:StartAutomationExecution",
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:document/UpdateMyLatestWindowsAmi",
"arn:aws:ssm:us-east-1:111122223333:automation-execution/*"
]
}
]
}
```
------
1. Selecione **Revisar política**.
1. Na página **Revisar política**, em **Nome**, digite um nome para a política em linha, como **JenkinsPolicy**.
1. Escolha **Criar política**.
1. No painel de navegação, escolha **Perfis**.
1. Escolha o perfil de instância que está anexado ao seu servidor Jenkins.
1. Na guia **Permissões**, selecione **Adicionar permissões** e escolha **Anexar políticas**.
1. Na seção **Outras políticas de permissões**, insira o nome da política criada nas etapas anteriores. Por exemplo, **JenkinsPolicy**.
1. Marque a caixa de seleção ao lado da sua política e escolha **Anexar políticas**.
Use o seguinte procedimento para configurar a AWS CLI no seu servidor Jenkins.
**Para configurar o servidor Jenkins para Automation**
1. Connect ao servidor Jenkins na porta 8080 usando seu navegador preferido para acessar a interface de gerenciamento.
1. Digite a senha encontrada em `/var/lib/jenkins/secrets/initialAdminPassword`. Para exibir sua senha, execute o comando a seguir.
```
sudo cat /var/lib/jenkins/secrets/initialAdminPassword
```
1. O script de instalação do Jenkins direciona você para a página **Personalizar o Jenkins**. Selecione **Install suggested plugins** (Instalar plugins sugeridos).
1. Uma vez concluída a instalação, escolha **Credenciais de administrador**, selecione **Salvar credenciais** e, depois, **Começar a usar o Jenkins**.
1. No painel de navegação à esquerda, escolha **Gerenciar Jenkins** e, em seguida, selecione **Gerenciar plugins**.
1. Selecione a guia **Available** (Disponível) e, em seguida, digite **Amazon EC2 plugin**.
1. Marque a caixa de seleção para **Amazon EC2 plugin**e, depois, selecione **Install without restart** (Instalar sem reiniciar).
1. Quando a instalação terminar, selecione **Go back to the top page** (Voltar para a página inicial).
1. Escolha **Gerenciar Jenkins** e, em seguida, **Gerenciar nós e nuvens**.
1. Na seção **Configurar nuvens**, selecione **Adicionar uma nova nuvem** e, em seguida, escolha **Amazon EC2**.
1. Insira suas informações nos campos restantes. Certifique-se de selecionar a opção **Usar perfil de instância do EC2 para obter credenciais**.
Use o procedimento a seguir para configurar o projeto do Jenkins para invocar o Automation.
**Para configurar o servidor Jenkins para invocar o Automation**
1. Abra o console do Jenkins em um navegador Web.
1. Escolha o projeto que deseja configurar com Automação e depois escolha **Configure**.
1. Na guia **Build**, escolha **Add Build Step**.
1. Escolha **Execute shell** ou **Execute Windows batch command** (dependendo do seu sistema operacional).
1. No campo **Command** (Comando), execute um comando da AWS CLI como o seguinte: Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
```
aws ssm start-automation-execution \
--document-name runbook name \
--region Região da AWS of your source AMI \
--parameters runbook parameters
```
O comando de exemplo a seguir usa o runbook **UpdateMyLatestWindowsAmi** e o parâmetro `latestAmi` do Systems Manager criado em [Atualize uma AMI dourada usando Automation, AWS Lambda e Parameter Store](automation-tutorial-update-patch-golden-ami.md).
```
aws ssm start-automation-execution \
--document-name UpdateMyLatestWindowsAmi \
--parameters \
"sourceAMIid='{{ssm:latestAmi}}'"
--region region
```
No Jenkins, o comando se parece com exemplo mostrado na captura de tela a seguir.
![\[Um exemplo de comando no software Jenkins.\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/sysman-ami-jenkins2.png)
1. No projeto do Jenkins, escolha **Criar agora**. Jenkins retorna uma saída semelhante ao exemplo a seguir.
![\[Exemplo de saída de comando no software Jenkins.\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/sysman-ami-jenkins.png)
# Atualização de AMIs para grupos do Auto Scaling
O seguinte exemplo atualiza um grupo do Auto Scaling com uma AMI com patch recém-aplicado. Essa abordagem garante que as novas imagens sejam automaticamente disponibilizadas para diferentes ambientes de computação que usam grupos do Auto Scaling.
A etapa final da automação neste exemplo usa uma função do Python para criar um novo modelo de execução que usa a AMI que acabou de receber patch. Em seguida, o grupo do Auto Scaling é atualizado para usar o novo modelo de execução. Neste tipo de cenário de Auto Scaling, os usuários podem encerrar instâncias existentes no grupo do Auto Scaling para forçar a execução de uma nova instância que usa a nova imagem. Como alternativa, os usuários podem aguardar e permitir que eventos de aumento ou redução de escala aconteçam para executar instâncias mais recentes.
**Antes de começar**
Conclua as seguintes tarefas antes de começar este exemplo.
+ Configure perfis do IAM para o Automation, uma ferramenta do AWS Systems Manager. O Systems Manager requer uma função de perfil da instância e um ARN da função de serviço para processar automações. Para obter mais informações, consulte [Configurar a automação](automation-setup.md).
## Criar o runbook **PatchAMIAndUpdateASG**
Use o procedimento a seguir para criar o runbook **PatchAMIAndUpdateASG**, que aplica patch à AMI que você especifica para o parâmetro **SourceAMI**. O runbook também atualiza o grupo do Auto Scaling para usar a AMI que recebeu o patch mais recente.
**Para criar e executar o runbook**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Documents**.
1. Na lista suspensa **Create document** (Criar documento), escolha **Automation** (Automação).
1. No campo **Name** (Nome), insira **PatchAMIAndUpdateASG**.
1. Escolha a guia **Editor** e escolha **Edit** (Editar).
1. Escolha **OK** quando solicitado e exclua o conteúdo do espaço reservado no campo **Document editor** (Editor de documentos).
1. No campo **Document editor** (Editor de documentos), cole o seguinte conteúdo do runbook de exemplo YAML:
```
---
description: Systems Manager Automation Demo - Patch AMI and Update ASG
schemaVersion: '0.3'
assumeRole: '{{ AutomationAssumeRole }}'
parameters:
AutomationAssumeRole:
type: String
description: '(Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to execute this document.'
default: ''
SourceAMI:
type: String
description: '(Required) The ID of the AMI you want to patch.'
SubnetId:
type: String
description: '(Required) The ID of the subnet where the instance from the SourceAMI parameter is launched.'
SecurityGroupIds:
type: StringList
description: '(Required) The IDs of the security groups to associate with the instance launched from the SourceAMI parameter.'
NewAMI:
type: String
description: '(Optional) The name of of newly patched AMI.'
default: 'patchedAMI-{{global:DATE_TIME}}'
TargetASG:
type: String
description: '(Required) The name of the Auto Scaling group you want to update.'
InstanceProfile:
type: String
description: '(Required) The name of the IAM instance profile you want the source instance to use.'
SnapshotId:
type: String
description: (Optional) The snapshot ID to use to retrieve a patch baseline snapshot.
default: ''
RebootOption:
type: String
description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.'
allowedValues:
- NoReboot
- RebootIfNeeded
default: RebootIfNeeded
Operation:
type: String
description: (Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.
allowedValues:
- Install
- Scan
default: Install
mainSteps:
- name: startInstances
action: 'aws:runInstances'
timeoutSeconds: 1200
maxAttempts: 1
onFailure: Abort
inputs:
ImageId: '{{ SourceAMI }}'
InstanceType: m5.large
MinInstanceCount: 1
MaxInstanceCount: 1
IamInstanceProfileName: '{{ InstanceProfile }}'
SubnetId: '{{ SubnetId }}'
SecurityGroupIds: '{{ SecurityGroupIds }}'
- name: verifyInstanceManaged
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 600
inputs:
Service: ssm
Api: DescribeInstanceInformation
InstanceInformationFilterList:
- key: InstanceIds
valueSet:
- '{{ startInstances.InstanceIds }}'
PropertySelector: '$.InstanceInformationList[0].PingStatus'
DesiredValues:
- Online
onFailure: 'step:terminateInstance'
- name: installPatches
action: 'aws:runCommand'
timeoutSeconds: 7200
onFailure: Abort
inputs:
DocumentName: AWS-RunPatchBaseline
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
InstanceIds:
- '{{ startInstances.InstanceIds }}'
- name: stopInstance
action: 'aws:changeInstanceState'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceIds:
- '{{ startInstances.InstanceIds }}'
DesiredState: stopped
- name: createImage
action: 'aws:createImage'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceId: '{{ startInstances.InstanceIds }}'
ImageName: '{{ NewAMI }}'
NoReboot: false
ImageDescription: Patched AMI created by Automation
- name: terminateInstance
action: 'aws:changeInstanceState'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceIds:
- '{{ startInstances.InstanceIds }}'
DesiredState: terminated
- name: updateASG
action: 'aws:executeScript'
timeoutSeconds: 300
maxAttempts: 1
onFailure: Abort
inputs:
Runtime: python3.11
Handler: update_asg
InputPayload:
TargetASG: '{{TargetASG}}'
NewAMI: '{{createImage.ImageId}}'
Script: |-
from __future__ import print_function
import datetime
import json
import time
import boto3
# create auto scaling and ec2 client
asg = boto3.client('autoscaling')
ec2 = boto3.client('ec2')
def update_asg(event, context):
print("Received event: " + json.dumps(event, indent=2))
target_asg = event['TargetASG']
new_ami = event['NewAMI']
# get object for the ASG we're going to update, filter by name of target ASG
asg_query = asg.describe_auto_scaling_groups(AutoScalingGroupNames=[target_asg])
if 'AutoScalingGroups' not in asg_query or not asg_query['AutoScalingGroups']:
return 'No ASG found matching the value you specified.'
# gets details of an instance from the ASG that we'll use to model the new launch template after
source_instance_id = asg_query.get('AutoScalingGroups')[0]['Instances'][0]['InstanceId']
instance_properties = ec2.describe_instances(
InstanceIds=[source_instance_id]
)
source_instance = instance_properties['Reservations'][0]['Instances'][0]
# create list of security group IDs
security_groups = []
for group in source_instance['SecurityGroups']:
security_groups.append(group['GroupId'])
# create a list of dictionary objects for block device mappings
mappings = []
for block in source_instance['BlockDeviceMappings']:
volume_query = ec2.describe_volumes(
VolumeIds=[block['Ebs']['VolumeId']]
)
volume_details = volume_query['Volumes']
device_name = block['DeviceName']
volume_size = volume_details[0]['Size']
volume_type = volume_details[0]['VolumeType']
device = {'DeviceName': device_name, 'Ebs': {'VolumeSize': volume_size, 'VolumeType': volume_type}}
mappings.append(device)
# create new launch template using details returned from instance in the ASG and specify the newly patched AMI
time_stamp = time.time()
time_stamp_string = datetime.datetime.fromtimestamp(time_stamp).strftime('%m-%d-%Y_%H-%M-%S')
new_template_name = f'{new_ami}_{time_stamp_string}'
try:
ec2.create_launch_template(
LaunchTemplateName=new_template_name,
LaunchTemplateData={
'BlockDeviceMappings': mappings,
'ImageId': new_ami,
'InstanceType': source_instance['InstanceType'],
'IamInstanceProfile': {
'Arn': source_instance['IamInstanceProfile']['Arn']
},
'KeyName': source_instance['KeyName'],
'SecurityGroupIds': security_groups
}
)
except Exception as e:
return f'Exception caught: {str(e)}'
else:
# update ASG to use new launch template
asg.update_auto_scaling_group(
AutoScalingGroupName=target_asg,
LaunchTemplate={
'LaunchTemplateName': new_template_name
}
)
return f'Updated ASG {target_asg} with new launch template {new_template_name} which uses AMI {new_ami}.'
outputs:
- createImage.ImageId
```
1. Escolha **Criar automação**.
1. No painel de navegação, selecione **Automation** e **Execute automation (Executar automação)**.
1. Na página **Choose document** (Escolher documento), escolha a guia **Owned by me** (Pertencem a mim).
1. Procure o runbook **PatchAMIAndUpdateASG** e selecione o botão no cartão **PatchAMIAndUpdateASG**.
1. Escolha **Próximo**.
1. Escolha **Simple execution (Execução simples)**.
1. Especificar valores para os parâmetro de entrada. Verifique se o `SubnetId` e o `SecurityGroupIds` especificados permitem acesso aos endpoints públicos do Systems Manager ou aos seus endpoints de interface para o Systems Manager.
1. Clique em **Executar**.
1. Após a conclusão da automação, no console do Amazon EC2, escolha **Auto Scaling** e depois escolha **Launch Templates** (Modelos de execução). Verifique se você vê o novo modelo de execução e se ele usa a nova AMI.
1. Selecione **Auto Scaling** e, depois, escolha**Auto Scaling Groups** (Grupos Auto Scaling). Verifique se o grupo do Auto Scaling usa o novo modelo de execução.
1. Encerre uma ou mais instâncias no grupo de Auto Scaling. As instâncias de substituição serão executadas usando a nova AMI.
# Uso de runbooks de autoatendimento do AWS Support
Esta seção descreve como usar algumas das automações de autoatendimento criadas pela equipe do AWS Support. Essas automações ajudam você a gerenciar seus recursos da AWS.
**Fluxos de trabalho do Automation de suporte**
Os fluxos de trabalho do Automation de suporte (SAW) são runbooks de automação escritos e mantidos pela equipe do AWS Support. Esses runbooks ajudam a solucionar problemas comuns com seus recursos da AWS, monitoram e identificam proativamente os problemas da rede, coletam e analisam logs e muito mais.
Os runbooks SAW usam o prefixo do **`AWSSupport`**. Por exemplo, [https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-awssupport-activatewindowswithamazonlicense.html](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-awssupport-activatewindowswithamazonlicense.html).
Além disso, os clientes com os planos Business Support\$1 e superiores do AWS Support também têm acesso aos runbooks que usam o prefixo **`AWSPremiumSupport`**. Por exemplo, [https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-awspremiumsupport-troubleshootEC2diskusage.html](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-awspremiumsupport-troubleshootEC2diskusage.html).
Para saber mais sobre o AWS Support, consulte [Conceitos básicos do AWS Support](https://docs.aws.amazon.com/awssupport/latest/user/getting-started.html).
**Topics**
+ [Executar a ferramenta EC2Rescue em instâncias inacessíveis](automation-ec2rescue.md)
+ [Redefinir senhas e chaves SSH em instâncias do EC2](automation-ec2reset.md)
# Executar a ferramenta EC2Rescue em instâncias inacessíveis
O EC2Rescue pode ajudar a diagnosticar e solucionar problemas em instâncias do Amazon Elastic Compute Cloud (Amazon EC2) para Linux e Windows Server. Você pode executar a ferramenta manualmente, conforme descrito em [Usar o EC2Rescue para Linux Server](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Linux-Server-EC2Rescue.html) e [Usar o EC2Rescue para Windows Server](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/Windows-Server-EC2Rescue.html). Ou você pode executar a ferramenta automaticamente usando o Systems Manager Automation e o runbook **`AWSSupport-ExecuteEC2Rescue`**. O Automation é uma ferramenta do AWS Systems Manager. O runbook **`AWSSupport-ExecuteEC2Rescue`** foi projetado para realizar uma combinação de ações do Systems Manager, ações do CloudFormation e funções do Lambda que automatizam as etapas normalmente necessárias para usar o EC2Rescue.
Você pode usar o runbook **`AWSSupport-ExecuteEC2Rescue`** para solucionar problemas e potencialmente corrigir diferentes tipos de problemas do sistema operacional (SO). Não há suporte para instâncias com volumes raiz criptografados. Veja os seguintes tópicos para uma lista completa:
**Windows**: consulte *Rescue Action* em [Usar o EC2Rescue para Windows Server com a linha de comando](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2rw-cli.html#ec2rw-rescue).
**Linux** e **macOS**: alguns módulos do EC2Rescue for Linux detectam e tentam corrigir problemas. Para obter mais informações, consulte a documentação [https://github.com/awslabs/aws-ec2rescue-linux/tree/master/docs](https://github.com/awslabs/aws-ec2rescue-linux/tree/master/docs) para cada módulo no GitHub.
## Como funciona
Solução de problemas de uma instância com o Automation e o runbook **`AWSSupport-ExecuteEC2Rescue`** funcionam da seguinte maneira:
+ Você especifica o ID da instância inacessível e inicia o runbook.
+ O sistema cria uma VPC temporária e, em seguida, executa uma série de funções do Lambda para configurar a VPC.
+ O sistema identifica uma sub-rede para sua VPC temporária na mesma Zona de disponibilidade da sua instância original.
+ O sistema executa uma instância temporária auxiliar do , habilitada para o SSM.
+ O sistema interrompe sua instância original e cria um backup. Em seguida, atribui o volume raiz original à instância auxiliar.
+ O sistema usa o Run Command para executar o EC2Rescue na instância auxiliar. O EC2Rescue identifica e tenta corrigir problemas no volume raiz original anexado. Ao terminar, o EC2Rescue anexa o volume raiz de volta à instância original.
+ O sistema reinicia sua instância original e encerra a instância temporária. O sistema também encerra a VPC temporária e as funções Lambda criadas no início da automação.
## Antes de começar
Antes de executar a automação a seguir:
+ Copie o ID da instância inacessível. Você especificará esse ID no procedimento.
+ Opcionalmente, colete o ID de uma sub-rede na mesma zona de disponibilidade como sua instância inacessível. A instância EC2Rescue será criada nessa sub-rede. Se você não especificar uma sub-rede, o Automation criará uma nova VPC temporária em sua Conta da AWS. Verifique se sua Conta da AWS tem pelo menos uma VPC disponível. Por padrão, você pode criar cinco VPCs em uma Região. Se você já tiver criado cinco VPCs na Região, a automação falhará sem fazer alterações na sua instância. Para obter mais informações sobre as cotas da Amazon VPC, consulte [VPC e sub-redes](https://docs.aws.amazon.com/vpc/latest/userguide/amazon-vpc-limits.html#vpc-limits-vpcs-subnets) no *Manual do usuário da Amazon VPC*.
+ Opcionalmente, você pode criar e especificar uma função do AWS Identity and Access Management (IAM) para o Automation. Se você não especificar essa função, a automação será executada no contexto do usuário que executou a automação.
### Conceder permissões ao `AWSSupport-EC2Rescue` para realizar ações nas instâncias
O EC2Rescue precisa de permissão para realizar uma série de ações nas suas instâncias durante a automação. Essas ações invocam os serviços do AWS Lambda, IAM e Amazon EC2 para tentar corrigir problemas com as instâncias de forma segura. Se você tiver permissões em nível de administrador na sua Conta da AWS e/ou VPC, poderá executar a automação sem configurar permissões, conforme descrito nesta seção. Se não tiver permissões em nível de Administrador, você ou um administrador deverá configurar permissões usando uma das seguintes opções.
+ [Conceder permissões usando políticas do IAM](#automation-ec2rescue-access-iam)
+ [Conceder permissões usando um modelo do CloudFormation](#automation-ec2rescue-access-cfn)
#### Conceder permissões usando políticas do IAM
É possível anexar a política do IAM a seguir ao seu usuário, grupo ou perfil como uma política em linha, ou criar uma nova política gerenciada do IAM e anexá-la ao seu usuário, grupo ou perfil. Para obter mais informações sobre como adicionar uma política em linha ao seu usuário, grupo ou perfil, consulte [Como trabalhar com políticas em linha](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html). Para obter mais informações sobre como criar uma nova política gerenciada, consulte [Como trabalhar com políticas gerenciadas](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html).
**nota**
Se você criar uma nova política gerenciada do IAM, deverá também anexar a ela a política gerenciada **AmazonSSMAutomationRole** para que suas instâncias possam se comunicar com a API do Systems Manager.
**Política do IAM para AWSSupport-EC2Rescue**
Substitua *account ID* (ID da conta) por suas próprias informações.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"lambda:InvokeFunction",
"lambda:DeleteFunction",
"lambda:GetFunction"
],
"Resource": "arn:aws:lambda:*:111122223333:function:AWSSupport-EC2Rescue-*",
"Effect": "Allow"
},
{
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": [
"arn:aws:s3:::awssupport-ssm.*/*.template",
"arn:aws:s3:::awssupport-ssm.*/*.zip"
],
"Effect": "Allow"
},
{
"Action": [
"iam:CreateRole",
"iam:CreateInstanceProfile",
"iam:GetRole",
"iam:GetInstanceProfile",
"iam:PutRolePolicy",
"iam:DetachRolePolicy",
"iam:AttachRolePolicy",
"iam:PassRole",
"iam:AddRoleToInstanceProfile",
"iam:RemoveRoleFromInstanceProfile",
"iam:DeleteRole",
"iam:DeleteRolePolicy",
"iam:DeleteInstanceProfile"
],
"Resource": [
"arn:aws:iam::111122223333:role/AWSSupport-EC2Rescue-*",
"arn:aws:iam::111122223333:instance-profile/AWSSupport-EC2Rescue-*"
],
"Effect": "Allow"
},
{
"Action": [
"lambda:CreateFunction",
"ec2:CreateVpc",
"ec2:ModifyVpcAttribute",
"ec2:DeleteVpc",
"ec2:CreateInternetGateway",
"ec2:AttachInternetGateway",
"ec2:DetachInternetGateway",
"ec2:DeleteInternetGateway",
"ec2:CreateSubnet",
"ec2:DeleteSubnet",
"ec2:CreateRoute",
"ec2:DeleteRoute",
"ec2:CreateRouteTable",
"ec2:AssociateRouteTable",
"ec2:DisassociateRouteTable",
"ec2:DeleteRouteTable",
"ec2:CreateVpcEndpoint",
"ec2:DeleteVpcEndpoints",
"ec2:ModifyVpcEndpoint",
"ec2:Describe*",
"autoscaling:DescribeAutoScalingInstances"
],
"Resource": "*",
"Effect": "Allow"
}
]
}
```
------
#### Conceder permissões usando um modelo do CloudFormation
CloudFormationO automatiza o processo de criação de políticas e funções do IAM, usando um modelo pré-configurado. Use o procedimento a seguir para criar as funções e políticas do IAM necessárias para o Automation EC2Rescue, usando o CloudFormation.
**Para criar as funções e políticas do IAM necessárias para o EC2Rescue**
1. Faça download de [https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWSSupport-EC2RescueRole.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWSSupport-EC2RescueRole.zip) e extraia o arquivo `AWSSupport-EC2RescueRole.json` para um diretório em sua máquina local.
1. Se sua Conta da AWS estiver em uma partição especial, edite o modelo para alterar os valores do ARN para os valores da sua partição.
Por exemplo, para as regiões da China, altere todos os casos de `arn:aws` para `arn:aws-cn`.
1. Faça login no Console de gerenciamento da AWS e abra o console CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Escolha **Create stack (Criar pilha)**, **With new resources (Com novos recursos (padrão))**.
1. Na página **Create stack (Criar pilha)**, em **Prerequisite - Prepare template (Pré-requisito – Preparar modelo)**, escolha **Template is ready (O modelo está pronto)**.
1. Em **Specify template (Especificar modelo)**, escolha **Upload a template file (Fazer upload de um arquivo de modelo)**.
1. Escolha **Choose file (Escolher arquivo)**, navegue até o arquivo `AWSSupport-EC2RescueRole.json` e selecione-o no diretório onde foi extraído.
1. Escolha **Próximo**.
1. Na página **Specify stack details (Especificar detalhes da pilha)**, no campo **Stack name (Nome da pilha)**, insira um nome para identificar essa pilha e escolha **Next (Próximo)**.
1. (Opcional) Na área **Tags**, aplique um ou mais pares de nome/valor de chave de tag a pilha.
Tags são metadados opcionais que você atribui a um recurso. Tags permitem categorizar um recurso de diferentes formas, como por finalidade, proprietário ou ambiente. Por exemplo, talvez você queira marcar uma pilha para identificar o tipo de tarefas que ela executa, os tipos de destinos ou outros recursos envolvidos e o ambiente em que ela é executada.
1. Escolha **Next** (Próximo).
1. Na página **Review** (Análise), role para baixo e escolha a opção **I acknowledge that CloudFormation might create IAM resources (Entendo que o ** poderá criar recursos do IAM).
1. Selecione **Criar pilha**.
O CloudFormation mostrará o status **CREATE\$1IN\$1PROGRESS (CRIAÇÃO\$1EM\$1ANDAMENTO)** por alguns minutos. O status mudará para **CREATE\$1COMPLETE** depois que a pilha tiver sido criada. Também é possível escolher o ícone de atualização para verificar o status do processo de criação.
1. Na lista de **Stacks (Pilhas)**, escolha ao botão de opção ao lado da pilha que você acabou de criar e depois escolha a guia **Outputs (Saídas)**.
1. Anote o **Value (Valor)**. Este é o ARN de AssumeRole. Você especificará esse ARN ao executar a automação no próximo procedimento, [Executar a Automação](#automation-ec2rescue-executing).
## Executar a Automação
**Importante**
A automação a seguir interrompe a instância inacessível. A interrupção da instância pode resultar em perda de dados em volumes de armazenamento de instâncias anexados (se presentes). A interrupção da instância também pode fazer com que o IP público seja alterado, caso nenhum IP elástico esteja associado.
**Para executar a automação do `AWSSupport-ExecuteEC2Rescue`**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação à esquerda, escolha **Automation** (Automação).
1. Escolha **Execute automation**.
1. Na seção **Automation document (Documento de automação)**, escolha **Owned by Amazon (De propriedade da Amazon)** na lista.
1. Na lista de runbooks, escolha o botão no cartão para o `AWSSupport-ExecuteEC2Rescue` e, depois, escolha **Next** (Próximo).
1. Na página **Execute automation document (Executar documento de automação)**, escolha **Simple execution (Execução simples)**.
1. Na seção **Document details (Detalhes do documento)**, verifique se **Versão do documento (Document version)** está definida como a versão padrão mais recente. Por exemplo, **\$1DEFAULT** ou **3 (default) (3 (padrão))**.
1. Na seção **Input parameters**, especifique os parâmetros a seguir:
1. Em **UnreachableInstanceId**, especifique o ID da instância inacessível.
1. (Opcional) Em **EC2RescueInstanceType**, especifique um tipo de instância para a instância EC2Rescue. O tipo de instância padrão é `t2.medium`.
1. Em **AutomationAssumeRole**, se você criou funções para esta automação usando o procedimento do CloudFormation descrito anteriormente neste tópico, escolha o ARN de AssumeRole que você criou no console do CloudFormation.
1. (Opcional) Em **LogDestination**, especifique um bucket do S3 se desejar coletar logs no nível do sistema operacional ao solucionar problemas da instância. Os logs são enviados automaticamente para o bucket especificado.
1. Em **SubnetId**, especifique uma sub-rede em uma VPC existente na mesma zona de disponibilidade da instância inacessível. Por padrão, o Systems Manager cria uma nova VPC, mas você pode especificar uma sub-rede em uma VPC existente, se quiser.
**nota**
Se a opção para especificar um bucket ou um ID de sub-rede não estiver disponível, verifique se você está usando a versão **padrão** mais recente do runbook.
1. (Opcional) Na área **Tags** aplique um ou mais pares de nome/valor de chave de tag para ajudar a identificar a automação, por exemplo, `Key=Purpose,Value=EC2Rescue`.
1. Clique em **Executar**.
O runbook cria uma AMI de backup como parte da automação. Todos os outros recursos criados pela automação são automaticamente excluídos, mas essa AMI permanece em sua conta. A AMI é chamada usando a convenção a seguir:
AMI de backup: AWSSupport-EC2Rescue:*UnreachableInstanceId*
Você pode localizar essa AMI no console do Amazon EC2 procurando o ID de execução do Automation.
# Redefinir senhas e chaves SSH em instâncias do EC2
Você pode usar o runbook `AWSSupport-ResetAccess` para reativar automaticamente a geração de senhas do administrador local em instâncias do Amazon Elastic Compute Cloud (Amazon EC2) para o Windows Server e para gerar uma nova chave SSH nas instâncias do EC2 do Linux. O runbook `AWSSupport-ResetAccess` foi projetado para realizar uma combinação de ações do AWS Systems Manager, ações do AWS CloudFormation e funções do AWS Lambda que automatizam as etapas normalmente necessárias para redefinir a senha de administrador local.
Você pode usar o Automation, uma ferramenta do AWS Systems Manager, com o runbook `AWSSupport-ResetAccess` para resolver os seguintes problemas:
**Windows**
*Você perdeu o par de chaves EC2*: para resolver esse problema, você pode usar o runbook **AWSSupport-ResetAccess** para criar uma AMI ativada por senha de sua instância atual, inicie uma nova instância em uma AMI e selecione um par de chaves que você tenha.
*Você perdeu a senha do administrador local*: para resolver esse problema, você pode usar o runbook `AWSSupport-ResetAccess` para gerar uma nova senha que você pode descriptografar com o par de chaves EC2 atual.
**Linux**
*Você perdeu seu par de chaves EC2 ou configurou o acesso SSH à instância com uma chave perdida*: para resolver esse problema, você pode usar o runbook `AWSSupport-ResetAccess` para criar uma nova chave SSH para a instância atual, que permite se conectar à instância novamente.
**nota**
Se a instância do EC2 para Windows Server for configurada para o Systems Manager, você poderá também redefinir a senha de administrador local usando o EC2Rescue e AWS Systems Manager Run Command. Para obter mais informações, consulte [Usar o EC2Rescue for Windows Server com o Run Command do Systems Manager](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2rw-ssm.html) no *Guia do usuário do Amazon EC2*.
**Informações relacionadas**
[Conexão à sua instância do Linux via Windows usando o PuTTY](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/putty.html) no *Guia do usuário do Amazon EC2*
## Como funciona
A solução de problemas em uma instância com o Automation e o runbook `AWSSupport-ResetAccess` funcionam da seguinte maneira:
+ Você especifica o ID da instância e executa o runbook.
+ O sistema cria uma VPC temporária e, em seguida, executa uma série de funções do Lambda para configurar a VPC.
+ O sistema identifica uma sub-rede para sua VPC temporária na mesma Zona de disponibilidade da sua instância original.
+ O sistema executa uma instância temporária auxiliar do , habilitada para o SSM.
+ O sistema interrompe sua instância original e cria um backup. Em seguida, atribui o volume raiz original à instância auxiliar.
+ O sistema usa o Run Command para executar o EC2Rescue na instância auxiliar. No Windows, o EC2Rescue permite a geração de senha para o administrador local usando o EC2Config ou EC2Launch no volume raiz original anexado. No Linux, o EC2Rescue gera e injeta uma nova chave SSH e salva a chave privada, criptografada em Parameter Store. Ao terminar, o EC2Rescue anexa o volume raiz de volta à instância original.
+ O sistema cria uma nova Amazon Machine Image (AMI) de sua instância, agora que a geração de senha está habilitada. Você pode usar essa AMI para criar uma nova instância do EC2 e associar um novo par de chaves, se necessário.
+ O sistema reinicia sua instância original e encerra a instância temporária. O sistema também encerra a VPC temporária e as funções Lambda criadas no início da automação.
+ **Windows**: a instância gera uma nova senha que você pode decodificar no console do Amazon EC2 usando o par de chaves atual designado para a instância.
**Linux**: você pode se conectar à instância via SSH usando a chave SSH armazenada no Systems Manager Parameter Store, como **/ec2rl/openssh/*instance ID*/key**.
## Antes de começar
Antes de executar a automação a seguir:
+ Copie o ID da instância na qual você deseja redefinir a senha de administrador. Você especificará esse ID no procedimento.
+ Opcionalmente, colete o ID de uma sub-rede na mesma zona de disponibilidade como sua instância inacessível. A instância EC2Rescue será criada nessa sub-rede. Se você não especificar uma sub-rede, o Automation criará uma nova VPC temporária em sua Conta da AWS. Verifique se sua Conta da AWS tem pelo menos uma VPC disponível. Por padrão, você pode criar cinco VPCs em uma Região. Se você já tiver criado cinco VPCs na Região, a automação falhará sem fazer alterações na sua instância. Para obter mais informações sobre as cotas da Amazon VPC, consulte [VPC e sub-redes](https://docs.aws.amazon.com/vpc/latest/userguide/amazon-vpc-limits.html#vpc-limits-vpcs-subnets) no *Manual do usuário da Amazon VPC*.
+ Opcionalmente, você pode criar e especificar uma função do AWS Identity and Access Management (IAM) para o Automation. Se você não especificar essa função, a automação será executada no contexto do usuário que executou a automação.
### Conceder a AWSSupport-EC2Rescue permissões para realizar ações em suas instâncias
O EC2Rescue precisa de permissão para realizar uma série de ações nas suas instâncias durante a automação. Essas ações invocam os serviços do AWS Lambda, IAM e Amazon EC2 para tentar corrigir problemas com as instâncias de forma segura. Se você tiver permissões em nível de administrador na sua Conta da AWS e/ou VPC, poderá executar a automação sem configurar permissões, conforme descrito nesta seção. Se não tiver permissões em nível de Administrador, você ou um administrador deverá configurar permissões usando uma das seguintes opções.
+ [Conceder permissões usando políticas do IAM](#automation-ec2reset-access-iam)
+ [Conceder permissões usando um modelo do CloudFormation](#automation-ec2reset-access-cfn)
#### Conceder permissões usando políticas do IAM
É possível anexar a política do IAM a seguir ao seu usuário, grupo ou perfil como uma política em linha, ou criar uma nova política gerenciada do IAM e anexá-la ao seu usuário, grupo ou perfil. Para obter mais informações sobre como adicionar uma política em linha ao seu usuário, grupo ou perfil, consulte [Como trabalhar com políticas em linha](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html). Para obter mais informações sobre como criar uma nova política gerenciada, consulte [Como trabalhar com políticas gerenciadas](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html).
**nota**
Se você criar uma nova política gerenciada do IAM, deverá também anexar a ela a política gerenciada **AmazonSSMAutomationRole** para que suas instâncias possam se comunicar com a API do Systems Manager.
**Política do IAM para `AWSSupport-ResetAccess`**
Substitua *account ID* (ID da conta) por suas próprias informações.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"lambda:InvokeFunction",
"lambda:DeleteFunction",
"lambda:GetFunction"
],
"Resource": "arn:aws:lambda:*:111122223333:function:AWSSupport-EC2Rescue-*",
"Effect": "Allow"
},
{
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": [
"arn:aws:s3:::awssupport-ssm.*/*.template",
"arn:aws:s3:::awssupport-ssm.*/*.zip"
],
"Effect": "Allow"
},
{
"Action": [
"iam:CreateRole",
"iam:CreateInstanceProfile",
"iam:GetRole",
"iam:GetInstanceProfile",
"iam:PutRolePolicy",
"iam:DetachRolePolicy",
"iam:AttachRolePolicy",
"iam:PassRole",
"iam:AddRoleToInstanceProfile",
"iam:RemoveRoleFromInstanceProfile",
"iam:DeleteRole",
"iam:DeleteRolePolicy",
"iam:DeleteInstanceProfile"
],
"Resource": [
"arn:aws:iam::111122223333:role/AWSSupport-EC2Rescue-*",
"arn:aws:iam::111122223333:instance-profile/AWSSupport-EC2Rescue-*"
],
"Effect": "Allow"
},
{
"Action": [
"lambda:CreateFunction",
"ec2:CreateVpc",
"ec2:ModifyVpcAttribute",
"ec2:DeleteVpc",
"ec2:CreateInternetGateway",
"ec2:AttachInternetGateway",
"ec2:DetachInternetGateway",
"ec2:DeleteInternetGateway",
"ec2:CreateSubnet",
"ec2:DeleteSubnet",
"ec2:CreateRoute",
"ec2:DeleteRoute",
"ec2:CreateRouteTable",
"ec2:AssociateRouteTable",
"ec2:DisassociateRouteTable",
"ec2:DeleteRouteTable",
"ec2:CreateVpcEndpoint",
"ec2:DeleteVpcEndpoints",
"ec2:ModifyVpcEndpoint",
"ec2:Describe*"
],
"Resource": "*",
"Effect": "Allow"
}
]
}
```
------
#### Conceder permissões usando um modelo do CloudFormation
CloudFormationO automatiza o processo de criação de políticas e funções do IAM, usando um modelo pré-configurado. Use o procedimento a seguir para criar as funções e políticas do IAM necessárias para o Automation EC2Rescue, usando o CloudFormation.
**Para criar as funções e políticas do IAM necessárias para o EC2Rescue**
1. Faça download de [https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWSSupport-EC2RescueRole.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWSSupport-EC2RescueRole.zip) e extraia o arquivo `AWSSupport-EC2RescueRole.json` para um diretório em sua máquina local.
1. Se sua Conta da AWS estiver em uma partição especial, edite o modelo para alterar os valores do ARN para os valores da sua partição.
Por exemplo, para as regiões da China, altere todos os casos de `arn:aws` para `arn:aws-cn`.
1. Faça login no Console de gerenciamento da AWS e abra o console CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Escolha **Create stack (Criar pilha)**, **With new resources (Com novos recursos (padrão))**.
1. Na página **Create stack (Criar pilha)**, em **Prerequisite - Prepare template (Pré-requisito – Preparar modelo)**, escolha **Template is ready (O modelo está pronto)**.
1. Em **Specify template (Especificar modelo)**, escolha **Upload a template file (Fazer upload de um arquivo de modelo)**.
1. Escolha **Choose file (Escolher arquivo)**, navegue até o arquivo `AWSSupport-EC2RescueRole.json` e selecione-o no diretório onde foi extraído.
1. Escolha **Próximo**.
1. Na página **Specify stack details (Especificar detalhes da pilha)**, no campo **Stack name (Nome da pilha)**, insira um nome para identificar essa pilha e escolha **Next (Próximo)**.
1. (Opcional) Na área **Tags**, aplique um ou mais pares de nome/valor de chave de tag a pilha.
Tags são metadados opcionais que você atribui a um recurso. Tags permitem categorizar um recurso de diferentes formas, como por finalidade, proprietário ou ambiente. Por exemplo, talvez você queira marcar uma pilha para identificar o tipo de tarefas que ela executa, os tipos de destinos ou outros recursos envolvidos e o ambiente em que ela é executada.
1. Escolha **Next** (Próximo).
1. Na página **Review** (Análise), role para baixo e escolha a opção **I acknowledge that CloudFormation might create IAM resources (Entendo que o ** poderá criar recursos do IAM).
1. O CloudFormation mostrará o status **CREATE\$1IN\$1PROGRESS (CRIAÇÃO\$1EM\$1ANDAMENTO)** por alguns minutos. O status mudará para **CREATE\$1COMPLETE** depois que a pilha tiver sido criada. Também é possível escolher o ícone de atualização para verificar o status do processo de criação.
1. Na lista de pilhas, escolha a opção ao lado da pilha que você acabou de criar e selecione a guia **Outputs (Saídas)**.
1. Copie o conteúdo em **Value**. Este é o ARN de AssumeRole. Você especificará esse ARN quando executar a automação.
## Executar a Automação
O procedimento a seguir descreve como executar o runbook `AWSSupport-ResetAccess` usando o console do AWS Systems Manager.
**Importante**
A automação a seguir interrompe a instância. A interrupção da instância pode resultar em perda de dados em volumes de armazenamento de instâncias anexados (se presentes). A interrupção da instância também pode fazer com que o IP público seja alterado, caso nenhum IP elástico esteja associado. Para evitar essas alterações de configuração, use o Run Command para redefinir o acesso. Para obter mais informações, consulte [Usar o EC2Rescue para Windows Server com o Run Command do Systems Manager](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2rw-ssm.html) no *Guia do usuário do Amazon EC2*.
**Para executar a automação AWSSupport-ResetAccess**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação à esquerda, escolha **Automation** (Automação).
1. Escolha **Execute automation**.
1. Na seção **Automation document (Documento de automação)**, escolha **Owned by Amazon (De propriedade da Amazon)** na lista.
1. Na lista de runbooks, escolha o botão no cartão para **AWSSupport-ResetAccess** e escolha **Next** (Próximo).
1. Na página **Execute automation document (Executar documento de automação)**, escolha **Simple execution (Execução simples)**.
1. Na seção **Document details (Detalhes do documento)**, verifique se **Versão do documento (Document version)** está definida como a versão padrão mais recente. Por exemplo, **\$1DEFAULT** ou **3 (default) (3 (padrão))**.
1. Na seção **Input parameters**, especifique os parâmetros a seguir:
1. Em **InstanceID**, especifique o ID da instância inacessível.
1. Em **SubnetId**, especifique uma sub-rede em uma VPC existente na mesma zona de disponibilidade da instância que você especificou. Por padrão, o Systems Manager cria uma nova VPC, mas você pode especificar uma sub-rede em uma VPC existente, se quiser.
**nota**
Se a opção para especificar um ID de sub-rede não estiver disponível, verifique se você está usando a versão **padrão** mais recente do runbook.
1. Em **EC2RescueInstanceType**, especifique um tipo de instância para a instância EC2Rescue. O tipo de instância padrão é `t2.medium`.
1. Em **AssumeRole**, se você criou funções para essa automação usando o procedimento do CloudFormation descrito anteriormente neste tópico, especifique o ARN de AssumeRole que você anotou no console do CloudFormation.
1. (Opcional) Na área **Tags** aplique um ou mais pares de nome/valor de chave de tag para ajudar a identificar a automação, por exemplo, `Key=Purpose,Value=ResetAccess`.
1. Clique em **Executar**.
1. Para monitorar o progresso da automação, escolha a automação em execução e depois escolha a guia **Steps** (Etapas). Quando a automação for concluída, escolha a guia **Descriptions** (Descrições) e, em seguida, **View output** (Exibir resultados) para visualizar os resultados. Para exibir a saída de etapas individuais, selecione a guia **Steps (Etapas)** e selecione **View Outputs (Visualizar saídas)** ao lado de uma etapa.
O runbook cria uma AMI de backup e uma AMI ativada por senha como parte da automação. Todos os outros recursos criados pela automação são automaticamente excluídos, mas essas AMIs permanecem em sua conta. As AMIs são nomeadas usando as seguintes convenções:
+ AMI de backup: `AWSSupport-EC2Rescue:InstanceID`
+ AMI ativada por senha: AWSSupport-EC2Rescue: AMI ativada por senha de *Instance ID*
Você pode localizar essas AMIs procurando o ID de execução do Automation.
No Linux, a nova chave privada SSH para sua instância é salva, criptografada, Parameter Store. O nome do parâmetro é **/ec2rl/openssh/*Instance ID*/key**.
# Transferência de dados para o Automation usando transformadores de entrada
Este tutorial do AWS Systems Manager Automation mostra como usar o recurso transformador de entrada do Amazon EventBridge para extrair o `instance-id` de uma instância do Amazon Elastic Compute Cloud (Amazon EC2) de um evento de alteração de estado da instância. O Automation é uma ferramenta do AWS Systems Manager. Usamos o transformador de entrada para passar esses dados ao destino do runbook do `AWS-CreateImage`, como o parâmetro de entrada do `InstanceId`. A regra será acionada quando qualquer instância for alterada para o estado `stopped`.
Para obter mais informações sobre como trabalhar com transformadores de entrada, consulte [Tutorial: Use o transformador de entrada para personalizar o que o EventBridge passa para o destino do evento](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-input-transformer-tutorial.html) no *Manual do usuário do Amazon EventBridge*.
**Antes de começar**
Verifique se adicionou as permissões necessárias e a política de confiança para o EventBridge para a função de serviço do Systems Manager Automation. Para obter mais informações, consulte [Visão geral do gerenciamento de permissões de acesso aos recursos do EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/iam-access-control-identity-based-eventbridge.html) no *Manual do usuário do Amazon EventBridge*.
**Como usar transformadores de entrada com automação**
1. Abra o console do Amazon EventBridge em [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. No painel de navegação, escolha **Regras**.
1. Escolha **Create rule**.
1. Insira um nome e uma descrição para a regra.
Uma regra não pode ter o mesmo nome que outra na mesma Região e barramento de eventos.
1. Em **Barramento de eventos**, selecione o barramento de eventos que você deseja associar a essa regra. Se você quiser que essa regra responda a eventos correspondentes provenientes da sua Conta da AWS, selecione **default** (padrão). Quando um AWS service (Serviço da AWS) na sua conta emite um evento, ele sempre vai para o barramento de eventos padrão da sua conta.
1. Em **Rule type**, escolha **Rule with an event pattern**.
1. Escolha **Próximo**.
1. Em **Event source**, escolha **Eventos da AWS ou eventos de parceiro do EventBridge**.
1. Na seção **Padrão de evento**, selecione **Formulário de padrão de evento**.
1. Em **Event source** (Origem do evento), escolha **AWS services** (Serviços da ).
1. Em **Serviço da AWS**, escolha **EC2**.
1. Para **Event Type (Tipo de evento)**, escolha **EC2 Instance State-change Notification (Notificação de alteração de estado da instância do EC2)**.
1. Para **Especificação de tipo de evento 1**, selecione **Estado(s) específico(s)** e escolha **parado**.
1. Para **Especificação de tipo de evento 2**, selecione **Qualquer instância** ou selecione **ID(s) de instância específica** e insira as IDs das instâncias a serem monitoradas.
1. Escolha **Próximo**.
1. Em **Tipos de destino**, escolha **Serviço da AWS**.
1. Para **Select a target** (Selecionar um destino), escolha **Systems Manager Automation** (Automation do Systems Manager).
1. Em **Document (Documento)**, escolha **AWS-CreateImage**.
1. Na seção **Configure automation parameter(s)** (Configurar parâmetros de automação), escolha **Input Transformer** (Transformador de entrada).
1. Para **Input path** (Caminho de entrada), insira **\$1"instance":"\$1.detail.instance-id"\$1**.
1. Para **Template** (Modelo), insira **\$1"InstanceId":[]\$1**.
1. Para **Execution role**, escolha **Use existing role** (Usar função existente) e escolha sua função de serviço do Automation.
1. Escolha **Próximo**.
1. (Opcional) Insira uma ou mais tags para a regra. Para obter mais informações, consulte [Marcar recursos do Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-tagging.html) no *Guia do usuário do Amazon EventBridge*.
1. Escolha **Próximo**.
1. Analise os detalhes da regra e selecione **Criar regra**.
# Saiba mais sobre os status retornados pelo Systems Manager Automation
AWS Systems ManagerO Automation relata informações detalhadas de status sobre os vários status que uma ação ou etapa de automação passa quando você executa uma automação e para a automação geral. O Automation é uma ferramenta do AWS Systems Manager. Você pode monitorar os status da automação usando os seguintes métodos:
+ Monitore o **Execution status** (Status da execução) no console do Systems Manager Automation.
+ Use suas ferramentas de linha de comando preferidas. Para a AWS Command Line Interface (AWS CLI), você pode usar [describe-automation-step-executions](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-automation-step-executions.html) ou [get-automation-execution](https://docs.aws.amazon.com/cli/latest/reference/ssm/get-automation-execution.html). Para o AWS Tools for Windows PowerShell, você pode usar [Get -SsMAutoMationStepExecution](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-SSMAutomationStepExecution.html) ou [Get -SsMAutoMationExecution](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-SSMAutomationExecution.html).
+ Configure o Amazon EventBridge para responder a alterações de status de ação ou automação.
Para obter mais informações sobre como processar tempos limite em uma automação, consulte [Gerenciar tempos limite em runbooks](automation-handling-timeouts.md).
## Sobre status de automação
Os relatórios de automação relatam detalhes das ações de automação individuais, além da automação geral.
O status geral da automação pode ser diferente do status relatado por uma ação individual ou etapa, conforme observado nas tabelas a seguir.
**Status detalhado das ações**
| Status | Detalhes |
| --- | --- |
| Pendente | A execução da etapa ainda não começou. Se a automação usar ações condicionais, as etapas permanecerão nesse estado após a conclusão de uma automação se a condição não tiver sido atendida para executar a etapa. As etapas também permanecem nesse estado se a automação for cancelada antes da execução da etapa. |
| InProgress | A etapa está em execução. |
| Aguardando | A etapa está aguardando inserção de informações. |
| Bem-sucedida | A etapa foi concluída com êxito. Este é um estado terminal. |
| TimedOut | Uma etapa ou aprovação não foi concluída antes do período de tempo limite especificado. Este é um estado terminal. |
| Cancelando | A etapa está em processo de interrupção após ser cancelada por um solicitante. |
| Cancelado | A etapa foi interrompida por um solicitante antes de ser concluída. Este é um estado terminal. |
| Failed | A etapa não foi concluída com êxito. Este é um estado terminal. |
| Exited | Retornado somente pela ação `aws:loop`. O loop não foi totalmente concluído. Uma etapa dentro do loop foi movida para uma etapa externa usando as propriedades `nextStep`, `onCancel` ou `onFailure`. |
**Status detalhado de uma automação**
| Status | Detalhes |
| --- | --- |
| Pendente | A automação ainda não começou a ser executada. |
| InProgress | A automação está em execução. |
| Aguardando | A automação está aguardando a entrada. |
| Bem-sucedida | A automação foi concluída com êxito. Este é um estado terminal. |
| TimedOut | Uma etapa ou aprovação não foi concluída antes do período de tempo limite especificado. Este é um estado terminal. |
| Cancelando | A automação está em processo de interrupção após ser cancelada por um solicitante. |
| Cancelado | A automação foi interrompida por um solicitante antes de ser concluída. Este é um estado terminal. |
| Failed | A automação não foi concluída com êxito. Este é um estado terminal. |
# Solução de problemas do Systems Manager Automation
Use as informações a seguir para obter ajuda para solucionar problemas com o AWS Systems Manager Automation, uma ferramenta do AWS Systems Manager. Este tópico inclui tarefas específicas para resolver problemas com base em mensagens de erro de Automação.
**Topics**
+ [Erros comuns de automação](#automation-trbl-common)
+ [Falha ao iniciar a execução da automação](#automation-trbl-access)
+ [Execução iniciada, mas o status falhou](#automation-trbl-exstrt)
+ [Execução iniciada, mas tempo limite atingido](#automation-trbl-to)
## Erros comuns de automação
Esta seção inclui informações sobre erros comuns de Automação.
### VPC não definida 400
Por padrão, quando o Automation executa o runbook `AWS-UpdateLinuxAmi` ou `AWS-UpdateWindowsAmi`, o sistema cria uma instância temporária na VPC padrão (172.30.0.0/16). Se tiver excluído a VPC padrão, você receberá o seguinte erro:
`VPC not defined 400`
Para resolver esse problema, você deve especificar um valor para o parâmetro de entrada `SubnetId`.
## Falha ao iniciar a execução da automação
Uma automação pode apresentar falhas com um erro de acesso negado ou um erro de perfil assumido inválido, se você não tiver configurado corretamente as políticas e os perfis do AWS Identity and Access Management (IAM) para o Automation.
### Acesso negado
Os exemplos a seguir descrevem situações em que uma automação não foi iniciada, sinalizando um erro de acesso negado.
**Acesso negado à API do Systems Manager**
**Mensagem de erro**: `User: user arn isn't authorized to perform: ssm:StartAutomationExecution on resource: document arn (Service: AWSSimpleSystemsManagement; Status Code: 400; Error Code: AccessDeniedException; Request ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)`
+ Causa possível 1: o usuário que está tentando iniciar a automação não tem permissões para invocar a API `StartAutomationExecution`. Para resolver esse problema, anexe a política do IAM requerida ao usuário que foi usado para iniciar a automação.
+ Causa possível 2: o usuário que está tentando iniciar a automação tem permissões para invocar a API `StartAutomationExecution`, mas não tem permissões para invocar a API usando o runbook específico. Para resolver esse problema, anexe a política do IAM requerida ao usuário que foi usado para iniciar a automação.
**Acesso negado por ausência de permissões PassRole**
**Mensagem de erro**: `User: user arn isn't authorized to perform: iam:PassRole on resource: automation assume role arn (Service: AWSSimpleSystemsManagement; Status Code: 400; Error Code: AccessDeniedException; Request ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)`
O usuário que está tentando iniciar a automação não tem permissões PassRole para assumir o perfil. Para resolver esse problema, anexe a política iam:PassRole ao perfil do usuário que está tentando iniciar a automação. Para obter mais informações, consulte [Tarefa 2: Anexar a política iam:PassRole à função de automação](automation-setup-iam.md#attach-passrole-policy).
### Função assumida inválida
Quando você executa um Automation, uma função assumida é fornecida no runbook ou transmitida como um valor de parâmetro para o runbook. Diferentes tipos de erros poderão ocorrer se a função assumida não for especificada ou configurada corretamente.
**Função de admissão malformada**
**Mensagem de erro**: `The format of the supplied assume role ARN isn't valid.` A função de admissão está mal formatada. Para resolver esse problema, verifique se uma função assumida válida está especificada no seu runbook ou como um parâmetro em runtime ao executar a automação.
**Não é possível assumir o perfil assumido**
**Mensagem de erro**: `The defined assume role is unable to be assumed. (Service: AWSSimpleSystemsManagement; Status Code: 400; Error Code: InvalidAutomationExecutionParametersException; Request ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)`
+ Causa possível 1: a função assumida não existe. Para resolver esse problema, crie a função. Para obter mais informações, consulte [Configurar a automação](automation-setup.md). Detalhes específicos para a criação dessa função estão descritos no seguinte tópico, [Tarefa 1: Criar uma função de serviço para a automação](automation-setup-iam.md#create-service-role).
+ Causa possível 2: a função assumida não possui uma relação de confiança com o serviço do Systems Manager. Para resolver esse problema, crie a relação de confiança. Para obter mais informações, consulte [Não consigo assumir uma função](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_roles.html#troubleshoot_roles_cant-assume-role) no *Manual do usuário do IAM*.
## Execução iniciada, mas o status falhou
### Falhas específicas da ação
Runbooks contêm etapas e elas são executadas em ordem. Cada etapa invoca uma ou mais APIs de AWS service (Serviço da AWS). Essas APIs determinam as entradas, o comportamento e as saídas da etapa. Há vários locais em que um erro pode causar uma falha na etapa. As mensagens de falha indicam quando e onde um erro ocorreu.
Para ver uma mensagem de falha no console do Amazon Elastic Compute Cloud (Amazon EC2), escolha o link **View Outputs** (Exibir resultados) da etapa com falha. Para ver uma mensagem de falha da AWS CLI, chame `get-automation-execution` e procure o atributo `FailureMessage` em um `StepExecution` com falha.
Nos exemplos a seguir, uma etapa associada à ação `aws:runInstance` falhou. Cada exemplo explora um tipo diferente de erro.
**Imagem ausente**
**Mensagem de erro**: `Automation Step Execution fails when it's launching the instance(s). Get Exception from RunInstances API of ec2 Service. Exception Message from RunInstances API: [The image id '[ami id]' doesn't exist (Service: AmazonEC2; Status Code: 400; Error Code: InvalidAMIID.NotFound; Request ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)]. Please refer to Automation Service Troubleshooting Guide for more diagnosis details.`
A ação `aws:runInstances` recebeu uma entrada para um `ImageId` que não existe. Para resolver esse problema, atualize o runbook ou os valores de parâmetros com o ID correto da AMI.
**A política do perfil assumido não tem permissões suficientes**
**Mensagem de erro**: `Automation Step Execution fails when it's launching the instance(s). Get Exception from RunInstances API of ec2 Service. Exception Message from RunInstances API: [You aren't authorized to perform this operation. Encoded authorization failure message: xxxxxxx (Service: AmazonEC2; Status Code: 403; Error Code: UnauthorizedOperation; Request ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)]. Please refer to Automation Service Troubleshooting Guide for more diagnosis details.`
A função de assunção não tem permissão suficiente para invocar a API `RunInstances` em instâncias do EC2. Para resolver esse problema, anexe uma política do IAM à função assumida que tenha permissão para invocar a API `RunInstances`. Para obter mais informações, consulte a [Criar perfis de serviço para o Automation usando o console](automation-setup-iam.md).
**Estado inesperado**
**Mensagem de erro**: `Step fails when it's verifying launched instance(s) are ready to be used. Instance i-xxxxxxxxx entered unexpected state: shutting-down. Please refer to Automation Service Troubleshooting Guide for more diagnosis details.`
+ Causa possível 1: há um problema com a instância ou o serviço do Amazon EC2. Para resolver esse problema, faça login na instância ou revise o log do sistema da instância para entender por que ela iniciou o desligamento.
+ Causa possível 2: o script de dados do usuário especificado para a ação `aws:runInstances` tem um problema ou uma sintaxe incorreta. Verifique a sintaxe do script de dados do usuário. Além disso, verifique se os scripts de dados do usuário não desligam a instância ou invocam outros scripts que desligam a instância.
**Referência a falhas específicas de ação**
Quando uma etapa falha, a mensagem de falha pode indicar qual serviço foi invocado quando a falha ocorreu. A tabela a seguir lista os serviços invocados por cada ação. Ela também fornece links para obter informações sobre cada serviço.
****
| Ação | Serviços da AWS invocados por essa ação | Para obter informações sobre este serviço | Solucionar problemas de conteúdo |
| --- | --- | --- | --- |
| `aws:runInstances` | Amazon EC2 | [Guia do usuário do Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/) | [Solucionar problemas com instâncias do EC](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-troubleshoot.html) |
| `aws:changeInstanceState` | Amazon EC2 | [Guia do usuário do Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/) | [Solucionar problemas com instâncias do EC](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-troubleshoot.html) |
| `aws:runCommand` | Systems Manager | [AWS Systems Manager Run Command](run-command.md) | [Solução de problemas do Run Commando do Systems Manager](troubleshooting-remote-commands.md) |
| `aws:createImage` | Amazon EC2 | [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) | |
| `aws:createStack` | CloudFormation | [AWS CloudFormation Guia do usuário do](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) | [Solução de problemas CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/troubleshooting.html) |
| `aws:deleteStack` | CloudFormation | [AWS CloudFormation Guia do usuário do](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) | [Solução de problemas CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/troubleshooting.html) |
| `aws:deleteImage` | Amazon EC2 | [Imagens de máquina da Amazon](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) | |
| `aws:copyImage` | Amazon EC2 | [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) | |
| `aws:createTag` | Amazon EC2, Systems Manager | [Recurso e etiquetas do EC](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_Resources.html) | |
| `aws:invokeLambdaFunction` | AWS Lambda | [AWS Lambda Guia do desenvolvedor](https://docs.aws.amazon.com/lambda/latest/dg/) | [Solução de problemas do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-functions.html) |
### Erro interno do serviço de automação
**Mensagem de erro**: `Internal Server Error. Please refer to Automation Service Troubleshooting Guide for more diagnosis details.`
Um problema com o serviço Automation está impedindo que o runbook especificado seja executado corretamente. Para resolver esse problema, entre em contato com o AWS Support. Forneça o ID de execução e o ID de cliente, se disponíveis.
## Execução iniciada, mas tempo limite atingido
**Mensagem de erro**: `Step timed out while step is verifying launched instance(s) are ready to be used. Please refer to Automation Service Troubleshooting Guide for more diagnosis details.`
Uma etapa na ação `aws:runInstances` atingiu o tempo limite. Isso pode acontecer se a ação da etapa demorar mais para ser executada do que o valor especificado para `timeoutSeconds` na etapa. Para resolver esse problema, especifique um valor mais longo para o parâmetro `timeoutSeconds` da ação `aws:runInstances`. Se isso não resolver o problema, investigue por que a etapa demora mais para ser executada do que o esperado
# AWS Systems Manager Change Calendar
O Change Calendar, uma ferramenta do AWS Systems Manager, permite configurar intervalos de data e hora quando as ações especificadas (por exemplo, em runbooks do [Systems Manager Automation](systems-manager-automation.md)) podem ou não ser executadas em sua Conta da AWS. No Change Calendar, esses intervalos são chamados de *eventos*. Ao criar uma entrada do Change Calendar, você está criando um [documento do Systems Manager](documents.md) do tipo `ChangeCalendar`. No Change Calendar, o documento armazena dados do [iCalendar 2.0](https://icalendar.org/) em formato de texto simples. Os eventos adicionados à entrada do Change Calendar tornam-se parte do documento. Para começar a usar o Change Calendar, abra o [Systems Manager console](https://console.aws.amazon.com//systems-manager/change-calendar) (Console do gerenciador de sistemas). No painel de navegação, escolha **Change Calendar**.
Você pode criar um calendário e seus eventos no console do Systems Manager. Você pode também importar um arquivo do iCalendar (`.ics`) que você exportou de um provedor de calendário de terceiros compatível, para adicionar seus eventos ao calendário. Os provedores compatíveis incluem o Google Agenda, o Microsoft Outlook e o Calendário do iCloud.
Uma entrada do Change Calendar pode ser de dois tipos:
**`DEFAULT_OPEN`**, ou Aberto por padrão
Todas as ações podem ser executadas por padrão, exceto durante eventos do calendário. Durante eventos, o estado de um calendário `DEFAULT_OPEN` é `CLOSED` e os eventos são bloqueados para execução.
**`DEFAULT_CLOSED`**, ou Fechado por padrão
Todas as ações são bloqueadas por padrão, exceto durante eventos do calendário. Durante eventos, o estado de um calendário `DEFAULT_CLOSED` é `OPEN` e as ações podem ser executadas.
Você pode optar por ter todos os fluxos de trabalho do Automation, janelas de manutenção e associações do State Manager agendados adicionados automaticamente a um calendário. Também é possível remover qualquer um desses tipos individuais da exibição de calendário.
## Quem deve usar o Change Calendar?
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
+ Clientes da AWS que realizam os seguintes tipos de ação:
+ Crie ou execute runbooks do Automation.
+ Crie solicitações de alteração no Change Manager.
+ Executar janelas de manutenção.
+ Crie associações no State Manager.
Automation, Change Manager, Maintenance Windows e State Manager são ferramentas do AWS Systems Manager. Ao integrar essas ferramentas ao Change Calendar, você poderá permitir ou bloquear esses tipos de ações dependendo do estado atual do calendário de alterações que associar a cada um deles.
+ Administradores responsáveis por manter as configurações dos nós gerenciados pelo Systems Manager consistentes, estáveis e funcionais.
## Benefícios do Change Calendar
Veja a seguir alguns benefícios do Change Calendar.
+ **Revisar as alterações antes de serem aplicadas**
Uma entrada do Change Calendar pode ajudar a garantir que alterações potencialmente destrutivas em seu ambiente sejam analisadas antes de serem aplicadas.
+ **Aplicar alterações somente nas horas apropriadas**
Change CalendarO ajuda a manter seu ambiente estável durante os horários dos eventos. Por exemplo, é possível criar uma entrada do Change Calendar para bloquear alterações quando você espera uma alta demanda em seus recursos, como durante uma conferência ou promoção de marketing pública. Uma entrada de calendário também pode bloquear alterações quando você espera suporte limitado do administrador, como durante férias ou feriados. É possível usar uma entrada de calendário para permitir alterações, exceto em determinadas horas do dia ou da semana, quando há suporte limitado do administrador para solucionar problemas de ações ou implantações com falha.
+ **Obter o estado atual ou futuro do calendário**
Você pode executar a operação da API `GetCalendarState` do Systems Manager para mostrar o estado atual do calendário, o estado em uma hora especificada ou a próxima vez que o estado do calendário estiver programado para alterar.
**nota**
A API `GetCalendarState` tem uma cota de dez solicitações por segundo. Para obter informações sobre as cotas do System Manager, consulte [Systems Manager service quotas](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm) no *Referência geral da Amazon Web Services*.
+
**Suporte ao EventBridge**
Essa ferramenta do Systems Manager pode ser usada como um tipo de *evento* nas regras do Amazon EventBridge. Para obter informações, consulte [Monitorar eventos do Systems Manager com o Amazon EventBridge](monitoring-eventbridge-events.md) e [Referência: padrões e tipos de eventos do Amazon EventBridge para o Systems Manager](reference-eventbridge-events.md).
**Topics**
+ [Quem deve usar o Change Calendar?](#systems-manager-change-calendar-who)
+ [Benefícios do Change Calendar](#systems-manager-change-calendar-benefits)
+ [Configurar o Change Calendar](systems-manager-change-calendar-prereqs.md)
+ [Trabalhar com o Change Calendar](systems-manager-change-calendar-working.md)
+ [Adicionar dependências do Change Calendar para runbooks do Automation](systems-manager-change-calendar-automations.md)
+ [Solução de problemas do Change Calendar](change-calendar-troubleshooting.md)
# Configurar o Change Calendar
Conclua o seguinte antes de usar o Change Calendar, uma ferramenta do AWS Systems Manager.
## Instalar as ferramentas de linha de comando mais recentes
Instale as ferramentas de linha de comando mais recentes para obter informações de estado sobre calendários.
| Requisito | Descrição |
| --- | --- |
| AWS CLI | (Opcional) Para usar a AWS Command Line Interface (AWS CLI) para obter informações de estado sobre calendários, instale a versão mais recente da AWS CLI no computador local. Para obter mais informações sobre como instalar ou atualizar a CLI, consulte [Instalar, atualizar e desinstalar a AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) no *Guia do usuário da AWS Command Line Interface*. |
| Ferramentas da AWS para PowerShell | (Opcional) Para usar o Tools for PowerShell para obter informações de estado sobre calendários, instale a versão mais recente do Tools for PowerShell no computador local. Para obter mais informações sobre como instalar ou atualizar a Tools for PowerShell, consulte [Instalar a Ferramentas da AWS para PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html) no *Guia do usuário da Ferramentas da AWS para PowerShell*. |
## Configurar permissões
Se seu usuário, grupo ou perfil tiver permissões de administrador atribuídas, você terá acesso total ao Change Calendar. Se você não tiver permissões de administrador, um administrador deverá conceder as permissões ao atribuir a política gerenciada `AmazonSSMFullAccess` ou ao atribuir uma política que forneça as permissões necessárias para seu usuário, grupo ou perfil.
As seguintes permissões são necessárias para trabalhar com o Change Calendar.
**Entradas do Change Calendar**
Para criar, atualizar ou excluir uma entrada do Change Calendar, incluindo adicionar e remover eventos da entrada, uma política anexada ao usuário, perfil ou grupo deve permitir as seguintes ações:
+ `ssm:CreateDocument`
+ `ssm:DeleteDocument`
+ `ssm:DescribeDocument`
+ `ssm:DescribeDocumentPermission`
+ `ssm:GetCalendar`
+ `ssm:ListDocuments`
+ `ssm:ModifyDocumentPermission`
+ `ssm:PutCalendar`
+ `ssm:UpdateDocument`
+ `ssm:UpdateDocumentDefaultVersion`
**Estado do calendário**
Para obter informações sobre o estado atual ou futuro do calendário, uma política anexada ao usuário, grupo ou perfil deve permitir a seguinte ação:
+ `ssm:GetCalendarState`
**Eventos operacionais**
Para visualizar eventos operacionais, como janelas de manutenção, associações e automações planejadas, a política anexada ao usuário, grupo ou perfil deve permitir estas ações:
+ `ssm:DescribeMaintenanceWindows`
+ `ssm:DescribeMaintenanceWindowExecution`
+ `ssm:DescribeAutomationExecutions`
+ `ssm:ListAssociations`
**nota**
Change CalendarAs entradas do que são de propriedade das (ou seja, criadas por) contas que não sejam suas são somente leitura, mesmo que compartilhadas com sua conta. Janelas de manutenção, associações do State Manager e automações não são compartilhadas.
# Trabalhar com o Change Calendar
É possível usar o console do AWS Systems Manager para adicionar, gerenciar ou excluir entradas no Change Calendar, uma ferramenta do AWS Systems Manager. Você também pode importar eventos de provedores de calendário de terceiros compatíveis, importando um arquivo do iCalendar (`.ics`) exportado do calendário de origem. E você pode usar a operação API `GetCalendarState` ou o comando `get-calendar-state` da AWS Command Line Interface (AWS CLI) para obter informações sobre o estado do Change Calendar em um horário específico.
**Topics**
+ [Criar um calendário de alterações](change-calendar-create.md)
+ [Criar e gerenciar eventos no Change Calendar](change-calendar-events.md)
+ [Importar e gerenciar eventos de calendários de terceiros](third-party-events.md)
+ [Atualizar um calendário de alterações](change-calendar-update.md)
+ [Compartilhar um calendário de alterações](change-calendar-share.md)
+ [Excluir um calendário de alterações](change-calendar-delete.md)
+ [Obter o estado de um calendário de alterações](change-calendar-getstate.md)
# Criar um calendário de alterações
Quando você cria uma entrada no Change Calendar, uma ferramenta do AWS Systems Manager, você está criando um documento do Systems Manager (documento SSM) que usa o formato `text`.
**Para criar um calendário de alterações**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Calendar**.
1. Escolha **Create calendar (Criar calendário)**.
- ou -
Se a página inicial **Change Calendar** abrir primeiro, escolha **Create change calendar** (Criar calendário de alterações).
1. Na página **Create calendar (Criar calendário)** em **Calendar details (Detalhes do calendário)**, insira um nome para a entrada do calendário. Nomes de entradas do calendário podem conter letras, números, pontos, traços e sublinhados. O nome deve ser específico o suficiente para identificar rapidamente a finalidade da entrada do calendário. Um exemplo é **support-off-hours**. Não é possível atualizar esse nome depois de criar a entrada do calendário.
1. Em **Description** (Descrição), insira uma descrição para a sua entrada do calendário.
1. (Opcional) Na área **Import calendar** (Importar calendário), selecione **Choose file** (Escolher arquivo) para selecionar um arquivo do iCalendar (`.ics`) exportado de um provedor de calendário terceirizado. Importar o arquivo adicionará seus eventos ao seu calendário.
Os provedores compatíveis incluem o Google Agenda, o Microsoft Outlook e o Calendário do iCloud.
Para ter mais informações, consulte [Importar eventos de provedores de calendário de terceiros](change-calendar-import.md).
1. Em **Calendar type (Tipo de calendário)**, escolha uma das seguintes opções.
+ **Open by default** (Aberto por padrão): o calendário é aberto (as ações de automação podem ser executadas até que um evento seja iniciado) e fechado logo depois pela duração de um evento associado.
+ **Closed by default** (Fechado por padrão) - o calendário está fechado (as ações do Automation não podem ser executadas até que um evento seja iniciado), mas é aberto durante um evento associado.
1. (Opcional) Em **Eventos de gerenciamento de alterações**, selecione **Adicionar eventos de gerenciamento de alterações ao calendário**. Essa seleção exibe todas as janelas de manutenção programada, associações do State Manager, fluxos de trabalho do Automation e solicitações de alterações do Change Manager na exibição do calendário mensal.
**dica**
Depois, caso você queira remover permanentemente esses tipos de eventos da exibição do calendário, edite o calendário, desmarque essa caixa de seleção e escolha **Salvar**.
1. Escolha **Create calendar (Criar calendário)**.
Depois que a entrada do calendário for criada, o Systems Manager exibirá a entrada do calendário na lista **Change Calendar**. As colunas exibem a versão do calendário e o número de conta da Conta da AWS do proprietário do calendário. Sua entrada do calendário não pode prevenir ou permitir nenhuma ação até que você adicione pelo menos um evento. Para obter mais informações sobre como criar um evento, consulte [Criar um evento do Change Calendar](change-calendar-create-event.md). Para obter mais informações sobre a importação de eventos, consulte [Importar eventos de provedores de calendário de terceiros](change-calendar-import.md).
# Criar e gerenciar eventos no Change Calendar
Depois de criar um calendário no AWS Systems Manager Change Calendar, você poderá criar, atualizar e excluir eventos incluídos no calendário aberto ou fechado. O Change Calendar é uma ferramenta do AWS Systems Manager.
**dica**
Como alternativa à criação de eventos diretamente no console do Systems Manager, você pode importar um iCalendar (`.ics`) de uma aplicação de calendário de terceiros compatível. Para mais informações, consulte [Importar e gerenciar eventos de calendários de terceiros](third-party-events.md).
**Topics**
+ [Criar um evento do Change Calendar](change-calendar-create-event.md)
+ [Atualizar um evento do Change Calendar](change-calendar-update-event.md)
+ [Excluir um evento do Change Calendar](change-calendar-delete-event.md)
# Criar um evento do Change Calendar
Ao adicionar um evento a uma entrada do Change Calendar, uma ferramenta do AWS Systems Manager, você está especificando um período durante o qual a ação padrão da entrada do calendário está suspensa. Por exemplo, se o tipo de entrada do calendário for fechado por padrão, o calendário estará aberto para alterações durante eventos. (Alternativamente, você pode criar um evento consultivo, que cumpre uma função informativa apenas no calendário.)
Atualmente, só é possível pode criar um evento do Change Calendar usando o console. Os eventos são adicionados ao documento do Change Calendar criado quando você cria uma entrada do Change Calendar.
**Para criar um evento do Change Calendar**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Calendar**.
1. Na lista de calendários, escolha o nome da entrada do calendário à qual você deseja adicionar um evento.
1. Na página de detalhes da entrada do calendário, escolha **Create event (Criar evento)**.
1. Na página **Create scheduled event (Criar evento programado)** em **Event details (Detalhes do evento)**, insira um nome de exibição para seu evento. Nomes de eventos podem conter letras, números, pontos, traços e sublinhados. O nome deve ser específico o suficiente para identificar a finalidade do evento. Um exemplo é **nighttime-hours**.
1. Em **Description** (Descrição), insira uma descrição para o seu evento. Por exemplo, **The support team isn't available during these hours**.
1. (Opcional) Se você quiser que este evento sirva como uma notificação visual ou lembrete apenas, selecione a opção **Advisory** (Consultivo). Eventos consultivos não desempenham nenhum papel funcional em seu calendário. Eles servem para fins informativos apenas para aqueles que visualizam seu calendário.
1. Em **Event start date** (Data de início do evento), insira ou escolha um dia no formato `MM/DD/YYYY` para iniciar o evento e insira uma hora no dia especificada no formato `hh:mm:ss` (horas, minutos e segundos) para iniciar o evento.
1. Em **Event end date** (Data de término do evento), insira ou escolha um dia no formato `MM/DD/YYYY` para encerrar o evento e insira uma hora no dia especificada no formato `hh:mm:ss` (horas, minutos e segundos) para encerrar o evento.
1. Em **Schedule time zone** (Fuso horário da programação), escolha um fuso horário que se aplique às horas de início e término do evento. É possível inserir parte de um nome de cidade ou diferença de fuso horário de Greenwich Mean Time (GMT) para encontrar um fuso horário mais rapidamente. O padrão é o Tempo Universal Coordenado (UTC).
1. (Opcional) Para criar um evento que se repita diariamente, semanalmente ou mensalmente, ative **Recurrence** (Recorrência) e, em seguida, especifique a frequência e a data final opcional para a recorrência.
1. Escolha **Create scheduled event (Criar evento programado)**. O novo evento é adicionado à entrada do calendário e é exibido na guia **Events (Eventos)** da página de detalhes da entrada do calendário.
# Atualizar um evento do Change Calendar
Use o procedimento a seguir para atualizar um evento do Change Calendar no console do AWS Systems Manager. O Change Calendar é uma ferramenta do AWS Systems Manager.
**Para atualizar um evento do Change Calendar**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Calendar**.
1. Na lista de calendários, escolha o nome da entrada do calendário para a qual você deseja editar um evento.
1. Na página de detalhes da entrada do calendário, escolha **Events (Eventos)**.
1. Na página do calendário, escolha o evento que deseja editar.
**dica**
Use os botões no canto superior esquerdo para se mover para atrás ou para frente de um ano e de um mês. Altere o fuso horário, se necessário, escolhendo o fuso horário correto na lista no canto superior direito.
1. Em **Event details** (Detalhes do evento), escolha **Edit** (Editar).
Para alterar o nome e a descrição do evento, adicione ou substitua os valores de texto atuais.
1. Para alterar o valor da **Event start date** (Data de início do evento), escolha a data de início atual e escolha uma nova data no calendário. Para alterar a hora de início, escolha a hora de início atual e escolha uma nova hora na lista.
1. Para alterar o valor da **Event end date** (Data de término do evento), escolha a data de término atual e escolha uma nova data no calendário. Para alterar a hora de término, escolha a hora de término atual e escolha uma nova hora na lista.
1. Para alterar o valor de **Schedule time zone** (Fuso horário da programação), escolha um fuso horário que se aplique às horas de início e término do evento. É possível inserir parte de um nome de cidade ou diferença de fuso horário de Greenwich Mean Time (GMT) para encontrar um fuso horário mais rapidamente. O padrão é o Tempo Universal Coordenado (UTC).
1. (Opcional) Se você quiser que este evento sirva como uma notificação visual ou lembrete apenas, selecione a opção **Advisory** (Consultivo). Eventos consultivos não desempenham nenhum papel funcional em seu calendário. Eles servem para fins informativos apenas para aqueles que visualizam seu calendário.
1. Escolha **Salvar**. Suas alterações são exibidas na guia **Events (Eventos)** da página de detalhes da entrada do calendário. Escolha o evento atualizado para exibir suas alterações.
# Excluir um evento do Change Calendar
É possível excluir um evento de cada vez no Change Calendar, uma ferramenta do AWS Systems Manager, usando o Console de gerenciamento da AWS.
**dica**
Caso selecione **Adicionar eventos de gerenciamento de alterações ao calendário** ao criar o calendário, você poderá fazer o seguinte:
Para ocultar um tipo de evento de gerenciamento de alterações na exibição do calendário *temporariamente*, escolha o **X** para o tipo na parte superior da pré-visualização mensal.
Para remover esses tipos da exibição do calendário *permanentemente*, edite o calendário, desmarque a caixa de seleção **Adicionar eventos de gerenciamento de alterações ao calendário**, e escolha **Salvar**. Remover os tipos da exibição do calendário não os excluirá da conta.
**Para excluir um evento do Change Calendar**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Calendar**.
1. Na lista de calendários, escolha o nome da entrada do calendário da qual você deseja excluir um evento.
1. Na página de detalhes da entrada do calendário, escolha **Events (Eventos)**.
1. Na página do calendário, escolha o evento que você deseja excluir.
**dica**
Use os botões no canto superior esquerdo para retroceder ou avançar o calendário em um ano ou um mês. Altere o fuso horário, se necessário, escolhendo o fuso horário correto na lista no canto superior direito.
1. Na página **Event details (Detalhes do evento)**, escolha **Delete (Excluir)**. Quando for solicitado, confirme que você deseja excluir o evento, escolhendo **Confirm** (Confirmar).
# Importar e gerenciar eventos de calendários de terceiros
Como alternativa à criação de eventos diretamente no console do AWS Systems Manager, você pode importar um iCalendar (`.ics`) de uma aplicação de calendário de terceiros compatível. Seu calendário pode incluir eventos importados e eventos que você cria no Change Calendar, uma ferramenta do AWS Systems Manager.
**Antes de começar**
Antes de tentar importar um arquivo de calendário, revise os seguintes requisitos e restrições:
Formato de arquivo do calendário
Somente arquivos iCalendar válidos (`.ics`) são compatíveis.
Fornecedores de calendário compatíveis
Somente os arquivos `.ics` exportados dos provedores de calendário de terceiros a seguir são compatíveis.
+ Calendário do Google ([Instruções de exportação](https://support.google.com/calendar/answer/37111))
+ Microsoft Outlook ([Instruções de exportação](https://support.microsoft.com/en-us/office/export-an-outlook-calendar-to-google-calendar-662fa3bb-0794-4b18-add8-9968b665f4e6))
+ Calendário do iCloud ([Instruções de exportação](https://support.apple.com/guide/calendar/import-or-export-calendars-icl1023/mac))
Tamanho do arquivo
Você pode importar qualquer número de arquivos `.ics` válidos. No entanto, o tamanho total de todos os arquivos importados para cada calendário não pode exceder 64 KB.
Para minimizar o tamanho do arquivo `.ics`, verifique se você está exportando somente detalhes básicos sobre suas entradas do calendário. Se necessário, reduza a duração do período de exportação.
Fuso horário
Além de um nome de calendário, um provedor de calendário e pelo menos um evento, o arquivo `.ics` exportado também deve indicar o fuso horário do calendário. Se isso não acontecer, ou se houver um problema ao identificar o fuso horário, você será solicitado a especificar um depois de importar o arquivo.
Limitação de eventos recorrentes
O arquivo exportado `.ics` pode incluir eventos recorrentes. No entanto, se uma ou mais ocorrências de um evento recorrente tiverem sido excluídas no calendário de origem, a importação falhará.
**Topics**
+ [Importar eventos de provedores de calendário de terceiros](change-calendar-import.md)
+ [Atualizar todos os eventos de um provedor de calendário de terceiros](change-calendar-import-add-remove.md)
+ [Excluir todos os eventos importados de um calendário de terceiros](change-calendar-delete-ics.md)
# Importar eventos de provedores de calendário de terceiros
Use o procedimento a seguir para importar um iCalendar (`.ics`) de uma aplicação de calendário de terceiros compatível. Os eventos contidos no arquivo são incorporados às regras do seu calendário aberto ou fechado. Você pode importar um arquivo para um novo calendário que está criando com o Change Calendar (uma ferramenta do AWS Systems Manager) ou para um calendário existente.
Depois de importar o arquivo `.ics`, você poderá remover eventos individuais dele usando a interface Change Calendar. Para mais informações, consulte [Excluir um evento do Change Calendar](change-calendar-delete-event.md). Você também pode excluir todos os eventos do calendário de origem excluindo o arquivo `.ics`. Para mais informações, consulte [Excluir todos os eventos importados de um calendário de terceiros](change-calendar-delete-ics.md).
**Para importar eventos de provedores de calendário de terceiros**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Calendar**.
1. Para começar com um novo calendário, escolha **Create calendar** (Criar calendário). Na área **Import calendar** (Importar calendário), selecione **Choose file** (Escolher arquivo). Para obter informações sobre outras etapas para criar um novo calendário, consulte [Criar um calendário de alterações](change-calendar-create.md).
- ou -
Para importar eventos de terceiros para um calendário existente, escolha o nome de um calendário existente para abri-lo.
1. Selecione **Actions, Edit** (Ações, Editar), e depois, na área **Import calendar** (Importar calendário), escolha **Choose file** (Escolher arquivo).
1. Acesse e selecione o arquivo `.ics` exportado em seu computador local.
1. Caso solicitado, para **Select a time zone** (Selecione um fuso horário), selecione o fuso horário que se aplica ao calendário.
1. Escolha **Salvar**.
# Atualizar todos os eventos de um provedor de calendário de terceiros
Se vários eventos forem adicionados ou removidos do calendário de origem depois de importar o arquivo `.ics` do iCalendar, você poderá refletir essas alterações no Change Calendar. Primeiro, exporte novamente o calendário de origem e, em seguida, importe o novo arquivo para o Change Calendar, que é uma ferramenta do AWS Systems Manager. Os eventos no calendário de alterações serão atualizados para refletir o conteúdo do arquivo mais recente.
**Para atualizar todos os eventos de um provedor de calendário de terceiros**
1. No calendário de terceiros, adicione ou remova eventos conforme você deseja que eles sejam refletidos no Change Calendar e, em seguida, reexporte o calendário para um novo arquivo `.ics`.
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Calendar**.
1. Na lista de calendários, escolha o nome do calendário na lista.
1. Selecione **Escolher arquivo** e, em seguida, acesse e selecione o arquivo `.ics` de substituição.
1. Em resposta à notificação sobre a substituição do arquivo existente, escolha**Confirm** (Confirme).
# Excluir todos os eventos importados de um calendário de terceiros
Se você não quiser mais nenhum dos eventos importados de um provedor de terceiros incluído no calendário, exclua o arquivo `.ics` importado do iCalendar.
**Para excluir todos os eventos importados de um calendário de terceiros**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Calendar**.
1. Na lista de calendários, escolha o nome do calendário na lista.
1. Na área **Import calendar** (Importar calendário), em **My imported calendars** (Meus calendários importados), localize o nome do calendário importado e marque **X** no cartão dele.
1. Escolha **Salvar**.
# Atualizar um calendário de alterações
Você pode atualizar a descrição de um calendário de alterações, mas não o nome dele. Embora seja possível alterar o estado padrão de uma entrada de calendário, esteja ciente de que isso reverte o comportamento das ações de alteração durante eventos associados à entrada do calendário. Por exemplo, se você alterar o estado de um calendário de **Open by default** (Aberto por padrão) para **Closed by default**(Fechado por padrão), as alterações indesejadas poderão ser feitas durante períodos do evento em que os usuários que criaram os eventos associados não estiverem esperando alterações.
Ao atualizar um calendário de alterações, você está editando o documento do Change Calendar criado quando você criou a entrada. O Change Calendar é uma ferramenta do AWS Systems Manager.
**Para atualizar um calendário de alterações**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Calendar**.
1. Na lista de calendários, escolha o nome do calendário que você deseja atualizar.
1. Na página de detalhes do calendário, escolha **Actions, Edit** (Ações, Editar).
1. Em **Description (Descrição)**, é possível alterar o texto da descrição. Não é possível editar o nome de um calendário de alteração.
1. Para alterar o estado do calendário, em **Calendar type (Tipo de calendário)**, escolha um valor diferente. Observe que isso reverte o comportamento das ações de alteração durante eventos associados ao calendário. Antes de alterar o tipo do calendário, verifique com outros usuários do Change Calendar se a alteração do tipo do calendário não permite alterações indesejadas durante os eventos criados.
+ **Open by default (Aberto por padrão)**: o calendário é aberto (as ações do Automation podem ser executadas até que um evento seja iniciado) e fechado logo depois pela duração de um evento associado.
+ **Closed by default** (Fechado por padrão) - o calendário está fechado (as ações do Automation não podem ser executadas até que um evento seja iniciado), mas é aberto durante um evento associado.
1. Escolha **Salvar**.
Sua entrada do calendário não pode prevenir ou permitir ações até que você adicione pelo menos um evento. Para obter informações sobre como adicionar um evento, consulte [Criar um evento do Change Calendar](change-calendar-create-event.md).
# Compartilhar um calendário de alterações
Você pode compartilhar um calendário no Change Calendar, uma ferramenta do AWS Systems Manager, com outras Contas da AWS usando o console do AWS Systems Manager. Ao compartilhar um calendário, o calendário é somente leitura para usuários na conta compartilhada. Janelas de manutenção, associações do State Manager e automações não são compartilhadas.
**Para compartilhar um calendário de alterações**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Calendar**.
1. Na lista de calendários, escolha o nome do calendário que você deseja compartilhar.
1. Na página de detalhes do calendário, escolha a guia **Sharing** (Compartilhamento).
1. Escolha **Actions, Share** (Ações, Compartilhar).
1. Em **Share calendar** (Compartilhar calendário), para **Account ID** (ID da conta), insira o número de ID de uma Conta da AWS válida e escolha **Share** (Compartilhar).
Os usuários da conta compartilhada podem ler o calendário de alterações, mas não podem fazer alterações.
# Excluir um calendário de alterações
Você pode excluir um calendário no Change Calendar, uma ferramenta do AWS Systems Manager, usando o console do Systems Manager ou a AWS Command Line Interface (AWS CLI). A exclusão de um calendário de alterações exclui todos os eventos associados.
**Para excluir um calendário de alterações**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Calendar**.
1. Na lista de calendários, escolha o nome do calendário que você deseja excluir.
1. Na página de detalhes do calendário, escolha **Actions, Delete** (Ações, Excluir). Quando for solicitado, confirme que você deseja excluir a entrada do calendário escolhendo **Delete** (Excluir).
# Obter o estado de um calendário de alterações
Você pode obter o estado geral de um calendário ou o estado de um calendário em um horário específico no Change Calendar, uma ferramenta do AWS Systems Manager. Também é possível mostrar a próxima vez em que o estado do calendário muda de `OPEN` para `CLOSED` ou vice-versa.
**nota**
Para obter informações sobre a integração do Change Calendar com o Amazon EventBridge para monitoramento automatizado das mudanças de estado do calendário, consulte [Integração do Change Calendar com o Amazon EventBridge](monitoring-systems-manager-event-examples.md#change-calendar-eventbridge-integration). A integração com o EventBridge fornece notificações orientadas por eventos quando os estados do calendário fazem a transição, complementando a abordagem baseada em polling da ação da API `GetCalendarState`.
Você só pode fazer essa tarefa usando a API `GetCalendarState`. O procedimento nesta seção usa a AWS Command Line Interface (AWS CLI).
**Para obter o estado de um calendário de alterações**
+ Execute o seguinte comando para mostrar o estado de um ou mais calendários em um horário específico. O parâmetro `--calendar-names` é obrigatório, mas `--at-time` é opcional. Substitua cada *espaço reservado para recurso de exemplo* por suas próprias informações.
------
#### [ Linux & macOS ]
```
aws ssm get-calendar-state \
--calendar-names "Calendar_name_or_document_ARN_1" "Calendar_name_or_document_ARN_2" \
--at-time "ISO_8601_time_format"
```
Veja um exemplo a seguir.
```
aws ssm get-calendar-state \
--calendar-names "arn:aws:ssm:us-east-2:123456789012:document/MyChangeCalendarDocument" "arn:aws:ssm:us-east-2:123456789012:document/SupportOffHours" \
--at-time "2020-07-30T11:05:14-0700"
```
------
#### [ Windows ]
```
aws ssm get-calendar-state ^
--calendar-names "Calendar_name_or_document_ARN_1" "Calendar_name_or_document_ARN_2" ^
--at-time "ISO_8601_time_format"
```
Veja um exemplo a seguir.
```
aws ssm get-calendar-state ^
--calendar-names "arn:aws:ssm:us-east-2:123456789012:document/MyChangeCalendarDocument" "arn:aws:ssm:us-east-2:123456789012:document/SupportOffHours" ^
--at-time "2020-07-30T11:05:14-0700"
```
------
O comando retorna informações como as seguintes.
```
{
"State": "OPEN",
"AtTime": "2020-07-30T16:18:18Z",
"NextTransitionTime": "2020-07-31T00:00:00Z"
}
```
Os resultados mostram o estado do calendário (se o calendário é do tipo `DEFAULT_OPEN` ou `DEFAULT_CLOSED`) para as entradas de calendário especificadas que são propriedade ou compartilhadas com sua conta, na hora especificada como o valor `--at-time` e a hora da próxima transição. Se você não adicionar o parâmetro `--at-time`, a hora atual será usada.
**nota**
Se você especificar mais de um calendário em uma solicitação, o comando retornará o status `OPEN` somente se todos os calendários na solicitação estiverem abertos. Se um ou mais calendários na solicitação forem fechados, o status retornado será `CLOSED`.
# Adicionar dependências do Change Calendar para runbooks do Automation
Para garantir que as ações do Automation sigam o Change Calendar, uma ferramenta do AWS Systems Manager, adicione uma etapa em um runbook do Automation que use a ação [`aws:assertAwsResourceProperty`](automation-action-assertAwsResourceProperty.md). Configure a ação para executar `GetCalendarState` a fim de verificar se uma entrada de calendário especificada está no estado desejado (`OPEN` ou `CLOSED`). O runbook do Automation só poderá passar para a próxima etapa se o estado do calendário for `OPEN`. Veja a seguir um trecho de exemplo baseado em YAML de um runbook do Automation que não pode prosseguir para a próxima etapa, `LaunchInstance`, a menos que o estado do calendário corresponda a `OPEN`, o estado especificado em `DesiredValues`.
Veja um exemplo a seguir.
```
mainSteps:
- name: MyCheckCalendarStateStep
action: 'aws:assertAwsResourceProperty'
inputs:
Service: ssm
Api: GetCalendarState
CalendarNames: ["arn:aws:ssm:us-east-2:123456789012:document/SaleDays"]
PropertySelector: '$.State'
DesiredValues:
- OPEN
description: "Use GetCalendarState to determine whether a calendar is open or closed."
nextStep: LaunchInstance
- name: LaunchInstance
action: 'aws:executeScript'
inputs:
Runtime: python3.11
...
```
# Solução de problemas do Change Calendar
Use as informações a seguir para obter ajuda para solucionar problemas com o Change Calendar, uma ferramenta do AWS Systems Manager.
**Topics**
+ [Erro 'Falha na importação do calendário'](#change-manager-troubleshooting-1)
## Erro 'Falha na importação do calendário'
**Problema**: ao importar um arquivo do iCalendar (`.ics`), o sistema informa que a importação do calendário falhou.
+ **Solução 1**: verifique se você está importando um arquivo que foi exportado de um provedor de calendário de terceiros compatível, que inclua o seguinte:
+ Calendário do Google ([Instruções de exportação](https://support.google.com/calendar/answer/37111))
+ Microsoft Outlook ([Instruções de exportação](https://support.microsoft.com/en-us/office/export-an-outlook-calendar-to-google-calendar-662fa3bb-0794-4b18-add8-9968b665f4e6))
+ Calendário do iCloud ([Instruções de exportação](https://support.apple.com/guide/calendar/import-or-export-calendars-icl1023/mac))
+ **Solução 2**: se o calendário de origem incluir eventos recorrentes, verifique se nenhuma ocorrência individual do evento foi cancelada ou excluída. No momento, o Change Calendar não suporta a importação de eventos recorrentes com cancelamentos individuais. Para resolver o problema, remova o evento recorrente do calendário de origem, exporte novamente o calendário, importe-o novamente para o Change Calendar e, em seguida, adicione o evento recorrente usando a interface do Change Calendar. Para mais informações, consulte [Criar um evento do Change Calendar](change-calendar-create-event.md).
+ **Solução 3**: verifique se o calendário de origem contém pelo menos um evento. Os carregamentos de arquivos `.ics` que não contêm eventos não têm êxito.
+ **Solução 4**: se o sistema relatar que a importação falhou porque a propriedade `.ics` é muito grande, verifique se você está exportando somente os detalhes básicos sobre suas entradas de calendário. Se necessário, reduza a duração do período de exportação.
+ **Solução 5**: se o Change Calendar não conseguir determinar o fuso horário do calendário exportado quando você tenta importá-lo da guia **Events** (Eventos), você poderá receber esta mensagem: “Falha na importação do calendário. O Change Calendar não localizou um fuso horário válido’’. Você pode importar o calendário do menu Edit (Editar). Nesse caso, escolha **Actions, Edit** (Ações, Editar) e, em seguida, tente importar o arquivo da página **Edit calendar** (Editar calendário).
+ **Solução 6**: não edite o arquivo `.ics` antes da importação. A tentativa de modificar o conteúdo do arquivo pode corromper os dados do calendário. Se você modificou o arquivo antes de tentar a importação, exporte o calendário do calendário de origem novamente e tente fazer o upload novamente.
# AWS Systems Manager Change Manager
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
O Change Manager, uma ferramenta do AWS Systems Manager, é um framework de gerenciamento de alterações corporativas para solicitar, aprovar, implementar e emitir relatórios sobre alterações operacionais em sua configuração e infraestrutura de aplicações. Em uma única *Conta de administrador delegado*, se você usar o AWS Organizations, poderá gerenciar alterações em várias Contas da AWS e Regiões da AWS. Como alternativa, usando um *conta local*, você pode gerenciar alterações para uma única Conta da AWS. Use o Change Manager para gerenciar alterações em recursos da AWS e recursos on-premises. Para começar a usar o Change Manager, abra o [Systems Manager console](https://console.aws.amazon.com//systems-manager/change-manager) (Console do gerenciador de sistemas). No painel de navegação, escolha **Change Manager**.
Com o Change Manager, você pode usar *modelos de alterações* pré-aprovado para ajudar a automatizar os processos de alteração para seus recursos e ajudar a evitar resultados não intencionais ao fazer alterações operacionais. Cada modelo de alteração especifica o seguinte:
+ Um ou mais runbooks do Automation para um usuário escolher ao criar uma solicitação de alteração. As alterações feitas nos recursos são definidas nos runbooks do Automation. Você pode incluir runbooks personalizados ou [runbooks gerenciados da AWS](automation-documents-reference.md) nos modelos de alteração criados. Quando um usuário cria uma solicitação de alteração, ele pode escolher qual dos runbooks disponíveis incluir na solicitação. Além disso, você pode criar modelos de alteração que permitem que o usuário que faz a solicitação especifique qualquer runbook na solicitação de alteração.
+ Os usuários da conta que devem revisar solicitações de alteração feitas usando esse modelo de alteração.
+ O tópico do Amazon Simple Notification Service (Amazon SNS) usado para notificar os aprovadores atribuídos de que uma solicitação de alteração está pronta para análise.
+ O alarme do Amazon CloudWatch usado para monitorar o fluxo de trabalho do runbook.
+ O tópico do Amazon SNS usado para enviar notificações sobre alterações de status para solicitações de alteração criadas usando o modelo de alteração.
+ As tags a serem aplicadas ao modelo de alteração para uso na categorização e filtragem dos modelos de alteração.
+ Se as solicitações de alteração criadas com o modelo de alteração podem ser executadas sem uma etapa de aprovação (solicitações aprovadas automaticamente).
Através da sua integração com o Change Calendar, que é outra ferramenta do Systems Manager, o Change Manager também ajudará você a implementar alterações com segurança, evitando conflitos de agendamento com eventos comerciais importantes. A integração do Change Manager com o AWS Organizations e Centro de Identidade do AWS IAM ajuda você a gerenciar alterações em toda a organização em uma única conta usando seu sistema de gerenciamento de identidades existente. Você pode monitorar o progresso das alterações no Change Manager e auditar alterações operacionais em toda a organização, proporcionando visibilidade e responsabilidade aprimoradas.
O Change Manager complementa os controles de segurança das práticas de [integração contínua](https://aws.amazon.com/devops/continuous-integration) (CI) e a metodologia de [fornecimento contínuo](https://aws.amazon.com/devops/continuous-delivery) (CD). O Change Manager não se destina a alterações feitas como parte de um processo de lançamento automatizado, como um pipeline CI/CD, a menos que haja uma exceção ou aprovação necessária.
## Como a Change Manager funciona
Quando a necessidade de uma alteração operacional padrão ou de emergência for identificada, alguém na organização criará uma solicitação de alteração baseada em um dos modelos de alteração criados para uso em sua organização ou conta.
Se a alteração solicitada exigir aprovações manuais, o Change Manager notificará os aprovadores designados por meio de uma notificação do Amazon SNS de que uma solicitação de alteração está pronta para sua revisão. É possível designar aprovadores para solicitações de alteração no modelo de alteração ou permitir que os usuários designem aprovadores em sua própria solicitação de alteração. Você pode atribuir diferentes revisores a diferentes modelos. Por exemplo, atribua um usuário, grupo de usuários ou função do AWS Identity and Access Management (IAM) que devem aprovar as solicitações de alterações em nós gerenciados e outro usuário, grupo ou função do IAM para alterações no banco de dados. Se o modelo de alteração permitir aprovações automáticas e a política de usuário de um solicitante não as proibir, o usuário também poderá optar por executar o runbook do Automation para sua solicitação sem uma etapa de análise (com exceção dos eventos de congelamento de alterações).
Para cada modelo de alteração, você pode adicionar até cinco níveis de aprovadores. Por exemplo, você pode exigir que os revisores técnicos aprovem primeiro uma solicitação de alteração criada a partir de um modelo de alteração e, em seguida, solicitar um segundo nível de aprovações de um ou mais gerentes.
Change Manager O é integrado ao [AWS Systems Manager Change Calendar](systems-manager-change-calendar.md). Quando uma alteração solicitada é aprovada, o sistema primeiro determina se a solicitação entra em conflito com outras atividades comerciais agendadas. Se um conflito for detectado, o Change Manager poderá bloquear a alteração ou exigir aprovações adicionais antes de iniciar o fluxo de trabalho do runbook. Por exemplo, você pode permitir alterações somente durante o horário comercial para garantir que as equipes estejam disponíveis para gerenciar problemas inesperados. Para quaisquer alterações solicitadas para serem executadas fora desse horário, você pode solicitar a aprovação da gerência de nível superior no formato de *change freeze approvers* (alterar aprovadores de congelamento). Para mudanças de emergência, o Change Manager pode ignorar a etapa de verificação Change Calendar para conflitos ou eventos de bloqueio após a aprovação de uma solicitação de alteração.
Quando for a hora de implementar uma alteração aprovada, o Change Manager executará o runbook do Automation especificado na solicitação de alteração associada. Somente as operações definidas em solicitações de alteração aprovadas serão permitidas quando os fluxos de trabalho de runbook forem executados. Essa abordagem ajuda você a evitar resultados não intencionais enquanto as mudanças estiverem sendo implementadas.
Além de restringir as alterações que podem ser feitas quando um fluxo de trabalho de runbook for executado, o Change Manager também ajuda a controlar a simultaneidade e os limites de erros. Você escolhe quantos recursos um fluxo de trabalho de runbook pode executar de uma só vez, quantas contas a alteração pode executar de uma só vez e quantas falhas serão permitidas antes do processo ser interrompido e (se o runbook incluir um script de reversão) revertido. Você também pode monitorar o andamento das alterações feitas usando os alarmes do CloudWatch.
Após a conclusão de um fluxo de trabalho do runbook, você pode revisar os detalhes sobre as alterações feitas. Esses detalhes incluem o motivo de uma solicitação de alteração, qual modelo de alteração foi usado, quem solicitou e aprovou as alterações e como as alterações foram implementadas.
**Mais informações**
[Apresentação do AWS Systems ManagerChange Manager](https://aws.amazon.com/blogs/aws/introducing-systems-manager-change-manager/) no *Blog de notícias da AWS*
## Como o Change Manager beneficia minhas operações?
Os benefícios do Change Manager incluem o seguinte:
+ **Reduza o risco de interrupção do serviço e tempo de inatividade**
Change ManagerO pode tornar as alterações operacionais mais seguras, garantindo que apenas as alterações aprovadas sejam implementadas quando um fluxo de trabalho de runbook for executado. Você pode bloquear alterações não planejadas e não revisadas. O Change Manager ajuda você a evitar os tipos de resultados não intencionais causados por erro humano que exigem horas dispendiosas de pesquisa e retrocesso.
+ **Obtenha auditoria e relatórios detalhados sobre os históricos de alterações**
Change ManagerO fornece responsabilidade com uma maneira consistente de relatar e auditar alterações feitas em toda a organização, a intenção das alterações e detalhes sobre quem as aprovou e implementou.
+ **Evite conflitos ou violações de agendamento**
Change ManagerO pode detectar conflitos de agendamento, como eventos de feriados ou lançamentos de novos produtos, com base no calendário de alterações ativo da sua organização. Você pode permitir que fluxos de trabalho do runbook sejam executados somente durante o horário comercial ou permiti-los somente com aprovações adicionais.
+ **Adapte os requisitos de mudança aos seus negócios em mudança**
Durante diferentes períodos comerciais, você poderá implementar diferentes requisitos de gerenciamento de alterações. Por exemplo, durante a geração de relatórios de fim de mês, época fiscal ou outros períodos comerciais críticos, você pode bloquear alterações ou exigir aprovação em nível de diretoria para alterações que possam introduzir riscos operacionais desnecessários.
+ **Gerencie centralmente as alterações nas contas**
Através da sua integração com o Organizations, o Change Manager permite que você gerencie alterações em todas as unidades organizacionais (UOs) em uma única conta de administrador delegado. É possível ativar o Change Manager para uso com toda a sua organização ou com apenas algumas das suas UOs.
## Quem deve usar o Change Manager?
O Change Manager é apropriado para o seguinte clientes e organizações da AWS:
+ Qualquer cliente da AWS que quiser melhorar a segurança e a governança das alterações operacionais feitas em seus ambientes na nuvem ou on-premises.
+ As organizações que desejam aumentar a colaboração e a visibilidade entre as equipes, melhorar a disponibilidade das aplicações evitando o tempo de inatividade e reduzir o risco associado a tarefas manuais e repetitivas.
+ Organizações que devem estar em conformidade com as práticas recomendadas para o gerenciamento de alterações.
+ Clientes que precisam de um histórico totalmente auditável das alterações feitas em sua configuração e infraestrutura de aplicações.
## Quais são os principais recursos do Change Manager?
Os principais recursos do Change Manager incluem o seguinte:
+ **Suporte integrado para as práticas recomendadas de gerenciamento de alterações**
Com o Change Manager, você pode aplicar práticas recomendadas de gerenciamento de alterações selecionadas às suas operações. Você pode ativar uma das seguintes opções:
+ Confira o Change Calendar para ver se os eventos estão restritos de forma que as alterações sejam feitas somente durante períodos de calendário abertos.
+ Permitir alterações durante eventos restritos com aprovações extras de aprovadores de congelamento de alterações.
+ Exija que os alarmes do CloudWatch sejam especificados para todos os modelos de alteração.
+ Exija que todos os modelos de alteração criados em sua conta sejam revisados e aprovados antes que possam ser usados para criar solicitações de alteração.
+ **Caminhos diferentes de aprovação para períodos de calendário fechados e solicitações de alteração de emergência**
Você pode permitir que uma opção escolha o Change Calendar para eventos restritos e bloqueie solicitações de alteração aprovadas, até que o evento seja concluído. No entanto, você também pode designar um segundo grupo de aprovadores, alterar aprovadores congelados, que podem permitir que a alteração seja feita mesmo que o calendário esteja fechado. Você também pode criar modelos de alteração de emergência. As solicitações de alteração criadas a partir de um modelo de alteração de emergência ainda exigem aprovações regulares, mas não estão sujeitas às restrições do calendário e não exigem aprovações de congelamento de alterações.
+ **Controle como e quando os fluxos de trabalho do runbook são iniciados**
Os fluxos de trabalho do runbook podem ser iniciados de acordo com uma programação ou assim que as aprovações forem concluídas (sujeito a regras de restrição de calendário).
+ **Suporte de notificação integrado**
Especifique quem na sua organização deve revisar e aprovar modelos e solicitações de alteração. Atribua um tópico do Amazon SNS a um modelo de alteração para enviar notificações aos assinantes do tópico sobre alterações de status para solicitações de alteração criadas com esse modelo de alteração.
+ **Integração com AWS Systems Manager Change Calendar**
Change ManagerO permite que os administradores restrinjam alterações de agendamento durante períodos de tempo especificados. Por exemplo, você pode criar uma política que permita alterações somente durante o horário comercial para garantir que a equipe esteja disponível para lidar com quaisquer problemas. Você também pode restringir alterações durante eventos comerciais importantes. Por exemplo, as empresas de varejo podem restringir as alterações durante grandes eventos de vendas. Você também pode exigir aprovações adicionais durante períodos restritos.
+ **Integração com o Centro de Identidade do AWS IAM e suporte ao Active Directory**
Com a integração ao IAM Identity Center, os membros da sua organização podem acessar Contas da AWS e gerenciar seus recursos usando o Systems Manager, com base em uma identidade de um usuário comum. Usando o IAM Identity Center, você pode atribuir acesso de usuários a contas na AWS.
A integração com o Active Directory torna possível atribuir usuários em sua conta do Active Directory como aprovadores para modelos de alteração criados para as operações do Change Manager.
+ **Integração com alarmes do Amazon CloudWatch**
O Change Manager é integrado aos alarmes do CloudWatch. O Change Manager escuta os alarmes do CloudWatch durante o fluxo de trabalho do runbook e executa todas as ações, incluindo o envio de notificações definidas para o alarme.
+ **Integração com o AWS CloudTrail Lake**
Ao criar um armazenamento de dados de eventos no AWS CloudTrail Lake, é possível visualizar informações auditáveis sobre as alterações feitas pelas solicitações de alteração executadas em sua conta ou organização. As informações do evento armazenadas incluem detalhes como os seguintes:
+ As ações de API que foram executadas
+ Os parâmetros de solicitação incluídos para essas ações
+ O usuário que executou a ação
+ Os recursos que foram atualizados durante o processo
+ **Integração com AWS Organizations**
Usando os recursos de contas cruzadas fornecidos pelo Organizations, você pode usar uma conta de administrador delegado para gerenciar as operações do Change Manager em UOs da sua organização. Na conta de gerenciamento do Organizations, você pode especificar qual conta será a conta de administrador delegado. Você também pode controlar em quais das UOs o Change Manager pode ser usado.
## Há cobrança pelo uso do Change Manager?
Sim. O preço do Change Manager é calculado com base no pagamento conforme o uso. Você paga somente pelo que usar. Para saber mais, consulte [Preços do AWS Systems Manager](https://aws.amazon.com/systems-manager/pricing/).
## Quais são os componentes primários do Change Manager?
Change ManagerOs componentes do que você usa para gerenciar o processo de alteração em sua organização ou conta incluem o seguinte:
### Conta de administrador delegado
Se você usar o Change Manager em uma organização, você usará uma conta de administrador delegado. Esta é a Conta da AWS designada como a conta para gerenciar atividades de operações no Systems Manager, incluindo o Change Manager. A conta de administrador delegado gerencia as atividades de alteração em toda a organização. Quando você configura sua organização para usar o Change Manager, você especifica qual das suas contas desempenhará essa função. A conta de administrador delegado deve ser o único membro da unidade organizacional (UO) à qual está atribuída. A conta de administrador delegado não será necessária se você usar o Change Manager apenas com uma única Conta da AWS.
**Importante**
Se você usar o Change Manager em uma organização, recomendamos sempre fazer as alterações na conta de administrador delegado. Embora seja possível fazer alterações de outras contas na organização, essas alterações não serão relatadas ou visíveis na conta do administrador delegado.
### Modelo de alteração
Um modelo de alteração é uma coleção de definições de configuração no Change Managerque definem itens como aprovações obrigatórias, runbooks disponíveis e opções de notificação para solicitações de alteração.
Você pode exigir que os modelos de alteração criados pelos usuários em sua organização ou conta passem por um processo de aprovação antes que possam ser usados.
Change ManagerO oferece suporte a dois tipos de modelos de alteração. Para uma solicitação de alteração aprovada que se baseia em um *modelo de alteração de emergência*, a alteração solicitada pode ser feita mesmo que existam eventos de bloqueio no Change Calendar. Para uma solicitação de alteração aprovada que se baseia em um *modelo de alteração padrão*, a alteração solicitada não poderá ser feita se houver eventos de bloqueio no Change Calendar a menos que aprovações adicionais sejam recebidas dos aprovadores designados em *change freeze event* (alterar evento de congelamento).
### Solicitação de alteração
Uma solicitação de alteração é uma solicitação no Change Manager para executar um runbook do Automation que atualiza um ou mais recursos na AWS ou em ambientes on-premises. Uma solicitação de alteração é criada usando um modelo de alteração.
Quando você cria uma solicitação de alteração, um ou mais aprovadores em sua organização ou conta devem revisar e aprovar a solicitação. Sem as aprovações necessárias, o fluxo de trabalho do runbook, que aplica as alterações solicitadas, não tem permissão para ser executado.
No sistema, as solicitações de alteração são um tipo de OpsItem no AWS Systems Manager OpsCenter. No entanto, OpsItems do tipo `/aws/changerequest` não são exibidos no OpsCenter. Como OpsItems, as solicitações de alteração estão sujeitas às mesmas cotas impostas que os outros tipos de OpsItems.
Além disso, para criar uma solicitação de alteração programaticamente, não chame a operação da API `CreateOpsItem`, Use a operação `[https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartChangeRequestExecution.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartChangeRequestExecution.html)` da API. Mas, em vez de ser executada imediatamente, a solicitação de alteração deve ser aprovada, e não deve haver nenhum evento de bloqueio no Change Calendar para impedir que o fluxo de trabalho seja executado. Quando as aprovações tiverem sido recebidas e o calendário não estiver bloqueado (ou tiver permissão para ignorar eventos de bloqueio do calendário), a ação `StartChangeRequestExecution` poderá ser concluída.
### Fluxo de trabalho do runbook
Um fluxo de trabalho de runbook é o processo de alterações solicitadas que estão sendo feitas nos recursos direcionados no ambiente de nuvem ou on-premises. Cada solicitação de alteração designa um único runbook do Automation a ser usado para fazer a alteração solicitada. O fluxo de trabalho do runbook ocorre depois que todas as aprovações necessárias foram concedidas e não houver eventos de bloqueio no Change Calendar. Se a alteração tiver sido agendada para uma data e hora específicas, o fluxo de trabalho do runbook não começará até o horário agendado, mesmo que todas as aprovações tenham sido recebidas e o calendário não esteja bloqueado.
**Topics**
+ [Como a Change Manager funciona](#how-change-manager-works)
+ [Como o Change Manager beneficia minhas operações?](#change-manager-benefits)
+ [Quem deve usar o Change Manager?](#change-manager-who)
+ [Quais são os principais recursos do Change Manager?](#change-manager-features)
+ [Há cobrança pelo uso do Change Manager?](#change-manager-cost)
+ [Quais são os componentes primários do Change Manager?](#change-manager-primary-components)
+ [Configurar o Change Manager](change-manager-setting-up.md)
+ [Como trabalhar com o Change Manager](working-with-change-manager.md)
+ [Auditar e registrar atividades do Change Manager em log](change-manager-auditing.md)
+ [Solução de problemas do Change Manager](change-manager-troubleshooting.md)
# Configurar o Change Manager
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Você pode usar o Change Manager, uma ferramenta do AWS Systems Manager, para gerenciar alterações de uma organização inteira, conforme configurado no AWS Organizations, ou para uma única Conta da AWS.
Se você estiver usando o Change Manager com uma organização, comece com o tópico [Configure o Change Manager para uma organização (conta de gerenciamento)](change-manager-organization-setup.md) e, em seguida, vá para [Configurar as opções e práticas recomendadas do Change Manager](change-manager-account-setup.md).
Se você estiver usando Change Manager com uma única conta, vá diretamente para [Configurar as opções e práticas recomendadas do Change Manager](change-manager-account-setup.md).
**nota**
Se começar você a usar o Change Manager com uma única conta, mas essa conta é posteriormente adicionada a uma unidade organizacional para a qual o Change Manager for permitido, as configurações de conta única serão desconsideradas.
**Topics**
+ [Configure o Change Manager para uma organização (conta de gerenciamento)](change-manager-organization-setup.md)
+ [Configurar as opções e práticas recomendadas do Change Manager](change-manager-account-setup.md)
+ [Configurar perfis e permissões para o Change Manager](change-manager-permissions.md)
+ [Controlar o acesso a fluxos de trabalho do runbook de aprovação automática](change-manager-auto-approval-access.md)
# Configure o Change Manager para uma organização (conta de gerenciamento)
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
As tarefas neste tópico se aplicam se você estiver usando o Change Manager, uma ferramenta do AWS Systems Manager, com uma organização configurada no AWS Organizations. Se você quiser usar o Change Manager apenas com uma única Conta da AWS, vá para o tópico [Configurar as opções e práticas recomendadas do Change Manager](change-manager-account-setup.md).
Execute as tarefas nesta seção em uma Conta da AWS que estiver atuando como a *Conta de gerenciamento* no Organizations. Para obter informações sobre a conta de gerenciamento e outros conceitos do Organizations, consulte [Terminologia e conceitos do AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_getting-started_concepts.html).
Se você precisar ativar o Organizations e especificar sua conta como conta de gerenciamento antes de prosseguir, consulte [Criar e gerenciar uma organização](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org.html) no *Manual do usuário do AWS Organizations*.
**nota**
Esse processo de configuração não pode ser executado na seguinte Regiões da AWS:
UE (Milão) (eu-south-1)
Oriente Médio (Bahrein) (me-south-1)
África (Cidade do Cabo) (af-south-1)
Ásia-Pacífico (Hong Kong) (ap-east-1)
Verifique se você está trabalhando em uma região diferente em sua conta de gerenciamento para este procedimento.
Durante o procedimento de instalação, você realizará as seguintes tarefas principais no Quick Setup, uma ferramenta do AWS Systems Manager.
+ **Tarefa 1: Registrar a conta do administrador delegado do para a sua organização**
As tarefas relacionadas à alteração que são executadas usando o Change Manager são gerenciadas em uma de suas contas de membro, que você especifica como sendo a *conta do administrador delegado*. A conta de administrador delegado na qual você registra o Change Manager torna-se a conta de administrador delegado para todas as operações do Systems Manager. (Você pode ter contas de administrador delegado para outros Serviços da AWS). A conta de administrador delegado do Change Manager, que não é o mesmo que sua conta de gerenciamento, gerencia atividades de alteração em toda a organização, incluindo modelos de alteração, solicitações de alteração e aprovações para cada uma delas. Na conta de administrador delegado, você também especifica outras opções de configuração para o as operações do Change Manager.
**Importante**
A conta de administrador delegado deve ser o único membro da unidade organizacional (UO) ao qual está atribuída no Organizations.
+ **Tarefa 2: Definir e especificar as políticas de acesso do runbook para funções do solicitante de alterações ou funções de trabalho personalizadas, que você quiser usar para as operações do Change Manager**
Para criar solicitações de alteração no Change Manager, os usuários em suas contas de membros devem ter permissões do AWS Identity and Access Management (IAM) para acessar somente os runbooks do Automation e alterar os modelos que você disponibilizar para eles.
**nota**
Quando um usuário cria uma solicitação de alteração, ele primeiro seleciona um modelo de alteração. Esse modelo de alteração pode disponibilizar vários runbooks, mas o usuário pode selecionar apenas um runbook para cada solicitação de alteração. Os modelos de alteração também podem ser configurados para permitir que os usuários incluam qualquer runbook disponível em suas solicitações.
Para conceder as permissões necessárias, o Change Manager usa o conceito de *funções de trabalho*, que também é usado pelo IAM. No entanto, ao contrário das [Políticas gerenciadas pela AWS para as funções de trabalho](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html) no IAM, você especifica os nomes das suas funções de trabalho do Change Manager e as permissões do IAM para elas.
Quando você configura uma função de trabalho, recomendamos criar uma política personalizada e fornecer apenas as permissões necessárias para executar tarefas de gerenciamento de alterações. Por exemplo, é possível especificar permissões que limitem os usuários a esse conjunto específico de runbooks com base nas *funções de trabalho* que você definir.
Por exemplo, você pode criar uma função de trabalho com o nome `DBAdmin`. Para essa função de trabalho, você pode conceder apenas permissões necessárias para runbooks relacionados aos bancos de dados do Amazon DynamoDB, como `AWS-CreateDynamoDbBackup` e `AWSConfigRemediation-DeleteDynamoDbTable`.
Como outro exemplo, você pode conceder a alguns usuários apenas as permissões necessárias para trabalhar com runbooks relacionados aos buckets do Amazon Simple Storage Service (Amazon S3), como `AWS-ConfigureS3BucketLogging` e `AWSConfigRemediation-ConfigureS3BucketPublicAccessBlock`.
O processo de configuração no Quick Setup para o Change Manager também disponibiliza um conjunto de permissões administrativas completas do Systems Manager para aplicar a uma função administrativa criada.
Cada configuração do Change Manager Quick Setup que você implanta cria uma função de trabalho em sua conta de administrador delegado com permissões para executar modelos do Change Manager e runbooks do Automation nas unidades organizacionais que você selecionou. Você pode criar até 15 configurações do Quick Setup para o Change Manager.
+ **Tarefa 3: Escolher quais contas de membro em sua organização usar com o Change Manager**
Você pode usar o Change Manager com todas as contas de membros em todas as unidades organizacionais que estiverem configuradas no Organizations e em todas as Regiões da AWS em que eles operam. Se você preferir, use o Change Manager com apenas algumas de suas unidades organizacionais.
**Importante**
Recomendamos enfaticamente que, antes de iniciar este procedimento, você leia as etapas para entender as opções de configuração que você está escolhendo e as permissões que está concedendo. Planeje principalmente as funções de trabalho personalizadas que você criará e as permissões atribuídas a cada função de trabalho. Isso garante que, posteriormente, você anexar as políticas de função de trabalho criadas a usuários individuais, grupos de usuários ou funções do IAM, eles estejam recebendo somente as permissões que você quer que eles tenham.
Como prática recomendada, comece configurando a conta de administrador delegado usando o login de um administrador da Conta da AWS. Em seguida, configure as funções de trabalho e suas permissões depois de criar os modelos de alteração e identificar os runbooks que cada um usa.
Para configurar o Change Manager para uso com uma organização, execute a seguinte tarefa na área Quick Setup do console do Systems Manager.
Repita essa tarefa para cada função de trabalho que você deseja criar para sua organização. Cada função de trabalho criada pode ter permissões para um conjunto diferente de unidades organizacionais.
**Para configurar uma organização no Change Manager na conta de gerenciamento de uma organização**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Quick Setup**.
1. No cartão do **Change Manager**, escolha **Create** (Criar).
1. Para a **Delegated administrator account** (Conta de administrador delegado), digite o ID da Conta da AWS que você quer usar para gerenciar modelos de alteração, solicitações de alteração e fluxos de trabalho de runbook no Change Manager.
Se você tiver especificado anteriormente uma conta de administrador delegado para o Systems Manager, seu ID já será relatado neste campo.
**Importante**
A conta de administrador delegado deve ser o único membro da unidade organizacional (UO) ao qual está atribuída no Organizations.
Se a conta de administrador delegado que você registrar for posteriormente cancelada dessa função, o sistema removerá suas permissões para gerenciar operações do Systems Manager ao mesmo tempo. Tenha em mente que será necessário que você retorne ao Quick Setup, designe uma conta de administrador delegado diferente e especifique todas as funções e permissões de trabalho novamente.
Se você usar o Change Manager em uma organização, recomendamos sempre fazer as alterações na conta de administrador delegado. Embora seja possível fazer alterações de outras contas na organização, essas alterações não serão relatadas ou visíveis na conta do administrador delegado.
1. Na seção **Permissions to request and make changes** (Permissões para solicitar e fazer alterações), faça o seguinte:
**nota**
Cada configuração de implantação criada fornece a política de permissões para apenas uma função de trabalho. Você pode retornar ao Quick Setup mais tarde para criar mais funções de trabalho quando você tiver criado modelos de alteração para usar em suas operações.
**Para criar uma função administrativa**: para uma função de trabalho de administrador que tenha permissões do IAM para todos as ações da AWS, faça o seguinte:
**Importante**
A concessão de permissões administrativas completas aos usuários deve ser feita com moderação e somente se suas funções exigirem acesso total ao Systems Manager. Para obter informações importantes sobre considerações de segurança para acesso ao Systems Manager, consulte [Gerenciamento de identidade e acesso para o AWS Systems Manager](security-iam.md) e [Melhores práticas de segurança do Systems Manager](security-best-practices.md).
1. Para **Job function** (Função de trabalho), insira um nome para identificar essa função e suas permissões, como **MyAWSAdmin**.
1. Para **Role and permissions option** (Opção Função e permissões), escolha **Administrator permissions** (Permissões de administrador).
**Para criar outras funções de trabalho**: para criar uma função não administrativa, faça o seguinte:
1. Para **Job function** (Função de trabalho), insira um nome para identificar essa função e sugira as permissões. O nome escolhido deverá representar o escopo dos runbooks para os quais você fornecerá permissões, como `DBAdmin` ou `S3Admin`.
1. Para **Role and permissions option** (Opção Função e permissões), escolha **Custom permissions** (Permissões personalizadas).
1. Em **Permissions policy editor** (Editor de políticas de permissões), insira as permissões do IAM, no formato JSON, para conceder a essa função de trabalho.
**dica**
Recomendamos que você use o editor de políticas do IAM para construir sua política e, em seguida, cole a política JSON no campo **Permissions policy** (Política de permissões).
**Exemplo de política: gerenciamento de banco de dados do DynamoDB**
Por exemplo, você pode começar com o conteúdo da política que fornece permissões para trabalhar com os documentos do Systems Manager (documentos SSM), os quais a função de trabalho precisa acessar. Aqui está um exemplo de conteúdo de política que concede acesso a todos os runbooks do Automation gerenciados pela AWS relacionados aos bancos de dados do DynamoDB e dois modelos de alteração que foram criados no exemplo Conta da AWS `123456789012`, na região Leste dos EUA (Ohio) (`us-east-2`).
A política também inclui permissão para a operação [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartChangeRequestExecution.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartChangeRequestExecution.html), que é necessária para criar uma solicitação de alteração no Change Calendar.
**nota**
Este exemplo não é abrangente. Permissões adicionais podem ser necessárias para trabalhar com outros recursos da AWS, como bancos de dados e nós.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:CreateDocument",
"ssm:DescribeDocument",
"ssm:DescribeDocumentParameters",
"ssm:DescribeDocumentPermission",
"ssm:GetDocument",
"ssm:ListDocumentVersions",
"ssm:ModifyDocumentPermission",
"ssm:UpdateDocument",
"ssm:UpdateDocumentDefaultVersion"
],
"Resource": [
"arn:aws:ssm:us-east-1:*:document/AWS-CreateDynamoDbBackup",
"arn:aws:ssm:us-east-1:*:document/AWS-AWS-DeleteDynamoDbBackup",
"arn:aws:ssm:us-east-1:*:document/AWS-DeleteDynamoDbTableBackups",
"arn:aws:ssm:us-east-1:*:document/AWSConfigRemediation-DeleteDynamoDbTable",
"arn:aws:ssm:us-east-1:*:document/AWSConfigRemediation-EnableEncryptionOnDynamoDbTable",
"arn:aws:ssm:us-east-1:*:document/AWSConfigRemediation-EnablePITRForDynamoDbTable",
"arn:aws:ssm:us-east-1:111122223333:document/MyFirstDBChangeTemplate",
"arn:aws:ssm:us-east-1:111122223333:document/MySecondDBChangeTemplate"
]
},
{
"Effect": "Allow",
"Action": "ssm:ListDocuments",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "ssm:StartChangeRequestExecution",
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:document/*",
"arn:aws:ssm:us-east-1:111122223333:automation-execution/*"
]
}
]
}
```
------
Para obter mais informações sobre políticas do IAM, consulte [Gerenciamento de acesso para recursos do AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/access.html) e [Criar políticas do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) no *Manual do usuário do IAM.*
1. Na seção **Targets** (Destinos), escolha se deseja conceder permissões para a função de trabalho que você está criando para toda a organização ou apenas algumas de suas unidades organizacionais.
Se você escolher **Entire organization** (Toda a organização), continue na etapa 9.
Se escolher **Custom** (Personalizado), continue na etapa 8.
1. Na seção **Target OUs** (UOs de destino), marque as caixas de seleção das unidades organizacionais a serem usadas com o Change Manager.
1. Escolha **Criar**.
Depois que o sistema terminar a configuração do Change Manager para sua organização, ele exibirá um resumo das implantações. Essas informações de resumo incluem o nome do perfil criado para a função de trabalho que você configurou. Por exemplo, `AWS-QuickSetup-SSMChangeMgr-DBAdminInvocationRole`.
**nota**
O Quick Setup usa StackSets do AWS CloudFormation para implantar suas configurações. Você também pode visualizar informações sobre uma configuração de implantação concluída no console do CloudFormation. Para obter mais informações sobre o StackSets, consulte [Trabalhar com o StackSets do AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/what-is-cfnstacksets.html) no *Manual do usuário do AWS CloudFormation*.
O próximo passo é configurar outras opções do Change Manager. Você pode concluir essa tarefa em sua conta de administrador delegado ou em qualquer conta em uma unidade organizacional que você tenha permitido para uso com o Change Manager. Você configura opções como escolher uma opção de gerenciamento de identidade de usuário, especificar quais usuários podem revisar e aprovar ou rejeitar modelos de alteração e solicitações de alteração, além de escolher quais opções de práticas recomendadas devem ser permitidas para sua organização. Para mais informações, consulte [Configurar as opções e práticas recomendadas do Change Manager](change-manager-account-setup.md).
# Configurar as opções e práticas recomendadas do Change Manager
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
As tarefas nesta seção deverão ser executadas se você estiver usando o Change Manager, uma ferramenta do AWS Systems Manager, em uma organização ou em uma Conta da AWS individual.
Se você estiver usando o Change Manager para uma organização, você poderá executar as tarefas a seguir em sua conta de administrador delegado ou em qualquer conta em uma unidade organizacional que você tenha permissão para uso com o Change Manager.
**Topics**
+ [Tarefa 1: Configurar o gerenciamento de identidade de usuário e revisores de modelo do Change Manager](#cm-configure-account-task-1)
+ [Tarefa 2: Configurar os aprovadores de eventos de congelamento de alterações e práticas recomendadas do Change Manager](#cm-configure-account-task-2)
+ [Configurar os tópicos do Amazon SNS para as notificações do Change Manager](change-manager-sns-setup.md)
## Tarefa 1: Configurar o gerenciamento de identidade de usuário e revisores de modelo do Change Manager
Execute a tarefa neste procedimento na primeira vez que você acessar Change Manager. Você pode atualizar essas configurações mais tarde, retornando ao Change Manager e escolhendo **Edit** (Editar) na guia **Settings** (Configurações).
**Para configurar o gerenciamento de identidade de usuário e revisores de modelo do Change Manager**
1. Faça login no Console de gerenciamento da AWS.
Se você estiver usando o Change Manager para uma organização, entre usando suas credenciais da sua conta de administrador delegado. O usuário deve ter as permissões necessárias do AWS Identity and Access Management (IAM) para realizar atualizações nas configurações do Change Manager.
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Manager**.
1. Na página inicial do serviço, dependendo das opções disponíveis, siga um destes procedimentos:
+ Se você estiver usando o Change Manager com o AWS Organizations, escolha **Set up delegated account** (Configurar conta delegada).
+ Se você estiver usando o Change Manager com uma única Conta da AWS, escolha **Setup Change Manager** (Configurar o Change Manager).
- ou -
Selecione **Create sample change request** (Criar solicitação de alteração de exemplo), **Skip** (Ignorar) e, em seguida, escolha a guia **Settings** (Configurações).
1. Para **User identity management** (Gerenciamento de identidade do usuário), escolha uma das seguintes opções:
+ **AWS Identity and Access Management (IAM)**: identifique os usuários que realizam e aprovam solicitações e executam outras ações no Change Manager ao usar seus usuários, grupos e perfis existentes.
+ **Centro de Identidade do AWS IAM (IAM Identity Center)**: permite que o [IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/) crie e gerencie identidades ou se conecte à sua fonte de identidade existente para identificar os usuários que executam ações no Change Manager.
1. Na seção **Template reviewer notification** (Notificação do revisor de modelo), especifique os tópicos do Amazon Simple Notification Service (Amazon SNS) a serem usados para notificar os revisores de modelos de que há um novo modelo de alteração ou versão de modelo de alteração pronto para análise. Verifique se o tópico do Amazon SNS escolhido está configurado para enviar notificações aos revisores do modelo.
Para obter informações sobre como criar e configurar tópicos do Amazon SNS para notificações de revisão de modelo de alteração, consulte [Configurar os tópicos do Amazon SNS para as notificações do Change Manager](change-manager-sns-setup.md).
1. Para especificar o tópico do Amazon SNS para notificação do revisor de modelo, escolha uma das opções a seguir:
+ **Insira um nome do recurso da Amazon (ARN)** – Para **ARN do tópico**, insira o ARN de um tópico existente do Amazon SNS. Esse tópico pode estar em qualquer uma das contas da sua organização.
+ **Selecione um tópico do SNS existente**: para **Target notification topic** (Tópico de notificação de destino), selecione o ARN de um tópico existente do Amazon SNS em sua Conta da AWS atual. (Essa opção não estará disponível se você ainda não tiver criado nenhum tópico do Amazon SNS na sua Conta da AWS e Região da AWS.)
**nota**
O tópico do Amazon SNS selecionado deve ser configurado para especificar as notificações que ele envia e os assinantes para os quais eles são enviados. Sua política de acesso também deve conceder permissões ao Systems Manager, para que o Change Manager possa enviar notificações. Para obter mais informações, consulte [Configurar os tópicos do Amazon SNS para as notificações do Change Manager](change-manager-sns-setup.md).
1. Escolha **Adicionar notificação**.
1. Na seção **Change template reviewers** (Revisores de modelos de alterações), selecione os usuários em sua organização ou conta para revisar novos modelos de alteração ou alterar versões de modelo antes que eles possam ser usados em suas operações.
Os revisores do modelo de alteração são responsáveis por verificar a adequação e a segurança dos modelos que outros usuários enviaram para uso nos fluxos de trabalho do runbook do Change Manager.
Selecione revisores de modelo de alteração fazendo o seguinte:
1. Escolha **Adicionar**.
1. Marque a caixa de seleção ao lado do nome de cada usuário, grupo ou função do IAM que você deseja atribuir como um revisor do modelo de alteração.
1. Selecione **Add approvers** (Adicionar aprovadores).
1. Selecione **Enviar**.
Depois de concluir este processo de configuração inicial, defina as configurações e práticas recomendadas do Change Manager seguindo as etapas em [Tarefa 2: Configurar os aprovadores de eventos de congelamento de alterações e práticas recomendadas do Change Manager](#cm-configure-account-task-2).
## Tarefa 2: Configurar os aprovadores de eventos de congelamento de alterações e práticas recomendadas do Change Manager
Após concluir as etapas em [Tarefa 1: Configurar o gerenciamento de identidade de usuário e revisores de modelo do Change Manager](#cm-configure-account-task-1), você poderá designar revisores adicionais para solicitações de alteração durante os *eventos de alteração do congelamento* e especificar quais as práticas recomendadas disponíveis que você deseja permitir para as operações do Change Manager.
Um evento de congelamento de alterações significa que as restrições estão em vigor no calendário de alterações atual (o estado do calendário em AWS Systems Manager Change Calendar é `CLOSED`). Nesses casos, além de aprovadores regulares para solicitações de alteração, ou se a solicitação de alteração for criada usando um modelo que permita aprovações automáticas, os aprovadores do congelamento de alterações devem conceder permissão para que essa solicitação de alteração seja executada. Se não o fizerem, a alteração não será processada até que o estado do calendário seja novamente `OPEN`.
**Para configurar os aprovadores de eventos de congelamento de alterações e práticas recomendadas do Change Manager**
1. No painel de navegação, escolha **Change Manager**.
1. Escolha a guia **Web Settings** (Configurações da Web) e escolha **Edit** (Editar).
1. Na seção **Approvers for change freeze events** (Aprovadores para eventos de congelamento de alterações), selecione os usuários em sua organização ou conta que podem aprovar alterações para execução, mesmo quando o calendário em uso no Change Calendar estiver atualmente FECHADO.
**nota**
Para permitir revisões do congelamento de alterações, você deve ativar a opção **Check Change Calendar for restricted change events** (Verificar o calendário de alterações para eventos de alteração restritos) em**Best practices** (Práticas recomendadas).
Selecione aprovadores para eventos de congelamento de alteração fazendo o seguinte:
1. Escolha **Adicionar**.
1. Marque a caixa de seleção ao lado do nome de cada usuário, grupo ou função do IAM que você deseja atribuir como um aprovador de eventos de congelamento de alterações.
1. Selecione **Add approvers** (Adicionar aprovadores).
1. Na seção **Best practices** (Práticas recomendadas), próxima à parte inferior da página, ative as práticas recomendadas que você deseja impor para cada uma das opções a seguir.
+ Opção: **verifique o Calendário de alterações para eventos de alteração restritos**
Para especificar que o Change Manager verifique um calendário no Change Calendar para garantir que as alterações não sejam bloqueadas por eventos agendados, selecione primeiro a caixa de seleção **Enabled** (Habilitado) e, em seguida, selecione o calendário para verificar se há eventos restritos na lista **Change Calendar** (Alterar calendário).
Para obter mais informações sobre o Change Calendar, consulte [AWS Systems Manager Change Calendar](systems-manager-change-calendar.md).
+ Opção: **tópico SNS para aprovadores em eventos fechados**
1. Escolha uma das opções a seguir para especificar o tópico Amazon Simple Notification Service (Amazon SNS) em sua conta a ser usado para enviar notificações aos aprovadores durante os eventos de congelamento de alterações. Observe que você também deve especificar os aprovadores na seção **Approvers for change freeze events** (Aprovadores para eventos de congelamento de alterações), acima de **Best practices** (Práticas recomendadas)
+ **Insira um nome do recurso da Amazon (ARN)** – Para **ARN do tópico**, insira o ARN de um tópico existente do Amazon SNS. Esse tópico pode estar em qualquer uma das contas da sua organização.
+ **Selecione um tópico do SNS existente**: para **Target notification topic** (Tópico de notificação de destino), selecione o ARN de um tópico existente do Amazon SNS em sua Conta da AWS atual. (Essa opção não estará disponível se você ainda não tiver criado nenhum tópico do Amazon SNS na sua Conta da AWS e Região da AWS.)
**nota**
O tópico do Amazon SNS selecionado deve ser configurado para especificar as notificações que ele envia e os assinantes para os quais eles são enviados. Sua política de acesso também deve conceder permissões ao Systems Manager, para que o Change Manager possa enviar notificações. Para obter mais informações, consulte [Configurar os tópicos do Amazon SNS para as notificações do Change Manager](change-manager-sns-setup.md).
1. Escolha **Adicionar notificação**.
+ Opção: **exija monitores para todos os modelos**
Se você quiser garantir que todos os modelos da sua organização ou conta especifiquem um alarme do Amazon CloudWatch para monitorar a operação de alteração, marque a caixa de seleção **Enabled** (Habilitado).
+ Opção: **exija revisão e aprovação do modelo antes de usar**
Para garantir que nenhuma solicitação de alteração seja criada e que nenhum fluxo de trabalho do runbook seja executado, sem se basear em um modelo que tenha sido revisado e aprovado, selecione a opção **Enabled** (Habilitado).
1. Escolha **Salvar**.
# Configurar os tópicos do Amazon SNS para as notificações do Change Manager
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Você pode configurar o Change Manager, uma ferramenta do AWS Systems Manager, para enviar notificações a um tópico do Amazon Simple Notification Service (Amazon SNS) para eventos relacionados a solicitações e modelos de alteração. Conclua as tarefas a seguir para receber notificações dos eventos do Change Manageraos quais você adiciona um tópico.
**Topics**
+ [Tarefa 1: Criar e assinar um tópico do Amazon SNS](#change-manager-sns-setup-create-topic)
+ [Tarefa 2: Atualizar a política de acesso do Amazon SNS](#change-manager-sns-setup-encryption-policy)
+ [Tarefa 3: Atualizar a política de acesso do AWS Key Management Service (opcional)](#change-manager-sns-setup-KMS-policy)
## Tarefa 1: Criar e assinar um tópico do Amazon SNS
Primeiro, crie e se inscreva em um tópico do Amazon SNS. Para obter informações, consulte [Criar um tópico do Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html) e [Assinar tópico do Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-tutorial-create-subscribe-endpoint-to-topic.html) no *Guia do desenvolvedor do Amazon Simple Notification Service*.
**nota**
Para receber notificações, você deverá especificar o nome do recurso da Amazon (ARN) de um tópico do Amazon SNS que estiver na mesma Região da AWS e Conta da AWS que a conta do administrador delegado.
## Tarefa 2: Atualizar a política de acesso do Amazon SNS
Use o procedimento a seguir para atualizar a política de acesso do Amazon SNS, para que o Systems Manager possa publicar notificações do Change Manager no tópico do Amazon SNS que você criou na tarefa 1. Sem concluir esta tarefa, o Change Manager não terá permissão para enviar notificações para os eventos aos quais você adicionou o tópico.
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon SNS em [https://console.aws.amazon.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home).
1. No painel de navegação, escolha **Tópicos**.
1. Selecione o tópico criado na tarefa 1 e escolha **Edit** (Editar).
1. Expanda **Access policy (Política de acesso)**.
1. Adicione e atualize o seguinte bloco do `Sid` à política existente e substitua cada *espaço reservado para entrada do usuário* pelas suas próprias informações.
```
{
"Sid": "Allow Change Manager to publish to this topic",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "sns:Publish",
"Resource": "arn:aws:sns:region:account-id:topic-name",
"Condition": {
"StringEquals": {
"aws:SourceAccount": [
"account-id"
]
}
}
}
```
Insira esse bloco após o bloco `Sid` existente e substitua *region*, *account-id* e *topic-name* pelos valores apropriados para o tópico que você criou.
1. Escolha **Salvar alterações**.
O sistema agora envia notificações para o tópico do Amazon SNS quando o tipo de evento que você adicionar ao tópico ocorrer.
**Importante**
Se você configurou o tópico do Amazon SNS com uma chave de criptografia do AWS Key Management Service (AWS KMS) no lado do servidor, conclua a tarefa 3.
## Tarefa 3: Atualizar a política de acesso do AWS Key Management Service (opcional)
Se você ativou a criptografia do lado do servidor do AWS Key Management Service (AWS KMS) para seu tópico do Amazon SNS, atualize também a política de acesso da AWS KMS key escolhida ao configurar o tópico. Use o procedimento a seguir para atualizar a política de acesso, de forma que o Systems Manager possa publicar as notificações de aprovação do Change Manager no tópico do Amazon SNS que você criou na tarefa 1.
1. Abra o console do AWS KMS em [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. No painel de navegação, escolha **Chaves gerenciadas pelo cliente**.
1. Selecione o ID da chave gerenciada do cliente que você escolheu ao criar o tópico.
1. Na seção **Key Policy (Política de chaves)**, selecione **Switch to policy view (Alternar para a visualização da política)**.
1. Escolha **Editar**.
1. Insira o seguinte bloco `Sid` após um dos blocos `Sid` existentes na política existente. Substitua cada *espaço reservado para entrada do usuário* por suas próprias informações.
```
{
"Sid": "Allow Change Manager to decrypt the key",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey*"
],
"Resource": "arn:aws:kms:region:account-id:key/key-id",
"Condition": {
"StringEquals": {
"aws:SourceAccount": [
"account-id"
]
}
}
}
```
1. Insira o seguinte bloco `Sid` após um dos blocos `Sid` existentes na política de recursos para ajudar a evitar o [problema confused deputy entre serviços](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html).
Esse bloco usa as chaves de contexto de condição global [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) e [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount) com o objetivo de limitar as permissões concedidas pelo Systems Manager para outro serviço ao recurso.
Substitua cada *espaço reservado para entrada do usuário* por suas próprias informações.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Configure confused deputy protection for AWS KMS keys used in Amazon SNS topic when called from Systems Manager",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": [
"sns:Publish"
],
"Resource": "arn:aws:sns:us-east-1:111122223333:topic-name",
"Condition": {
"ArnLike": {
"aws:SourceArn": "arn:aws:ssm:us-east-1:111122223333:*"
},
"StringEquals": {
"aws:SourceAccount": "111122223333"
}
}
}
]
}
```
------
1. Escolha **Salvar alterações**.
# Configurar perfis e permissões para o Change Manager
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Por padrão, o Change Manager não tem permissão para executar ações em suas instâncias. Você deve conceder acesso usando uma AWS Identity and Access ManagementFunção de serviço (IAM) ou *Função assumida*. Essa função permite Change Manager executar com segurança os fluxos de trabalho de runbook especificados em uma solicitação de alteração aprovada em seu nome. Essa função concede a AWS Security Token Service (AWS STS) [AssumeRole (Função assuida)](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) de Change Manager.
Ao fornecer essas permissões a uma função para agir em nome de usuários em uma organização, os usuários não precisam receber essa matriz de permissões. As ações permitidas pelas permissões são limitadas apenas a operações aprovadas.
Quando os usuários em sua conta ou organização criam uma solicitação de alteração, eles podem selecionar essa função para realizar as operações de alteração.
Você pode criar uma nova função assumida para Change Manager ou atualizar uma função existente com as permissões necessárias.
Se você precisar criar uma função de serviço para o Change Manager, conclua as tarefas a seguir.
**Topics**
+ [Tarefa 1: Criar uma política de função assumida para Change Manager](#change-manager-role-policy)
+ [Tarefa 2: Criando uma função assumida para Change Manager](#change-manager-role)
+ [Tarefa 3: Anexar a política `iam:PassRole` a outras funções](#change-manager-passpolicy)
+ [Tarefa 4: Adicionar políticas em linha a um papel assumido para invocar outros Serviços da AWS](#change-manager-role-add-inline-policy)
+ [Tarefa 5: Configurar o acesso do usuário para Change Manager](#change-manager-passrole)
## Tarefa 1: Criar uma política de função assumida para Change Manager
Use o procedimento a seguir para criar a política que você anexará à sua função assumida Change Manager.
**Para criar uma política de função assumida para Change Manager**
1. Abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. No painel de navegação, escolha **Policies** e, em seguida, **Create Policy**.
1. Na página **Criar política**, escolha a guia **JSON** e substitua o conteúdo padrão pelo seguinte, que você modificará para suas próprias Change Manager operações nas etapas a seguir.
**nota**
Se você estiver criando uma política para usar com uma única Conta da AWS e não uma organização com várias contas e Regiões da AWS, é possível omitir o primeiro bloco de instrução. A `iam:PassRole` permissão não é necessária no caso de uma única conta usando Change Manager.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/AWS-SystemsManager-job-functionAdministrationRole",
"Condition": {
"StringEquals": {
"iam:PassedToService": "ssm.amazonaws.com"
}
}
},
{
"Effect": "Allow",
"Action": [
"ssm:DescribeDocument",
"ssm:GetDocument",
"ssm:StartChangeRequestExecution"
],
"Resource": [
"arn:aws:ssm:us-east-1::document/template-name",
"arn:aws:ssm:us-east-1:111122223333:automation-execution/*"
]
},
{
"Effect": "Allow",
"Action": [
"ssm:ListOpsItemEvents",
"ssm:GetOpsItem",
"ssm:ListDocuments",
"ssm:DescribeOpsItems"
],
"Resource": "*"
}
]
}
```
------
1. Para a ação `iam:PassRole`, atualize o valor `Resource` para incluir os ARNs de todas as funções de trabalho definidas para sua organização que você deseja conceder permissões para iniciar fluxos de trabalho de runbook.
1. Substitua os espaços reservados de *region*, *account-id*, *template-name*, *delegated-admin-account-id* e *job-function* por valores para as operações do Change Manager.
1. Para a segunda instrução `Resource`, modifique a lista para incluir todos os modelos de alteração para os quais você deseja conceder permissões. Como alternativa, especifique `"Resource": "*"` para conceder permissões para todos os modelos de alteração em sua organização.
1. Escolha **Próximo: tags**.
1. (Opcional) Adicione um ou mais pares de chave-valor de etiqueta para organizar, monitorar ou controlar acesso para essa política.
1. Escolha **Próximo: revisar**.
1. Na página **Review policy (Revisar política)**, insira um nome na caixa **Name (Nome)**, como **MyChangeManagerAssumeRole**, e insira uma descrição opcional.
1. Escolha **Create policy (Criar política)** e continue para [Tarefa 2: Criando uma função assumida para Change Manager](#change-manager-role).
## Tarefa 2: Criando uma função assumida para Change Manager
Use o procedimento a seguir para criar uma função assumida Change Manager, um tipo de função de serviço, para Change Manager.
**Para criar uma função assumida para Change Manager**
1. Abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. No painel de navegação, escolha **Roles** e **Create role**.
1. Em **Select trusted entity** (Selecionar entidade confiável), faça as seguintes escolhas:
1. Em **Trusted entity type** (Tipo de entidade confiável), escolha ** service** (Serviço da AWS)
1. Em **Casos de uso para outros Serviços da AWS**, escolha **Systems Manager**.
1. Escolha **Systems Manager**, como mostrado na imagem a seguir.
![\[Captura de tela ilustrando a opção Systems Manager selecionada como um caso de uso.\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/iam_use_cases_for_MWs.png)
1. Escolha **Próximo**.
1. Na página **Attached permissions policy (Política de permissões anexadas)**, procure a política de função assumida que você criou em [Tarefa 1: Criar uma política de função assumida para Change Manager](#change-manager-role-policy), por exemplo,**MyChangeManagerAssumeRole**.
1. Marque a caixa de seleção ao lado do nome da política assumir função e escolha **Próximo: tags.**.
1. Em **Role name** (Nome da função), insira um nome para seu novo perfil da instância, como **MyChangeManagerAssumeRole**.
1. (Opcional) Em **Description** (Descrição), atualize a descrição deste perfil de instância.
1. (Opcional) Adicione um ou mais pares de chave-valor de etiqueta para organizar, monitorar ou controlar acesso para essa função.
1. Escolha **Próximo: revisar**.
1. (Opcional) Em **Tags** (Etiquetas), adicione um ou mais pares de valores etiqueta-chave para organizar, monitorar ou controlar o acesso para esse perfil e, em seguida, escolha **Create role** (Criar perfil). O sistema faz com que você retorne para a página **Roles**.
1. Selecione **Create role** (Criar função). O sistema faz com que você retorne para a página **Roles**.
1. Na página **Roles** (Funções), escolha a função que você acabou de criar para abrir a página **Summary** (Resumo).
## Tarefa 3: Anexar a política `iam:PassRole` a outras funções
Use o procedimento a seguir para anexar a política `iam:PassRole` a um perfil de instância do IAM ou função de serviço do IAM. (O serviço Systems Manager usa perfis de instância do IAM para se comunicar com instâncias do EC2. Para nós gerenciados que não são do EC2 em um ambiente [híbrido e multinuvem](operating-systems-and-machine-types.md#supported-machine-types), utiliza-se um perfil de serviço do IAM.)
Ao anexar o política `iam:PassRole`, o serviço Change Manager pode passar permissões de função para outros serviços ou ferramentas do Systems Manager (Gerenciador de sistemas) ao executar fluxos de trabalho do runbook.
**Para anexar a política `iam:PassRole` a um perfil de instância ou perfil de serviço do IAM**
1. Abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. No painel de navegação, escolha **Perfis**.
1. Procure pela função assumida Change Manager que você criou, como **MyChangeManagerAssumeRole**, e escolha seu nome.
1. Na página **Summary (Resumo)** da função assumida, escolha a guia **Permissions (Permissões)**.
1. Escolha **Add permissions, Create inline policy** (Adicionar permissões, Criar política em linha).
1. Na página **Create policy** (Criar política), selecione a guia **Visual editor** (Editor visual).
1. Selecione **Service** (Serviço) e, em seguida, selecione **IAM**.
1. Na caixa de texto **Filter actions (Filtrar ações)**, insira **PassRole** e selecione a opção **PassRole**.
1. Ampliar os **Resources (Recursos)**. Verifique se **Specific** (Específico) está selecionado e, em seguida, selecione **Add ARN** (Adicionar ARN).
1. No campo **Specify ARN for role (Especificar ARN para função)**, insira o ARN da função de perfil da instância do IAM ou da função de serviço do IAM para a qual você deseja passar permissões de função assumida. O sistema preenche os campos **Account (Conta)** e **Role name with path (Nome da função com caminho)**.
1. Escolha **Add** (Adicionar).
1. Escolha **Review policy** (Revisar política).
1. Em **Name** (Nome), insira um nome para identificar essa política e escolha **Create policy** (Criar política).
**Mais informações**
+ [Configurar permissões de instância obrigatórias para o Systems Manager](setup-instance-permissions.md)
+ [Criar o perfil de serviço do IAM obrigatório para o Systems Manager em ambientes híbridos e multinuvem](hybrid-multicloud-service-role.md)
## Tarefa 4: Adicionar políticas em linha a um papel assumido para invocar outros Serviços da AWS
Quando uma solicitação de alteração invoca outros Serviços da AWS usando a função assumida Change Manager, a função assume deve ser configurada com permissão para invocar esses serviços. Esse requisito se aplica a todos os AWSRunbooks do Automation (runbooks AWS-\$1) que podem ser usados em uma solicitação de alteração, como os Runbooks `AWS-ConfigureS3BucketLogging`, `AWS-CreateDynamoDBBackup` e `AWS-RestartEC2Instance`. Esse requisito também se aplica a todos os runbooks personalizados criados que invoquem outros Serviços da AWS, usando ações que chamam outros serviços. Por exemplo, se você usar as ações `aws:executeAwsApi`, `aws:CreateStack` ou `aws:copyImage`, então você deve configurar um perfil de serviço com permissão para invocar esses serviços. É possível habilitar permissões para outros Serviços da AWS adicionando uma política em linha do IAM à função.
**Para adicionar uma política em linha a uma função de assunção para invocar outros Serviços da AWS (console do IAM)**
1. Faça login no Console de gerenciamento da AWS e abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. No painel de navegação, escolha **Perfis**.
1. Na lista, escolha o nome da função assumida que você deseja atualizar, como `MyChangeManagerAssumeRole`.
1. Escolha a aba **Permissões**.
1. Escolha **Add permissions, Create inline policy** (Adicionar permissões, Criar política em linha).
1. Selecione a guia **JSON**.
1. Insira um documento de política JSON para os Serviços da AWS que você deseja chamar. Veja a seguir dois exemplos de documentos de política JSON
**Simple Storage Service (Amazon S3) `PutObject` e `GetObject` exemplo**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
}
]
}
```
------
**Amazon EC2 `CreateSnapshot` e `DescribeSnapShots` exemplo**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshot",
"Resource":"*"
},
{
"Effect":"Allow",
"Action":"ec2:DescribeSnapshots",
"Resource":"*"
}
]
}
```
------
Para obter detalhes sobre a linguagem da política do IAM, consulte a [Referência da política JSON do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) no *Guia do usuário do IAM*.
1. Ao concluir, selecione **Review policy (Revisar política)**. O [Validador de política](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_policy-validator.html) indica se há qualquer erro de sintaxe.
1. Em **Name** (Nome), insira um nome para identificar a política que você está criando. Revise o **Resumo** da política para ver as permissões que são concedidas pela política. Em seguida, escolha **Criar política** para salvar seu trabalho.
1. Após a criação de uma política em linha, ela é automaticamente incorporada à sua função.
## Tarefa 5: Configurar o acesso do usuário para Change Manager
Se seu usuário, grupo ou perfil tiver permissões de administrador atribuídas, você terá acesso ao Change Manager. Se você não tiver permissões de administrador, um administrador deverá atribuir a política gerenciada `AmazonSSMFullAccess` ou uma política que forneça permissões comparáveis ao seu usuário, grupo ou perfil.
Use o procedimento a seguir para configurar um usuário para usar o Change Manager. O usuário escolhido terá permissões para configurar e executar o Change Manager.
Dependendo da aplicação de identidade que você usa em sua organização, é possível selecionar qualquer uma das três opções disponíveis para configurar o acesso do usuário. Ao configurar o acesso do usuário, atribua ou adicione o seguinte:
1. Atribua a política `AmazonSSMFullAccess` ou uma política comparável que forneça permissões para acessar o Systems Manager.
1. Atribua a política `iam:PassRole`.
1. Adicione o ARN para o perfil assumido do Change Manager copiado no final de [Tarefa 2: Criando uma função assumida para Change Manager](#change-manager-role).
Para conceder acesso, adicione as permissões aos seus usuários, grupos ou perfis:
+ Usuários e grupos no Centro de Identidade do AWS IAM:
Crie um conjunto de permissões. Siga as instruções em [Criação de um conjunto de permissões](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) no *Guia do usuário do Centro de Identidade do AWS IAM*.
+ Usuários gerenciados no IAM com provedor de identidades:
Crie um perfil para a federação de identidades. Siga as instruções em [Criando um perfil para um provedor de identidades de terceiros (federação)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) no *Guia do Usuário do IAM*.
+ Usuários do IAM:
+ Crie um perfil que seu usuário possa assumir. Siga as instruções em [Criação de um perfil para um usuário do IAM](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) no *Guia do usuário do IAM*.
+ (Não recomendado) Vincule uma política diretamente a um usuário ou adicione um usuário a um grupo de usuários. Siga as instruções em [Adição de permissões a um usuário (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) no *Guia do usuário do IAM*.
Você terminou de configurar as funções necessárias para Change Manager. Agora é possível usar a função assumida ARN Change Manager em suas operações Change Manager.
# Controlar o acesso a fluxos de trabalho do runbook de aprovação automática
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Em cada modelo de alteração criado para sua organização ou conta, você pode especificar se as solicitações de alteração criadas com esse modelo podem ser executadas como solicitações de alteração aprovadas automaticamente, o que significa que elas são executadas automaticamente sem uma etapa de revisão (com exceção dos eventos de congelamento de alterações).
No entanto, você pode querer impedir determinados usuários, grupos ou grupos funções do AWS Identity and Access Management (IAM) de executar solicitações de alteração aprovadas automaticamente, mesmo que um modelo de alteração permita. Você pode fazer isso usando a chave de condição `ssm:AutoApprove` para a operação `StartChangeRequestExecution`em uma política do IAM atribuída ao usuário, grupo ou função do IAM.
Você pode adicionar a seguinte política como uma política em linha, onde a condição é especificada como `false` para impedir que os usuários executem solicitações de alteração aprovadas automaticamente.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ssm:StartChangeRequestExecution",
"Resource": "*",
"Condition": {
"BoolIfExists": {
"ssm:AutoApprove": "false"
}
}
}
]
}
```
------
Para obter informações sobre como especificar políticas em linha, consulte [Políticas em linha](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_policies_managed-vs-inline.html#inline-policies) e [Adicionar e remover permissões de identidade do IAM](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_policies_manage-attach-detach.html) no *Manual do usuário do IAM*.
Para obter mais informações sobre chaves de condição das políticas do Systems Manager, consulte[Chaves de condição do Systems Manager](security_iam_service-with-iam.md#policy-conditions).
# Como trabalhar com o Change Manager
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Com o Change Manager, uma ferramenta do AWS Systems Manager, os usuários em toda a sua organização ou em uma única Conta da AWS podem executar tarefas relacionadas a alterações para as quais receberam as permissões necessárias. As tarefas do Change Manager incluem o seguinte:
+ Crie, revise e aprove ou rejeite os modelos de alteração.
Um modelo de alteração é uma coleção de definições de configuração no Change Managerque definem itens como aprovações obrigatórias, runbooks disponíveis e opções de notificação para solicitações de alteração.
+ Crie, revise e aprove ou rejeite as solicitações de alteração.
Uma solicitação de alteração é uma solicitação no Change Manager para executar um runbook do Automation que atualiza um ou mais recursos na AWS ou em ambientes on-premises. Uma solicitação de alteração é criada usando um modelo de alteração.
+ Especifique quais usuários em sua organização ou conta podem ser revisores para modelos e solicitações de alteração.
+ Edite as definições de configuração, por exemplo, a forma como as identidades do usuário são gerenciadas no Change Manager e qual das opções de *práticas recomendadas* são impostas nas operações do Change Manager. Para obter mais informações sobre como definir essas configurações consulte [Configurar as opções e práticas recomendadas do Change Manager](change-manager-account-setup.md).
**Topics**
+ [Trabalhar com modelos de alteração](change-templates.md)
+ [Trabalhar com solicitações de alteração](change-requests.md)
+ [Revisar detalhes, tarefas e cronogramas das solicitações de alteração (console)](reviewing-changes.md)
+ [Visualizar contagens agregadas de solicitações de alteração (linha de comando)](change-requests-review-aggregate-command-line.md)
# Trabalhar com modelos de alteração
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Um modelo de alteração é uma coleção de definições de configuração no Change Managerque definem itens como aprovações obrigatórias, runbooks disponíveis e opções de notificação para solicitações de alteração.
**nota**
A AWS fornece um exemplo de modelo de alteração [Hello World](change-templates-aws-managed.md) que você pode usar para testar o Change Manager, uma ferramenta do AWS Systems Manager. No entanto, você cria seus próprios modelos de alteração para definir as alterações que deseja permitir aos recursos em sua organização ou conta.
As alterações feitas quando um fluxo de trabalho do runbook é executado são baseadas no conteúdo de um runbook do Automation. Em cada modelo de alteração criado, você pode incluir um ou mais runbooks do Automation, que o usuário que faz uma solicitação de alteração poderá escolher para executar durante a atualização. Você também pode criar modelos de alteração que permitem que os solicitantes escolham qualquer runbook do Automation disponível para a solicitação de alteração.
Para criar um modelo de alteração, você pode usar a opção **Builder** na página do console **Create template** (Criar modelo). Como alternativa, use a opção **Editor**. Crie manualmente conteúdo JSON ou YAML com a configuração desejada para o fluxo de trabalho do runbook. Você também pode usar uma ferramenta de linha de comando para criar um modelo de alteração com conteúdo JSON para o modelo de alteração armazenado em um arquivo externo.
**Topics**
+ [Experimente o modelo de alteração `Hello World` gerenciado pela AWS](change-templates-aws-managed.md)
+ [Criar modelos de alteração](change-templates-create.md)
+ [Revisar e aprovar ou rejeitar solicitações de alteração (modelos)](change-templates-review.md)
+ [Excluir modelos de alteração](change-templates-delete.md)
# Experimente o modelo de alteração `Hello World` gerenciado pela AWS
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Você pode usar o modelo de alteração de exemplo `AWS-HelloWorldChangeTemplate`, que usa o runbook do Automation de exemplo `AWS-HelloWorld`, para testar o processo de revisão e aprovação depois de concluir a configuração do Change Manager, uma ferramenta do AWS Systems Manager. Esse modelo foi projetado para testar ou verificar suas permissões configuradas, atribuições de aprovador e processo de aprovação. A aprovação para usar esse modelo de alteração em sua organização ou conta já foi fornecida pela AWS. Porém, qualquer solicitação de alteração com base nesse modelo de alteração ainda deve ser aprovada pelos revisores em sua organização ou conta.
Em vez de fazer alterações em um recurso, o resultado do fluxo de trabalho do runbook associado a esse modelo é a impressão de uma mensagem na saída de uma etapa do Automation.
**Antes de começar**
Antes de começar, realize as seguintes tarefas:
+ Se você estiver usando o AWS Organizations para gerenciar alterações em uma organização, conclua as tarefas de configuração da organização descritas em [Configure o Change Manager para uma organização (conta de gerenciamento)](change-manager-organization-setup.md).
+ Configure o Change Manager para a conta de administrador delegada ou conta única, conforme descrito em [Configurar as opções e práticas recomendadas do Change Manager](change-manager-account-setup.md).
**nota**
Se você ativou a opção de prática recomendada **Require monitors for all templates** (Exigir monitores para todos os modelos) nas configurações do Change Manager, desative-a temporariamente enquanto testa o modelo de alteração Hello World.
**Para experimentar o modelo de alteração Hello World gerenciado pela AWS**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Manager**.
1. Selecione **Create request** (Criar solicitação).
1. Selecione o modelo de alteração chamado `AWS-HelloWorldChangeTemplate` e, em seguida, escolha **Next** (Próximo).
1. Para **Name** (Nome), insira um nome para a solicitação de alteração que facilite a identificação de sua finalidade, como **MyChangeRequestTest**.
1. Para que o restante das etapas crie sua solicitação de alteração, consulte [Criar solicitações de alteraçãoCriar solicitações de alteração (console)](change-requests-create.md).
**Próximas etapas**
Para obter informações sobre como aprovar solicitações de alteração, consulte [Revisar e aprovar ou rejeitar solicitações de alteração](change-requests-review.md).
Para exibir o status e os resultados da solicitação de alteração, escolha o nome da solicitação de alteração na guia **Requests** (Solicitações) no Change Manager.
# Criar modelos de alteração
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Um modelo de alteração é uma coleção de definições de configuração no Change Managerque definem itens como aprovações obrigatórias, runbooks disponíveis e opções de notificação para solicitações de alteração.
É possível criar modelos de alteração para suas operações no Change Manager, uma ferramenta do AWS Systems Manager usando o console, que inclui opções do Builder e Editor ou ferramentas da linha de comando.
**Topics**
+ [Sobre as aprovações em seus modelos de alteração](cm-approvals-templates.md)
+ [Criar modelos de alteração usando o Builder](change-templates-custom-builder.md)
+ [Criando modelos de alteração usando o Editor](change-templates-custom-editor.md)
+ [Criar modelos de alteração usando ferramentas de linha de comando](change-templates-tools.md)
# Sobre as aprovações em seus modelos de alteração
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Para cada modelo de alteração criado, é possível especificar até cinco *níveis* de aprovação para as solicitações de alteração criadas nele. Para cada um desses níveis, você pode designar até cinco possíveis *aprovadores*. Um aprovador não está limitado a um único usuário. Também é possível especificar um grupo do IAM ou um perfil do IAM como um aprovador individual. Para grupos do IAM e perfis do IAM, um ou mais usuários pertencentes ao grupo ou perfil podem fornecer aprovações para receber o número total de aprovações requeridas para uma solicitação de alteração. Você também pode especificar mais aprovadores do que o requerido pelo seu modelo de alteração.
O Change Manager oferece suporte para duas abordagens principais para aprovações: *aprovações por nível* e *aprovações por linha*. Em algumas situações, também é possível realizar uma combinação dos dois tipos. Recomendamos usar somente aprovações por nível em suas operações do Change Manager.
------
#### [ Per-level approvals ]
*Recomendado*. A partir de 23 de janeiro de 2023, o Change Manager oferecerá suporte para aprovações por nível. Nesse modelo, para cada nível de aprovação em seu modelo de alteração, primeiro é necessário especificar quantas aprovações são requeridas para esse nível. Em seguida, você especifica, no mínimo, esse número de aprovadores para o nível e pode especificar mais aprovadores. No entanto, somente o número de aprovadores por nível que você especificar precisará aprovar a solicitação de alteração. Por exemplo, é possível especificar cinco aprovadores, mas requerer três aprovações.
Para obter amostras de visualização do console e JSON desse tipo de aprovação, consulte [Amostra de configuração de aprovação por nível](approval-type-samples.md#per-level-approvals).
------
#### [ Per-line approvals ]
*Com suporte para compatibilidade com versões anteriores*. A versão original do Change Manager oferecia suporte somente para aprovações por linha. Nesse modelo, cada aprovador especificado para um nível de aprovação é representado como uma linha de aprovação. Cada aprovador precisava aprovar uma solicitação de alteração para que ela fosse aprovada nesse nível. Antes de 23 de janeiro de 2023, este era o único modelo com suporte para aprovações. Os modelos de alteração criados antes dessa data continuam a oferecer suporte às aprovações por linha, mas recomendamos usar as aprovações por nível.
Para obter amostras de visualização do console e JSON desse tipo de aprovação, consulte [Amostra de configuração de aprovação por linha](approval-type-samples.md#per-line-approvals).
------
#### [ Combined per-line and per-level approvals ]
*Não recomendado*. No console, a guia **Builder** não oferece mais suporte para a adição de aprovações por linha. No entanto, em alguns casos, é possível ter aprovações por linha e por nível em um modelo de alteração. Isso pode ocorrer caso você atualize um modelo de alteração criado antes de 23 de janeiro de 2023 ou crie ou atualize um modelo de alteração ao editar seu conteúdo YAML manualmente.
Para obter amostras de visualização do console e JSON desse tipo de aprovação, consulte [Amostra de configuração de aprovação combinada por nível e por linha](approval-type-samples.md#combined-approval-levels).
------
**Importante**
Embora seja possível criar um modelo de alteração que combine aprovações por linha e por nível, essa configuração não é recomendada ou necessária. Qualquer tipo de aprovação que requeira mais aprovações (aprovações por linha ou por nível) tem precedência. Por exemplo:
Se um modelo de alteração especificar três aprovações por nível, mas cinco aprovações por linha, serão requeridas cinco aprovações.
Se um modelo de alteração especificar quatro aprovações por nível, mas duas aprovações por linha, serão requeridas quatro aprovações.
É possível criar um nível que inclua aprovações por linha e por nível ao editar o conteúdo YAML ou JSON manualmente. Em seguida, a guia **Builder** exibirá os controles para especificação do número requerido de aprovações para o nível e para as linhas individuais. No entanto, os novos níveis adicionados usando o console ainda oferecem suporte somente às configurações de aprovação por nível.
## Notificações e rejeições das solicitações de alteração
Notificações do Amazon SNS
Quando uma solicitação de alteração é criada usando seu modelo de alteração, as notificações são enviadas aos assinantes do tópico do Amazon Simple Notification Service (Amazon SNS) que foi designado para notificações de aprovação nesse nível. É possível especificar o tópico de notificação no modelo de alteração ou permitir que o usuário que está criando a solicitação de alteração o especifique.
Após o número mínimo de aprovações requeridas ser recebido em um nível, as notificações serão enviadas aos aprovadores inscritos no tópico do Amazon SNS para o próximo nível, e assim sucessivamente.
Certifique-se de que os grupos, usuários e perfis do IAM designados em conjunto forneçam aprovadores suficientes para atender ao número requerido de aprovações especificado. Por exemplo, se você designar como aprovador um único grupo do IAM que contém três usuários, não poderá especificar que cinco aprovações sejam requeridas nesse nível, somente três ou menos.
Rejeições de solicitações de alteração
Não importa quantos níveis de aprovação e aprovadores você especificar, somente uma rejeição a uma solicitação de alteração é requerida para evitar que o fluxo de trabalho do runbook para essa solicitação ocorra.
# Exemplos de tipos de aprovação do Change Manager
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
As amostras a seguir demonstram a visualização do console e o conteúdo JSON para os três tipos de tipos de aprovação no Change Manager.
**Topics**
+ [Amostra de configuração de aprovação por nível](#per-level-approvals)
+ [Amostra de configuração de aprovação por linha](#per-line-approvals)
+ [Amostra de configuração de aprovação combinada por nível e por linha](#combined-approval-levels)
## Amostra de configuração de aprovação por nível
Na configuração do nível de aprovação por nível mostrada na imagem a seguir, são requeridas três aprovações. Essas aprovações poderão ser originadas de qualquer combinação de usuários, grupos e perfis do IAM que são especificados como aprovadores. Os aprovadores especificados incluem dois usuários do IAM (John Stiles e Ana Carolina Silva), um grupo de usuários que contém três membros (`GroupOfThree`) e um perfil de usuário que representa dez usuários (`RoleOfTen`).
Se todos os três usuários do grupo `GroupOfThree` aprovarem a solicitação de alteração, ela será aprovada para esse nível. Não é necessário receber uma aprovação de cada usuário, grupo ou perfil. O número mínimo de aprovações pode ser originado de qualquer combinação de aprovadores especificados. Recomendamos aprovações por nível para suas operações do Change Manager.
![\[Nível de aprovação apresentando três aprovações requeridas e quatro aprovadores especificados.\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/Add-approval-2.png)
A amostra a seguir ilustra parte do código YAML para essa configuração.
**nota**
Essa versão do código YAML inclui uma entrada adicional, `MinRequiredApprovals` (com uma letra maiúscula inicial `M`). O valor para essa entrada indica quantas aprovações são requeridas entre todos os revisores disponíveis. Observe também que o valor `minRequiredApprovals` (com uma letra minúscula inicial `m`) para cada aprovador na lista `Approvers` é `0` (zero). Isso indica que o aprovador poderá contribuir com as aprovações gerais, mas não é obrigado a fazê-lo.
```
schemaVersion: "0.3"
emergencyChange: false
autoApprovable: false
mainSteps:
- name: ApproveAction1
action: aws:approve
timeoutSeconds: 604800
inputs:
Message: Please approve this change request
MinRequiredApprovals: 3
EnhancedApprovals:
Approvers:
- approver: John Stiles
type: IamUser
minRequiredApprovals: 0
- approver: Ana Carolina Silva
type: IamUser
minRequiredApprovals: 0
- approver: GroupOfThree
type: IamGroup
minRequiredApprovals: 0
- approver: RoleOfTen
type: IamRole
minRequiredApprovals: 0
templateInformation: >
#### What is the purpose of this change?
//truncated
```
## Amostra de configuração de aprovação por linha
Na configuração do nível de aprovação mostrada na imagem a seguir, quatro aprovadores estão especificados. Destes, temos dois usuários do IAM (John Stiles e Ana Carolina Silva), um grupo de usuários que contém três membros (`GroupOfThree`) e um perfil de usuário que representa dez usuários (`RoleOfTen`). As aprovações por linha oferecem suporte para a compatibilidade com versões anteriores, mas não são recomendadas.
![\[Nível de aprovação apresentando quatro aprovadores requeridos por linha.\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/Add-approval-1.png)
Para que a solicitação de alteração seja aprovada nessa configuração de aprovação por linha, ela deve ser aprovada por todas as linhas de aprovadores: John Stiles, Ana Carolina Silva, um membro do grupo `GroupOfThree` e um membro do perfil `RoleOfTen`.
A amostra a seguir ilustra parte do código YAML para essa configuração.
**nota**
Observe que o valor para cada aprovador `minRequiredApprovals` é `1`. Isso indica que uma aprovação é requerida de cada aprovador.
```
schemaVersion: "0.3"
emergencyChange: false
autoApprovable: false
mainSteps:
- name: ApproveAction1
action: aws:approve
timeoutSeconds: 10000
inputs:
Message: Please approve this change request
EnhancedApprovals:
Approvers:
- approver: John Stiles
type: IamUser
minRequiredApprovals: 1
- approver: Ana Carolina Silva
type: IamUser
minRequiredApprovals: 1
- approver: GroupOfThree
type: IamGroup
minRequiredApprovals: 1
- approver: RoleOfTen
type: IamRole
minRequiredApprovals: 1
executableRunBooks:
- name: AWS-HelloWorld
version: $DEFAULT
templateInformation: >
#### What is the purpose of this change?
//truncated
```
## Amostra de configuração de aprovação combinada por nível e por linha
Na configuração de aprovação combinada por nível e por linha mostrada na imagem a seguir, três aprovações são especificadas para o nível, mas quatro aprovações são especificadas para as aprovações de itens de linha. O tipo de aprovação que requer mais aprovações tem precedência sobre o outro, portanto, quatro aprovações são requeridas para essa configuração. A aprovação combinada por nível e por linha não é recomendada.
![\[Nível de aprovação apresenta três aprovações requeridas para o nível, mas quatro requeridas no nível de linha.\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/Add-approval-3.png)
```
schemaVersion: "0.3"
emergencyChange: false
autoApprovable: false
mainSteps:
- name: ApproveAction1
action: aws:approve
timeoutSeconds: 604800
inputs:
Message: Please approve this change request
MinRequiredApprovals: 3
EnhancedApprovals:
Approvers:
- approver: John Stiles
type: IamUser
minRequiredApprovals: 1
- approver: Ana Carolina Silva
type: IamUser
minRequiredApprovals: 1
- approver: GroupOfThree
type: IamGroup
minRequiredApprovals: 1
- approver: RoleOfTen
type: IamRole
minRequiredApprovals: 1
templateInformation: >
#### What is the purpose of this change?
//truncated
```
**Topics**
+ [Sobre as aprovações em seus modelos de alteração](cm-approvals-templates.md)
+ [Criar modelos de alteração usando o Builder](change-templates-custom-builder.md)
+ [Criando modelos de alteração usando o Editor](change-templates-custom-editor.md)
+ [Criar modelos de alteração usando ferramentas de linha de comando](change-templates-tools.md)
# Criar modelos de alteração usando o Builder
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Usando o Builder para modelos de alteração no Change Manager, uma ferramenta do AWS Systems Manager, é possível configurar o fluxo de trabalho do runbook definido no modelo de alteração, sem precisar usar a sintaxe JSON ou YAML. Depois de especificar suas opções, o sistema converterá sua entrada no formato YAML que o Systems Manager pode usar para executar fluxos de trabalho do runbook.
**Para criar um modelo de alteração usando o Builder**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Manager**.
1. Selecione **Criar modelo**.
1. Para **Name** (Nome), insira um nome para o modelo que facilite a identificação de sua finalidade, como **UpdateEC2LinuxAMI**.
1. Na seção **Change template details** (Detalhes do modelo de alteração), faça o seguinte:
+ Em **Descrição**, forneça uma breve explicação de como e quando o modelo de alteração que você está criando deve ser usado.
Esta descrição ajuda os usuários que criam solicitações de alteração a determinar se estão usando o modelo de alteração correto. Isso ajuda aqueles que revisam solicitações de alteração a entender se a solicitação deve ser aprovada.
+ Para **Change template type** (Alterar tipo de modelo), especifique se você está criando um modelo de alteração padrão ou um modelo de alteração de emergência.
Um modelo de alteração de emergência é usado para situações em que uma alteração deve ser feita, mesmo que as alterações sejam bloqueadas por um evento no calendário em uso pelo AWS Systems Manager Change Calendar. As solicitações de alteração criadas a partir de um modelo de alteração de emergência ainda devem ser aprovadas pelos aprovadores designados, mas as alterações solicitadas ainda podem ser executadas mesmo quando o calendário estiver bloqueado.
+ Para **Runbook options** (Opções do Runbook), especifique os runbooks que os usuários podem escolher ao criar uma solicitação de alteração. Você pode adicionar um único runbook ou vários runbooks. Como alternativa, você pode permitir que os solicitantes especifiquem qual runbook usar. Em qualquer um desses casos, apenas um runbook pode ser incluído na solicitação de alteração.
+ Para **Runbook**, selecione os nomes e as versões dos runbooks que os usuários podem escolher para as solicitações de alteração. Não importa quantos runbooks você adicionar ao modelo de alteração, somente um poderá ser selecionado em cada solicitação de alteração.
Não especifique um runbook se escolher **Any runbook can be used** (Qualquer runbook pode ser usado).
**dica**
Selecione um runbook e uma versão dele e escolha **View** (Exibir) para examinar o conteúdo do runbook na interface de documentos do Systems Manager.
1. Na seção **Template information** (Informações do modelo), use Markdown para inserir informações para usuários que criam solicitações de alteração com esse modelo de alteração. Fornecemos um conjunto de perguntas que você pode incluir para os usuários que criam solicitações de alteração, ou você pode adicionar outras informações e perguntas.
**nota**
Markdown é uma linguagem de marcação, que permite adicionar descrições de documentos no estilo wiki e etapas individuais dentro do documento. Para obter mais informações sobre como usar Markdown, consulte [Usar Markdown na AWS](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html).
Recomendamos fornecer perguntas para que os usuários respondam sobre suas solicitações de alteração para ajudar os aprovadores a decidir se devem ou não conceder cada solicitação de alteração, como listar as etapas manuais necessárias para serem executadas como parte da alteração e um plano de reversão.
**dica**
Alterne entre **Hide preview** (Ocultar visualização) e **Show preview**(Exibir visualização) para ver o conteúdo de descrição à medida que você o cria.
1. Na seção **Change request approvals** (Aprovações de solicitação de alteração), faça o seguinte:
+ (Opcional) Se você quiser permitir que as solicitações de alteração criadas neste modelo de alteração sejam executadas automaticamente, sem revisão por nenhum aprovador (com exceção dos eventos de congelamento de alterações), selecione **Enable auto-approval** (Habilitar aprovação automática).
**nota**
Ativar aprovações automáticas em um modelo de alteração fornece aos usuários a *opção* de ignorar os revisores. Eles ainda podem optar por especificar revisores ao criar uma solicitação de alteração. Portanto, você ainda deve especificar as opções do revisor no modelo de alteração.
**Importante**
Se você ativar a aprovação automática para um modelo de alteração, os usuários poderão enviar solicitações de alteração usando esse modelo que não exige revisão antes de serem executados (com exceção dos aprovadores de eventos de congelamento de alterações). Se você quiser restringir um determinado usuário, grupo ou função do IAM de enviar solicitações de aprovação automática, você poderá usar uma condição em uma política do IAM para essa finalidade. Para obter mais informações, consulte [Controlar o acesso a fluxos de trabalho do runbook de aprovação automática](change-manager-auto-approval-access.md).
+ Em **Número de aprovações requeridas nesse nível**, escolha o número de aprovações que as solicitações de alteração criadas nesse modelo de alteração devem receber para esse nível.
+ Para adicionar aprovadores obrigatórios de primeiro nível, escolha **Add approver** (Adicionar aprovador) e, em seguida, escolha uma das seguintes opções:
+ **Aprovadores especificados pelo modelo**: escolha um ou mais usuários, grupos ou funções do AWS Identity and Access Management (IAM) da sua conta para aprovar solicitações de alteração criadas com este modelo de alteração. Quaisquer solicitações de alteração criadas usando este modelo devem ser revisadas e aprovadas por cada aprovador especificado.
+ **Request specified approvers** (Solicitar aprovadores especificados): o usuário que fizer a solicitação de alteração especificará os revisores no momento em que fizer a solicitação, e poderá escolher em uma lista de usuários da sua conta.
O número que você inserir na coluna **Required** (Obrigatório) determinará quantos revisores devem ser especificados por uma solicitação de alteração que usar esse modelo de alteração.
**Importante**
Antes de 23 de janeiro de 2023, a guia **Builder** oferecia suporte à especificação somente de aprovações por linha. Os novos modelos de alteração e os novos níveis adicionados aos modelos de alteração existentes usando a guia **Builder** oferecem suporte somente a aprovações por nível. Recomendamos usar somente aprovações por nível em suas operações do Change Manager.
Para obter mais informações, consulte [Sobre as aprovações em seus modelos de alteração](cm-approvals-templates.md).
+ Para **SNS topic to notify approvers** (Tópico do SNS para notificar os aprovadores), faça o seguinte:
1. Escolha uma das opções a seguir para especificar o tópico Amazon Simple Notification Service (Amazon SNS) em sua conta a ser usado para enviar notificações aos aprovadores avisando que a solicitação de alteração está pronta para avaliação.
+ **Insira um nome do recurso da Amazon (ARN)** – Para **ARN do tópico**, insira o ARN de um tópico existente do Amazon SNS. Esse tópico pode estar em qualquer uma das contas da sua organização.
+ **Selecione um tópico do SNS existente**: para **Target notification topic** (Tópico de notificação de destino), selecione o ARN de um tópico existente do Amazon SNS em sua Conta da AWS atual. (Essa opção não estará disponível se você ainda não tiver criado nenhum tópico do Amazon SNS na sua Conta da AWS e Região da AWS.)
+ **Especifique o tópico SNS quando a solicitação de alteração for criada**: o usuário que cria uma solicitação de alteração pode especificar o tópico do Amazon SNS a ser usado para as notificações.
**nota**
O tópico do Amazon SNS selecionado deve ser configurado para especificar as notificações que ele envia e os assinantes para os quais eles são enviados. Sua política de acesso também deve conceder permissões ao Systems Manager, para que o Change Manager possa enviar notificações. Para obter mais informações, consulte [Configurar os tópicos do Amazon SNS para as notificações do Change Manager](change-manager-sns-setup.md).
1. Escolha **Adicionar notificação**.
1. (Opcional) Para adicionar outro nível de aprovadores, escolha **Add approval level** (Adicionar nível de aprovação) e escolha entre os aprovadores especificados pelo modelo e os aprovadores especificados pela solicitação para esse nível. Em seguida, escolha um tópico do SNS para notificar esse nível de aprovadores.
Depois de todas as aprovações terem sido recebidas pelos aprovadores de primeiro nível, os aprovadores de segundo nível são notificados, e assim por diante.
Você pode adicionar um máximo de cinco níveis de aprovadores em cada modelo. Você pode, por exemplo, exigir aprovações de usuários em funções técnicas para o primeiro nível e, em seguida, aprovação gerencial para o segundo nível.
1. Na seção **Monitoring** (Monitoramento), para **CloudWatch alarm to monitor** (Alarme do CloudWatch a ser monitorado), insira o nome de um alarme do Amazon CloudWatch na conta atual para monitorar o andamento dos fluxos de trabalho do runbook baseados nesse modelo.
**dica**
Para criar um novo alarme, ou para rever as configurações de um alarme que deseja especificar, escolha **Open the Amazon CloudWatch console** (Abrir o console do Amazon CloudWatch). Para obter informações sobre o trabalho com os alarmes do CloudWatch, consulte [Usar alarmes do CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) no *Guia do usuário do Amazon CloudWatch*.
1. Na seção **Notifications** (Notificações), faça o seguinte:
1. Escolha uma das opções a seguir para especificar o tópico do Amazon SNS em sua conta a ser usado para enviar notificações sobre solicitações de alteração criadas usando este modelo de alteração:
+ **Insira um nome do recurso da Amazon (ARN)** – Para **ARN do tópico**, insira o ARN de um tópico existente do Amazon SNS. Esse tópico pode estar em qualquer uma das contas da sua organização.
+ **Selecione um tópico do SNS existente**: para **Target notification topic** (Tópico de notificação de destino), selecione o ARN de um tópico existente do Amazon SNS em sua Conta da AWS atual. (Essa opção não estará disponível se você ainda não tiver criado nenhum tópico do Amazon SNS na sua Conta da AWS e Região da AWS.)
**nota**
O tópico do Amazon SNS selecionado deve ser configurado para especificar as notificações que ele envia e os assinantes para os quais eles são enviados. Sua política de acesso também deve conceder permissões ao Systems Manager, para que o Change Manager possa enviar notificações. Para obter mais informações, consulte [Configurar os tópicos do Amazon SNS para as notificações do Change Manager](change-manager-sns-setup.md).
1. Escolha **Adicionar notificação**.
1. (Opcional) Na seção **Tags**, aplique um ou mais pares de nome/valor de chave de tag ao modelo de alteração.
Tags são metadados opcionais que você atribui a um recurso. Usando tags, você pode categorizar um recurso de diferentes formas, como por finalidade, proprietário ou ambiente. Por exemplo, você poderá marcar um modelo de alteração para identificar o tipo de alteração que ele faz e o ambiente em que ele é executado. Nesse caso, você pode especificar os seguintes pares de nome/valor:
+ `Key=TaskType,Value=InstanceRepair`
+ `Key=Environment,Value=Production`
1. Selecione **Save and preview** (Salvar e pré-visualizar).
1. Analise os detalhes do modelo de alteração que você estiver criando.
Se você quiser alterar o modelo de alteração antes de enviá-lo para análise, escolha **Actions, Edit** (Ações, Editar).
Se você estiver satisfeito com o conteúdo do modelo de alteração, escolha**Submit for review** (Enviar para análise). Os usuários em sua organização ou conta que foram especificados como revisores de modelo na guia **Settings** (Configurações) do Change Manager serão notificados de que um novo modelo de alteração está com a revisão pendente.
Se um tópico do Amazon SNS tiver sido especificado para modelos de alteração, as notificações serão enviadas quando o modelo de alteração for rejeitado ou aprovado. Se você não receber notificações relacionadas a este modelo de alteração, retorne ao Change Manager mais tarde para verificar seu status.
# Criando modelos de alteração usando o Editor
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Use as etapas neste tópico para configurar um modelo de alteração no Change Manager, uma ferramenta do AWS Systems Manager, inserindo JSON ou YAML em vez de usar os controles do console.
**Para criar um modelo de alteração usando o Editor**
1. No painel de navegação, escolha **Change Manager**.
1. Selecione **Criar modelo**.
1. Para **Name** (Nome), insira um nome para o modelo que facilite a identificação de sua finalidade, como **RestartEC2LinuxInstance**.
1. Acima de **Change template details** (Alterar detalhes do modelo), escolha **Editor**.
1. Na seção **Document editor** (Editor de documentos), selecione **Edit** (Editar) e insira o conteúdo JSON ou YAML para o modelo de alteração.
Veja um exemplo a seguir.
**nota**
O parâmetro `minRequiredApprovals` é usado para especificar quantos revisores em um nível especificado devem aprovar uma solicitação de alteração criada usando esse modelo.
Este exemplo demonstra dois níveis de aprovações. Você pode especificar até cinco níveis de aprovações, mas somente um nível é necessário.
No primeiro nível, o usuário específico "John-Doe" deve aprovar cada solicitação de alteração. Depois disso, quaisquer três membros da função do IAM `Admin` devem aprovar a solicitação de alteração.
Para obter mais informações sobre aprovações para modelos de alteração, consulte [Sobre as aprovações em seus modelos de alteração](cm-approvals-templates.md).
------
#### [ YAML ]
```
description: >-
This change template demonstrates the feature set available for creating
change templates for Change Manager. This template starts a Runbook workflow
for the Automation runbook called AWS-HelloWorld.
templateInformation: >
### Document Name: HelloWorldChangeTemplate
## What does this document do?
This change template demonstrates the feature set available for creating
change templates for Change Manager. This template starts a Runbook workflow
for the Automation runbook called AWS-HelloWorld.
## Input Parameters
* ApproverSnsTopicArn: (Required) Amazon Simple Notification Service ARN for
approvers.
* Approver: (Required) The name of the approver to send this request to.
* ApproverType: (Required) The type of reviewer.
* Allowed Values: IamUser, IamGroup, IamRole, SSOGroup, SSOUser
## Output Parameters
This document has no outputs
schemaVersion: '0.3'
parameters:
ApproverSnsTopicArn:
type: String
description: Amazon Simple Notification Service ARN for approvers.
Approver:
type: String
description: IAM approver
ApproverType:
type: String
description: >-
Approver types for the request. Allowed values include IamUser, IamGroup,
IamRole, SSOGroup, and SSOUser.
executableRunBooks:
- name: AWS-HelloWorld
version: '1'
emergencyChange: false
autoApprovable: false
mainSteps:
- name: ApproveAction1
action: 'aws:approve'
timeoutSeconds: 3600
inputs:
Message: >-
A sample change request has been submitted for your review in Change
Manager. You can approve or reject this request.
EnhancedApprovals:
NotificationArn: '{{ ApproverSnsTopicArn }}'
Approvers:
- approver: John-Doe
type: IamUser
minRequiredApprovals: 1
- name: ApproveAction2
action: 'aws:approve'
timeoutSeconds: 3600
inputs:
Message: >-
A sample change request has been submitted for your review in Change
Manager. You can approve or reject this request.
EnhancedApprovals:
NotificationArn: '{{ ApproverSnsTopicArn }}'
Approvers:
- approver: Admin
type: IamRole
minRequiredApprovals: 3
```
------
#### [ JSON ]
```
{
"description": "This change template demonstrates the feature set available for creating
change templates for Change Manager. This template starts a Runbook workflow
for the Automation runbook called AWS-HelloWorld",
"templateInformation": "### Document Name: HelloWorldChangeTemplate\n\n
## What does this document do?\n
This change template demonstrates the feature set available for creating change templates for Change Manager.
This template starts a Runbook workflow for the Automation runbook called AWS-HelloWorld.\n\n
## Input Parameters\n* ApproverSnsTopicArn: (Required) Amazon Simple Notification Service ARN for approvers.\n
* Approver: (Required) The name of the approver to send this request to.\n
* ApproverType: (Required) The type of reviewer. * Allowed Values: IamUser, IamGroup, IamRole, SSOGroup, SSOUser\n\n
## Output Parameters\nThis document has no outputs\n",
"schemaVersion": "0.3",
"parameters": {
"ApproverSnsTopicArn": {
"type": "String",
"description": "Amazon Simple Notification Service ARN for approvers."
},
"Approver": {
"type": "String",
"description": "IAM approver"
},
"ApproverType": {
"type": "String",
"description": "Approver types for the request. Allowed values include IamUser, IamGroup, IamRole, SSOGroup, and SSOUser."
}
},
"executableRunBooks": [
{
"name": "AWS-HelloWorld",
"version": "1"
}
],
"emergencyChange": false,
"autoApprovable": false,
"mainSteps": [
{
"name": "ApproveAction1",
"action": "aws:approve",
"timeoutSeconds": 3600,
"inputs": {
"Message": "A sample change request has been submitted for your review in Change Manager. You can approve or reject this request.",
"EnhancedApprovals": {
"NotificationArn": "{{ ApproverSnsTopicArn }}",
"Approvers": [
{
"approver": "John-Doe",
"type": "IamUser",
"minRequiredApprovals": 1
}
]
}
}
},
{
"name": "ApproveAction2",
"action": "aws:approve",
"timeoutSeconds": 3600,
"inputs": {
"Message": "A sample change request has been submitted for your review in Change Manager. You can approve or reject this request.",
"EnhancedApprovals": {
"NotificationArn": "{{ ApproverSnsTopicArn }}",
"Approvers": [
{
"approver": "Admin",
"type": "IamRole",
"minRequiredApprovals": 3
}
]
}
}
}
]
}
```
------
1. Selecione **Save and preview** (Salvar e pré-visualizar).
1. Analise os detalhes do modelo de alteração que você estiver criando.
Se você quiser alterar o modelo de alteração antes de enviá-lo para análise, escolha **Actions, Edit** (Ações, Editar).
Se você estiver satisfeito com o conteúdo do modelo de alteração, escolha**Submit for review** (Enviar para análise). Os usuários em sua organização ou conta que foram especificados como revisores de modelo na guia **Settings** (Configurações) do Change Manager serão notificados de que um novo modelo de alteração está com a revisão pendente.
Se um tópico do Amazon Simple Notification Service (Amazon SNS) tiver sido especificado para modelos de alteração, as notificações serão enviadas quando o modelo de alteração for rejeitado ou aprovado. Se você não receber notificações relacionadas a este modelo de alteração, retorne ao Change Manager mais tarde para verificar seu status.
# Criar modelos de alteração usando ferramentas de linha de comando
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Os procedimentos a seguir descrevem como usar o AWS Command Line Interface (AWS CLI) (no Linux,macOS ou Windows Server) ou o AWS Tools for Windows PowerShell para criar uma solicitação de alteração no Change Manager, uma ferramenta do AWS Systems Manager.
**Para criar um novo modelo de alteração**
1. Instale e configure a AWS CLI ou o Ferramentas da AWS para PowerShell, caso ainda não o tenha feito.
Para obter informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) e [Instalar o Ferramentas da AWS para PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
1. Crie um arquivo JSON em sua máquina local com um nome, como `MyChangeTemplate.json` e, em seguida, cole o conteúdo do modelo de alteração nesse arquivo.
**nota**
Os modelos de alteração usam uma versão do esquema 0.3 que não inclui o mesmo suporte dos runbooks do Automation.
Veja um exemplo a seguir.
**nota**
O parâmetro `minRequiredApprovals` é usado para especificar quantos revisores em um nível especificado devem aprovar uma solicitação de alteração criada usando esse modelo.
Este exemplo demonstra dois níveis de aprovações. Você pode especificar até cinco níveis de aprovações, mas somente um nível é necessário.
No primeiro nível, o usuário específico "John-Doe" deve aprovar cada solicitação de alteração. Depois disso, quaisquer três membros da função do IAM `Admin` devem aprovar a solicitação de alteração.
Para obter mais informações sobre aprovações para modelos de alteração, consulte [Sobre as aprovações em seus modelos de alteração](cm-approvals-templates.md).
```
{
"description": "This change template demonstrates the feature set available for creating
change templates for Change Manager. This template starts a Runbook workflow
for the Automation runbook called AWS-HelloWorld",
"templateInformation": "### Document Name: HelloWorldChangeTemplate\n\n
## What does this document do?\n
This change template demonstrates the feature set available for creating change templates for Change Manager.
This template starts a Runbook workflow for the Automation runbook called AWS-HelloWorld.\n\n
## Input Parameters\n* ApproverSnsTopicArn: (Required) Amazon Simple Notification Service ARN for approvers.\n
* Approver: (Required) The name of the approver to send this request to.\n
* ApproverType: (Required) The type of reviewer. * Allowed Values: IamUser, IamGroup, IamRole, SSOGroup, SSOUser\n\n
## Output Parameters\nThis document has no outputs\n",
"schemaVersion": "0.3",
"parameters": {
"ApproverSnsTopicArn": {
"type": "String",
"description": "Amazon Simple Notification Service ARN for approvers."
},
"Approver": {
"type": "String",
"description": "IAM approver"
},
"ApproverType": {
"type": "String",
"description": "Approver types for the request. Allowed values include IamUser, IamGroup, IamRole, SSOGroup, and SSOUser."
}
},
"executableRunBooks": [
{
"name": "AWS-HelloWorld",
"version": "1"
}
],
"emergencyChange": false,
"autoApprovable": false,
"mainSteps": [
{
"name": "ApproveAction1",
"action": "aws:approve",
"timeoutSeconds": 3600,
"inputs": {
"Message": "A sample change request has been submitted for your review in Change Manager. You can approve or reject this request.",
"EnhancedApprovals": {
"NotificationArn": "{{ ApproverSnsTopicArn }}",
"Approvers": [
{
"approver": "John-Doe",
"type": "IamUser",
"minRequiredApprovals": 1
}
]
}
}
},
{
"name": "ApproveAction2",
"action": "aws:approve",
"timeoutSeconds": 3600,
"inputs": {
"Message": "A sample change request has been submitted for your review in Change Manager. You can approve or reject this request.",
"EnhancedApprovals": {
"NotificationArn": "{{ ApproverSnsTopicArn }}",
"Approvers": [
{
"approver": "Admin",
"type": "IamRole",
"minRequiredApprovals": 3
}
]
}
}
}
]
}
```
1. Execute o comando a seguir para criar o modelo de alteração.
------
#### [ Linux & macOS ]
```
aws ssm create-document \
--name MyChangeTemplate \
--document-format JSON \
--document-type Automation.ChangeTemplate \
--content file://MyChangeTemplate.json \
--tags Key=tag-key,Value=tag-value
```
------
#### [ Windows ]
```
aws ssm create-document ^
--name MyChangeTemplate ^
--document-format JSON ^
--document-type Automation.ChangeTemplate ^
--content file://MyChangeTemplate.json ^
--tags Key=tag-key,Value=tag-value
```
------
#### [ PowerShell ]
```
$json = Get-Content -Path "C:\path\to\file\MyChangeTemplate.json" | Out-String
New-SSMDocument `
-Content $json `
-Name "MyChangeTemplate" `
-DocumentType "Automation.ChangeTemplate" `
-Tags "Key=tag-key,Value=tag-value"
```
------
Para obter informações sobre outras opções que você pode especificar, consulte [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-document.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-document.html).
O sistema retorna informações como estas.
```
{
"DocumentDescription":{
"CreatedDate":1.585061751738E9,
"DefaultVersion":"1",
"Description":"Use this template to update an EC2 Linux AMI. Requires one
approver specified in the template and an approver specified in the request.",
"DocumentFormat":"JSON",
"DocumentType":"Automation",
"DocumentVersion":"1",
"Hash":"0d3d879b3ca072e03c12638d0255ebd004d2c65bd318f8354fcde820dEXAMPLE",
"HashType":"Sha256",
"LatestVersion":"1",
"Name":"MyChangeTemplate",
"Owner":"123456789012",
"Parameters":[
{
"DefaultValue":"",
"Description":"Level one approvers",
"Name":"LevelOneApprovers",
"Type":"String"
},
{
"DefaultValue":"",
"Description":"Level one approver type",
"Name":"LevelOneApproverType",
"Type":"String"
},
"cloudWatchMonitors": {
"monitors": [
"my-cloudwatch-alarm"
]
}
],
"PlatformTypes":[
"Windows",
"Linux"
],
"SchemaVersion":"0.3",
"Status":"Creating",
"Tags":[
]
}
}
```
Os usuários em sua organização ou conta que foram especificados como revisores de modelo na guia **Settings** (Configurações) do Change Manager serão notificados de que um novo modelo de alteração está com a revisão pendente.
Se um tópico do Amazon Simple Notification Service (Amazon SNS) tiver sido especificado para modelos de alteração, as notificações serão enviadas quando o modelo de alteração for rejeitado ou aprovado. Se você não receber notificações relacionadas a este modelo de alteração, retorne ao Change Manager mais tarde para verificar seu status.
# Revisar e aprovar ou rejeitar solicitações de alteração (modelos)
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Se você foi designado como revisor para modelos de alteração no Change Manager, uma ferramenta do AWS Systems Manager, você será notificado quando um novo modelo de alteração, ou uma nova versão de um modelo de alteração, estiver aguardando sua revisão. Um tópico de um Amazon Simple Notification Service (Amazon SNS) envia as notificações.
**nota**
Essa funcionalidade depende da conta ser configurada para usar um tópico do Amazon SNS para enviar notificações sobre a revisão do modelo de alteração. Para obter informações sobre como especificar um tópico de notificação do avaliador de modelos, consulte [Tarefa 1: Configurar o gerenciamento de identidade de usuário e revisores de modelo do Change Manager](change-manager-account-setup.md#cm-configure-account-task-1).
Para revisar o modelo de alteração, você pode seguir o link em sua notificação ou entrar no Console de gerenciamento da AWS diretamente e executar as etapas deste procedimento.
**Para revisar e aprovar ou rejeitar um modelo de alteração**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Manager**.
1. Na seção **Change templates** (Modelos de alterações), na parte inferior da guia **Overview** (Visão geral), selecione o número em **Pending review** (Análise pendente).
1. Na lista **Change templates** (Modelos de alterações), localize e escolha o nome do modelo de alteração a ser analisado.
1. Na página de resumo, revise o conteúdo proposto do modelo de alteração e siga um destes procedimentos:
+ Para aprovar o modelo de alteração, que permite que ele seja usado em solicitações de alteração, escolha **Approve** (Aprovar).
+ Para rejeitar o modelo de alteração, o que impedirá que ele seja usado em solicitações de alteração, escolha **Reject ** (Rejeitar).
# Excluir modelos de alteração
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Este tópico descreve como excluir modelos que você criou no Change Manager, uma ferramenta do Systems Manager. Se você estiver usando o Change Manager para uma organização, esse procedimento é executado em sua conta de administrador delegado.
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Manager**.
1. Escolha a guia **Modelos**.
1. Escolha o nome do modelo a ser excluído.
1. Escolha **Actions (Ações), Delete template (Excluir modelo)**.
1. Na caixa de diálogo de confirmação, insira **DELETE** e selecione **Delete** (Excluir).
# Trabalhar com solicitações de alteração
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Uma solicitação de alteração é uma solicitação no Change Manager para executar um runbook do Automation que atualiza um ou mais recursos na AWS ou em ambientes on-premises. Uma solicitação de alteração é criada usando um modelo de alteração.
Quando você cria uma solicitação de alteração no Change Manager, uma ferramenta do AWS Systems Manager, um ou mais aprovadores em sua organização ou conta devem revisar e aprovar a solicitação. Sem as aprovações necessárias, o fluxo de trabalho do runbook, que faz as alterações solicitadas, não tem permissão para ser executado.
**Topics**
+ [Criar solicitações de alteração](change-requests-create.md)
+ [Revisar e aprovar ou rejeitar solicitações de alteração](change-requests-review.md)
# Criar solicitações de alteração
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Quando você cria uma solicitação de alteração no Change Manager, uma ferramenta do AWS Systems Manager, o modelo de alteração selecionado normalmente faz o seguinte:
+ Designa aprovadores para a solicitação de alteração ou especifica quantas aprovações são necessárias
+ Especifica o tópico do Amazon Simple Notification Service (Amazon SNS) a ser usado para notificar os aprovadores sobre a solicitação de alteração
+ Especifica um alarme do Amazon CloudWatch para monitorar o fluxo de trabalho do runbook para a solicitação de alteração
+ Identifica quais runbooks do Automation você pode escolher para fazer a alteração solicitada
Em alguns casos, um modelo de alteração pode ser configurado para que você especifique seu próprio runbook do Automation a ser usado e para especificar quem deve revisar e aprovar a solicitação.
**Importante**
Se você usar o Change Manager em uma organização, recomendamos sempre fazer as alterações na conta de administrador delegado. Embora seja possível fazer alterações de outras contas na organização, essas alterações não serão relatadas ou visíveis na conta do administrador delegado.
**Topics**
+ [Sobre as aprovações de solicitação de alteração](#cm-approvals-requests)
+ [Criar solicitações de alteração (console)](#change-requests-create-console)
+ [Criar solicitações de alteração (AWS CLI)](#change-requests-create-cli)
## Sobre as aprovações de solicitação de alteração
Dependendo dos requisitos especificados em um modelo de alteração, as solicitações de alteração criadas nele podem requerer aprovações de até cinco *níveis* antes que o fluxo de trabalho do runbook para a solicitação possa ocorrer. Para cada um desses níveis, o criador do modelo poderá especificar até cinco possíveis *aprovadores*. Um aprovador não está limitado a um único usuário. Nesse sentido, um aprovador também pode ser um grupo do IAM ou um perfil do IAM. Para grupos do IAM e perfis do IAM, um ou mais usuários pertencentes ao grupo ou perfil podem fornecer aprovações para receber o número total de aprovações requeridas para uma solicitação de alteração. Os criadores do modelo também poderão especificar mais aprovadores do que o requerido pelo modelo de alteração.
**Fluxos de trabalho de aprovação originais e atualizados e/ou aprovações**
Ao usar modelos de alteração criados antes de 23 de janeiro de 2023, uma aprovação deve ser recebida de cada aprovador especificado para que a solicitação de alteração seja aprovada nesse nível. Por exemplo, na configuração do nível de aprovação mostrada na imagem a seguir, quatro aprovadores estão especificados. Os aprovadores especificados incluem dois usuários (John Stiles e Ana Carolina Silva), um grupo de usuários que contém três membros (GroupOfThree) e um perfil de usuário que representa dez usuários (RoleOfTen).
![\[Nível de aprovação apresentando quatro aprovadores requeridos por linha.\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/Add-approval-1.png)
Para que a solicitação de alteração seja aprovada nesse nível, ela deve ser aprovada por John Stiles, Ana Carolina Silva, um membro do grupo `GroupOfThree` e um membro do perfil `RoleOfTen`.
Ao usar modelos de alteração criados em ou após 23 de janeiro de 2023, para cada nível de aprovação, os criadores de modelos poderão especificar um número total geral de aprovações requeridas. Essas aprovações poderão ser originadas de qualquer combinação de usuários, grupos e perfis especificados como aprovadores. Um modelo de alteração pode requerer somente uma aprovação para um nível, mas especificar, por exemplo, dois usuários individuais, dois grupos e um perfil como possíveis aprovadores.
Por exemplo, na área do nível de aprovação mostrada na imagem a seguir, são requeridas três aprovações. Os aprovadores especificados pelo modelo incluem dois usuários (John Stiles e Ana Carolina Silva), um grupo de usuários que contém três membros (`GroupOfThree`) e um perfil de usuário que representa dez usuários (`RoleOfTen`).
![\[Nível de aprovação apresentando três aprovações requeridas e quatro aprovadores especificados.\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/Add-approval-2.png)
Se todos os três usuários do grupo `GroupOfThree` aprovarem a sua solicitação de alteração, ela será aprovada para esse nível. Não é necessário receber uma aprovação de cada usuário, grupo ou perfil. O número mínimo de aprovações pode ser originado de qualquer combinação de possíveis aprovadores.
Quando a solicitação de alteração é criada, as notificações são enviadas aos assinantes do tópico do Amazon SNS que foi especificado para notificações de aprovação nesse nível. É possível que o criador do modelo de alteração tenha especificado o tópico de notificação que deve ser usado ou permitido que você o especificasse.
Após o número mínimo de aprovações requeridas ser recebido em um nível, as notificações serão enviadas aos aprovadores inscritos no tópico do Amazon SNS para o próximo nível, e assim sucessivamente.
Não importa quantos níveis de aprovação e aprovadores estejam especificados, somente uma rejeição a uma solicitação de alteração é requerida para evitar que o fluxo de trabalho do runbook para essa solicitação ocorra.
## Criar solicitações de alteração (console)
O procedimento a seguir descreve como criar uma solicitação de alteração usando o console do Systems Manager.
**Para criar uma solicitação de alteração (console)**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Manager**.
1. Selecione **Create request** (Criar solicitação).
1. Pesquise e selecione um modelo de alteração que você deseja usar para essa solicitação de alteração.
1. Escolha **Próximo**.
1. Para **Name** (Nome), insira um nome para a solicitação de alteração que facilite a identificação de sua finalidade, como **UpdateEC2LinuxAMI-us-east-2**.
1. Para **Runbook**, selecione o runbook que quiser usar para fazer a alteração solicitada.
**nota**
Se a opção para selecionar um runbook não estiver disponível, o autor do modelo de alteração especificou qual runbook deve ser usado.
1. Para **Change request information** (Alterar as informações da solicitação), use Markdown para fornecer informações adicionais sobre a solicitação de alteração para ajudar os revisores a decidir se devem aprovar ou rejeitar a solicitação de alteração. O autor do modelo que você está usando pode ter fornecido instruções ou perguntas para você responder.
**nota**
Markdown é uma linguagem de marcação, que permite adicionar descrições de documentos no estilo wiki e etapas individuais dentro do documento. Para obter mais informações sobre como usar Markdown, consulte [Usar Markdown na AWS](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html).
1. Na seção **Workflow start time** (Horário de início do fluxo de trabalho), escolha uma das seguintes opções:
+ **Execute a operação em um horário agendado**: para **Requested start time** (Horário de início solicitado), insira a data e a hora proposta para executar o fluxo de trabalho do runbook para esta solicitação. Para **Estimated end time** (Hora estimada para o término), insira a data e a hora em que você espera que o fluxo de trabalho do runbook seja concluído. (Esse tempo é apenas uma estimativa que você fornece aos revisores).
**dica**
Selecione**View Change Calendar** (Exibir o calendário de alterações) para verificar se há eventos de bloqueio para o tempo especificado.
+ **Execute a operação o mais rápido possível após a aprovação**: se a solicitação de alteração for aprovada, o fluxo de trabalho do runbook será executado assim que houver um período sem restrições no qual as alterações podem ser feitas.
1. Na seção **Change request approvals** (Aprovações de solicitação de alteração), faça o seguinte:
1. Se as opções de **Approval type** (Tipo de aprovação) forem apresentadas, escolha uma das seguintes opções:
+ **Aprovação automática**: o modelo de alteração selecionado é configurado para permitir que as solicitações de alteração sejam executadas automaticamente sem revisão por nenhum aprovador. Continue na etapa 11.
**nota**
As permissões especificadas nas políticas do IAM que regem seu uso do Systems Manager não devem restringir o envio de solicitações de alteração de aprovação automática para que elas sejam executadas automaticamente.
+ **Especifique os aprovadores**: você deve adicionar um ou mais usuários, grupos ou funções do IAM para revisar e aprovar essa solicitação de alteração.
**nota**
Você pode optar por especificar revisores mesmo que as permissões especificadas nas políticas do IAM que regem seu uso do Systems Manager permitam que você execute solicitações de alteração de aprovação automática.
1. Escolha **Add approver** (Adicionar aprovador) e selecione um ou mais usuários, grupos ou funções do AWS Identity and Access Management (IAM) nas listas de revisores disponíveis.
**nota**
Um ou mais aprovadores já podem estar especificados. Isso significa que os aprovadores obrigatórios já estão especificados no modelo de alteração selecionado. Não é possível remover esses aprovadores da solicitação. Se o botão **Adicionar aprovador** não estiver disponível, o modelo escolhido não permitirá que revisores adicionais sejam adicionados às solicitações.
Para obter mais informações sobre aprovações para solicitações de alteração, consulte [Sobre as aprovações de solicitação de alteração](#cm-approvals-requests).
1. Em **SNS topic to notify approvers** (Tópico do SNS para notificar aprovadores), escolha uma das opções a seguir para especificar o tópico do Amazon SNS em sua conta a ser usado para enviar notificações aos aprovadores que você estiver adicionando a essa solicitação de alteração.
**nota**
Se a opção para especificar um tópico do Amazon SNS não estiver disponível, o modelo de alteração selecionado já especificará o tópico do Amazon SNS a ser usado.
+ **Insira um nome do recurso da Amazon (ARN)** – Para **ARN do tópico**, insira o ARN de um tópico existente do Amazon SNS. Esse tópico pode estar em qualquer uma das contas da sua organização.
+ **Selecione um tópico do SNS existente**: para **Target notification topic** (Tópico de notificação de destino), selecione o ARN de um tópico existente do Amazon SNS em sua conta atual. (Essa opção não estará disponível se você ainda não tiver criado nenhum tópico do Amazon SNS na sua Conta da AWS e Região da AWS.)
**nota**
O tópico do Amazon SNS selecionado deve ser configurado para especificar as notificações que ele envia e os assinantes para os quais eles são enviados. Sua política de acesso também deve conceder permissões ao Systems Manager, para que o Change Manager possa enviar notificações. Para obter mais informações, consulte [Configurar os tópicos do Amazon SNS para as notificações do Change Manager](change-manager-sns-setup.md).
1. Escolha **Adicionar notificação**.
1. Escolha **Próximo**.
1. Para **IAM role** (Função do IAM), selecione uma função do IAM *na sua conta atual* que tenha as permissões necessárias para executar os runbooks especificados para esta solicitação de alteração.
Essa função também é referida como a função de serviço, ou função assumida, para o Automation. Para obter mais informações sobre esse perfil, consulte [Configurar a automação](automation-setup.md).
1. Na seção **Deployment location** (Local de implantação), escolha uma das seguintes opções:
**nota**
Se você estiver usando o Change Manager com uma única Conta da AWS e não com uma organização configurada no AWS Organizations, você não precisará especificar um local de implantação.
+ **Aplique alterações a esta conta**. O fluxo de trabalho do runbook é executado somente na conta atual. Para uma organização, isso significa a conta de administrador delegado.
+ **Aplique alterações a várias unidades organizacionais (UOs)**. Faça o seguinte:
1. Para **Accounts and organizational units (OUs)** (Contas e unidades organizacionais, UOs), insira o ID de uma conta de membro em sua organização, no formato **123456789012** ou o ID de uma unidade organizacional, no formato **o-o96EXAMPLE**.
1. (Opcional) Em **Execution role name** (Nome da função de execução), insira o nome da função do IAM *na conta de destino* ou a UO que tiver as permissões necessárias para executar os runbooks especificados para esta solicitação de alteração. Todas as contas em qualquer UO que você especificar devem usar o mesmo nome para essa função.
1. (Opcional) Escolha **Add another target location** (Adicionar outro local de destino) para cada conta adicional ou UO que você deseja especificar e repita as etapas A e B.
1. Em Target ** (Região da AWS** de destino), selecione a região na qual fazer a alteração, como `Ohio (us-east-2)` para a região Leste dos EUA (Ohio).
1. Expanda **Rate control** (Controle de taxa).
Para **Concurrency** (Simultaneidade), insira um número e, na lista, selecione se isso representa o número ou porcentagem de contas em que o fluxo de trabalho do runbook pode ser executado ao mesmo tempo.
Em **Error threshold** (Limite de erro), insira um número e, na lista, selecione se isso representa o número ou porcentagem de contas em que o fluxo de trabalho do runbook pode falhar antes que a operação seja interrompida.
1. Na seção **Deployment targets** (Destinos das implantações), faça o seguinte:
1. Escolha uma das seguintes opções:
+ **Recurso único**: a alteração deve ser feita para apenas um recurso. Por exemplo, um único nó ou uma única Amazon Machine Image (AMI), dependendo da operação definida nos runbooks para essa solicitação de alteração.
+ **Vários recursos**: para **Parameter** (Parâmetro), selecione um dos parâmetros disponíveis nos runbooks para essa solicitação de alteração. Essa seleção reflete o tipo de recurso que está sendo atualizado.
Por exemplo, se o runbook para esta solicitação de alteração for `AWS-RetartEC2Instance`, você poderá escolher `InstanceId` e, em seguida, definir quais instâncias serão atualizadas selecionando uma das seguintes opções:
+ **Especifique as tags**: insira um par chave-valor com o qual todos os recursos a serem atualizados serão marcados.
+ **Escolha um grupo de recursos**: escolha o nome do grupo de recursos ao qual todos os recursos a serem atualizados pertencem.
+ **Especifique valores do parâmetro**: identifique os recursos a serem atualizados na seção **Parâmetros do runbook**.
+ **Selecione todas as instâncias como destino**: faça a alteração em todos os nós gerenciados nos locais de destino.
1. Se você escolheu **Multiple resources** (Vários recursos), expanda **Rate control** (Controle de taxa).
Para **Concurrency** (Simultaneidade), insira um número e, na lista, selecione se isso representa o número ou porcentagem de destinos nos quais o fluxo de trabalho do runbook pode ser atualizado ao mesmo tempo.
Em **Error threshold** (Limite de erros), insira um número e, na lista, selecione se isso representa o número ou a porcentagem de destinos onde a atualização pode falhar antes que a operação seja interrompida.
1. Se você escolheu **Specify parameter values** (Especificar valores de parâmetro) para atualizar vários recursos na etapa anterior: na seção **Runbook parameters** (Parâmetros do runbook), especifique valores para os parâmetros de entrada necessários. Os valores de parâmetro que você deve fornecer são baseados no conteúdo dos runbooks do Automation associados ao modelo de alteração escolhido.
Por exemplo, se o modelo de alteração usar o runbook do `AWS-RetartEC2Instance`, você deverá inserir um ou mais IDs de instância para o parâmetro **InstanceId**. Como alternativa, selecione **Show interactive instance picker** (Mostrar o seletor de instâncias interativas) e selecione as instâncias disponíveis uma a uma.
1. Escolha **Próximo**.
1. Na página **Review and submit** (Analise e envie), verifique novamente os recursos e as opções que você especificou para esta solicitação de alteração.
Selecione o botão **Edit** (Editar) para qualquer seção na qual você deseja fazer alterações.
Quando estiver satisfeito com os detalhes da solicitação de alteração, escolha**Submit for approval** (Enviar para aprovação).
Se um tópico do Amazon SNS foi especificado no modelo de alteração escolhido para a solicitação, as notificações são enviadas quando a solicitação for rejeitada ou aprovada. Se você não receber notificações para a solicitação, retorne ao Change Manager para verificar o status da sua solicitação.
## Criar solicitações de alteração (AWS CLI)
Você pode criar uma solicitação de alteração usando o AWS Command Line Interface (AWS CLI) especificando opções e parâmetros para a solicitação de alteração em um arquivo JSON e usando o comando `--cli-input-json` para incluí-la em seu comando.
**Para criar uma solicitação de alteração (AWS CLI)**
1. Instale e configure a AWS CLI ou o Ferramentas da AWS para PowerShell, caso ainda não o tenha feito.
Para obter informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) e [Instalar o Ferramentas da AWS para PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
1. Crie um arquivo JSON em sua máquina local com um nome, como `MyChangeRequest.json` e cole o seguinte conteúdo nesse arquivo:
Substitua os *espaços reservados* pelos valores da solicitação de alteração.
**nota**
Esse JSON de exemplo cria uma solicitação de alteração usando o modelo de alteração `AWS-HelloWorldChangeTemplate` e o runbook `AWS-HelloWorld`. Para ajudar você a adaptar esse exemplo para as suas próprias solicitações de alteração, consulte [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartChangeRequestExecution.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartChangeRequestExecution.html) na *AWS Systems Manager API Reference* para obter informações sobre todos os parâmetros disponíveis
Para obter mais informações sobre aprovações para solicitações de alteração, consulte [Sobre as aprovações de solicitação de alteração](#cm-approvals-requests).
```
{
"ChangeRequestName": "MyChangeRequest",
"DocumentName": "AWS-HelloWorldChangeTemplate",
"DocumentVersion": "$DEFAULT",
"ScheduledTime": "2021-12-30T03:00:00",
"ScheduledEndTime": "2021-12-30T03:05:00",
"Tags": [
{
"Key": "Purpose",
"Value": "Testing"
}
],
"Parameters": {
"Approver": [
"JohnDoe"
],
"ApproverType": [
"IamUser"
],
"ApproverSnsTopicArn": [
"arn:aws:sns:us-east-2:123456789012:MyNotificationTopic"
]
},
"Runbooks": [
{
"DocumentName": "AWS-HelloWorld",
"DocumentVersion": "1",
"MaxConcurrency": "1",
"MaxErrors": "1",
"Parameters": {
"AutomationAssumeRole": [
"arn:aws:iam::123456789012:role/MyChangeManagerAssumeRole"
]
}
}
],
"ChangeDetails": "### Document Name: HelloWorldChangeTemplate\n\n## What does this document do?\nThis change template demonstrates the feature set available for creating change templates for Change Manager. This template starts a Runbook workflow for the Automation document called AWS-HelloWorld.\n\n## Input Parameters\n* ApproverSnsTopicArn: (Required) Amazon Simple Notification Service ARN for approvers.\n* Approver: (Required) The name of the approver to send this request to.\n* ApproverType: (Required) The type of reviewer.\n * Allowed Values: IamUser, IamGroup, IamRole, SSOGroup, SSOUser\n\n## Output Parameters\nThis document has no outputs \n"
}
```
1. No diretório em que você criou o arquivo JSON, execute o seguinte comando:
```
aws ssm start-change-request-execution --cli-input-json file://MyChangeRequest.json
```
O sistema retorna informações como estas.
```
{
"AutomationExecutionId": "b3c1357a-5756-4839-8617-2d2a4EXAMPLE"
}
```
# Revisar e aprovar ou rejeitar solicitações de alteração
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Se estiver designado como revisor para uma solicitação de alteração no Change Manager, uma ferramenta do AWS Systems Manager, você será notificado por meio de um tópico do Amazon Simple Notification Service (Amazon SNS) quando uma nova solicitação de alteração estiver aguardando sua análise.
**nota**
Essa funcionalidade depende de um Amazon SNS estar especificado no modelo de alteração para enviar notificações de revisão. Para mais informações, consulte [Configurar os tópicos do Amazon SNS para as notificações do Change Manager](change-manager-sns-setup.md).
Para revisar a solicitação de alteração, você pode seguir o link em sua notificação ou entrar no Console de gerenciamento da AWS diretamente e executar as etapas deste procedimento.
**nota**
Se um tópico do Amazon SNS for atribuído aos revisores em um modelo de alteração, as notificações serão enviadas aos assinantes do tópico quando a solicitação de alteração alterar o status.
Para obter mais informações sobre aprovações para solicitações de alteração, consulte [Sobre as aprovações de solicitação de alteração](change-requests-create.md#cm-approvals-requests).
## Revisar e aprovar ou rejeitar solicitações de alteração (console)
Os procedimentos a seguir descrevem como usar o console do Systems Manager (Gerenciador de sistemas) para revisar e aprovar ou rejeitar solicitações de mudança.
**Para revisar e aprovar ou rejeitar uma única solicitação de alteração**
1. Abra o link na notificação por e-mail que você recebeu e entre no Console de gerenciamento da AWS, que o direcionará para a avaliação da solicitação de alteração.
1. Na página de resumo, revise o conteúdo proposto da solicitação de alteração.
Para aprovar a solicitação de alteração, escolha **Approve** (Aprovar). Na caixa de diálogo, forneça os comentários que você deseja adicionar para essa aprovação e escolha **Approve** (Aprovar). O fluxo de trabalho do runbook representado por essa solicitação começa a ser executado quando agendado ou assim que as alterações não estiverem bloqueadas por nenhuma restrição.
- ou -
Para rejeitar a solicitação de alteração, escolha **Reject** (Rejeitar). Na caixa de diálogo, forneça os comentários que você deseja adicionar para essa rejeição e escolha **Reject** (Rejeitar).
**Para revisar e aprovar ou rejeitar solicitações de alteração em massa**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Change Manager**.
1. Escolha a guia **Approvals (Aprovações)**.
1. (Opcional) Revise os detalhes das solicitações pendentes de sua aprovação escolhendo o nome de cada solicitação e, em seguida, retorne à guia **Approvals (Aprovações)**.
1. Marque a caixa de seleção de cada solicitação de alteração que você deseja aprovar.
- ou -
Marque a caixa de seleção de cada solicitação de alteração que você deseja rejeitar.
1. Na caixa de diálogo, forneça os comentários que deseja adicionar para esta aprovação ou rejeição.
1. Dependendo se você está aprovando ou rejeitando as solicitações de alteração selecionadas, escolha **Aprovar** ou **Rejeitar**.
## Revisar e aprovar ou rejeitar uma solicitação de alteração (linha de comando)
O procedimento a seguir descreve como usar o AWS Command Line Interface (AWS CLI) (no Linux, macOS ou Windows Server) para analisar e aprovar ou rejeitar uma solicitação de alteração.
**Para revisar e aprovar ou rejeitar as solicitações de alteração**
1. Instale e configure a AWS Command Line Interface (AWS CLI), caso ainda não o tenha feito.
Para obter informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
1. Crie um arquivo JSON em sua máquina local que especifique os parâmetros para a chamada da AWS CLI.
```
{
"OpsItemFilters":
[
{
"Key": "OpsItemType",
"Values": ["/aws/changerequest"],
"Operator": "Equal"
}
],
"MaxResults": number
}
```
Você pode filtrar os resultados de um aprovador específico, determinando o Amazon Resource Name (ARN) do aprovador no arquivo JSON. Aqui está um exemplo.
```
{
"OpsItemFilters":
[
{
"Key": "OpsItemType",
"Values": ["/aws/changerequest"],
"Operator": "Equal"
},
{
"Key": "ChangeRequestByApproverArn",
"Values": ["arn:aws:iam::account-id:user/user-name"],
"Operator": "Equal"
}
],
"MaxResults": number
}
```
1. Execute o comando a seguir para visualizar o número máximo de solicitações de alteração especificadas no arquivo JSON.
------
#### [ Linux & macOS ]
```
aws ssm describe-ops-items \
--cli-input-json file://filename.json
```
------
#### [ Windows ]
```
aws ssm describe-ops-items ^
--cli-input-json file://filename.json
```
------
1. Execute o comando a seguir para aprovar ou rejeitar uma solicitação de alteração.
------
#### [ Linux & macOS ]
```
aws ssm send-automation-signal \
--automation-execution-id ID \
--signal-type Approve_or_Reject \
--payload Comment="message"
```
------
#### [ Windows ]
```
aws ssm send-automation-signal ^
--automation-execution-id ID ^
--signal-type Approve_or_Reject ^
--payload Comment="message"
```
------
Se um tópico do Amazon SNS tiver sido especificado no modelo de alteração escolhido para a solicitação, as notificações serão enviadas quando a solicitação for rejeitada ou aprovada. Se você não receber notificações para a solicitação, retorne ao Change Manager para verificar o status da sua solicitação. Para obter informações sobre outras opções ao usar esse comando, consulte [https://docs.aws.amazon.com/cli/latest/reference/ssm/send-automation-signal.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-automation-signal.html) na seção AWS Systems Manager da *AWS CLI Command Reference*.
# Revisar detalhes, tarefas e cronogramas das solicitações de alteração (console)
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Você pode visualizar informações sobre uma solicitação de alteração, incluindo solicitações para as quais as alterações foram processadas, no painel do Change Manager, uma ferramenta do AWS Systems Manager. Esses detalhes incluem um link para a operação do Automation, que executa os runbooks que fazem a alteração. Um ID de execução do Automation é gerado quando a solicitação é criada, mas o processo não é executado até que todas as aprovações tenham sido fornecidas e não haja restrições para bloquear a alteração.
**Para revisar detalhes, tarefas e cronogramas das solicitações de alteração**
1. No painel de navegação, escolha **Change Manager**.
1. Selecione a guia **Requests** (Solicitações).
1. Na seção **Change requests** (Solicitações de alteração), procure a solicitação de alteração que você quiser analisar.
Você pode usar as opções **Create date range** (Criar intervalo de datas) para limitar os resultados a um período de tempo específico.
Você pode filtrar solicitações pelas seguintes propriedades:
+ `Status`
+ `Request ID`
+ `Approver`
+ `Requester`
Por exemplo, para visualizar detalhes de todas as solicitações de alteração concluídas com êxito nas últimas 24 horas, faça o seguinte:
1. Para **Create date range** (Criar intervalo de datas), escolha**1d**.
1. Na caixa de pesquisa, selecione **Status, CompletedWithSuccess** (Status, concluído com êxito).
1. Nos resultados, escolha o nome da solicitação de alteração concluída com êxito para revisar os resultados.
1. Visualizar informações sobre a solicitação de alteração nas seguintes guias:
+ **Detalhes do pedido**: visualize os detalhes básicos sobre a solicitação de alteração, incluindo o solicitante, o modelo de alteração e os runbooks do Automation selecionados para a alteração. Você também pode seguir um link para os detalhes da operação do Automation e exibir informações sobre quaisquer parâmetros do runbook especificados na solicitação, alarmes do Amazon CloudWatch atribuídos à solicitação de alteração e aprovações e comentários fornecidos para a solicitação.
+ **Tarefa**: exiba informações sobre a tarefa na alteração, incluindo o status da tarefa para solicitações de alteração concluídas, os recursos de destino, as etapas nos runbooks do Automation associados e detalhes do limite de erros e simultaneidade.
+ **Cronograma**: exiba um resumo de todos os eventos associados à solicitação de alteração, listados por data e hora. O resumo indica quando a solicitação de alteração foi criada, ações dos aprovadores atribuídos, uma observação de quando as solicitações de alteração aprovadas são programadas para execução, detalhes do fluxo de trabalho do runbook e alterações de status para o processo de alteração geral e de cada etapa do runbook.
+ **Associated events**: exibe detalhes auditáveis sobre solicitações de alteração registradas no [AWS CloudTrail Lake](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake.html). Os detalhes incluem quais ações da API foram executadas, os parâmetros de solicitação incluídos para essas ações, a conta do usuário que executou a ação, os recursos atualizados durante o processo e outros.
Quando você habilita o rastreamento de eventos do CloudTrail Lake, o CloudTrail Lake cria um armazenamento de dados de eventos para eventos relacionados às suas solicitações de alteração. Os detalhes de eventos estão disponíveis para a conta ou organização em que a solicitação de alteração foi executada. É possível ativar o rastreamento de eventos do CloudTrail Lake a partir de qualquer solicitação de alteração em sua conta ou organização. Para obter informações sobre como habilitar a integração com o CloudTrail Lake e criar um armazenamento de dados de eventos, consulte [Monitoramento dos seus eventos de solicitação de alteração](monitoring-change-request-events.md).
**nota**
Há uma cobrança para o uso do **CloudTrail Lake**. Para obter detalhes, consulte [Definição de preço do AWS CloudTrail](https://aws.amazon.com/cloudtrail/pricing/).
# Visualizar contagens agregadas de solicitações de alteração (linha de comando)
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
É possível visualizar contagens agregadas de solicitações de alteração no Change Manager, uma ferramenta do AWS Systems Manager, usando a operação da API [GetOpsSummary](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetOpsSummary.html). Esta operação de API pode retornar contagens para uma única Conta da AWS em uma única Região da AWS ou para várias contas e regiões.
**nota**
Se você quiser exibir contagens agregadas de solicitações de alteração para várias Contas da AWS e várias Regiões da AWS, defina e configure uma sincronização de dados dos recursos. Para obter mais informações, consulte [Creating a resource data sync for Inventory](inventory-create-resource-data-sync.md).
O procedimento a seguir descreve como usar o AWS Command Line Interface (AWS CLI) (no Linux, macOS ou Windows Server) para visualizar contagens agregadas de solicitações de alteração.
**Para visualizar as contagens agregadas das solicitações de alteração**
1. Instale e configure a AWS Command Line Interface (AWS CLI), caso ainda não o tenha feito.
Para obter informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
1. Execute um dos seguintes comandos:
**Uma única conta e região**
Este comando retorna uma contagem de todas as solicitações de alteração para a Conta da AWS e Região da AWS, para as quais a AWS CLI está configurada.
------
#### [ Linux & macOS ]
```
aws ssm get-ops-summary \
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal \
--aggregators AggregatorType=count,AttributeName=Status,TypeName=AWS:OpsItem
```
------
#### [ Windows ]
```
aws ssm get-ops-summary ^
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal ^
--aggregators AggregatorType=count,AttributeName=Status,TypeName=AWS:OpsItem
```
------
O sistema retorna informações como as seguintes:
```
{
"Entities": [
{
"Data": {
"AWS:OpsItem": {
"Content": [
{
"Count": "38",
"Status": "Open"
}
]
}
}
}
]
}
```
**Várias contas e/ou regiões**
Este comando retorna uma contagem de todas as solicitações de alteração para a Contas da AWS e Regiões da AWS especificada na sincronização de dados do recurso.
------
#### [ Linux & macOS ]
```
aws ssm get-ops-summary \
--sync-name resource_data_sync_name \
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal \
--aggregators AggregatorType=count,AttributeName=Status,TypeName=AWS:OpsItem
```
------
#### [ Windows ]
```
aws ssm get-ops-summary ^
--sync-name resource_data_sync_name ^
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal ^
--aggregators AggregatorType=count,AttributeName=Status,TypeName=AWS:OpsItem
```
------
O sistema retorna informações como as seguintes:
```
{
"Entities": [
{
"Data": {
"AWS:OpsItem": {
"Content": [
{
"Count": "43",
"Status": "Open"
},
{
"Count": "2",
"Status": "Resolved"
}
]
}
}
}
]
}
```
**Várias contas e uma região específica**
Este comando retorna uma contagem de todas as solicitações de alteração para as Contas da AWS especificadas na sincronização de dados do recurso. No entanto, ele retorna apenas dados da região especificada no comando.
------
#### [ Linux & macOS ]
```
aws ssm get-ops-summary \
--sync-name resource_data_sync_name \
--filters Key=AWS:OpsItem.SourceRegion,Values='Region',Type=Equal Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal \
--aggregators AggregatorType=count,AttributeName=Status,TypeName=AWS:OpsItem
```
------
#### [ Windows ]
```
aws ssm get-ops-summary ^
--sync-name resource_data_sync_name ^
--filters Key=AWS:OpsItem.SourceRegion,Values='Region',Type=Equal Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal ^
--aggregators AggregatorType=count,AttributeName=Status,TypeName=AWS:OpsItem
```
------
**Várias contas e regiões com saída agrupada por região**
Este comando retorna uma contagem de todas as solicitações de alteração para a Contas da AWS e Regiões da AWS especificada na sincronização de dados do recurso. A saída exibe informações de contagem por região.
------
#### [ Linux & macOS ]
```
aws ssm get-ops-summary \
--sync-name resource_data_sync_name \
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal \
--aggregators '[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"Status","Aggregators":[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"SourceRegion"}]}]'
```
------
#### [ Windows ]
```
aws ssm get-ops-summary ^
--sync-name resource_data_sync_name ^
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal ^
--aggregators '[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"Status","Aggregators":[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"SourceRegion"}]}]'
```
------
O sistema retorna informações como as seguintes:
```
{
"Entities": [
{
"Data": {
"AWS:OpsItem": {
"Content": [
{
"Count": "38",
"SourceRegion": "us-east-1",
"Status": "Open"
},
{
"Count": "4",
"SourceRegion": "us-east-2",
"Status": "Open"
},
{
"Count": "1",
"SourceRegion": "us-west-1",
"Status": "Open"
},
{
"Count": "2",
"SourceRegion": "us-east-2",
"Status": "Resolved"
}
]
}
}
}
]
}
```
**Várias contas e regiões com saída agrupada por contas e regiões**
Este comando retorna uma contagem de todas as solicitações de alteração para a Contas da AWS e Regiões da AWS especificada na sincronização de dados do recurso. A saída agrupa as informações de contagem por contas e regiões.
------
#### [ Linux & macOS ]
```
aws ssm get-ops-summary \
--sync-name resource_data_sync_name \
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal \
--aggregators '[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"Status","Aggregators":[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"SourceAccountId","Aggregators":[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"SourceRegion"}]}]}]'
```
------
#### [ Windows ]
```
aws ssm get-ops-summary ^
--sync-name resource_data_sync_name ^
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal ^
--aggregators '[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"Status","Aggregators":[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"SourceAccountId","Aggregators":[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"SourceRegion"}]}]}]'
```
------
O sistema retorna informações como as seguintes:
```
{
"Entities": [
{
"Data": {
"AWS:OpsItem": {
"Content": [
{
"Count": "38",
"SourceAccountId": "123456789012",
"SourceRegion": "us-east-1",
"Status": "Open"
},
{
"Count": "4",
"SourceAccountId": "111122223333",
"SourceRegion": "us-east-2",
"Status": "Open"
},
{
"Count": "1",
"SourceAccountId": "111122223333",
"SourceRegion": "us-west-1",
"Status": "Open"
},
{
"Count": "2",
"SourceAccountId": "444455556666",
"SourceRegion": "us-east-2",
"Status": "Resolved"
},
{
"Count": "1",
"SourceAccountId": "222222222222",
"SourceRegion": "us-east-1",
"Status": "Open"
}
]
}
}
}
]
}
```
# Auditar e registrar atividades do Change Manager em log
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Você pode auditar atividades no Change Manager, uma ferramenta do AWS Systems Manager, usando o Amazon CloudWatch e alarmes do AWS CloudTrail.
Para obter mais informações sobre opções de auditoria e registro para o Systems Manager, consulte [Registrar em log e monitorar no AWS Systems Manager](monitoring.md).
## Auditore a atividade do Change Manager usando alarmes do CloudWatch
Você pode configurar e atribuir um alarme do CloudWatch a um modelo de alteração. Se quaisquer condições definidas no alarme forem atendidas, as ações especificadas para o alarme serão realizadas. Na configuração do alarme, você pode especificar um tópico do Amazon Simple Notification Service (Amazon SNS) para notificar quando uma condição de alarme for atendida.
Para obter mais informações sobre como criar um modelo do Change Manager, consulte [Trabalhar com modelos de alteração](change-templates.md).
Para obter mais informações sobre como criar alarmes do CloudWatch, consulte [Usar alarmes do CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) no *Guia do usuário do Amazon CloudWatch*.
## Auditore a atividade do Change Manager usando o CloudTrail
O CloudTrail captura chamadas à API feitas no console do Systems Manager, na AWS Command Line Interface (AWS CLI) e no SDK do Systems Manager. Você pode visualizar as informações no console do CloudTrail ou em um bucket do Amazon Simple Storage Service (Amazon S3), onde elas estão armazenadas. Um bucket é usado em todos os logs do CloudTrail para sua conta.
Os logs de ações do Change Manager mostram a criação do documento de modelo de alteração, as aprovações e rejeições da solicitação de alteração e o modelo de alteração, atividade gerada por runbooks do Automation e muito mais. Para obter mais informações sobre como visualizar e utilizar os logs do CloudTrail de atividades do Systems Manager, consulte [Registrar em log chamadas de API do AWS Systems Manager com o AWS CloudTrail](monitoring-cloudtrail-logs.md).
# Solução de problemas do Change Manager
**Mudança de disponibilidade do Change Manager**
O AWS Systems Manager Change Manager não estará mais disponível para novos clientes a partir de 7 de novembro de 2025. Se quiser usar o Change Manager, inscreva-se antes dessa data. Os clientes atuais podem continuar usando o serviço normalmente. Para obter mais informações, consulte [mudança de disponibilidade do AWS Systems Manager Change Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html).
Use as informações a seguir para obter ajuda para solucionar problemas com o Change Manager, uma ferramenta do AWS Systems Manager.
**Topics**
+ [Erro “Group *\$1GUID\$1* not found” (Grupo \$1GUID\$1 não encontrado) durante aprovações de solicitação ao usar o Active Directory.](#change-manager-troubleshooting-sso)
## Erro “Group *\$1GUID\$1* not found” (Grupo \$1GUID\$1 não encontrado) durante aprovações de solicitação ao usar o Active Directory.
**Problema**: quando o Centro de Identidade do AWS IAM (IAM Identity Center) é usado para o gerenciamento de identidade de usuários, um membro de um grupo do Active Directory que recebe permissões de aprovação no Change Manager recebe um erro “não autorizado” ou “grupo não encontrado”.
+ **Solução**: quando você seleciona grupos do Active Directory no IAM Identity Center para acesso ao Console de gerenciamento da AWS, o sistema agenda uma sincronização periódica que copia informações desses grupos do Active Directory no IAM Identity Center. Esse processo deve ser concluído antes que os usuários autorizados por meio da associação de grupo do Active Directory possam aprovar com êxito uma solicitação. Para obter mais informações, consulte [Conectar ao diretório do Microsoft AD](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-ad.html) no *Guia do usuário do Centro de Identidade do AWS IAM*.
# Documentos do AWS Systems Manager
Um documento do AWS Systems Manager (documento SSM) define as ações que o Systems Manager realiza nas suas instâncias gerenciadas. O Systems Manager inclui mais de 100 documentos pré-configurados, que você pode usar especificando parâmetros no runtime. Documentos pré-configurados podem ser encontrados no console de documentos do Systems Manager escolhendo a guia **Owned by Amazon** (Propriedade da Amazon) ou especificando a Amazon para o filtro `Owner` ao chamar a operação da API `ListDocuments`. Os documentos usam JSON (JavaScript Object Notation) ou YAML e incluem etapas e parâmetros especificados por você.
Para maior segurança, desde 14 de julho de 2025, os documentos do SSM são compatíveis com a interpolação de variáveis de ambiente ao processar parâmetros. Esse recurso, disponível na versão 2.2 do esquema e com a versão 3.3.2746.0 ou superior do SSM Agent, ajuda a evitar ataques de injeção de comando.
Para começar a usar o , abra o [Systems Manager console (Console do gerenciador de sistemas).](https://console.aws.amazon.com/systems-manager/documents) No painel de navegação, escolha **Documents**.
**Importante**
No Systems Manager, um documento SSM *pertencente à Amazon* é um documento criado e gerenciado pela própria Amazon Web Services. Os documentos *pertencentes à Amazon* incluem um prefixo como `AWS-*` no nome do documento. O proprietário do documento é considerado a Amazon, e não uma conta de usuário específica em AWS. Esses documentos estão disponíveis publicamente para uso de todos.
## Como a ferramenta Documentos pode beneficiar minha organização?
O Documentos, uma ferramenta do AWS Systems Manager, oferece os seguintes benefícios:
+ **Categorias de documentos**
Para ajudar a encontrar os documentos necessários, escolha uma categoria dependendo do tipo de documento que você está procurando. Para ampliar sua pesquisa, você pode escolher várias categorias do mesmo tipo de documento. Não há suporte para a escolha de categorias de diferentes tipos de documentos. As categorias só são compatíveis com documentos de propriedade da Amazon.
+ **Versões de documentos**
Você pode criar e salvar diferentes versões de documentos. Em seguida, pode especificar uma versão padrão para cada documento. A versão padrão de um documento pode ser atualizada para uma versão mais recente ou revertida para uma mais antiga. Quando você altera o conteúdo de um documento, o Systems Manager incrementa automaticamente a versão do documento. Você pode recuperar ou usar qualquer versão de um documento especificando a versão do documento no console, comandos da AWS Command Line Interface (AWS CLI) ou chamadas de API.
+ **Personalize documentos para suas necessidades**
Se quiser personalizar as etapas e ações em um documento, você pode criar seu próprio. O sistema armazena o documento com sua Conta da AWS na Região da AWS em que você o cria. Para obter mais informações sobre como criar um documento do SSM, consulte [Criar conteúdo de documento do SSM](documents-creating-content.md).
+ **Tags de documentos**
Você pode atribuir uma tag aos seus documentos para ajudar a identificar rapidamente um ou mais documentos de acordo com as tags que tiver atribuído a eles. Por exemplo, você pode marcar documentos para ambientes, departamentos, usuários, grupos ou períodos específicos. Você pode também restringir o acesso aos documentos criando uma política do AWS Identity and Access Management (IAM) que especifique as tags que um usuário ou grupo pode acessar.
+ **Compartilhar documentos**
Você pode tornar seus documentos públicos ou compartilhá-los com contas da Contas da AWS específicas na mesma Região da AWS. Compartilhar documentos entre contas pode ser útil se, por exemplo, você desejar que todas as instâncias do Amazon Elastic Compute Cloud (Amazon EC2) fornecidas aos seus clientes ou funcionários tenham a mesma configuração. Além de manter atualizadas as aplicações ou patches nessas instâncias, talvez você queira restringir algumas atividades nas instâncias dos clientes. Ou talvez você queira garantir que as instâncias usadas por contas de funcionário na organização recebam acesso a recursos internos específicos. Para obter mais informações, consulte [Compartilhar documentos do Systems Manager](documents-ssm-sharing.md).
## Quem deve usar documentos?
+ Qualquer cliente da AWS que deseje usar as ferramentas do Systems Manager para melhorar sua eficiência operacional em escala, reduzir erros associados à intervenção manual e reduzir o tempo de resolução de problemas comuns.
+ Especialistas em infraestrutura que desejem automatizar tarefas de implantação e configuração.
+ Administradores que desejem resolver problemas comuns de forma confiável, melhorar a eficiência da solução de problemas e reduzir operações repetitivas.
+ Usuários que desejarem automatizar uma tarefa que normalmente executam manualmente.
## Quais são os tipos de documentos de SSM?
A tabela a seguir descreve os diferentes tipos de documentos do SSM e seus usos.
****
| Tipo | Use com | Detalhes |
| --- | --- | --- |
| ApplicationConfiguration ApplicationConfigurationSchema | [AWS AppConfig](https://docs.aws.amazon.com/appconfig/latest/userguide/what-is-appconfig.html) | O AWS AppConfig, uma ferramenta do AWS Systems Manager, permite criar, gerenciar e implantar rapidamente configurações de aplicações. Você pode armazenar dados de configuração em um documento SSM criando um documento que usa o tipo de documento `ApplicationConfiguration`. Para obter mais informações, consulte [Configurações de forma livre](https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-creating-configuration-and-profile.html#free-form-configurations) no *Guia do usuário do AWS AppConfig*. Se você criar uma configuração em um documento do SSM, deverá especificar um esquema JSON correspondente. O esquema usa o tipo de documento `ApplicationConfigurationSchema` e, como um conjunto de regras, define as propriedades permitidas para cada definição de configuração de aplicação. Para obter mais informações, consulte [About validators (Sobre validadores)](https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-creating-configuration-and-profile-validators.html) no *AWS AppConfig User Guide. (Guia do usuário do *). |
| Runbook de automação | [Automação](systems-manager-automation.md) [State Manager](systems-manager-state.md) [Maintenance Windows](maintenance-windows.md) | Use runbooks do Automation ao realizar tarefas comuns de manutenção e implantação, como criar ou atualizar uma Amazon Machine Image (AMI). O State Manager usa runbooks do Automation para aplicar uma configuração. Essas ações podem ser executadas em um ou mais destinos em qualquer ponto durante o ciclo de vida de uma instância. O Maintenance Windows usa ao realizar tarefas comuns de manutenção e implantação com base na programação especificada. Todos os runbooks de automação compatíveis com sistemas operacionais baseados em Linux também são compatíveis com as instâncias do EC2 para macOS. |
| Alterar documento do calendário | [Change Calendar](systems-manager-change-calendar.md) | O Change Calendar, uma ferramenta do AWS Systems Manager, usa o tipo de documento `ChangeCalendar`. Um documento do Change Calendar armazena uma entrada de calendário e eventos associados que podem permitir ou impedir que as ações de automação alterem seu ambiente. No Change Calendar, um documento armazena dados do [iCalendar 2.0](https://icalendar.org/) em formato de texto simples. Change Calendar O não tem suporte em instâncias EC2 para macOS. |
| Modelo do AWS CloudFormation | [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) | AWS CloudFormationOs modelos do descrevem os recursos que você deseja provisionar nas suas pilhas do CloudFormation. Com o armazenamento de modelos do CloudFormation como documentos do Systems Manager, você pode se beneficiar dos recursos de documento do Systems Manager Isso inclui criar e comparar várias versões do seu modelo e compartilhar seu modelo com outras contas na mesma Região da AWS. Você pode criar e editar modelos e pilhas do CloudFormation usando o Application Manager, uma ferramenta do Systems Manager. Para obter mais informações, consulte [Trabalhar com modelos e pilhas do CloudFormation no Application Manager.](application-manager-working-stacks.md). |
| Documento de comando | [Run Command](run-command.md) [State Manager](systems-manager-state.md) [Maintenance Windows](maintenance-windows.md) | O Run Command, uma ferramenta do AWS Systems Manager, usa documentos do Command para executar comandos. O State Manager, uma ferramenta do AWS Systems Manager usa documentos de comando para aplicar uma configuração. Essas ações podem ser executadas em um ou mais destinos em qualquer ponto durante o ciclo de vida de uma instância. O Maintenance Windows, uma ferramenta do AWS Systems Manager, usa documentos de comando para aplicar uma configuração de acordo com a programação especificada. A maioria dos documentos de comando é aceita em todos os sistemas operacionais Linux e Windows Server aos quais o Systems Manager oferece suporte. Os seguintes documentos de comandos são aceitos em instâncias do EC2 para macOS: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/documents.html) |
| Modelo de pacote de conformidade do AWS Config | [AWS Config](https://docs.aws.amazon.com/config/latest/developerguide/WhatIsConfig.html) | Os modelos de pacote de conformidade do AWS Config são documentos formatados em YAML usados para criar pacotes de conformidade que contêm a lista de regras gerenciadas ou personalizadas e ações de remediação do AWS Config. Para obter mais informações, consulte [Pacotes de conformidade](https://docs.aws.amazon.com/config/latest/developerguide/conformance-packs.html). |
| Documento de pacote | [Distributor](distributor.md) | No Distributor, uma ferramenta do AWS Systems Manager, um pacote é representado por um documento do SSM. Um documento de pacote inclui arquivos ZIP anexados que contêm software ou ativos para instalar nas instâncias gerenciadas. Criar um pacote no Distributor cria o documento de pacote. O Distributor não tem suporte em instâncias gerenciadas no Oracle Linux e macOS |
| Documento de política | [State Manager](systems-manager-state.md) | O Inventory, uma ferramenta do AWS Systems Manager, usa o documento de política `AWS-GatherSoftwareInventory` com uma associação ao State Manager para coletar dados de inventário de instâncias gerenciadas. Ao criar seus próprios documentos do SSM, os runbooks do Automation e os documentos de comando são o método preferido para aplicar uma política em uma instância gerenciada. O Systems Manager Inventory e o documento de políticas `AWS-GatherSoftwareInventory` são compatíveis com todos os sistemas operacionais suportados pelo Systems Manager. |
| Modelo de análise pós-incidente | [Análise pós-incidente do Incident Manager](https://docs.aws.amazon.com/incident-manager/latest/userguide/analysis.html) | O Incident Manager usa o modelo de análise pós-incidente para criar uma análise baseada nas práticas recomendadas para o gerenciamento de operações da AWS. Use o modelo para criar uma análise que sua equipe possa usar para identificar melhorias na sua resposta a incidentes. |
| Documento de sessão | [Session Manager](session-manager.md) | O Session Manager, uma ferramenta do AWS Systems Manager, usa documentos de sessão para determinar qual tipo de sessão iniciar, como uma sessão de encaminhamento de portas, uma sessão para executar um comando interativo ou uma sessão para criar um túnel SSH. Documentos de sessão são aceitos em todos os sistemas operacionais Linux e Windows Server aos quais o Systems Manager oferece suporte. Os seguintes documentos Command são suportados em instâncias do EC2 para macOS: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/documents.html) |
**Cotas de documentos do SSM**
Para obter mais informações sobre cotas de documentos do SSM, consulte [Systems Manager service quotas](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm) no *Referência geral da Amazon Web Services*.
**Topics**
+ [Como a ferramenta Documentos pode beneficiar minha organização?](#ssm-docs-benefits)
+ [Quem deve usar documentos?](#documents-who)
+ [Quais são os tipos de documentos de SSM?](#what-are-document-types)
+ [Componentes do documento](documents-components.md)
+ [Criar conteúdo de documento do SSM](documents-creating-content.md)
+ [Trabalhar com documentos](documents-using.md)
+ [Solução de problemas de tratamento de parâmetros](parameter-troubleshooting.md)
# Componentes do documento
Esta seção contém informações sobre os componentes presentes nos documentos do SSM.
**Topics**
+ [Esquemas, atributos e exemplos](documents-schemas-features.md)
+ [Elementos e parâmetros de dados](documents-syntax-data-elements-parameters.md)
+ [Referência de plug-ins de documentos de comando](documents-command-ssm-plugin-reference.md)
# Esquemas, atributos e exemplos
AWS Systems ManagerOs documentos do (SSM) usam as versões de esquema a seguir.
+ Os documentos do tipo `Command` podem usar o esquema versão 1.2, 2.0 e 2.2. Se você usa documentos do esquema 1.2, recomendamos criar documentos que utilizem o esquema versão 2.2.
+ Os documentos do tipo `Policy` devem usar o esquema versão 2.0 ou posterior.
+ Os documentos do tipo `Automation` devem usar o esquema versão 0.3.
+ Os documentos do tipo `Session` devem usar o esquema versão 1.0.
+ Você pode criar documentos em JSON ou YAML.
Para obter mais informações sobre o esquema de documentos do `Session`, consulte [Esquema do documento de sessão](session-manager-schema.md).
Ao usar a versão de esquema mais recentes para documentos `Command` e `Policy`, você poderá aproveitar os seguintes recursos.
**Recursos de documentos da versão 2.2 do esquema**
| Recurso | Detalhes |
| --- | --- |
| Edição de documentos | Agora, documentos podem ser atualizados. Com a versão 1.2, qualquer atualização de um documento exigia que você o salvasse com um nome diferente. |
| Versionamento automático | Qualquer atualização de um documento cria uma nova versão. Esta não é uma versão de esquema, mas uma versão do documento. |
| Versão padrão | Se você possui várias versões de um documento, pode especificar qual delas é o documento padrão. |
| Sequenciamento | Os plugins ou as *etapas* em um documento são executados na ordem que você especificou. |
| Suporte entre plataformas | O suporte entre plataformas permite que você especifique diferentes sistemas operacionais para diferentes plugins dentro do mesmo documento do SSM. O suporte entre plataformas usa o parâmetro `precondition` dentro de uma etapa. |
| Interpolação de parâmetros | Interpolação significa inserir ou substituir um valor variável em uma string. Pense nisso como preencher um espaço em branco com valores reais antes que a string seja usada. No contexto de documentos do SSM, a interpolação de parâmetros permite que parâmetros de string sejam interpolados em variáveis de ambiente antes da execução do comando, fornecendo melhor segurança contra injeções de comando. Quando definido como `ENV_VAR`, o agente cria uma variável de ambiente denominada `SSM_parameter-name` que contém o valor do parâmetro. |
**nota**
Você deve manter o AWS Systems Manager SSM Agent atualizado em suas instâncias com a versão mais recente para usar os novos recursos do Systems Manager e os recursos de documento do SSM. Para obter mais informações, consulte [Atualização do SSM Agent por meio de Run Command](run-command-tutorial-update-software.md#rc-console-agentexample).
A tabela a seguir lista as diferenças entre as principais versões de esquema.
****
| Versão 1.2 | Versão 2.2 (versão mais recente) | Detalhes |
| --- | --- | --- |
| runtimeConfig | mainSteps | Na versão 2.2, a seção `mainSteps` substitui `runtimeConfig`. O`mainSteps`A seção permite que o Systems Manager execute etapas em sequência. |
| propriedades | inputs | Na versão 2.2, a seção `inputs` substitui a seção `properties`. A seção `inputs` aceita parâmetros para as etapas. |
| comandos | runCommand | Na versão 2.2, a seção `inputs` usa o parâmetro `runCommand` em vez do parâmetro `commands`. |
| id | ação | Na versão 2.2, `Action` substitui `ID`. Esta é apenas uma mudança de nome. |
| não aplicável | name | Na versão 2.2, `name` é um nome definido pelo usuário para uma etapa. |
**Usar o parâmetro precondition**
Com o esquema versão 2.2 ou superior, você pode usar o parâmetro `precondition` para especificar o sistema operacional de destino de cada plugin ou para validar parâmetros de entrada que você definiu em seu documento do SSM. O`precondition`suporta referenciar os parâmetros de entrada do documento SSM, e`platformType`usando valores de`Linux`,`MacOS`, e`Windows`. Somente a`StringEquals`é suportado.
Para documentos que utilizam o esquema versão 2.2 ou posterior, se a `precondition` não for especificada, cada plugin será executado ou ignorado com base na compatibilidade do plugin com o sistema operacional. Compatibilidade de plugins com o sistema operacional é avaliada antes do `precondition`. Para documentos que utilizam o esquema 2.0 ou anterior, os plugins incompatíveis geram um erro.
Por exemplo, em um documento com a versão 2.2 do esquema, se `precondition` não for especificado e o plugin `aws:runShellScript` estiver relacionado, a etapa será executada em instâncias do Linux, mas será ignorada pelo sistema em instâncias do Windows Server porque o `aws:runShellScript` não é compatível com instâncias do Windows Server. No entanto, para um documento de esquema versão 2.0, se você especificar o plugin `aws:runShellScript` e depois executar o documento em instâncias do Windows Server, a execução falhará. Você poderá ver um exemplo do parâmetro de pré-condição em um documento do SSM ainda nesta seção.
## Versão 2.2 do esquema
**Elementos de nível superior**
O exemplo a seguir mostra os elementos de nível superior de um documento do SSM usando o esquema versão 2.2.
------
#### [ YAML ]
```
---
schemaVersion: "2.2"
description: A description of the document.
parameters:
parameter 1:
property 1: "value"
property 2: "value"
parameter 2:
property 1: "value"
property 2: "value"
mainSteps:
- action: Plugin name
name: A name for the step.
inputs:
input 1: "value"
input 2: "value"
input 3: "{{ parameter 1 }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "A description of the document.",
"parameters": {
"parameter 1": {
"property 1": "value",
"property 2": "value"
},
"parameter 2":{
"property 1": "value",
"property 2": "value"
}
},
"mainSteps": [
{
"action": "Plugin name",
"name": "A name for the step.",
"inputs": {
"input 1": "value",
"input 2": "value",
"input 3": "{{ parameter 1 }}"
}
}
]
}
```
------
**Exemplo de esquema versão 2.2**
Veja como o exemplo a seguir usa o plugin `aws:runPowerShellScript` para executar um comando do PowerShell nas instâncias de destino.
------
#### [ YAML ]
```
---
schemaVersion: "2.2"
description: "Example document"
parameters:
Message:
type: "String"
description: "Example parameter"
default: "Hello World"
allowedValues:
- "Hello World"
mainSteps:
- action: "aws:runPowerShellScript"
name: "example"
inputs:
timeoutSeconds: '60'
runCommand:
- "Write-Output {{Message}}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Example document",
"parameters": {
"Message": {
"type": "String",
"description": "Example parameter",
"default": "Hello World",
"allowedValues": ["Hello World"]
}
},
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "example",
"inputs": {
"timeoutSeconds": "60",
"runCommand": [
"Write-Output {{Message}}"
]
}
}
]
}
```
------
**Exemplos do parâmetro precondition da versão 2.2 do esquema**
O esquema versão 2.2 fornece suporte para várias plataformas. Isso significa que, dentro de um único documento do SSM, você pode especificar diferentes sistemas operacionais para diferentes plugins. O suporte entre plataformas usa o parâmetro `precondition` dentro de uma etapa, como mostra o exemplo a seguir. Você também pode usar o`precondition`para validar os parâmetros de entrada definidos no documento do SSM. Veja isso no segundo exemplo a seguir.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: cross-platform sample
mainSteps:
- action: aws:runPowerShellScript
name: PatchWindows
precondition:
StringEquals:
- platformType
- Windows
inputs:
runCommand:
- cmds
- action: aws:runShellScript
name: PatchLinux
precondition:
StringEquals:
- platformType
- Linux
inputs:
runCommand:
- cmds
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "cross-platform sample",
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "PatchWindows",
"precondition": {
"StringEquals": [
"platformType",
"Windows"
]
},
"inputs": {
"runCommand": [
"cmds"
]
}
},
{
"action": "aws:runShellScript",
"name": "PatchLinux",
"precondition": {
"StringEquals": [
"platformType",
"Linux"
]
},
"inputs": {
"runCommand": [
"cmds"
]
}
}
]
}
```
------
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
parameters:
action:
type: String
allowedValues:
- Install
- Uninstall
confirmed:
type: String
allowedValues:
- True
- False
mainSteps:
- action: aws:runShellScript
name: InstallAwsCLI
precondition:
StringEquals:
- "{{ action }}"
- "Install"
inputs:
runCommand:
- sudo apt install aws-cli
- action: aws:runShellScript
name: UninstallAwsCLI
precondition:
StringEquals:
- "{{ action }} {{ confirmed }}"
- "Uninstall True"
inputs:
runCommand:
- sudo apt remove aws-cli
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"parameters": {
"action": {
"type": "String",
"allowedValues": [
"Install",
"Uninstall"
]
},
"confirmed": {
"type": "String",
"allowedValues": [
true,
false
]
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "InstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }}",
"Install"
]
},
"inputs": {
"runCommand": [
"sudo apt install aws-cli"
]
}
},
{
"action": "aws:runShellScript",
"name": "UninstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }} {{ confirmed }}",
"Uninstall True"
]
},
"inputs": {
"runCommand": [
"sudo apt remove aws-cli"
]
}
}
]
}
```
------
**Exemplo de interpolação do esquema versão 2.2 com versões do SSM Agent anteriores à 3.3.2746.0**
Nas versões do SSM Agent anteriores à 3.3.2746.0, o agente ignora o parâmetro `interpolationType` e, em vez disso, executa uma substituição de string bruta. Se estiver referenciando `SSM_parameter-name` de forma explícita, você deve definir explicitamente. No exemplo a seguir para Linux, a variável de ambiente `SSM_Message` é referenciada explicitamente.
```
{
"schemaVersion": "2.2",
"description": "An example document",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType" : "ENV_VAR",
"allowedPattern: "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"inputs": {
"runCommand": [
"if [ -z "${SSM_Message+x}" ]; then",
" export SSM_Message=\"{{Message}}\"",
"fi",
"",
"echo $SSM_Message"
]
}
}
}
```
**nota**
`allowedPattern` não será tecnicamente necessário se um documento do SSM não usar chaves duplas: `{{ }}`
**Exemplo de esquema versão 2.2 do State Manager**
Você pode usar o seguinte documento do SSM com o State Manager, uma ferramenta do Systems Manager, para baixar e instalar o software antivírus ClamAV. O State Manager impõe uma configuração específica, o que significa que cada vez que a associação do State Manager for executada, o sistema verificará se o software ClamAV está instalado. Se não, o State Manager executa novamente esse documento.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: State Manager Bootstrap Example
parameters: {}
mainSteps:
- action: aws:runShellScript
name: configureServer
inputs:
runCommand:
- sudo yum install -y httpd24
- sudo yum --enablerepo=epel install -y clamav
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "State Manager Bootstrap Example",
"parameters": {},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "configureServer",
"inputs": {
"runCommand": [
"sudo yum install -y httpd24",
"sudo yum --enablerepo=epel install -y clamav"
]
}
}
]
}
```
------
**Exemplo de inventário do esquema versão 2.2**
Você pode usar o documento SSM a seguir com o State Manager para coletar metadados de inventário sobre suas instâncias.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: Software Inventory Policy Document.
parameters:
applications:
type: String
default: Enabled
description: "(Optional) Collect data for installed applications."
allowedValues:
- Enabled
- Disabled
awsComponents:
type: String
default: Enabled
description: "(Optional) Collect data for AWS Components like amazon-ssm-agent."
allowedValues:
- Enabled
- Disabled
networkConfig:
type: String
default: Enabled
description: "(Optional) Collect data for Network configurations."
allowedValues:
- Enabled
- Disabled
windowsUpdates:
type: String
default: Enabled
description: "(Optional) Collect data for all Windows Updates."
allowedValues:
- Enabled
- Disabled
instanceDetailedInformation:
type: String
default: Enabled
description: "(Optional) Collect additional information about the instance, including
the CPU model, speed, and the number of cores, to name a few."
allowedValues:
- Enabled
- Disabled
customInventory:
type: String
default: Enabled
description: "(Optional) Collect data for custom inventory."
allowedValues:
- Enabled
- Disabled
mainSteps:
- action: aws:softwareInventory
name: collectSoftwareInventoryItems
inputs:
applications: "{{ applications }}"
awsComponents: "{{ awsComponents }}"
networkConfig: "{{ networkConfig }}"
windowsUpdates: "{{ windowsUpdates }}"
instanceDetailedInformation: "{{ instanceDetailedInformation }}"
customInventory: "{{ customInventory }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Software Inventory Policy Document.",
"parameters": {
"applications": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for installed applications.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"awsComponents": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for AWS Components like amazon-ssm-agent.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"networkConfig": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for Network configurations.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"windowsUpdates": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for all Windows Updates.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"instanceDetailedInformation": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect additional information about the instance, including\nthe CPU model, speed, and the number of cores, to name a few.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"customInventory": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for custom inventory.",
"allowedValues": [
"Enabled",
"Disabled"
]
}
},
"mainSteps": [
{
"action": "aws:softwareInventory",
"name": "collectSoftwareInventoryItems",
"inputs": {
"applications": "{{ applications }}",
"awsComponents": "{{ awsComponents }}",
"networkConfig": "{{ networkConfig }}",
"windowsUpdates": "{{ windowsUpdates }}",
"instanceDetailedInformation": "{{ instanceDetailedInformation }}",
"customInventory": "{{ customInventory }}"
}
}
]
}
```
------
**Exemplo de esquema versão 2.2 do `AWS-ConfigureAWSPackage`**
O exemplo a seguir mostra o documento `AWS-ConfigureAWSPackage`. O`mainSteps`Inclui a seção`aws:configurePackage`plugin no`action`Etapa.
**nota**
Nos sistemas operacionais Linux, somente os pacotes `AmazonCloudWatchAgent` e `AWSSupport-EC2Rescue` são suportados.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Install or uninstall the latest version or specified version of an AWS
package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver,
AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.'
parameters:
action:
description: "(Required) Specify whether or not to install or uninstall the package."
type: String
allowedValues:
- Install
- Uninstall
name:
description: "(Required) The package to install/uninstall."
type: String
allowedPattern: "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
version:
type: String
description: "(Optional) A specific version of the package to install or uninstall."
mainSteps:
- action: aws:configurePackage
name: configurePackage
inputs:
name: "{{ name }}"
action: "{{ action }}"
version: "{{ version }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Install or uninstall the latest version or specified version of an AWS package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver, AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.",
"parameters": {
"action": {
"description":"(Required) Specify whether or not to install or uninstall the package.",
"type":"String",
"allowedValues":[
"Install",
"Uninstall"
]
},
"name": {
"description": "(Required) The package to install/uninstall.",
"type": "String",
"allowedPattern": "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
},
"version": {
"type": "String",
"description": "(Optional) A specific version of the package to install or uninstall."
}
},
"mainSteps":[
{
"action": "aws:configurePackage",
"name": "configurePackage",
"inputs": {
"name": "{{ name }}",
"action": "{{ action }}",
"version": "{{ version }}"
}
}
]
}
```
------
## Versão 1.2 do esquema
O exemplo a seguir mostra os elementos de nível superior de um documento do esquema versão 1.2.
```
{
"schemaVersion":"1.2",
"description":"A description of the SSM document.",
"parameters":{
"parameter 1":{
"one or more parameter properties"
},
"parameter 2":{
"one or more parameter properties"
},
"parameter 3":{
"one or more parameter properties"
}
},
"runtimeConfig":{
"plugin 1":{
"properties":[
{
"one or more plugin properties"
}
]
}
}
}
```
**Exemplo de esquema versão 1.2 do `aws:runShellScript`**
O exemplo a seguir mostra o`AWS-RunShellScript`Documento do MUS do. A seção **runtimeConfig** inclui o plugin `aws:runShellScript`.
```
{
"schemaVersion":"1.2",
"description":"Run a shell script or specify the commands to run.",
"parameters":{
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
},
"workingDirectory":{
"type":"String",
"default":"",
"description":"(Optional) The path to the working directory on your instance.",
"maxChars":4096
},
"executionTimeout":{
"type":"String",
"default":"3600",
"description":"(Optional) The time in seconds for a command to complete before it is considered to have failed. Default is 3600 (1 hour). Maximum is 172800 (48 hours).",
"allowedPattern":"([1-9][0-9]{0,3})|(1[0-9]{1,4})|(2[0-7][0-9]{1,3})|(28[0-7][0-9]{1,2})|(28800)"
}
},
"runtimeConfig":{
"aws:runShellScript":{
"properties":[
{
"id":"0.aws:runShellScript",
"runCommand":"{{ commands }}",
"workingDirectory":"{{ workingDirectory }}",
"timeoutSeconds":"{{ executionTimeout }}"
}
]
}
}
}
```
## Versão 0.3 do esquema
**Elementos de nível superior**
O exemplo a seguir mostra os elementos de nível superior de um runbook do Automation versão 0.3 do esquema no formato JSON.
```
{
"description": "document-description",
"schemaVersion": "0.3",
"assumeRole": "{{assumeRole}}",
"parameters": {
"parameter1": {
"type": "String",
"description": "parameter-1-description",
"default": ""
},
"parameter2": {
"type": "String",
"description": "parameter-2-description",
"default": ""
}
},
"variables": {
"variable1": {
"type": "StringMap",
"description": "variable-1-description",
"default": {}
},
"variable2": {
"type": "String",
"description": "variable-2-description",
"default": "default-value"
}
},
"mainSteps": [
{
"name": "myStepName",
"action": "action-name",
"maxAttempts": 1,
"inputs": {
"Handler": "python-only-handler-name",
"Runtime": "runtime-name",
"Attachment": "script-or-zip-name"
},
"outputs": {
"Name": "output-name",
"Selector": "selector.value",
"Type": "data-type"
}
}
],
"files": {
"script-or-zip-name": {
"checksums": {
"sha256": "checksum"
},
"size": 1234
}
}
}
```
**Exemplo de runbook de automação YAML**
O exemplo a seguir mostra o conteúdo de um runbook do Automation, no formato YAML. Este exemplo funcional da versão 0.3 do esquema do documento também demonstra o uso do Markdown para formatar descrições de documentos.
```
description: >-
##Title: LaunchInstanceAndCheckState
-----
**Purpose**: This Automation runbook first launches an EC2 instance
using the AMI ID provided in the parameter ```imageId```. The second step of
this document 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/al2023-ami-kernel-6.1-x86_64 }}
schemaVersion: '0.3'
assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole'
parameters:
imageId:
type: String
default: '{{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}'
description: >-
(Optional) The AMI ID to use for launching the instance. The default value
uses the latest released Amazon Linux AMI ID.
tagValue:
type: String
default: ' LaunchedBySsmAutomation'
description: >-
(Optional) The tag value to add to the instance. The default value is
LaunchedBySsmAutomation.
instanceType:
type: String
default: t2.micro
description: >-
(Optional) The instance type to use for the instance. The default value is
t2.micro.
mainSteps:
- name: LaunchEc2Instance
action: 'aws:executeScript'
outputs:
- Name: payload
Selector: $.Payload
Type: StringMap
inputs:
Runtime: python3.11
Handler: launch_instance
Script: ''
InputPayload:
image_id: '{{ imageId }}'
tag_value: '{{ tagValue }}'
instance_type: '{{ instanceType }}'
Attachment: launch.py
description: >-
**About This Step**
This step first launches an EC2 instance using the ```aws:executeScript```
action and the provided python script.
- name: WaitForInstanceStatusOk
action: 'aws:executeScript'
inputs:
Runtime: python3.11
Handler: poll_instance
Script: |-
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}
InputPayload: '{{ LaunchEc2Instance.payload }}'
description: >-
**About This Step**
The python script continuously polls the instance status check value for
the instance launched in Step 1 until the ```ok``` status is returned.
files:
launch.py:
checksums:
sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```
## Exemplos de tratamento seguro de parâmetros
Os exemplos a seguir demonstram o tratamento seguro de parâmetros usando a variável de ambiente `interpolationType`.
### Execução segura básica de comandos
Este exemplo mostra como tratar com segurança um parâmetro de comando:
**nota**
`allowedPattern` não é tecnicamente exigido em documentos do SSM que não usam chaves duplas: `{{ }}`
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: An example document.
parameters:
Message:
type: String
description: "Message to be printed"
default: Hello
interpolationType: ENV_VAR
allowedPattern: "^[^"]*$"
mainSteps:
- action: aws:runShellScript
name: printMessage
precondition:
StringEquals:
- platformType
- Linux
inputs:
runCommand:
- echo {{Message}}
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "An example document.",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType": "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"precondition": {
"StringEquals": ["platformType", "Linux"]
},
"inputs": {
"runCommand": [
"echo {{Message}}"
]
}
}]
}
```
------
### Uso de parâmetros em linguagens interpretadas
Este exemplo demonstra o tratamento seguro de parâmetros em Python:
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Secure Python script execution'
parameters:
inputData:
type: String
description: 'Input data for processing'
interpolationType: 'ENV_VAR'
mainSteps:
- action: aws:runPowerShellScript
name: runPython
inputs:
runCommand:
- |
python3 -c '
import os
import json
# Safely access parameter through environment variable
input_data = os.environ.get("SSM_inputData", "")
# Process the data
try:
processed_data = json.loads(input_data)
print(f"Successfully processed: {processed_data}")
except json.JSONDecodeError:
print("Invalid JSON input")
'
```
------
### Exemplo de compatibilidade com versões anteriores
Este exemplo mostra como tratar parâmetros de forma segura enquanto mantém a compatibilidade com versões anteriores:
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Backwards compatible secure parameter handling'
parameters:
userInput:
type: String
description: 'User input to process'
interpolationType: 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: processInput
inputs:
runCommand:
- |
# Handle both modern and legacy agent versions
if [ -z "${SSM_userInput+x}" ]; then
# Legacy agent - fall back to direct parameter reference
export SSM_userInput="{{userInput}}"
fi
# Process the input securely
echo "Processing input: $SSM_userInput"
```
------
**nota**
`allowedPattern` não é tecnicamente exigido em documentos do SSM que não usam chaves duplas: `{{ }}`
## Práticas recomendadas de segurança de parâmetros
Siga estas práticas recomendadas ao tratar parâmetros em documentos do SSM:
+ **Use a interpolação de variáveis de ambiente**: sempre use `interpolationType: "ENV_VAR"` para parâmetros de string que serão usados na execução do comando.
+ **Implemente uma validação de entrada**: use `allowedPattern` para restringir os valores dos parâmetros a padrões seguros.
+ **Lide com sistemas legados**: inclua lógica de fallback para as versões anteriores do SSM Agent que não são compatíveis com a interpolação de variáveis de ambiente.
+ **Escape de caracteres especiais**: ao usar valores de parâmetros em comandos, escape adequadamente dos caracteres especiais para evitar a interpretação pelo shell.
+ **Limite o escopo do parâmetro**: use os padrões de parâmetros mais restritivos possíveis para seu caso de uso.
# Elementos e parâmetros de dados
Este tópico descreve os elementos de dados usados nos documentos do SSM. A versão do esquema usada para criar um documento define a sintaxe e os elementos de dados que o documento aceita. Recomendamos usar a versão 2.2 ou posterior do esquema para documentos do Command. Runbooks de automação usam o esquema versão 0.3. Além disso, runbooksde automação são compatíveis com o uso de Markdown, uma linguagem de marcação, que permite adicionar descrições de estilo wiki a documentos e etapas individuais dentro do documento. Para obter mais informações sobre o uso de Markdown, consulte [Usar o Markdown no console](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html) no *Guia de conceitos básicos do Console de gerenciamento da AWS*.
A seção a seguir descreve os elementos de dados que você pode incluir em um documento SSM.
## Elementos de dados de nível superior
**schemaVersion**
A versão do esquema a ser usada.
Tipo: versão
Obrigatório: Sim
**descrição**
Informações que você fornece para descrever a finalidade do documento. Você também pode usar esse campo para especificar se um parâmetro requer um valor para que um documento seja executado ou se fornecer um valor para o parâmetro é opcional. Parâmetros obrigatórios e opcionais podem ser vistos nos exemplos neste tópico.
Tipo: string
Obrigatório: não
**parameters**
Uma estrutura que define os parâmetros que o documento aceita.
Para maior segurança ao tratar parâmetros de string, você pode usar a interpolação de variáveis de ambiente especificando a propriedade `interpolationType`. Quando definido como `ENV_VAR`, o sistema cria uma variável de ambiente denominada `SSM_parameter-name` contendo o valor do parâmetro.
Veja a seguir um exemplo de um parâmetro usando a variável de ambiente `interpolationType`:
```
{
"schemaVersion": "2.2",
"description": "An example document.",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType" : "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"precondition" : {
"StringEquals" : ["platformType", "Linux"]
},
"inputs": {
"runCommand": [
"echo {{Message}}"
]
}
}
}
```
`allowedPattern` não é tecnicamente exigido em documentos do SSM que não usam chaves duplas: `{{ }}`
Para os parâmetros usados com frequência, recomendamos armazená-los no Parameter Store, uma ferramenta do AWS Systems Manager. Em seguida, você pode definir parâmetros em seu documento que façam referência a parâmetros do Parameter Store como o valor padrão deles. Para fazer referência a um parâmetro do Parameter Store, use a sintaxe a seguir.
```
{{ssm:parameter-name}}
```
Você pode usar um parâmetro que faça referência a um parâmetro do Parameter Store da mesma forma que faria com qualquer outro parâmetro de documento. No exemplo a seguir, o valor padrão para o parâmetro `commands` é o parâmetro `myShellCommands` do Parameter Store. Ao especificar o parâmetro `commands` como uma string `runCommand`, o documento executa os comandos armazenados no parâmetro `myShellCommands`.
```
---
schemaVersion: '2.2'
description: runShellScript with command strings stored as Parameter Store parameter
parameters:
commands:
type: StringList
description: "(Required) The commands to run on the instance."
default: ["{{ ssm:myShellCommands }}"],
interpolationType : 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: runShellScriptDefaultParams
inputs:
runCommand:"{{ commands }}"
```
```
{
"schemaVersion": "2.2",
"description": "runShellScript with command strings stored as Parameter Store parameter",
"parameters": {
"commands": {
"type": "StringList",
"description": "(Required) The commands to run on the instance.",
"default": ["{{ ssm:myShellCommands }}"],
"interpolationType" : "ENV_VAR"
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "runShellScriptDefaultParams",
"inputs": {
"runCommand": [
"{{ commands }}"
]
}
}
]
}
```
Você pode fazer referência aos parâmetros `String` e `StringList` do Parameter Store na seção `parameters` do seu documento. Você não pode fazer referência a parâmetros `SecureString` do Parameter Store.
Para obter mais informações sobre o Parameter Store, consulte [AWS Systems Manager Parameter Store](systems-manager-parameter-store.md).
Tipo: estrutura
A estrutura `parameters` aceita os seguintes campos e valores:
+ `type`: (obrigatório) os valores permitidos incluem os seguintes: `String`, `StringList`, `Integer`, `Boolean`, `MapList` e `StringMap`. Para ver exemplos de cada tipo, consulte [Exemplos de `type` de parâmetro de documentos SSM](#top-level-properties-type) na próxima seção.
**nota**
Os documentos do tipo de comando oferecem suporte somente aos tipos de parâmetros `String` e `StringList`.
+ `description`: (opcional) uma descrição do parâmetro.
+ `default`: (opcional) o valor padrão do parâmetro ou uma referência a um parâmetro no Parameter Store.
+ `allowedValues`: (opcional) uma matriz de valores permitidos para o parâmetro. A definição de valores permitidos para o parâmetro valida a entrada do usuário. Se um usuário inserir um valor que não é permitido, a execução falhará ao iniciar.
------
#### [ YAML ]
```
DirectoryType:
type: String
description: "(Required) The directory type to launch."
default: AwsMad
allowedValues:
- AdConnector
- AwsMad
- SimpleAd
```
------
#### [ JSON ]
```
"DirectoryType": {
"type": "String",
"description": "(Required) The directory type to launch.",
"default": "AwsMad",
"allowedValues": [
"AdConnector",
"AwsMad",
"SimpleAd"
]
}
```
------
+ `allowedPattern`: (opcional) uma expressão regular que valida se a entrada do usuário corresponde ao padrão definido para o parâmetro. Se a entrada do usuário não corresponder ao padrão permitido, a execução não será iniciada.
**nota**
O Systems Manager realiza duas validações para `allowedPattern`. A primeira validação é realizada usando a [biblioteca de regex Java](https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html) no nível da API quando você usa um documento. A segunda validação é realizada no SSM Agent usando [a biblioteca de regex GO ](https://pkg.go.dev/regexp) antes de processar o documento.
------
#### [ YAML ]
```
InstanceId:
type: String
description: "(Required) The instance ID to target."
allowedPattern: "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$"
default: ''
```
------
#### [ JSON ]
```
"InstanceId": {
"type": "String",
"description": "(Required) The instance ID to target.",
"allowedPattern": "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$",
"default": ""
}
```
------
+ `displayType`: (opcional) usado para exibir um `textfield` ou uma `textarea` no Console de gerenciamento da AWS. `textfield` é uma caixa de texto de uma única linha. `textarea` é uma área de texto de várias linhas.
+ `minItems`: (opcional) o número mínimo de itens permitidos.
+ `maxItems`: (opcional) o número máximo de itens permitidos.
+ `minChars`: (opcional) o número mínimo de caracteres de parâmetro permitidos.
+ `maxChars`: (opcional) o número máximo de caracteres de parâmetro permitidos.
+ `interpolationType`: (opcional) define como os valores dos parâmetros são processados antes da execução do comando. Quando definido como `ENV_VAR`, o valor do parâmetro é disponibilizado como uma variável de ambiente denominada `SSM_parameter-name`. Esse recurso ajuda a evitar a injeção de comando tratando os valores dos parâmetros como strings literais.
Tipo: string
Valores válidos: `ENV_VAR`
Obrigatório: não
**variables**
(Somente na versão 0.3 do esquema) Valores que podem ser referenciados ou atualizados em todas as etapas em um runbook de automação. As variáveis são semelhantes aos parâmetros, mas diferem de uma forma muito importante. Os valores dos parâmetros são estáticos no contexto de um runbook, mas os valores das variáveis podem ser alterados no contexto do runbook. Ao atualizar o valor de uma variável, o tipo de dados deve corresponder ao tipo de dados definido. Para informações sobre como atualizar valores de variáveis em uma automação, consulte [`aws:updateVariable`: atualiza um valor para uma variável do runbook](automation-action-update-variable.md)
Tipo: Boolean \$1 Integer \$1 MapList \$1 String \$1 StringList \$1 StringMap
Obrigatório: não
```
variables:
payload:
type: StringMap
default: "{}"
```
```
{
"variables": [
"payload": {
"type": "StringMap",
"default": "{}"
}
]
}
```
**runtimeConfig**
(Esquema somente para a versão 1.2) A configuração para a instância conforme aplicada por um ou mais plugins do Systems Manager. Não há garantia de execução dos plugins em sequência.
Tipo: Dictionary
Obrigatório: não
**mainSteps**
(Somente para versões 0.3, 2.0 e 2.2 do esquema) um objeto que pode incluir várias etapas (plugins). Plugins são definidos dentro de etapas. As etapas são executadas na ordem sequencial listada no documento.
Tipo: Dictionary
Obrigatório: Sim
**outputs**
(Somente versão 0.3 do esquema) dados gerados pela execução deste documento que podem ser usados em outros processos. Por exemplo, se o documento criar uma nova AMI, você poderá especificar "CreateImage.ImageId" como o valor de saída e usar essa saída para criar novas instâncias em uma execução de automação subsequente. Para obter mais informações sobre saídas, consulte [Uso de saídas de ações como entradas](automation-action-outputs-inputs.md).
Tipo: Dictionary
Obrigatório: não
**files**
(Somente a versão 0.3 do esquema) os arquivos de script (e as respectivas somas de verificação) anexados ao documento e executados durante uma execução de automação. Aplica-se somente a documentos que incluem a ação `aws:executeScript` e para os quais anexos foram especificados em uma ou mais etapas.
Para saber mais sobre os runtimes compatíveis com os runbooks do Automation, consulte [`aws:executeScript` – Executa um script](automation-action-executeScript.md). Para obter mais informações sobre como incluir scripts em runbooks do Automation, consulte [Uso de scripts em runbooks](automation-document-script-considerations.md) e [Experiência de design visual para runbooks de automação](automation-visual-designer.md).
Ao criar um runbook de automação com anexos, é necessário especificar arquivos de anexo usando a opção `--attachments` (na AWS CLI) ou `Attachments` (na API e no SDK). É possível especificar o local do arquivo para documentos do SSM e arquivos armazenados nos buckets do Amazon Simple Storage Service (Amazon S3). Para obter mais informações, consulte [Anexos](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateDocument.html#systemsmanager-CreateDocument-request-Attachments) na referência da API da AWS Systems Manager.
```
---
files:
launch.py:
checksums:
sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```
```
"files": {
"launch.py": {
"checksums": {
"sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE"
}
}
}
```
Tipo: Dictionary
Obrigatório: não
## Exemplos de `type` de parâmetro de documentos SSM
Os tipos de parâmetro em documentos SSM são estáticos. Isso significa que o tipo de parâmetro não pode ser alterado depois de definido. Ao usar parâmetros com plugins de documento do , o tipo de um parâmetro não pode ser alterado dinamicamente dentro da entrada de um plugin. Por exemplo, você não pode fazer referência a um parâmetro `Integer` dentro da entrada `runCommand` do plugin `aws:runShellScript` porque essa entrada aceita uma string ou lista de strings. Para usar um parâmetro para uma entrada de plugin, o tipo de parâmetro deve corresponder ao tipo aceito. Por exemplo, você deve especificar um parâmetro de tipo `Boolean` para a entrada `allowDowngrade` do plugin `aws:updateSsmAgent`. Se o tipo de parâmetro não corresponder ao tipo de entrada de um plugin, o documento do não será validado e o sistema não criará o documento. Isso também é verdadeiro ao usar parâmetros downstream dentro de entradas para outros plugins ou ações do AWS Systems Manager Automation. Por exemplo, não é possível fazer referência a um parâmetro `StringList` dentro da entrada `documentParameters` do plugin `aws:runDocument`. A entrada `documentParameters` aceita um mapa de strings mesmo que o tipo de parâmetro de documento do SSM downtream seja um parâmetro `StringList` e corresponda ao parâmetro que você está referenciando.
Ao usar parâmetros com ações do Automation do , os tipos de parâmetro não são validados quando você cria o documento SSM na maioria dos casos. Somente quando você usa a ação `aws:runCommand`, os tipos de parâmetro são validados ao criar o documento SSM. Em todos os outros casos, a validação do parâmetro ocorre durante a execução da automação quando a entrada de uma ação é verificada antes de executar a ação. Por exemplo, se o parâmetro de entrada for uma `String` e você fizer referência a ele como o valor da entrada `MaxInstanceCount` da ação `aws:runInstances`, o documento SSM será criado. No entanto, ao executar o documento, a automação falha ao validar a ação `aws:runInstances` porque a entrada `MaxInstanceCount` requer um `Integer`.
Veja a seguir exemplos de cada parâmetro `type`.
String
Uma sequência de zero ou mais caracteres Unicode colocados entre aspas. Por exemplo, "i-1234567890abcdef0". Use barras invertidas como caractere de escape.
Os parâmetros de string podem incluir um campo opcional `interpolationType` com o valor `ENV_VAR` para habilitar a interpolação de variáveis de ambiente para melhorar a segurança.
```
---
InstanceId:
type: String
description: "(Optional) The target EC2 instance ID."
interpolationType: ENV_VAR
```
```
"InstanceId":{
"type":"String",
"description":"(Optional) The target EC2 instance ID.",
"interpolationType": "ENV_VAR"
}
```
StringList
Uma lista de itens de strings separadas por vírgulas. Por exemplo, ["cd \$1", "pwd"].
```
---
commands:
type: StringList
description: "(Required) Specify a shell script or a command to run."
default: ""
minItems: 1
displayType: textarea
```
```
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
}
```
Booleano
Aceita somente `true` ou `false`. Não aceita "true" ou 0.
```
---
canRun:
type: Boolean
description: ''
default: true
```
```
"canRun": {
"type": "Boolean",
"description": "",
"default": true
}
```
Inteiro
Números inteiros. Não aceita números decimais, como 3,14159, ou números colocados entre aspas, como "3".
```
---
timeout:
type: Integer
description: The type of action to perform.
default: 100
```
```
"timeout": {
"type": "Integer",
"description": "The type of action to perform.",
"default": 100
}
```
StringMap
Um mapeamento de chaves para valores. Chaves e valores devem ser strings. Por exemplo, \$1"Env”: “Prod"\$1.
```
---
notificationConfig:
type: StringMap
description: The configuration for events to be notified about
default:
NotificationType: 'Command'
NotificationEvents:
- 'Failed'
NotificationArn: "$dependency.topicArn"
maxChars: 150
```
```
"notificationConfig" : {
"type" : "StringMap",
"description" : "The configuration for events to be notified about",
"default" : {
"NotificationType" : "Command",
"NotificationEvents" : ["Failed"],
"NotificationArn" : "$dependency.topicArn"
},
"maxChars" : 150
}
```
MapList
Uma lista de objetos StringMap.
```
blockDeviceMappings:
type: MapList
description: The mappings for the create image inputs
default:
- DeviceName: "/dev/sda1"
Ebs:
VolumeSize: "50"
- DeviceName: "/dev/sdm"
Ebs:
VolumeSize: "100"
maxItems: 2
```
```
"blockDeviceMappings":{
"type":"MapList",
"description":"The mappings for the create image inputs",
"default":[
{
"DeviceName":"/dev/sda1",
"Ebs":{
"VolumeSize":"50"
}
},
{
"DeviceName":"/dev/sdm",
"Ebs":{
"VolumeSize":"100"
}
}
],
"maxItems":2
}
```
## Visualizar o conteúdo do documento do SSM Command
Para visualizar os parâmetros obrigatórios e opcionais para um documento de comando do AWS Systems Manager (SSM), além das ações executadas pelo documento, você pode visualizar o conteúdo do documento no console do Systems Manager.
**Para visualizar o conteúdo do documento do Comando SSM**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Documents**.
1. Na caixa de pesquisa, selecione **Tipo de documento** e, em seguida, **Comando**.
1. Selecione o nome de um documento existente e, em seguida, escolha a guia **Content** (Conteúdo).
1. No campo de conteúdo, revise os parâmetros disponíveis e as etapas de ação para o documento.
Por exemplo, a seguinte imagem mostra que (1) `version` e (2) `allowDowngrade` são parâmetros opcionais para o documento `AWS-UpdateSSMAgent` e que a primeira ação executada pelo documento é (3) `aws:updateSsmAgent`.
![\[Visualizar o conteúdo do documento do SSM no console do Systems Manager\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/view-document-content.png)
# Referência de plug-ins de documentos de comando
Essa referência descreve os plugins que você pode especificar em um documento de comando do AWS Systems Manager (SSM). Esses plugins não podem ser usados em documentos de automação do SSM que usam ações de automação. Para obter informações sobre ações de automação do AWS Systems Manager, consulte [Referência de ações do Systems Manager Automation](automation-actions.md).
O Systems Manager determina as ações a serem executadas em uma instância gerenciada lendo o conteúdo de um documento do SSM. Todo documento contém uma seção de execução de código. Dependendo da versão do esquema do documento, essa seção de execução de código pode conter um ou mais plugins ou etapas. Para a finalidade deste tópico da Ajuda, plugins e etapas são chamados de *plugins*. Esta seção inclui informações sobre cada um dos plugins do Systems Manager. Para obter mais informações sobre documentos, incluindo informações sobre a criação de documentos e as diferenças entre as versões de esquema, consulte [Documentos do AWS Systems Manager](documents.md).
Para plug-ins que aceitam parâmetros String, como `aws:runShellScript` e `aws:runPowerShellScript`, o parâmetro `interpolationType` pode ser usado para aumentar a segurança, tratando as entradas de parâmetros como literais de string em vez de comandos potencialmente executáveis. Por exemplo:
```
{
"schemaVersion": "2.2",
"description": "runShellScript with command strings stored as Parameter Store parameter",
"parameters": {
"commands": {
"type": "StringList",
"description": "(Required) The commands to run on the instance.",
"default": ["{{ ssm:myShellCommands }}"],
"interpolationType" : "ENV_VAR"
}
},
//truncated
}
```
**nota**
Alguns dos plugins descritos aqui são executados apenas em instâncias do Windows Server ou em instâncias do Linux. São indicadas dependências de plataforma para cada plugin.
Os plugins de documento a seguir são compatíveis com instâncias do Amazon Elastic Compute Cloud (Amazon EC2) para o macOS:
`aws:refreshAssociation`
`aws:runShellScript`
`aws:runPowerShellScript`
`aws:softwareInventory`
`aws:updateSsmAgent`
**Topics**
+ [Entradas compartilhadas](#shared-inputs)
+ [`aws:applications`](#aws-applications)
+ [`aws:cloudWatch`](#aws-cloudWatch)
+ [`aws:configureDocker`](#aws-configuredocker)
+ [`aws:configurePackage`](#aws-configurepackage)
+ [`aws:domainJoin`](#aws-domainJoin)
+ [`aws:downloadContent`](#aws-downloadContent)
+ [`aws:psModule`](#aws-psModule)
+ [`aws:refreshAssociation`](#aws-refreshassociation)
+ [`aws:runDockerAction`](#aws-rundockeraction)
+ [`aws:runDocument`](#aws-rundocument)
+ [`aws:runPowerShellScript`](#aws-runPowerShellScript)
+ [`aws:runShellScript`](#aws-runShellScript)
+ [`aws:softwareInventory`](#aws-softwareinventory)
+ [`aws:updateAgent`](#aws-updateagent)
+ [`aws:updateSsmAgent`](#aws-updatessmagent)
## Entradas compartilhadas
comSSM Agentversão 3.0.502 e posterior somente, todos os plugins podem usar as seguintes entradas:
**finallyStep**
A última etapa que você deseja que o documento seja executado. Se essa entrada for definida para uma etapa, ela terá precedência sobre um`exit`especificado no parâmetro`onFailure`ou`onSuccess`entradas. Para que uma etapa com essa entrada seja executada conforme esperado, a etapa deve ser a última definida no`mainSteps`do documento.
Tipo: booliano
Valores válidos: `true` \$1 `false`
Obrigatório: não
**onFailure**
Se você especificar esta entrada para um plugin com a opção`exit`e a etapa falhar, o status da etapa reflete a falha e o documento não executa as etapas restantes, a menos que um`finallyStep`foi definido. Se você especificar esta entrada para um plugin com a opção`successAndExit`e a etapa falhar, o status da etapa mostra bem-sucedida e o documento não executa as etapas restantes, a menos que um`finallyStep`foi definido.
Tipo: string
Valores válidos: `exit` \$1 `successAndExit`
Obrigatório: não
**onSuccess**
Se você especificar essa entrada para um plugin e a etapa for executada com êxito, o documento não executará nenhuma etapa restante, a menos que um`finallyStep`foi definido.
Tipo: string
Valores válidos: `exit`
Obrigatório: não
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: Shared inputs example
parameters:
customDocumentParameter:
type: String
description: Example parameter for a custom Command-type document.
mainSteps:
- action: aws:runDocument
name: runCustomConfiguration
inputs:
documentType: SSMDocument
documentPath: "yourCustomDocument"
documentParameters: '"documentParameter":{{customDocumentParameter}}'
onSuccess: exit
- action: aws:runDocument
name: ifConfigurationFailure
inputs:
documentType: SSMDocument
documentPath: "yourCustomRepairDocument"
onFailure: exit
- action: aws:runDocument
name: finalConfiguration
inputs:
documentType: SSMDocument
documentPath: "yourCustomFinalDocument"
finallyStep: true
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Shared inputs example",
"parameters": {
"customDocumentParameter": {
"type": "String",
"description": "Example parameter for a custom Command-type document."
}
},
"mainSteps":[
{
"action": "aws:runDocument",
"name": "runCustomConfiguration",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomDocument",
"documentParameters": "\"documentParameter\":{{customDocumentParameter}}",
"onSuccess": "exit"
}
},
{
"action": "aws:runDocument",
"name": "ifConfigurationFailure",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomRepairDocument",
"onFailure": "exit"
}
},
{
"action": "aws:runDocument",
"name":"finalConfiguration",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomFinalDocument",
"finallyStep": true
}
}
]
}
```
------
## `aws:applications`
Instala, repara ou desinstala aplicativos em uma instância do EC2. Este plugin é executado somente em sistemas operacionais Windows Server.
### Sintaxe
#### Esquema 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:applications plugin
parameters:
source:
description: "(Required) Source of msi."
type: String
mainSteps:
- action: aws:applications
name: example
inputs:
action: Install
source: "{{ source }}"
```
------
#### [ JSON ]
```
{
"schemaVersion":"2.2",
"description":"aws:applications",
"parameters":{
"source":{
"description":"(Required) Source of msi.",
"type":"String"
}
},
"mainSteps":[
{
"action":"aws:applications",
"name":"example",
"inputs":{
"action":"Install",
"source":"{{ source }}"
}
}
]
}
```
------
#### Esquema 1.2
------
#### [ YAML ]
```
---
runtimeConfig:
aws:applications:
properties:
- id: 0.aws:applications
action: "{{ action }}"
parameters: "{{ parameters }}"
source: "{{ source }}"
sourceHash: "{{ sourceHash }}"
```
------
#### [ JSON ]
```
{
"runtimeConfig":{
"aws:applications":{
"properties":[
{
"id":"0.aws:applications",
"action":"{{ action }}",
"parameters":"{{ parameters }}",
"source":"{{ source }}",
"sourceHash":"{{ sourceHash }}"
}
]
}
}
}
```
------
### Propriedades
**ação**
A medida a ser tomada.
Tipo: Enum
Valores válidos: `Install` \$1 `Repair` \$1 `Uninstall`
Obrigatório: Sim
**parameters**
Os parâmetros para o instalador.
Tipo: string
Obrigatório: não
**origem**
O URL do arquivo `.msi` para o aplicativo.
Tipo: String
Exigido: sim
**sourceHash**
O hash SHA256 do arquivo `.msi`.
Tipo: string
Obrigatório: não
## `aws:cloudWatch`
Exporte dados do Windows Server para o Amazon CloudWatch ou Amazon CloudWatch Logs e monitore os dados usando as métricas do CloudWatch. Este plugin é executado somente em sistemas operacionais Windows Server. Para obter mais informações sobre como configurar a integração do CloudWatch, ao Amazon Elastic Compute Cloud (Amazon EC2) consulte [Coletar métricas, logs e rastreamentos com o atendente do CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) no *Guia de usuário do Amazon CloudWatch*.
**Importante**
O atendente unificado do CloudWatch substituiu SSM Agent como a ferramenta para enviar dados de log para o Amazon CloudWatch Logs. Não há compatibilidade com o plugin aws:cloudWatch do SSM Agent. Recomendamos usar somente o atendente do CloudWatch unificado nos processos de coleta de logs. Para saber mais, consulte os seguintes tópicos:
[Enviar logs de nós para o CloudWatch Logs unificado (agente do CloudWatch)](monitoring-cloudwatch-agent.md)
[Migrar a coleta de logs de nós do Windows Server para o agente do CloudWatch](monitoring-cloudwatch-agent.md#monitoring-cloudwatch-agent-migrate)
[Coletar métricas, logs e rastreamentos com o atendente do CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) no *Guia do usuário do Amazon CloudWatch*.
Você pode exportar e monitorar os seguintes tipos de dados:
**ApplicationEventLog**
Envia dados de log de eventos da aplicação para o CloudWatch Logs.
**CustomLogs**
Envia qualquer arquivo de log baseado em texto para o Amazon CloudWatch Logs. O plugin do CloudWatch cria uma impressão digital para os arquivos de log. O sistema associa então um deslocamento de dados com cada impressão digital. O plugin faz upload dos arquivos quando há alterações, registra o deslocamento e associa o deslocamento com uma impressão digital. Esse método é usado para evitar uma situação em que um usuário ativa o plugin, associa o serviço com um diretório que contém um grande número de arquivos, e o sistema faz upload de todos os arquivos.
Lembre-se de que, se seu aplicativo truncar ou tentar limpar os logs durante a sondagem, qualquer log especificado para `LogDirectoryPath` pode perder entradas. Se, por exemplo, você quiser limitar o tamanho do arquivo de log, crie um novo arquivo de log quando o limite for atingido e continue a gravar dados no novo arquivo.
**ETW**
Envia os dados de rastreamento de eventos para Windows (ETW) ao CloudWatch Logs.
**IIS**
Envia dados de log do IIS ao CloudWatch Logs.
**PerformanceCounter**
Envia contadores de performance do Windows para o CloudWatch. Você poderá selecionar categorias diferentes para fazer upload no CloudWatch como métricas. Para cada contador de performance que você deseja carregar, crie uma seção **PerformanceCounter** com um ID exclusivo (por exemplo, "PerformanceCounter2", "PerformanceCounter3" e assim por diante) e configure as respectivas propriedades.
Se o AWS Systems Manager SSM Agent ou o plugin do CloudWatch for interrompido, os dados do contador de performance não serão registrados em log no CloudWatch. Esse comportamento é diferente daquele dos logs personalizados ou dos logs de eventos do Windows. Os logs personalizados e logs de eventos do Windows preservarão dados do contador de performance e farão upload dos dados no CloudWatch depois que o SSM Agent ou o plugin do CloudWatch estiver disponível.
**SecurityEventLog**
Envia dados de log de eventos de segurança para o CloudWatch Logs.
**SystemEventLog**
Envia dados de log de eventos de sistema ao CloudWatch Logs
Você pode definir os seguintes destinos para os dados:
**CloudWatch**
O destino para o qual os dados de métrica do contador de performance são enviados. Você pode incluir mais seções com IDs exclusivos (por exemplo, "CloudWatch2", "CloudWatch3" etc.) e especificar uma região diferente para cada novo ID a fim de enviar os mesmos dados para diferentes locais.
**CloudWatchLogs**
O destino para o qual os dados de log são enviados. Você pode incluir mais seções com IDs exclusivos (por exemplo, "CloudWatchLogs2", "CloudWatchLogs3" etc.) e especificar uma região diferente para cada novo ID a fim de enviar os mesmos dados para diferentes locais.
### Sintaxe
```
"runtimeConfig":{
"aws:cloudWatch":{
"settings":{
"startType":"{{ status }}"
},
"properties":"{{ properties }}"
}
}
```
### Configurações e propriedades
**AccessKey**
Sua ID de chave de acesso. Essa propriedade é obrigatória, a menos que você tenha lançado sua instância usando uma função do IAM. Essa propriedade não pode ser usada com o SSM.
Tipo: string
Obrigatório: não
**CategoryName**
A categoria de contador de performance no Performance Monitor.
Tipo: String
Exigido: sim
**CounterName**
O nome do contador de performance no Performance Monitor.
Tipo: String
Exigido: sim
**CultureName**
O local em que o time stamp é registrado. Se **CultureName** estiver em branco, o mesmo local usado atualmente por sua instância do Windows Server será usado como o padrão.
Tipo: string
Valores válidos: para obter uma lista de valores comportados, consulte [National Language Support (NLS)](https://msdn.microsoft.com/en-us/library/cc233982.aspx) no site da Microsoft. Os valores **div**, **div-MV**, **hu** e **hu-HU** não são compatíveis.
Obrigatório: não
**DimensionName**
Uma dimensão para sua métrica do Amazon CloudWatch. Se você especificar `DimensionName`, também deverá especificar `DimensionValue`. Esses parâmetros produzem outro modo de exibição para a listagem de métricas. Você pode usar a mesma dimensão para várias métricas de modo a visualizar todas as métricas que pertencem a uma dimensão específica.
Tipo: string
Obrigatório: não
**DimensionValue**
Um valor de dimensão para a métrica do Amazon CloudWatch.
Tipo: string
Obrigatório: não
**Codificação**
A codificação de arquivo a ser usada (por exemplo, UTF-8). Use o nome da codificação, não o nome da exibição.
Tipo: string
Valores válidos: para obter uma lista de valores comportados, consulte [Encoding Class](https://learn.microsoft.com/en-us/dotnet/api/system.text.encoding?view=net-7.0) na biblioteca Microsoft Learn.
Obrigatório: Sim
**Filtro**
O prefixo dos nomes de log. Deixe esse parâmetro em branco para monitorar todos os arquivos.
Tipo: string
Valores válidos: para obter uma lista de valores compatíveis, consulte [FileSystemWatcherFilter property](http://msdn.microsoft.com/en-us/library/system.io.filesystemwatcher.filter.aspx) na biblioteca do MSDN.
Obrigatório: não
**Fluxos**
Cada tipo de dados para fazer upload, bem como o destino dos dados (CloudWatch ou CloudWatch Logs). Por exemplo, para enviar um contador de performance definido de acordo com `"Id": "PerformanceCounter"` para o destino do CloudWatch definido em `"Id": "CloudWatch"`, insira **"PerformanceCounter,CloudWatch"**. Da mesma forma, para enviar o log personalizado, o log do ETW e o log do sistema para o destino do CloudWatch Logs definido em `"Id": "ETW"`, insira **“(ETW),CloudWatchLogs”**. Além disso, é possível enviar o mesmo contador de performance ou arquivo de log para mais de um destino. Por exemplo, para enviar o log do aplicativo para dois destinos diferentes que você definiu em `"Id": "CloudWatchLogs"` e `"Id": "CloudWatchLogs2"`, insira **"ApplicationEventLog, (CloudWatchLogs, CloudWatchLogs2)"**.
Tipo: string
Valores válidos (origem): `ApplicationEventLog` \$1 `CustomLogs` \$1 `ETW` \$1 `PerformanceCounter` \$1 `SystemEventLog` \$1 `SecurityEventLog`
Valores válidos (destino): `CloudWatch` \$1 `CloudWatchLogs` \$1 `CloudWatch`*n* \$1 `CloudWatchLogs`*n*
Obrigatório: Sim
**FullName**
O nome completo do componente.
Tipo: String
Exigido: sim
**Id**
Identifica a origem de dados ou o destino. Esse identificador deve ser exclusivo no arquivo de configuração.
Tipo: String
Exigido: sim
**InstanceName**
O nome da instância do contador de performance. Não use um asterisco (\$1) para indicar todas as instâncias, pois cada componente do contador de performance só é compatível com uma única métrica. Você pode, porém, usar **\$1Total**.
Tipo: String
Exigido: sim
**Níveis**
Os tipos de mensagem a enviar para o Amazon CloudWatch.
Tipo: string
Valores válidos:
+ **1** - Somente o upload de mensagens de erro.
+ **2** - Somente o upload de mensagens de aviso.
+ **4** - Somente o upload de mensagens de informação.
Observe que você pode adicionar valores para incluir mais de um tipo de mensagem. Por exemplo, **3** significa que mensagens de erro (**1**) e mensagens de aviso (**2**) estão incluídas. Um valor de **7** significa que mensagens de erro (**1**), mensagens de aviso (**2**) e mensagens informativas (**4**) estão incluídas.
Obrigatório: Sim
Os logs de segurança do Windows devem definir os níveis como 7.
**LineCount**
O número de linha no cabeçalho para identificar o arquivo de log. Por exemplo, os arquivos de log do IIS têm cabeçalhos praticamente idênticos. Você pode especificar **3**, que leria as três primeiras linhas do cabeçalho do arquivo de log para identificá-lo. Em arquivos de log do IIS, a terceira linha é o time stamp que é diferente entre arquivos de log.
Tipo: inteiro
Obrigatório: não
**LogDirectoryPath**
Em CustomLogs, o caminho em que os logs são armazenados na instância do EC2. Para logs do IIS, a pasta em que os logs do IIS são armazenados para um site específico (por exemplo, **C:\$1\$1inetpub\$1\$1logs\$1\$1LogFiles\$1\$1W3SVC*n***). Para logs do IIS, somente o formato de log W3C é comportado. Não há suporte para os formatos IIS, NCSA e Personalizado.
Tipo: String
Exigido: sim
**LogGroup**
O nome para o seu grupo de logs. Esse nome é exibido na tela **Log Groups** (Grupos de logs) no console do CloudWatch.
Tipo: String
Exigido: sim
**LogName**
O nome do arquivo de log.
1. Para encontrar o nome do log, no Visualizador de Eventos, no painel de navegação, clique em **Logs de aplicações e serviços**.
1. Na lista de logs, clique com o botão direito do mouse no log do qual você deseja fazer upload (por exemplo, `Microsoft` > `Windows` > `Backup` > `Operational`) e clique em **Criar Modo de Exibição Personalizado**.
1. Na caixa de diálogo **Create Custom View** (Criar modo de exibição personalizado), selecione a guia **XML**. O **LogName** está na tag