Introducción Aplicación de atributos JSON a los destinos al ejecutar una receta Usar Git como fuente para el libro de recetas Usar GitHub como fuente de libro de recetas Usar HTTP como fuente para el libro de recetas Uso de Amazon S3 como fuente de libro de recetas Crear una asociación que ejecute recetas de Chef (consola)Crear una asociación que ejecute recetas de Chef (CLI)Visualización de los detalles de cumplimiento del recurso de Chef

Creación de asociaciones que ejecuten recetas de Chef

Puede crear asociaciones de State Manager que ejecuten recetas de Chefutilizando el documento AWS-ApplyChefRecipes de SSM. State Manager es una capacidad de AWS Systems Manager. Puede dirigirse a nodos administrados por Systems Manager basados en Linux con el documento AWS-ApplyChefRecipes de SSM. Este documento ofrece los siguientes beneficios para ejecutar recetas de Chef:

Admite múltiples versiones de Chef (de Chef 11 a Chef 18).
Instala automáticamente el software cliente de Chef en los nodos de destino.
Opcionalmente, ejecuta comprobaciones de conformidad de Systems Manager en nodos de destino y almacena los resultados de las comprobaciones de conformidad en un bucket de Amazon Simple Storage Service (Amazon S3).
Ejecuta varios libros de recetas y recetas en una sola ejecución del documento.
Opcionalmente, ejecuta recetas en modo why-run, para mostrar qué recetas cambian en nodos de destino sin realizar cambios.
Opcionalmente aplica atributos JSON personalizados a las ejecuciones de chef-client.
De forma opcional, aplica atributos JSON personalizados desde un archivo fuente que se almacena en la ubicación que especifique.

Puede utilizar buckets de Git, GitHub, HTTP o Amazon S3 como fuentes para descargar los libros de recetas y recetas de Chef que especifique en un documento AWS-ApplyChefRecipes.

nota

Las asociaciones que ejecutan recetas de Chef no son compatibles con macOS.

Introducción

Antes de crear un documento AWS-ApplyChefRecipes, prepare sus libros de recetas de Chef y su repositorio de libros de recetas. Si aún no tiene un libro de recetas de Chef que desea utilizar, puede comenzar usando un libro de recetas HelloWorld de prueba que AWS ha preparado para usted. El documento AWS-ApplyChefRecipes ya apunta a este libro de recetas de forma predeterminada. Sus libros de recetas deben configurarse de forma similar a la siguiente estructura de directorios. En el siguiente ejemplo, jenkins y nginx son ejemplos de libros de recetas de Chef que están disponibles en Chef Supermarket en el sitio web de Chef.

Aunque AWS no puede admitir oficialmente libros de recetas en el sitio web de Chef Supermarket muchos de ellos trabajan con el documento AWS-ApplyChefRecipes. Los siguientes son ejemplos de criterios para determinar cuándo se está probando un libro de recetas de la comunidad:

El libro de recetas debe admitir los sistemas operativos basados en Linux de los nodos Systems Manager administrados a los que se dirige.
El libro de recetas debe ser válido para la versión cliente de Chef (de Chef 11 a Chef 18) que utilice.
El libro de recetas es compatible con Chef Infra Client y no requiere un servidor Chef.

Compruebe que puede comunicarse con el sitio web de Chef.io para que los libros de recetas que especifique en la lista de ejecución se puedan instalar cuando se ejecute el documento de Systems Manager (documento de SSM). Se admite el uso de una carpeta cookbooks, pero no es necesario; puede almacenar libros de recetas directamente bajo el nivel raíz.


<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 crear una asociación State Manager que ejecute recetas de Chef, tenga en cuenta que la ejecución del documento instala el software cliente de Chef en los nodos administrados por Systems Manager, a menos que establezca el valor de la versión de cliente de Chef a None. Esta operación utiliza un script de instalación de Chef para instalar componentes de Chef en su nombre. Antes de ejecutar un documento AWS-ApplyChefRecipes, asegúrese de que su empresa pueda cumplir con los requisitos legales aplicables, incluidos los términos de licencia aplicables al uso del software Chef. Para obtener más información, consulte el sitio web de Chef.

Systems Manager puede entregar informes de conformidad a un bucket de S3, a la consola de Systems Manager o hacer que los resultados de conformidad estén disponibles en respuesta a los comandos de la API de Systems Manager. Para ejecutar informes de conformidad de Systems Manager, el perfil de instancias adjuntado a nodos administrados por Systems Manager debe tener permisos para escribir en el bucket de S3. El perfil de instancias debe tener permisos para poder utilizar la API PutComplianceItem de Systems Manager. Para obtener más información acerca de la conformidad de Systems Manager, consulte Conformidad de AWS Systems Manager.

