Execução de comandos em escala - AWS Systems Manager

Execução de comandos em escala

É possível usar Run Command, um recurso de AWS Systems Manager, para executar comandos em uma frota de nós gerenciados usando targets. O parâmetro targets aceita uma combinação Key,Value baseada em etiquetas que você especificou para seus nós gerenciados. Quando você executa o comando, o sistema localiza e tenta executar o comando em todos os nós gerenciados que correspondem às etiquetas especificadas. Para obter mais informações sobre como etiquetar instâncias gerenciadas, consulte Tagging your AWS resources no Guia do usuário de recursos de marcação da AWS. Para obter informações sobre como marcar os dispositivos IoT gerenciados, consulte Marcar com etiqueta os recursos do AWS IoT Greengrass Version 2 no Guia do desenvolvedor do AWS IoT Greengrass Version 2.

Você também pode usar o parâmetro targets para direcionar uma lista de IDs de nós gerenciados específicos, conforme descrito na próxima seção.

Para controlar como os comandos são executados em centenas ou milhares de nós gerenciados, o Run Command também inclui parâmetros para restringir quantos nós podem processar simultaneamente uma solicitação e quantos erros podem ser gerados por um comando antes que ele seja cancelado.

Selecionar vários nós gerenciados como destino

Você pode executar um comando e os nós gerenciados de destino especificando etiquetas, nomes de grupos de recursos da AWS ou IDs dos nós gerenciados.

Os exemplos a seguir mostram o formato do comando ao usar o Run Command do AWS Command Line Interface (AWS CLI). Substitua cada espaço reservado para recurso de exemplo por suas próprias informações. Os comandos de exemplo nesta seção são truncados usando [...].

Exemplo 1: direcionar tags

Linux & macOS
aws ssm send-command \ --document-name document-name \ --targets Key=tag:tag-name,Values=tag-value \ [...]
Windows
aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:tag-name,Values=tag-value ^ [...]

Exemplo 2: direcionar um grupo de recursos da AWS por nome

Você pode especificar um máximo de um nome de grupo de recursos por comando. Ao criar um grupo de recursos, recomendamos incluir AWS::SSM:ManagedInstance e AWS::EC2::Instance como tipos de recurso em seus critérios de agrupamento.

nota

Para enviar comandos que têm um grupo de recursos como destino, você deverá ter recebido permissões do AWS Identity and Access Management (IAM) para listar ou visualizar os recursos que pertencem a esse grupo. Para obter mais informações, consulte Configurar permissões no Guia do usuário do AWS Resource Groups.

Linux & macOS
aws ssm send-command \ --document-name document-name \ --targets Key=resource-groups:Name,Values=resource-group-name \ [...]
Windows
aws ssm send-command ^ --document-name document-name ^ --targets Key=resource-groups:Name,Values=resource-group-name ^ [...]

Exemplo 3: direcionar um grupo de recursos da AWS por tipo de recurso

Você pode especificar um máximo de cinco tipos de grupo de recursos por comando. Ao criar um grupo de recursos, recomendamos incluir AWS::SSM:ManagedInstance e AWS::EC2::Instance como tipos de recurso em seus critérios de agrupamento.

nota

Para enviar comandos que têm um grupo de recursos como destino, você deverá ter recebido permissões do IAM para listar ou visualizar os recursos que pertencem a esse grupo. Para obter mais informações, consulte Configurar permissões no Guia do usuário do AWS Resource Groups.

Linux & macOS
aws ssm send-command \ --document-name document-name \ --targets Key=resource-groups:ResourceTypeFilters,Values=resource-type-1,resource-type-2 \ [...]
Windows
aws ssm send-command ^ --document-name document-name ^ --targets Key=resource-groups:ResourceTypeFilters,Values=resource-type-1,resource-type-2 ^ [...]

Exemplo 4: IDs de instâncias como destino

