Conceitos básicos Aplicar atributos JSON aos destinos ao executar uma fórmula Usar o Git como a origem do cookbook Usar o GitHub como a origem de livros de receitas Usar o HTTP como a origem do cookbook Usar o Amazon S3 como a origem de livros de receitas Criar uma associação que executa receitas do Chef (console)Criar uma associação que executa receitas do Chef (CLI)Visualizar detalhes de conformidade de recursos do Chef

Criar associações que executam receitas do Chef

Você pode criar associações do State Manager que executam receitas do Chef usando o documento do SSM AWS-ApplyChefRecipes. O State Manager é um recurso do AWS Systems Manager. Você pode segmentar nós gerenciados do Systems Manager baseados em Linux com o documento AWS-ApplyChefRecipes. Esse documento oferece os seguintes benefícios para a execução de receitas do Chef:

Compatível com várias versões do Chef (Chef 11 a Chef 18).
Instala automaticamente o software cliente do Chef nos nós de destino.
Opcionalmente, executa as verificações de conformidade do Systems Manager nos nós de destino e armazena os resultados das verificações de conformidade em um bucket do Amazon Simple Storage Service (Amazon S3).
Executa vários livros de receitas e receitas em uma única execução do documento.
Opcionalmente, executa receitas no modo why-run, para mostrar quais receitas serão alteradas nos nós de destino sem fazer alterações.
Opcionalmente aplica atributos JSON personalizados a execuções do chef-client.
Opcionalmente, aplica atributos JSON personalizados de um arquivo de origem armazenado em um local que você especificou.

Você pode usar o Git, o GitHub, HTTP ou buckets do Amazon S3 como origens para cookbooks e fórmulas do Chef especificados em um documento AWS-ApplyChefRecipes.

nota

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

Conceitos básicos

Antes de criar um documento AWS-ApplyChefRecipes, prepare seus livros de receitas e o repositório de livros de receitas do Chef. Se ainda não tiver um livro de receitas do Chef que deseja usar, você pode começar usando um livro de receitas HelloWorld de teste que a AWS preparou para você. O documento AWS-ApplyChefRecipes já aponta para esse livro de receitas por padrão. Seus livros de receitas devem ser configurados de forma semelhante à seguinte estrutura de diretório. No exemplo a seguir, jenkins e nginx são exemplos de livros de receitas do Chef que estão disponíveis no Chef Supermarket no site do Chef.

Embora a AWS não possa oferecer suporte oficialmente a livros de receitas no site do Chef Supermarket, muitos deles trabalham com o documento AWS-ApplyChefRecipes. Veja a seguir exemplos de critérios a serem verificados ao testar um livro de receitas da comunidade:

O livro de receitas deve oferecer suporte aos sistemas operacionais baseados em Linux dos nós gerenciados do Systems Manager que você tem como destino.
O cookbook deve ser válido para a versão do cliente do Chef (Chef 11 a Chef 18) que você usa.
O livro de receitas é compatível com o Chef Infra Client e não requer um servidor do Chef.

Verifique se você pode acessar o site Chef.io para que todos os livros de receitas que você especificar na lista de execução possam ser instalados quando o documento do Systems Manager (documento SSM) for executado. O uso de uma pasta cookbooks aninhada é compatível, mas não é necessário; você pode armazenar livros de receitas diretamente sob o nível raiz.


<Top-level directory, or the top level of the archive file (ZIP or tgz or tar.gz)>
    └── cookbooks (optional level)
        ├── jenkins
        │   ├── metadata.rb
        │   └── recipes
        └── nginx
            ├── metadata.rb
            └── recipes

Importante

Antes de criar uma associação do State Manager que executa receitas do Chef, lembre-se de que a execução do documento instala o software cliente do Chef em seus nós gerenciados do Systems Manager, a menos que você defina o valor de Versão do cliente do Chef como None. Essa ação usa um script de instalação do Chef para instalar componentes do Chef em seu nome. Antes de executar um documento AWS-ApplyChefRecipes, certifique-se de que sua empresa pode cumprir todos os requisitos legais aplicáveis, incluindo termos de licença aplicáveis ao uso do software Chef. Para obter mais informações, acesse o site do Chef.

O Systems Manager pode fornecer relatórios de conformidade para um bucket do S3, para o console do Systems Manager ou disponibilizar resultados da conformidade em resposta a comandos da API do Systems Manager. Para executar relatórios de conformidade do Systems Manager, o perfil da instância anexado a nós gerenciados pelo Systems Manager deve ter permissões para gravar no bucket do S3. O perfil de instância deve ter permissões para usar a API PutComplianceItem do Systems Manager. Para obter mais informações sobre a conformidade do Systems Manager, consulte Conformidade com o AWS Systems Manager.