Registro de la ejecución del documento

Cuando ejecuta un documento de Systems Manager (documento de SSM) mediante una asociación de State Manager, puede configurar la asociación para elegir la salida de la ejecución del documento y puede enviar la salida a Amazon S3 o los Registros de Amazon CloudWatch (Registros de CloudWatch). Para facilitar la solución de problemas cuando una asociación ha terminado de ejecutarse, compruebe que la asociación esté configurada para escribir la salida del comando en un bucket de Amazon S3 o los Registros de CloudWatch. Para obtener más información, consulte Trabajo con asociaciones en Systems Manager.

Aplicación de atributos JSON a los destinos al ejecutar una receta

Puede especificar los atributos JSON para que su cliente de Chef los aplique a los nodos de destino durante una ejecución de asociación. Al configurar la asociación, puede proporcionar JSON sin procesar o la ruta a un archivo JSON almacenado en Amazon S3.

Utilice los atributos JSON cuando desee personalizar la forma en que se ejecuta la receta sin tener que modificar la propia receta, por ejemplo:

Anular un número reducido de atributos

Use un JSON personalizado para evitar tener que mantener varias versiones de una receta para adaptarse a pequeñas diferencias.
Proporcionar los valores de las variables

Use un JSON personalizado para especificar los valores que pueden cambiar de una ejecución a otra. Por ejemplo, si sus libros de recetas de Chef configuran una aplicación de terceros que acepta pagos, puede usar un JSON personalizado para especificar la URL del punto de conexión de pago.

Especificar atributos en JSON sin procesar

El siguiente es un ejemplo del formato que puede usar para especificar atributos JSON personalizados para su receta de Chef.


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

Especificación de una ruta a un archivo JSON

El siguiente es un ejemplo del formato que puede usar para especificar la ruta a los atributos JSON personalizados para su receta de Chef.


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

Usar Git como fuente para el libro de recetas

El documento AWS-ApplyChefRecipes utiliza el complemento aws:downloadContent para descargar libros de recetas de Chef. Para descargar contenido desde Git, especifique la información sobre el repositorio de Git en formato JSON, como se muestra en el siguiente ejemplo. Reemplace cada example-resource-placeholder con su propia información.


