Demonstração: criar associações que executam manuais do Ansible - AWS Systems Manager
Dependências instaladasCriar uma associação que execute manuais do Ansible (console)Criar uma associação que execute manuais do Ansible (CLI)

Demonstração: criar associações que executam manuais do Ansible

Você pode criar associações do State Manager que executam manuais do Ansible usando o documento do SSM AWS-ApplyAnsiblePlaybooks. O State Manager é um recurso do AWS Systems Manager. Esse documento oferece os seguintes benefícios para executar manuais:

  • Suporte à execução de manuais complexos

  • Support ao download de playbooks do GitHub e do Amazon Simple Storage Service (Amazon S3)

  • Suporte à estrutura de manual compactada

  • Registro em log aprimorado

  • Capacidade de especificar qual manual executar quando os manuais estiverem empacotados

nota

O Systems Manager inclui dois documentos do SSM que permitem criar associações do State Manager que executam manuais do Ansible: AWS-RunAnsiblePlaybook e AWS-ApplyAnsiblePlaybooks. O documento AWS-RunAnsiblePlaybook está obsoleto. Ele permanece disponível no Systems Manager para fins legados. Recomendamos usar o documento AWS-ApplyAnsiblePlaybooks devido aos aprimoramentos descritos aqui.

As associações que executam manuais do Ansible não são compatíveis com o macOS.

Suporte à execução de manuais complexos

O documento AWS-ApplyAnsiblePlaybooks oferece suporte a manuais complexos e empacotados porque copia toda a estrutura de arquivos para um diretório local antes de executar o manual principal especificado. Você pode fornecer manuais de origem em arquivos Zip ou em uma estrutura de diretórios. O arquivo Zip ou diretório pode ser armazenado no GitHub ou no Amazon S3.

Suporte ao download de manuais do GitHub

O documento AWS-ApplyAnsiblePlaybooks usa o plugin aws:downloadContent para fazer download dos arquivos de manual. Os arquivos podem ser armazenados no GitHub em um único arquivo ou como um conjunto combinado de arquivos de manual. Para fazer download de conteúdo do GitHub, é necessário especificar informações sobre seu repositório do GitHub no formato JSON. Aqui está um exemplo.

{
   "owner":"TestUser",
   "repository":"GitHubTest",
   "path":"scripts/python/test-script",
   "getOptions":"branch:master",
   "tokenInfo":"{{ssm-secure:secure-string-token}}"
}

Suporte ao download de manuais do Amazon S3

Também é possível armazenar e baixar manuais do Ansible no Amazon S3 como um único arquivo .zip ou uma estrutura de diretórios. Para fazer download de conteúdo do Amazon S3, é necessário especificar o caminho para o arquivo. Veja dois exemplos a seguir.

Exemplo 1: fazer download de um arquivo de manual específico

{
   "path":"https://s3.amazonaws.com/DOC-EXAMPLE-BUCKET/playbook.yml"
}

Exemplo 2: fazer download do conteúdo de um diretório

{
   "path":"https://s3.amazonaws.com/DOC-EXAMPLE-BUCKET/ansible/webservers/"
}
Importante

Se você especificar o Amazon S3, o perfil de instância do AWS Identity and Access Management (IAM) nos nós gerenciados deverá ser configurado com a política AmazonS3ReadOnlyAccess. Para obter mais informações, consulte Configurar permissões de instância obrigatórias para o Systems Manager.

Suporte à estrutura de manual compactada

O documento AWS-ApplyAnsiblePlaybooks permite executar arquivos .zip compactados no pacote obtido por download. O documento verifica se os arquivos obtidos por download contêm um arquivo compactado no formato .zip. Se um .zip for encontrado, o documento descompactará automaticamente o arquivo e executará a automação do Ansible especificada.

Registro em log aprimorado

O documento AWS-ApplyAnsiblePlaybooks inclui um parâmetro opcional para especificar diferentes níveis de registro em log. Especifique -v para nível de detalhe baixo, -vv ou -vvv para nível de detalhe médio e -vvvv para registro em log no nível de depuração. Essas opções são mapeadas diretamente nas opções de nível de detalhe do Ansible.

Capacidade de especificar qual manual executar quando os manuais estiverem empacotados

O documento AWS-ApplyAnsiblePlaybooks inclui um parâmetro necessário para especificar qual manual executar quando vários manuais estiverem empacotados. Essa opção fornece flexibilidade para executar manuais a fim de oferecer suporte a diferentes casos de uso.

Dependências instaladas

Se você especificar True (Verdadeiro) para o parâmetro InstallDependencies, o Systems Manager verificará se as dependências a seguir estão instaladas em seus nós.

  • Ubuntu Server/Debian Server: Apt-get (gerenciamento de pacotes), Python 3, Ansible, Unzip

  • Amazon Linux: Ansible

  • RHEL: Python 3, Ansible, Unzip

Se uma ou mais dessas dependências não forem encontradas, o Systems Manager as instalará automaticamente.

Criar uma associação que execute manuais do Ansible (console)

O procedimento a seguir descreve como usar o console do Systems Manager para criar uma associação do State Manager que execute manuais do Ansible usando o documento AWS-ApplyAnsiblePlaybooks.