Registrar a execução do documento em log

Quando você executa um documento do Systems Manager (documento SSM) usando uma associação do State Manager você pode configurar a associação para escolher a saída da execução do documento e pode enviar a saída para o Amazon S3 ou Amazon CloudWatch Logs (CloudWatch Logs). Para ajudar a facilitar a solução de problemas quando a execução de uma associação for concluída, verifique se a associação está configurada para gravar a saída do comando em um bucket do Amazon S3 ou do CloudWatch Logs. Para ter mais informações, consulte Para obter informações, consulte Trabalhar com associações no Systems Manager..

Aplicar atributos JSON aos destinos ao executar uma fórmula

Você pode especificar atributos JSON para seu cliente do Chef aplicar aos nós de destino durante uma execução de associação. Ao configurar a associação, é possível fornecer JSON bruto ou fornecer o caminho para um arquivo JSON armazenado no Amazon S3.

Use atributos JSON quando quiser personalizar como a fórmula é executada sem precisar modificar a fórmula em si, por exemplo:

Substituir poucos atributos

Use JSON personalizado para evitar a necessidade de manter múltiplas versões de uma fórmula para ajustar pequenas diferenças.
Fornecer valores variáveis

Use JSON personalizado para especificar valores que podem ser alterados entre execuções. Por exemplo, se seus cookbooks do Chef configurarem uma aplicação de terceiros que aceite pagamentos, você poderá usar JSON personalizado para especificar o URL do endpoint de pagamento.

Especificar atributos em JSON bruto

Veja a seguir um exemplo do formato que você pode usar para especificar atributos JSON personalizados para sua receita do Chef.


{"filepath":"/tmp/example.txt", "content":"Hello, World!"}

Especificar um caminho para um arquivo JSON

Veja a seguir um exemplo do formato que você pode usar para especificar o caminho para atributos JSON personalizados para sua receita do Chef.


{"sourceType":"s3", "sourceInfo":"someS3URL1"}, {"sourceType":"s3", "sourceInfo":"someS3URL2"}

Usar o Git como a origem do cookbook

O documento AWS-ApplyChefRecipes usa o plugin aws:downloadContent para fazer download de livros de receitas do Chef. Para baixar conteúdo do Git, especifique informações sobre seu repositório Git no formato JSON, como no exemplo a seguir. Substitua cada example-resource-placeholder por suas próprias informações.


{
   "repository":"GitCookbookRepository",
   "privateSSHKey":"{{ssm-secure:ssh-key-secure-string-parameter}}",
   "skipHostKeyChecking":"false",
   "getOptions":"branch:refs/head/main",
   "username":"{{ssm-secure:username-secure-string-parameter}}",
   "password":"{{ssm-secure:password-secure-string-parameter}}"
}

Usar o GitHub como a origem de livros de receitas

O documento AWS-ApplyChefRecipes usa o plugin aws:downloadContent para fazer download de livros de receitas. Para baixar conteúdo do GitHub, especifique informações sobre seu repositório GitHub no formato JSON, como no exemplo a seguir. Substitua cada example-resource-placeholder por suas próprias informações.


{
   "owner":"TestUser",
   "repository":"GitHubCookbookRepository",
   "path":"cookbooks/HelloWorld",
   "getOptions":"branch:refs/head/main",
   "tokenInfo":"{{ssm-secure:token-secure-string-parameter}}"
}

Usar o HTTP como a origem do cookbook

Você pode armazenar cookbooks do Chef em um local HTTP personalizado como um único arquivo .zip ou tar.gz ou uma estrutura de diretórios. Para baixar conteúdo de HTTP, é necessário especificar o caminho para o arquivo ou diretório no formato JSON, como no exemplo a seguir. Substitua cada example-resource-placeholder por suas próprias informações.


{
   "url":"https://my.website.com/chef-cookbooks/HelloWorld.zip",
   "allowInsecureDownload":"false",
   "authMethod":"Basic",
   "username":"{{ssm-secure:username-secure-string-parameter}}",
   "password":"{{ssm-secure:password-secure-string-parameter}}"
}

Usar o Amazon S3 como a origem de livros de receitas

Também é possível armazenar e baixar cookbooks do Chef no Amazon S3 como um único arquivo .zip ou tar.gz ou como uma estrutura de diretórios. Para baixar conteúdo do Amazon S3, é necessário especificar o caminho para o arquivo no formato JSON, como nos exemplos a seguir. Substitua cada example-resource-placeholder por suas próprias informações.