Os exemplos a seguir mostram como direcionar os nós gerenciados usando a chave instanceids com o parâmetro targets. Você pode usar essa chave para utilizar os dispositivos principais do AWS IoT Greengrass porque cada dispositivo recebe um mi-ID_number. Você pode visualizar IDs de dispositivo no Fleet Manager, um recurso do AWS Systems Manager.

Linux & macOS
aws ssm send-command \ --document-name document-name \ --targets Key=instanceids,Values=instance-ID-1,instance-ID-2,instance-ID-3 \ [...]
Windows
aws ssm send-command ^ --document-name document-name ^ --targets Key=instanceids,Values=instance-ID-1,instance-ID-2,instance-ID-3 ^ [...]

Se você marcou nós gerenciados para diferentes ambientes usando uma Key chamada Environment e Values de Development, Test, Pre-production e Production, poderá enviar um comando para todas os nós gerenciados em um desses ambientes usando o parâmetro targets com a sintaxe a seguir.

Linux & macOS
aws ssm send-command \ --document-name document-name \ --targets Key=tag:Environment,Values=Development \ [...]
Windows
aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:Environment,Values=Development ^ [...]

Você pode ter nós gerenciados adicionais como destino em outros ambientes, adicionando à lista Values. Separe itens usando vírgulas.

Linux & macOS
aws ssm send-command \ --document-name document-name \ --targets Key=tag:Environment,Values=Development,Test,Pre-production \ [...]
Windows
aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:Environment,Values=Development,Test,Pre-production ^ [...]

Variação: refinar os destinos usando vários critérios Key

É possível refinar o número de destinos para o seu comando incluindo vários critérios para Key. Se você incluir mais de um critério para Key, o sistema usará os nós gerenciados que atenderem a todos os critérios. O seguinte comando direciona todos os nós gerenciados marcados para o Departamento de finanças e marcados para a função de servidor de banco de dados.

Linux & macOS
aws ssm send-command \ --document-name document-name \ --targets Key=tag:Department,Values=Finance Key=tag:ServerRole,Values=Database \ [...]
Windows
aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:Department,Values=Finance Key=tag:ServerRole,Values=Database ^ [...]

Variação: usar vários critérios Key e Value

Expandindo o exemplo anterior, você pode direcionar vários departamentos e várias funções de servidor, incluindo itens adicionais nos critérios Values.

Linux & macOS
aws ssm send-command \ --document-name document-name \ --targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database \ [...]
Windows
aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database ^ [...]

Variação: definir nós gerenciados marcados como destino usando vários critérios Values

Se você marcou nós gerenciados para diferentes ambientes usando uma Key chamada Department e Values de Sales e Finance, poderá enviar um comando para todas os nós em um desses ambientes usando o parâmetro targets com a sintaxe a seguir.

Linux & macOS
aws ssm send-command \ --document-name document-name \ --targets Key=tag:Department,Values=Sales,Finance \ [...]
Windows
aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:Department,Values=Sales,Finance ^ [...]

É possível especificar um máximo de cinco chaves e cinco valores para cada chave.

Se uma chave de etiqueta (o nome da etiqueta) ou um valor de etiqueta incluir espaços, você deverá incluir a chave ou o valor da etiqueta entre aspas, conforme mostrado nos exemplos a seguir.

Exemplo: espaços na tag Value

Linux & macOS
aws ssm send-command \ --document-name document-name \ --targets Key=tag:OS,Values="Windows Server 2016" \ [...]
Windows
aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:OS,Values="Windows Server 2016" ^ [...]

Exemplo: espaços na chave tag e em Value

Linux & macOS
aws ssm send-command \ --document-name document-name \ --targets Key="tag:Operating System",Values="Windows Server 2016" \ [...]
Windows
aws ssm send-command ^ --document-name document-name ^ --targets Key="tag:Operating System",Values="Windows Server 2016" ^ [...]

Exemplo: espaços em um item em uma lista de Values

