Como programar associações Criar uma associação (console)Criar uma associação (linha de comando)

Criar associações

O State Manager, um recurso do AWS Systems Manager, ajuda você a manter seu recursos da AWS em um estado que você define e reduz o desvio de configuração. Para fazer isso, o State Manager usa associações. Uma associação é uma configuração que você atribui aos seus recursos da AWS. A configuração define o estado que você deseja manter em seus recursos. Por exemplo, uma associação pode especificar que o software antivírus deve estar instalado e em execução nas instâncias ou que determinadas portas devem ser fechadas.

Uma associação especifica uma programação para quando aplicar a configuração e destinos para a associação. Por exemplo, uma associação a um software antivírus pode ser executada uma vez por dia em uma Conta da AWS. Se o software não estiver instalado em um nó, a associação poderá instruir o State Manager para instalá-lo. Se o software estiver instalado, mas o serviço não estiver em execução, a associação poderá instruir o State Manager a iniciar o serviço.

Atenção

Ao criar uma associação, você pode escolher um grupo de recursos da AWS de nós gerenciados como o destino da associação. Se um usuário do AWS Identity and Access Management (IAM), grupo ou função tem permissão para criar uma associação direcionada a um grupo de recursos de nós gerenciados, então esse usuário, grupo ou função automaticamente tem controle em nível raiz de todos os nós do grupo. Permitir somente administradores confiáveis criarem associações.

Destino de associação e controles de taxa

Uma associação especifica quais nós gerenciados, ou destinos, devem receber a associação. O State Manager inclui diversos recursos para ajudar você a direcionar os nós gerenciados e controlar como a associação é implantada para esses destinos. Para obter mais informações sobre destinos e controles de taxa, consulte Sobre destinos e controles de taxa em associações do State Manager.

Como marcar associações

É possível atribuir tags a uma associação ao criá-la usando uma ferramenta de linha de comando, como a AWS CLI ou AWS Tools for PowerShell. Não há suporte à adição de tags a uma associação usando o console do Systems Manager.

Como executar associações

Por padrão, o State Manager executa uma associação imediatamente após a criação e, em seguida, de acordo com a programação que você definiu.

O sistema também executa associações de acordo com as regras a seguir:

O State Manager tenta executar a associação em todos os nós especificados ou direcionados durante um intervalo.
Se uma associação não for executada durante um intervalo (porque, por exemplo, um valor de simultaneidade limita o número de nós que podem processar a associação de uma só vez), o State Manager tentará executar a associação durante o próximo intervalo.
O State Manager executa a associação após alterações na configuração, nos nós de destino, nos documentos ou nos parâmetros da associação. Para ter mais informações, consulte Noções básicas sobre quando associações são aplicadas a recursos.
O State Manager registra o histórico de todos os intervalos ignorados. Você pode visualizar o histórico na guia Execution History.

Como programar associações

É possível programar associações para serem executadas em intervalos básicos, como a cada dez horas, ou criar programações mais avançadas usando expressões “cron” e “rate” personalizadas. Também é possível impedir que as associações sejam executadas ao criá-las pela primeira vez.

Como usar expressões “cron” e “rate” para programar execuções de associação