{
   "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 GitHub como fuente de libro de recetas

El documento AWS-ApplyChefRecipes utiliza el complemento aws:downloadContent para descargar libros de recetas. Para descargar contenido desde GitHub, especifique la información sobre el repositorio de GitHub en formato JSON, como se muestra en el siguiente ejemplo. Reemplace cada example-resource-placeholder con su propia información.


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

Usar HTTP como fuente para el libro de recetas

Puede almacenar los libros de recetas de Chef en una ubicación HTTP personalizada ya sea como un solo archivo .zip, un archivo tar.gz o como una estructura de directorios. Para descargar contenido desde HTTP, especifique la ruta al archivo o al directorio en formato JSON, como se muestra en el siguiente ejemplo. Reemplace cada example-resource-placeholder con su propia información.


{
   "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}}"
}

Uso de Amazon S3 como fuente de libro de recetas

También, puede almacenar y descargar libros de recetas de Chef en Amazon S3 como un único archivo .zip, un archivo tar.gz o como una estructura de directorios. Para descargar contenido desde Amazon S3, especifique la ruta al archivo en formato JSON, como se muestra en los ejemplos siguientes. Reemplace cada example-resource-placeholder con su propia información.

Ejemplo 1: descargar un libro de recetas específico


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

Ejemplo 2: descargar el contenido de un directorio


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

importante

Si especifica Simple Storage Service (Amazon S3), el perfil de instancias de AWS Identity and Access Management (IAM) en los nodos administrados debe configurarse con la política AmazonS3ReadOnlyAccess. Para obtener más información, consulte Configuración de permisos de instancia requeridos para Systems Manager.

Crear una asociación que ejecute recetas de Chef (consola)

En el siguiente procedimiento se describe cómo utilizar la consola de Systems Manager para crear una asociación de State Manager que ejecuta libros de recetas de Chef mediante el documento de AWS-ApplyChefRecipes.

Abra la consola de AWS Systems Manager en https://console.aws.amazon.com/systems-manager/.
En el panel de navegación, elija State Manager.
Elija State Manager y, a continuación, Create association (Crear asociación).
En Name (Nombre), escriba un nombre que le ayude a recordar el objetivo de la asociación.
En la lista Document (Documento), elija AWS-ApplyChefRecipes.
En Parámetros, en Tipo de origen, seleccione Git, GitHub, HTTP o S3.
En Información sobre el origen, introduzca la información sobre la fuente del libro de recetas en el formato adecuado para el Tipo de origen que seleccionó en el paso 6. Para obtener más información, consulte los temas siguientes:
En Run list (Lista de ejecución), enumera las recetas que desea ejecutar en el siguiente formato, separando cada receta con una coma como se muestra. No incluya un espacio después de la coma. Reemplace cada example-resource-placeholder con su propia información.
```
recipe[cookbook-name1::recipe-name],recipe[cookbook-name2::recipe-name]
```
(Opcional) Especifique los atributos JSON personalizados que desee que el cliente de Chef pase a los nodos de destino.
1. En Contenido de atributos JSON, agregue cualquier atributo que desee que el cliente de Chef pase a los nodos de destino.
2. En Contenido de atributos JSON, agregue las rutas a los atributos que desee que el cliente de Chef pase a los nodos de destino.
Para obtener más información, consulte Aplicación de atributos JSON a los destinos al ejecutar una receta.
Para Versión de cliente de Chef, especifique una versión de Chef. Los valores válidos son de 11 a 18 o None. Si especifica un número entre 11 y 18 (inclusive), Systems Manager instala la versión correcta del cliente de Chef en los nodos de destino. Si especifica None, Systems Manager no instala el cliente de Chef en nodos de destino antes de ejecutar las recetas del documento.
(Opcional) En Argumentos del cliente deChef Chef, especifique argumentos adicionales que sean compatibles con la versión de Chef que esté utilizando. Para obtener más información acerca de los argumentos admitidos, ejecute chef-client -h en un nodo que esté ejecutando el cliente de Chef.
(Opcional) Active Why-Run para mostrar los cambios que se realizaron en los nodos de destino si se ejecutan las recetas, sin cambiar realmente los nodos de destino.
Para Compliance severity (Severidad de conformidad), elija la severidad de los resultados de conformidad de configuración de Systems Manager que desee informar. Los informes de conformidad indican si el estado de asociación es conforme o no conforme, junto con el nivel de gravedad que especifique. Los informes de conformidad se almacenan en un bucket de S3 que se especifica como valor del parámetro de Bucket del informe de conformidad (paso 14). Para obtener más información acerca de la conformidad, consulte Detalles sobre el cumplimiento en esta guía.

Los análisis de conformidad miden la desviación entre la configuración especificada en las recetas de Chef y los recursos de nodo. Los valores válidos son Critical, High, Medium, Low, Informational, Unspecified o None. Para omitir los informes de cumplimiento, elija None.
En Compliance type (Tipo de conformidad), especifique el tipo de conformidad para el que desea que se informe de los resultados. Los valores válidos son Association para asociaciones de State Manager o Custom:custom-type. El valor predeterminado es Custom:Chef.
En Bucket de informe de conformidad, ingrese el nombre de un bucket de S3 en el que almacene información sobre cada ejecución de Chef realizada por este documento, incluidos los resultados de configuración de recursos y de conformidad.
En Rate control (Control de frecuencia), configure las opciones para ejecutar asociaciones de State Manager a través de una flota de nodos administrados. Para obtener más información sobre el uso de controles de frecuencia, consulte Comprensión de los controles de frecuencia y destinos en las asociaciones de State Manager.

En Concurrency (Simultáneamente), elija una opción:
- Elija Targets (Destinos) para introducir un número absoluto de destinos que pueda ejecutar la asociación de forma simultánea.
- Elija porcentaje para introducir un porcentaje del destino definido que puede ejecutar la asociación de forma simultánea.
En Error threshold (Umbral de error), elija una opción:
- Elija errors (errores) para especificar un número absoluto de errores permitidos antes de que State Manager deje de ejecutar asociaciones en más destinos.
- Elija percentage (porcentaje) para especificar un porcentaje de errores permitidos antes de que State Manager deje de ejecutar asociaciones en más destinos.
(Opcional) En Output options (Opciones de salida), para guardar la salida del comando en un archivo, seleccione el cuadro Enable writing output to S3 (Permitir la escritura de salida en S3). Ingrese los nombres del bucket y del prefijo (carpeta) en los cuadros.

nota
Los permisos de S3 que conceden la capacidad de escribir datos en un bucket de S3 son los del perfil de instancias asignado al nodo administrado, no los del usuario de IAM que realiza esta tarea. Para obtener más información, consulte Configuración de permisos de instancia requeridos para Systems Manager o Creación de un rol de servicio de IAM para un entorno híbrido. Además, si el bucket de S3 especificado se encuentra en una Cuenta de AWS diferente, verifique que el perfil de instancias o el rol de servicio de IAM asociado al nodo administrado tenga los permisos necesarios para escribir en ese bucket.
Elija Crear asociación.

Crear una asociación que ejecute recetas de Chef (CLI)

En el siguiente procedimiento se describe cómo utilizar la AWS Command Line Interface (AWS CLI) para crear una asociación de State Manager que ejecute cuadernos de trabajo de Chef mediante el documento AWS-ApplyChefRecipes.

Si aún no lo ha hecho, instale y configure la AWS Command Line Interface (AWS CLI).

Para obtener más información, consulte Instalación o actualización de la última versión de la AWS CLI.

Ejecute uno de los siguientes comandos para crear una asociación que ejecute libros de recetas de Chef en nodos de destino que contengan las etiquetas especificadas. Use el comando adecuado para el tipo de fuente y el sistema operativo de su libro de recetas. Reemplace cada example-resource-placeholder con su propia información.

Origen de 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"

Origen de GitHub

A continuación se muestra un ejemplo.

Origen de 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"

Origen de Amazon S3

A continuación se muestra un ejemplo.

El sistema crea la asociación y, a menos que la expresión cron o rate especificada lo impida, el sistema ejecuta la asociación en los nodos de destino.

nota

Las asociaciones de State Manager no admiten todas las expresiones cron y de frecuencia. Para obtener más información acerca de la creación de expresiones cron y de frecuencia para asociaciones, consulte Referencia: expresiones cron y rate para Systems Manager.

Ejecute el siguiente comando para ver el estado de la asociación que acaba de crear.
```
aws ssm describe-association --association-id "ID"
```

Visualización de los detalles de cumplimiento del recurso de Chef

Systems Manager captura información de conformidad sobre los recursos administrados por Chef en el valor Bucket de informe de conformidad de Amazon S3 que especificó cuando ejecutó el documento AWS-ApplyChefRecipes. La búsqueda de información acerca de los errores del recurso de Chef en un bucket de S3 puede llevar tiempo. En su lugar, puede ver esta información en la página Compliance (Conformidad) de Systems Manager.

Un análisis de conformidad de Systems Manager recopila información acerca de los recursos de los nodos administrados que se crearon o se registraron en la ejecución más reciente de Chef. Los recursos pueden incluir archivos, directorios, servicios de systemd, paquetes de yum, archivos con plantillas, paquetes de gem y libros de recetas dependientes, entre otros.

La sección Compliance resources summary (Resumen de los recursos de cumplimiento muestra una cuenta de los recursos que fallaron. En el siguiente ejemplo, el Tipo de conformidad es Personalizado: Chef y un recurso no conforme.

nota

Custom:Chef es el valor ComplianceType predeterminado del documento AWS-ApplyChefRecipes. Este valor se puede personalizar.

Ver recuentos en la sección Compliance resources summary (Resumen de recursos de conformidad) de la página Compliance (Conformidad).

La sección Details overview for resources (Información general de los detalles de los recursos) muestra información sobre el recurso de AWS que no cumple los requisitos. Esta sección también incluye el tipo de recursos de Chef con el que se ejecutó la conformidad, la gravedad del problema, el estado de conformidad y los vínculos a información adicional cuando corresponda.

Visualización de los detalles de conformidad de un error de recurso administrado por Chef

View output (Ver salida) muestra los últimos 4000 caracteres del estado detallado. Systems Manager comienza con la excepción como primer elemento, encuentra mensajes detallados y los muestra hasta que alcanza la cuota de 4000 caracteres. Este proceso muestra los mensajes de registros que salieron antes de lanzar la excepción. Estos mensajes son los más importantes para la resolución de errores.

Para obtener más información acerca de cómo ver la información de cumplimiento, consulte Conformidad de AWS Systems Manager.

importante

Si la asociación de State Manager falla, no se notifican datos de cumplimiento. Por ejemplo, si Systems Manager intenta descargar un libro de recetas de Chef de un bucket de S3 para el cual el nodo no tiene permiso de acceso, la asociación falla y Systems Manager no notifica datos de conformidad.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Creación de asociaciones que ejecuten manuales de estrategia de Ansible

Tutorial: actualización automática de SSM Agent con AWS CLI