Linux & macOS
aws ssm send-command \ --document-name document-name \ --targets Key=tag:Department,Values="Sales","Finance","Systems Mgmt" \ [...]
Windows
aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:Department,Values="Sales","Finance","Systems Mgmt" ^ [...]

Usar controles de taxa

Você pode controlar a taxa na qual os comandos são enviados para nós gerenciados em um grupo usando controles de simultaneidade e controles de erro.

Usar controles de simultaneidade

Você pode controlar quantos nós gerenciados executam o comando ao mesmo tempo usando o parâmetro max-concurrency (as opções Concurrency [Simultaneidade] na página Run a command [Executar um comando]). Você pode especificar um número absoluto de nós gerenciados, por exemplo, 10 ou uma porcentagem do conjunto de destino, por exemplo, 10%. O sistema de enfileiramento entrega o comando a um único nó e aguarda até que o sistema reconheça a invocação inicial antes de enviar o comando para mais dois nós. O sistema envia de forma exponencial comandos para mais nós até que o valor max-concurrency seja atingido. O padrão para o valor max-concurrency é 50. Os exemplos a seguir mostram como especificar valores para o parâmetro max-concurrency.

Linux & macOS
aws ssm send-command \ --document-name document-name \ --max-concurrency 10 \ --targets Key=tag:Environment,Values=Development \ [...]
aws ssm send-command \ --document-name document-name \ --max-concurrency 10% \ --targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database \ [...]
Windows
aws ssm send-command ^ --document-name document-name ^ --max-concurrency 10 ^ --targets Key=tag:Environment,Values=Development ^ [...]
aws ssm send-command ^ --document-name document-name ^ --max-concurrency 10% ^ --targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database ^ [...]

Usar controles de erro

Você também pode controlar a execução de um comando para centenas ou milhares de nós gerenciados definindo um limite de erro usando os parâmetros max-errors no campo Error threshold (Limitação de erros) na página Run a command (Executar um comando). O parâmetro especifica quantos erros são permitidos antes que o sistema pare de enviar o comando para nós gerenciados adicionais. Você pode especificar um número absoluto de erros (por exemplo, 10) ou uma porcentagem do conjunto de destino (por exemplo, 10%). Se você especificar 3, por exemplo, o sistema deixará de enviar o comando quando o quarto erro for recebido. Se você especificar 0, o sistema deixará de enviar o comando para nós adicionais depois que o primeiro resultado de erro for retornado. Se você enviar um comando para 50 nós gerenciados e definir max-errors como 10%, o sistema deixará de enviar o comando para nós adicionais quando o sexto erro for recebido.

As invocações que já estão executando um comando quando max-errors é atingido podem ser concluídas, mas algumas dessas invocações também podem falhar. Para garantir que não haverá mais do que max-errors invocações com falha, defina max-concurrency como 1 para que as invocações prossigam uma por vez. O padrão para o máximo de erros é 0. Os exemplos a seguir mostram como especificar valores para o parâmetro max-errors.

Linux & macOS
aws ssm send-command \ --document-name document-name \ --max-errors 10 \ --targets Key=tag:Database,Values=Development \ [...]
aws ssm send-command \ --document-name document-name \ --max-errors 10% \ --targets Key=tag:Environment,Values=Development \ [...]
aws ssm send-command \ --document-name document-name \ --max-concurrency 1 \ --max-errors 1 \ --targets Key=tag:Environment,Values=Production \ [...]
Windows
aws ssm send-command ^ --document-name document-name ^ --max-errors 10 ^ --targets Key=tag:Database,Values=Development ^ [...]
aws ssm send-command ^ --document-name document-name ^ --max-errors 10% ^ --targets Key=tag:Environment,Values=Development ^ [...]
aws ssm send-command ^ --document-name document-name ^ --max-concurrency 1 ^ --max-errors 1 ^ --targets Key=tag:Environment,Values=Production ^ [...]