Além das expressões “cron” e “rate” padrão, o State Manager também oferece suporte para expressões “cron” que incluem um dia da semana e o sinal numérico (#) para designar o enésimo dia de um mês para a execução de uma associação. Aqui está um exemplo que executa uma programação do cron na terceira terça-feira de cada mês às 23h30 UTC:

cron(30 23 ? * TUE#3 *)

Aqui está um exemplo que acontece na segunda quinta-feira de cada mês à meia-noite UTC:

cron(0 0 ? * THU#2 *)

O State Manager também oferece suporte ao sinal (L) para indicar o último dia X do mês. Aqui está um exemplo que executa uma programação do cron na última terça-feira de cada mês à meia-noite UTC:

cron(0 0 ? * 3L *)

Para controlar ainda mais quando uma associação é executada, por exemplo, se você quiser executar uma associação dois dias após o patch de terça-feira, você pode especificar um deslocamento. Um deslocamento define quantos dias esperar após o dia programado para executar uma associação. Por exemplo, se você especificou uma programação do cron de cron(0 0 ? * THU#2 *), você pode especificar o número 3 no campo Schedule offset (Deslocamento da programação) para executar a associação todos os domingos após a segunda quinta-feira do mês.

nota

Para usar deslocamentos, é necessário selecionar Aplicar associação somente no próximo intervalo Cron especificado no console ou especificar o parâmetro ApplyOnlyAtCronInterval na linha de comando. Quando uma dessas opções está ativada, o State Manager não executa a associação imediatamente após a criação.

Para obter mais informações sobre expressões cron e rate, consulte Referência: Expressões cron e rate para o Systems Manager.

Criar uma associação (console)

O procedimento a seguir descreve como usar o console do Systems Manager para criar uma associação do State Manager.

Importante

Este procedimento descreve como criar uma associação que usa um documento Command ou Policy para direcionar nós gerenciados. Para obter informações sobre como criar uma associação que usa um runbook de automação para direcionar nós ou outros tipos de recursos da AWS, consulteProgramação de automações com associações do State Manager.

Como criar uma associação do State Manager

Abra o console do AWS Systems Manager em https://console.aws.amazon.com/systems-manager/.
No painel de navegação, escolha State Manager.
Selecione Criar associação.
No campo Name, especifique um nome.
Na lista Document (Documento), escolha a opção ao lado do nome de um documento. Observe o tipo de documento. Este procedimento aplica-se apenas a documentos Command e Policy. Para obter informações sobre como criar uma associação que usa um documento do runbook de Automação, consulte Programação de automações com associações do State Manager.

Importante
O State Manager não é compatível com a execução de associações que usam uma nova versão de um documento se esse documento for compartilhado de outra conta. O State Manager sempre executa a versão default de um documento se compartilhada de outra conta, mesmo que o console do Systems Manager mostre que uma nova versão foi processada. Se você quiser executar uma associação usando uma nova versão de um documento compartilhado de outra conta, deverá definir a versão do documento como default.
Em Parameters (Parâmetros), especifique os parâmetros de entrada obrigatórios.
(Opcional) Escolha um alarme do CloudWatch para aplicar à sua associação para monitoramento.
nota
Observe as informações a seguir sobre esta etapa.
- A lista de alarmes exibe um máximo de 100 alarmes. Se você não vir o alarme na lista, use a AWS Command Line Interface para criar a associação. Para obter mais informações, consulte Criar uma associação (linha de comando).
- Para anexar um alarme do CloudWatch ao seu comando, a entidade principal do IAM que cria a associaçã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.
- Se o alarme for ativado, quaisquer invocações ou automações de comando pendentes não serão executadas.
Em Targets (Destinos), escolha uma opção. Para obter informações sobre como usar destinos, consulte Sobre destinos e controles de taxa em associações do State Manager.

nota
Para que as associações criadas com os runbooks do Automation sejam aplicadas quando novos nós de destino são detectados, algumas condições específicas devem ser atendidas. Para ter mais informações, consulte Sobre as atualizações de destino com runbooks do Automation.
Na seção Specify schedule (Especificar programação), escolha On Schedule (Na programação) ou No schedule (Sem programação). Se você escolher On Schedule (Na programação), use os botões fornecidos para criar uma programação cron ou rate para a associação.

Se você não quiser que a associação seja executada imediatamente após ser criada, selecione Aplicar associação somente no próximo intervalo Cron especificado.
(Opcional) No campo Schedule offset (Deslocamento da programação), especifique um número entre 1 e 6.
Na seção Advanced options (Opções avançadas), use Compliance severity (Gravidade de conformidade) para escolher um nível de gravidade para a associação e use Change Calendars (Alterar calendários) para escolher um calendário de alteração para a associação.

Relatórios de conformidade indicam se o estado é compatível ou não, juntamente com o nível de gravidade que você indicar aqui. Para obter mais informações, consulte Sobre a conformidade de associações do State Manager.

O calendário de alteração determina quando a associação é executada. Se o calendário estiver fechado, a associação não será aplicada. Se o calendário estiver aberto, a associação será executada apropriadamente. Para obter mais informações, consulte AWS Systems Manager Change Calendar.
Na seção Rate control (Controle de taxa), escolha opções para controlar como a associação é executada em vários nós. Para obter mais informações sobre como usar controles de taxa, consulte Sobre destinos e controles de taxa em associações do State Manager.

Na seção Concurrency (Simultaneidade), escolha uma opção:
- Escolha Targets (Destinos) para inserir um número absoluto de destinos que podem executar a associação simultaneamente.
- Escolha Percentage (Porcentagem) para inserir uma porcentagem do conjunto de destino que pode executar a associação simultaneamente.
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 de o State Manager parar de executar associações em destinos adicionais.
- Escolha percentage (porcentagem) para inserir uma porcentagem de erros permitidos antes de o State Manager parar de executar associações em destinos adicionais.
(Opcional) Em Opções de saída, para salvar a saída de comando em um arquivo, selecione a caixa Habilitar a gravação da saída no S3. Digite os nomes de bucket e prefixo (pastas) nas caixas de texto.

nota
As permissões do S3 que concedem a possibilidade de gravar os dados em um bucket do S3 são as do perfil da instância atribuído ao nó gerenciado, e não as do usuário do IAM que realiza essa tarefa. Para obter mais informações, consulte Configurar permissões de instância obrigatórias para o Systems Manager ou Criar um perfil de serviço do IAM para um ambiente híbrido. Além disso, se o bucket do S3 especificado estiver em uma conta da Conta da AWS diferente, verifique se o perfil da instância ou a função de serviço IAM associada ao nó gerenciado tenha as permissões necessárias para gravar nesse bucket.

A seguir estão as permissões mínimas necessárias para ativar a saída do Amazon S3 para uma associação. É possível restringir ainda mais o acesso ao anexar políticas do IAM a usuários ou perfis em uma conta. No mínimo, um perfil de instância do Amazon EC2 deve ter uma função do IAM com a política gerenciada do AmazonSSMManagedInstanceCore e a política inline a seguir.
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
        }
    ]
}
```
Para permissões mínimas, o bucket do Amazon S3 para o qual você exporta deve ter as configurações padrão definidas pelo console do Amazon S3. Para obter mais informações sobre como criar buckets do Amazon S3, consulte Criar um bucket, no Guia do usuário do console do Amazon S3.

nota
As operações de API iniciadas pelo documento SSM durante uma execução de associação não são registradas em log no AWS CloudTrail.
Escolha Create Association (Criar associação).

nota

Se você excluir a associação criada, a associação não será mais executada em nenhum destino dessa associação.

Criar uma associação (linha de comando)

O seguinte procedimento descreve como usar a AWS CLI (no Linux ou no Windows) ou o Tools for PowerShell para criar uma associação do State Manager. Esta seção inclui vários exemplos que mostram como usar destinos e controles de taxa. Destinos e controles de taxa permitem atribuir uma associação a dezenas ou centenas de nós enquanto controla a execução dessas associações. Para obter mais informações sobre destinos e controles de taxa, consulte Sobre destinos e controles de taxa em associações do State Manager.

Importante

Antes de começar

O parâmetro targets é uma matriz de critérios de pesquisa que segmenta nós usando uma combinação Key,Value especificada por você. Se você planeja criar uma associação em dezenas ou centenas de nós usando o parâmetro targets, revise as seguintes opções de direcionamento antes de iniciar o procedimento.

Direcionar nós específicos especificando IDs


--targets Key=InstanceIds,Values=instance-id-1,instance-id-2,instance-id-3


--targets Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE,i-07782c72faEXAMPLE

Direcionar instâncias usando tags do


--targets Key=tag:tag-key,Values=tag-value-1,tag-value-2,tag-value-3


--targets Key=tag:Environment,Values=Development,Test,Pre-production

Direcionar nós usando AWS Resource Groups


--targets Key=resource-groups:Name,Values=resource-group-name


--targets Key=resource-groups:Name,Values=WindowsInstancesGroup

Direcionar todas as instâncias na Conta da AWS e Região da AWS atuais


--targets Key=InstanceIds,Values=*

nota

Observe as seguintes informações:

O State Manager não é compatível com a execução de associações que usam uma nova versão de um documento se esse documento for compartilhado de outra conta. O State Manager sempre executa a versão default de um documento se compartilhada de outra conta, mesmo que o console do Systems Manager mostre que uma nova versão foi processada. Se você quiser executar uma associação usando uma nova versão de um documento compartilhado de outra conta, você deverá definir a versão do documento como default.
É possível especificar no máximo cinco chaves de etiqueta usando a AWS CLI. Se você usar a AWS CLI, todas as chaves de etiqueta especificadas no comando create-association deverão estar atualmente atribuídas ao nó. Se não estiverem, o State Manager falhará em direcionar o nó para uma associação.
Ao criar uma associação, você especifica quando a programação é executada. Você deve especificar a programação usando uma expressão cron ou rate. Para obter mais informações sobre expressões cron e rate, consulte Expressões cron e rate para associações.
Para que as associações criadas com os runbooks do Automation sejam aplicadas quando novos nós de destino são detectados, algumas condições específicas devem ser atendidas. Para ter mais informações, consulte Sobre as atualizações de destino com runbooks do Automation.

Como criar uma associação

Instale e configure a AWS CLI ou o AWS Tools for PowerShell, caso ainda não o tenha feito.

Para obter informações, consulte Instalar ou atualizar a versão mais recente da AWS CLI e Instalar o AWS Tools for PowerShell.

Use o seguinte formato para criar um comando que cria uma associação do State Manager. Substitua cada espaço reservado para recurso de exemplo por suas próprias informações.

Linux & macOS


aws ssm create-association \
    --name document_name \
    --document-version version_of_document_applied \
    --instance-id instances_to_apply_association_on \
    --parameters (if any) \
    --targets target_options \
    --schedule-expression "cron_or_rate_expression" \
    --apply-only-at-cron-interval required_parameter_for_schedule_offsets \
    --schedule-offset number_between_1_and_6 \
    --output-location s3_bucket_to_store_output_details \
    --association-name association_name \
    --max-errors a_number_of_errors_or_a_percentage_of_target_set \
    --max-concurrency a_number_of_instances_or_a_percentage_of_target_set \
    --compliance-severity severity_level \
    --calendar-names change_calendar_names \
    --target-locations aws_region_or_account \
    --tags "Key=tag_key,Value=tag_value"

Windows


aws ssm create-association ^
    --name document_name ^
    --document-version version_of_document_applied ^
    --instance-id instances_to_apply_association_on ^
    --parameters (if any) ^
    --targets target_options ^
    --schedule-expression "cron_or_rate_expression" ^
    --apply-only-at-cron-interval required_parameter_for_schedule_offsets ^
    --schedule-offset number_between_1_and_6 ^
    --output-location s3_bucket_to_store_output_details ^
    --association-name association_name ^
    --max-errors a_number_of_errors_or_a_percentage_of_target_set ^
    --max-concurrency a_number_of_instances_or_a_percentage_of_target_set ^
    --compliance-severity severity_level ^
    --calendar-names change_calendar_names ^
    --target-locations aws_region_or_account ^
    --tags "Key=tag_key,Value=tag_value"

PowerShell


New-SSMAssociation `
    -Name document_name `
    -DocumentVersion version_of_document_applied `
    -InstanceId instances_to_apply_association_on `
    -Parameters (if any) `
    -Target target_options `
    -ScheduleExpression "cron_or_rate_expression" `
    -ApplyOnlyAtCronInterval required_parameter_for_schedule_offsets `
    -ScheduleOffSet number_between_1_and_6 `
    -OutputLocation s3_bucket_to_store_output_details `
    -AssociationName association_name `
    -MaxError  a_number_of_errors_or_a_percentage_of_target_set
    -MaxConcurrency a_number_of_instances_or_a_percentage_of_target_set `
    -ComplianceSeverity severity_level `
    -CalendarNames change_calendar_names `
    -TargetLocations aws_region_or_account `
    -Tags "Key=tag_key,Value=tag_value"

O exemplo a seguir cria uma associação em nós marcados com "Environment,Linux". A associação usa o documento AWS-UpdateSSMAgent para atualizar o SSM Agent nos nós marcados todo domingo às 2h UTC. Essa associação é executada simultaneamente em um máximo de 10 nós a qualquer momento. Além disso, essa associação tem a execução interrompida em mais nós para um intervalo de execução específico se a contagem de erros exceder 5. Para relatórios de conformidade, essa associação recebe o nível de gravidade Médio.

O exemplo a seguir direciona IDs de nós, especificando um valor curinga (*). Isso permite que o Systems Manager crie uma associação em todos os nós na Conta da AWS e Região da AWS atuais. Essa associação é executada simultaneamente em um máximo de 10 nós a qualquer momento. Além disso, essa associação tem a execução interrompida em mais nós para um intervalo de execução específico se a contagem de erros exceder 5. Para relatórios de conformidade, essa associação recebe o nível de gravidade Médio. Essa associação usa um deslocamento de programação, o que significa que ela é executada dois dias após a programação do cron especificada. Ela também inclui o ApplyOnlyAtCronInterval, que é necessário para usar o deslocamento da programação, e que indica que a associação não será executada imediatamente após a sua criação.

O exemplo a seguir cria uma associação em nós em grupos de recurso. O grupo é chamado de “Departamento de RH”. A associação usa o documento AWS-UpdateSSMAgent para atualizar o SSM Agent nos nós marcados todo domingo às 2h UTC. Essa associação é executada simultaneamente em um máximo de 10 nós a qualquer momento. Além disso, essa associação tem a execução interrompida em mais nós para um intervalo de execução específico se a contagem de erros exceder 5. Para relatórios de conformidade, essa associação recebe o nível de gravidade Médio. Essa associação será executada na programação de cron especificada. Ela não será executada imediatamente após criação da associação.

O exemplo a seguir cria uma associação que é executada em nós marcados com um ID de nó específico. A associação usa o documento SSM Agent para atualizar o SSM Agent nos nós de destino uma vez quando o calendário de alteração está aberto. A associação verifica o estado do calendário quando é executado. Se o calendário estiver fechado no momento do lançamento e a associação for executada apenas uma vez, ela não será executada novamente porque a janela de execução da associação já haverá passado. Se o calendário estiver aberto, a associação será executada apropriadamente.

nota

Se você adicionar novos nós às tags ou grupos de recursos nos quais uma associação atua quando o calendário de alteração for fechado, a associação será aplicada a esses nós assim que o calendário de alteração for aberto.

O exemplo a seguir cria uma associação que é executada em nós marcados com um ID de nó específico. A associação usa o documento SSM Agent para atualizar o SSM Agent nos nós marcados todo domingo às 2h UTC. Essa associação será executada somente na programação do cron especificada, quando o calendário de alterações for aberto. Quando a associação é criada, ela verifica o estado do calendário. Se o calendário estiver fechado, a associação não será aplicada. Quando o intervalo para aplicar a associação começa às 2:00 da manhã de domingo, a associação verifica se o calendário está aberto. Se o calendário estiver aberto, a associação será executada apropriadamente.

nota

Se você excluir a associação criada, a associação não será mais executada em nenhum destino dessa associação. Além disso, se você especificou o parâmetro apply-only-at-cron-interval, poderá redefinir essa opção. Para fazer isso, especifique o parâmetro no-apply-only-at-cron-interval ao atualizar a associação pela linha de comando. Este parâmetro força a execução da associação imediatamente após a atualização da associação e de acordo com o intervalo especificado.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Noções básicas sobre destinos e controles de taxa

Edite uma associação