Exemplo 1: Fazer download de um livro de receitas específico


{
   "path":"https://s3.amazonaws.com/chef-cookbooks/HelloWorld.zip"
}

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


{
   "path":"https://s3.amazonaws.com/chef-cookbooks-test/HelloWorld"
}

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.

Criar uma associação que executa receitas do Chef (console)

O procedimento a seguir descreve como usar o console do Systems Manager para criar uma associação do State Manager que execute livros de receitas do Chef usando o documento AWS-ApplyChefRecipes.

Abra o console AWS Systems Manager em https://console.aws.amazon.com/systems-manager/.
No painel de navegação, escolha State Manager.
Escolha State Manager e, em seguida, Create Association (Criar associação).
Em Name (Nome), insira um nome que ajude você a lembrar a finalidade da associação.
Na lista Document (Documento), escolha AWS-ApplyChefRecipes.
Em Parâmetros, em Tipo de origem, selecione Git, GitHub, HTTP ou S3.
Em Informações da origem, insira as informações da origem do cookbook usando o formato apropriado para o Tipo de origem que você selecionou na etapa 6. Para obter mais informações, consulte os tópicos a seguir.
Em Run list (Lista de execução), liste as receitas que você deseja executar no seguinte formato, separando cada receita com uma vírgula, como mostrado. Não inclua um espaço após a vírgula. Substitua cada example-resource-placeholder por suas próprias informações.
```
recipe[cookbook-name1::recipe-name],recipe[cookbook-name2::recipe-name]
```
(Opcional) Especifique atributos JSON que você deseja que o cliente do Chef passe para seus nós de destino.
1. Em Conteúdo de atributos JSON, adicione os atributos que você deseja que o cliente do Chef passe para seus nós de destino.
2. Em Origens de atributos JSON, adicione caminhos para atributos que você deseja que o cliente do Chef passe para seus nós de destino.
Para ter mais informações, consulte Aplicar atributos JSON aos destinos ao executar uma fórmula.
Em Versão do cliente do Chef, especifique uma versão do Chef. Os valores válidos são 11 a 18 ou None. Se você especificar em número de 11 a 18 (inclusive), o Systems Manager instalará a versão correta do cliente do Chef em seus nós de destino. Se você especificar None, o Systems Manager não instalará o cliente do Chefem nós de destino antes de executar as receitas do documento.
(Opcional) Em Argumentos do cliente do Chef, especifique argumentos adicionais que sejam compatíveis com a versão do Chef que você está usando. Para saber mais sobre os argumentos compatíveis, execute chef-client -h em um nó que esteja executando o cliente do Chef.
(Opcional) Ative o Why-Run (Por que executar) para mostrar as alterações feitas nos nós de destino, se as receitas forem executadas, sem realmente alterar os nós de destino.
Em Compliance severity (Gravidade da conformidade), escolha a gravidade dos resultados da Conformidade so Systems Manager que você deseja relatar. Os relatórios de conformidade indicam se o estado é compatível ou não, juntamente com o nível de gravidade que você especificar. Os relatórios de conformidade são armazenados em um bucket do S3 especificado como o valor do parâmetro Compliance report bucket (Bucket de relatório de conformidade) (etapa 14). Para obter mais informações sobre a Conformidade da configuração, consulte Conheça mais sobre a conformidade neste guia.

As verificações de conformidade medem a variação entre a configuração especificada nas receitas do Chef e nos recursos do nó. Os valores válidos são Critical, High, Medium, Low, Informational, Unspecified ou None. Para ignorar os relatórios de conformidade, escolha None.
Em Compliance type (Tipo de conformidade), especifique o tipo de conformidade para o qual você deseja que os resultados sejam relatados. Os valores válidos são Association para associações do State Manager ou Custom:custom_type. O valor padrão é Custom:Chef.
Em Bucket do relatório de conformidade, insira o nome de um bucket do S3 no qual armazenar informações sobre cada execução do Chef realizada por este documento, incluindo a configuração de recursos e os resultados da Conformidade.
Em 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.

Em 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.
Em Error threshold (Limitação de erros), 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.
Escolha Create Association (Criar associação).

Criar uma associação que executa receitas do Chef (CLI)

O procedimento a seguir descreve como usar a AWS Command Line Interface (AWS CLI) para criar uma associação do State Manager que executa livros de receitas do Chef usando o documento AWS-ApplyChefRecipes.

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.

Execute um dos comandos a seguir para criar uma associação que execute cookbooks do Chef em nós de destino que tenham as etiquetas especificadas. Use o comando apropriado para o tipo de origem e sistema operacional do cookbook. Substitua cada example-resource-placeholder por suas próprias informações.