Para criar uma associação que execute manuais do Ansible (console)

  1. Abra o console AWS Systems Manager em https://console.aws.amazon.com/systems-manager/.

  2. No painel de navegação, escolha State Manager.

  3. Escolha State Manager e, em seguida, Create Association (Criar associação).

  4. Em Name (Nome), especifique um nome que ajude você a lembrar a finalidade da associação.

  5. Na lista Document (Documento), escolha AWS-ApplyAnsiblePlaybooks.

  6. Na seção Parameters (Parâmetros), em Source Type (Tipo de origem), escolha GitHub ou S3.

    GitHub

    Se você escolher GitHub, insira as informações do repositório no seguinte formato:

    {
   "owner":"user_name",
   "repository":"name",
   "path":"path_to_directory_or_playbook_to_download",
   "getOptions":"branch:branch_name",
   "tokenInfo":"{{(Optional)_token_information}}"
}

    S3

    Se você escolher S3, insira as informações do caminho no seguinte formato:

    {
   "path":"https://s3.amazonaws.com/path_to_directory_or_playbook_to_download"
}

  7. Em Install Dependencies (Instalar dependências), escolha uma opção.

  8. (Opcional) Em Playbook File (Arquivo do manual), insira um nome de arquivo. Se o manual estiver contido em um arquivo Zip, especifique um caminho relativo para o arquivo Zip.

  9. (Opcional) Em Variáveis extras, insira as variáveis que você deseja que o State Manager envie ao Ansible no runtime.

  10. (Opcional) Em Check (Verificar), escolha uma opção.

  11. (Opcional) Em Verbose (Detalhado), escolha uma opção.

  12. 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.

  13. 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.

  14. Na seção Advanced options (Opções avançadas), em Compliance severity (Severidade de conformidade), escolha um nível de gravidade 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 ter mais informações, consulte Sobre a conformidade de associações do State Manager.

  15. Na seção Rate control (Controle de taxa), configure opções para executar associações do State Manager na frota de nós gerenciados. Para obter 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.

  16. (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.

  17. Escolha Create Association (Criar associação).

nota

Se você usar tags para criar uma associação em um ou mais nós de destino e, em seguida, remover as tags de um nó, esse nó não executará mais a associação. O nó será dissociado do documento do State Manager.

Criar uma associação que execute manuais do Ansible (CLI)

O procedimento a seguir descreve como usar a AWS Command Line Interface (AWS CLI) para criar uma associação do State Manager que execute manuais do Ansible usando o documento AWS-ApplyAnsiblePlaybooks.

Para criar uma associação que execute manuais do Ansible (CLI)

  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.

  2. Execute um dos comandos a seguir para criar uma associação que execute manuais do Ansible definindo como destino nós que utilizam tags. Substitua cada espaço reservado para recurso de exemplo por suas próprias informações. O comando (A) especifica GitHub como o tipo de origem. O comando (B) especifica o Amazon S3 como o tipo de origem.

    (A) Origem do GitHub

    Linux & macOS
    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
    --targets Key=tag:TagKey,Values=TagValue \
    --parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"owner_name\", \"repository\": \"name\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"],"TimeoutSeconds":["3600"]}' \
    --association-name "name" \
    --schedule-expression "cron_or_rate_expression"
    Windows
    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" ^
    --targets Key=tag:TagKey,Values=TagValue ^
    --parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"owner_name\", \"repository\": \"name\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"], "TimeoutSeconds":["3600"]}' ^
    --association-name "name" ^
    --schedule-expression "cron_or_rate_expression"

    Aqui está um exemplo.

    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
    --targets "Key=tag:OS,Values=Linux" \
    --parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"ansibleDocumentTest\", \"repository\": \"Ansible\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True"],"PlaybookFile":["hello-world-playbook.yml"],"ExtraVariables":["SSM=True"],"Check":["False"],"Verbose":["-v"]}' \
    --association-name "AnsibleAssociation" \
    --schedule-expression "cron(0 2 ? * SUN *)"

    (B) Origem do S3

    Linux & macOS
    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
    --targets Key=tag:TagKey,Values=TagValue \
    --parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/path_to_Zip_file,_directory,_or_playbook_to_download\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"]}' \
    --association-name "name" \
    --schedule-expression "cron_or_rate_expression"
    Windows
    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" ^
    --targets Key=tag:TagKey,Values=TagValue ^
    --parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/path_to_Zip_file,_directory,_or_playbook_to_download\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"]}' ^
    --association-name "name" ^
    --schedule-expression "cron_or_rate_expression"

    Aqui está um exemplo.

    aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
    --targets "Key=tag:OS,Values=Linux" \
    --parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/DOC-EXAMPLE-BUCKET/playbook.yml\"}"],"InstallDependencies":["True"],"PlaybookFile":["playbook.yml"],"ExtraVariables":["SSM=True"],"Check":["False"],"Verbose":["-v"]}' \
    --association-name "AnsibleAssociation" \
    --schedule-expression "cron(0 2 ? * SUN *)"
    nota

    As associações do State Manager, não comportam todas as expressões cron e de taxa. Para obter mais informações sobre como criar expressões cron e rate para associações, consulte Referência: Expressões cron e rate para o Systems Manager.

    O sistema tenta criar a associação nos nós e aplicar imediatamente o estado.

  3. Execute o comando a seguir para visualizar um status atualizado da associação que você acabou de criar. 

    aws ssm describe-association --association-id "ID"