Origem Git

Linux & macOS


aws ssm create-association --name "AWS-ApplyChefRecipes" \
    --targets Key=tag:TagKey,Values=TagValue \
    --parameters '{"SourceType":["Git"],"SourceInfo":["{\"repository\":\"repository-name\", \"getOptions\": \"branch:branch-name\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json-content}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' \
    --association-name "name" \
    --schedule-expression "cron-or-rate-expression"

Windows


aws ssm create-association --name "AWS-ApplyChefRecipes" ^
    --targets Key=tag:TagKey,Values=TagValue ^
    --parameters '{"SourceType":["Git"],"SourceInfo":["{\"repository\":\"repository-name\", \"getOptions\": \"branch:branch-name\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' ^
    --association-name "name" ^
    --schedule-expression "cron-or-rate-expression"

Origem do GitHub

Aqui está um exemplo.

Origem HTTP

Linux & macOS


aws ssm create-association --name "AWS-ApplyChefRecipes" \
    --targets Key=tag:TagKey,Values=TagValue \
    --parameters '{"SourceType":["HTTP"],"SourceInfo":["{\"url\":\"url-to-zip-file|directory|cookbook\", \"authMethod\": \"auth-method\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json-content}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' \
    --association-name "name" \
    --schedule-expression "cron-or-rate-expression"

Windows


aws ssm create-association --name "AWS-ApplyChefRecipes" ^
    --targets Key=tag:TagKey,Values=TagValue ^
    --parameters '{"SourceType":["HTTP"],"SourceInfo":["{\"url\":\"url-to-zip-file|directory|cookbook\", \"authMethod\": \"auth-method\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json-content}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' \
    --association-name "name" ^
    --schedule-expression "cron-or-rate-expression"

Origem Amazon S3

Aqui está um exemplo.

O sistema criará a associação e, a menos que sua expressão cron ou de taxa especificada a impeça, o sistema executará a associação nos nós de destino.

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.

Execute o comando a seguir para visualizar um status da associação que você acabou de criar.
```
aws ssm describe-association --association-id "ID"
```

Visualizar detalhes de conformidade de recursos do Chef

O Systems Manager captura informações de conformidade sobre recursos gerenciados pelo Chef no valor de Bucket de relatórios de conformidade do Amazon S3 que você especificou ao executar o documento AWS-ApplyChefRecipes. Pesquisar informações sobre falhas de recursos do Chef em um bucket do S3 pode ser demorado. Em vez disso, você pode exibir essas informações na página Compliance (Conformidade) do Systems Manager.

Uma verificação de conformidade do Systems Manager coleta informações sobre recursos em seus nós gerenciados que foram criados ou verificados na execução mais recente do Chef. Os recursos podem incluir arquivos, diretórios, serviços do systemd, pacotes do yum, arquivos de modelos, pacotes do gem e livros de receitas dependentes, entre outros.

A seção Compliance resources summary (Resumo dos recursos de conformidade) exibe uma contagem do recursos com falha. No exemplo a seguir, ComplianceType é Custom:Chef e um recurso não está em conformidade.

nota

Custom:Chef é o valor padrão de ComplianceType no documento AWS-ApplyChefRecipes. Esse valor é personalizável.

Visualizar contagens na seção Compliance resources summary (Resumo dos recursos de conformidade) da página Compliance (Conformidade).

A seção Details overview for resources (Visão geral de detalhes dos recursos) mostra informações sobre o recurso da AWS que não está em conformidade. Essa seção também inclui o tipo de recurso do Chef em relação ao qual a conformidade foi executada, a gravidade do problema, o status da conformidade e os links para mais informações quando aplicável.

Visualizar detalhes de conformidade de uma falha de recurso gerenciado pelo Chef

Visualizar saída mostra os últimos 4.000 caracteres do status detalhado. O Systems Manager começa com a exceção como o primeiro elemento, localiza as mensagens detalhadas e as exibe até atingir a cota de 4.000 caracteres. Esse processo exibe as mensagens de log que foram registradas antes da exceção ser gerada, que são as mensagens mais relevantes para a solução de problemas.

Para obter informações sobre como visualizar informações de conformidade, consulte Conformidade com o AWS Systems Manager.

Importante

Se houver falha na associação do State Manager, os dados de conformidade não serão relatados. Por exemplo, se o Systems Manager tentar baixar um livro de receitas do Chef em um bucket do S3 que o nó não tem permissão para acessar, haverá falha na associação e o Systems Manager relatará dados fora de conformidade.

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

Criar associações que executam manuais do Ansible

Walkthrough: Automatically update SSM Agent with the AWS CLI