Configuración de los entornos de Docker - AWS Elastic Beanstalk
Configuración de software en entornos de DockerReferencia a variables de entorno en contenedoresUso de la característica de interpolación para variables de entorno (Docker Compose)Creación de registros para informes de estado avanzados (Docker Compose)Registro personalizado del contenedor de Docker (Docker Compose)Imágenes de DockerConfiguración de actualizaciones administradas para entornos de DockerEspacios de nombres de la configuración de DockerConfiguración de Docker en la AMI de Amazon Linux (anterior a Amazon Linux 2)

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Configuración de los entornos de Docker

Hay varias maneras de configurar el comportamiento de su entorno de Docker de Elastic Beanstalk.

nota

Si su entorno Elastic Beanstalk utiliza una versión de la plataforma Docker AMI de Amazon Linux (anterior a Amazon Linux 2), asegúrese de leer la información adicional en Configuración de Docker en la AMI de Amazon Linux (anterior a Amazon Linux 2).

Configuración de software en entornos de Docker

Puede utilizar la consola de Elastic Beanstalk para configurar el software que se ejecuta en las instancias del entorno.

Para configurar el entorno Docker en la consola de Elastic Beanstalk

  1. Abra la consola de Elastic Beanstalk y, en la lista Regions (Regiones), seleccione su Región de AWS.

  2. En el panel de navegación, elija Environments (Entornos) y, a continuación, elija el nombre del entorno en la lista.

    nota

    Si tiene muchos entornos, utilice la barra de búsqueda para filtrar la lista de entornos.

  3. En el panel de navegación, elija Configuration (Configuración).

  4. En la categoría de configuración Actualizaciones, supervisión y registro, seleccione Editar.

  5. Realice los cambios de configuración necesarios.

  6. Para guardar los cambios, elija Aplicar en la parte inferior de la página.

Para obtener información sobre cómo configurar el software en cualquier entorno, consulte Propiedades del entorno y otras opciones del software. En las siguientes secciones se aborda información específica de Docker.

Opciones de contenedor

La sección Container options (Opciones de contenedor) contiene opciones específicas de la plataforma. Para los entornos de Docker, le permite elegir si su entorno incluirá o no el servidor proxy NGINX.

Entornos con Docker Compose

Si administra su entorno de Docker con Docker Compose, Elastic Beanstalk presupone que va a ejecutar un servidor proxy como contenedor. Por lo tanto, Elastic Beanstalk establece el valor None (Ninguno) en la opción Proxy server (Servidor proxy) y no proporciona una configuración NGINX.

nota

Incluso si selecciona NGINX como servidor proxy, esta configuración se omite en un entorno con Docker Compose. La opción Proxy server (Servidor proxy) seguirá teniendo el valor predeterminado None (Ninguno).

Como el proxy del servidor web NGINX está deshabilitado para la plataforma de Docker en Amazon Linux 2 con Docker Compose, debe seguir las instrucciones para generar registros para informes de estado mejorados. Para obtener más información, consulte Creación de registros para informes de estado avanzados (Docker Compose).

Propiedades del entorno y variables de entorno

La sección Environment Properties (Propiedades de entorno) le permite especificar opciones de configuración del entorno en las instancias de Amazon Elastic Compute Cloud (Amazon EC2) que ejecutan la aplicación. Las propiedades del entorno se pasan como pares de clave-valor a la aplicación. En un entorno de Docker, Elastic Beanstalk pasa las propiedades de entorno a contenedores como variables de entorno.

El código de la aplicación que se ejecuta en un contenedor puede hacer referencia a una variable de entorno por su nombre y leer su valor. El código fuente que lee estas variables de entorno variará en función del lenguaje de programación. Encontrará instrucciones para leer los valores de las variables de entorno en los lenguajes de programación que son compatibles con las plataformas administradas por Elastic Beanstalk en el tema correspondiente a la plataforma de que se trate. Para obtener una lista de enlaces a estos temas, consulte Propiedades del entorno y otras opciones del software.

Entornos con Docker Compose

Si administra su entorno de Docker con Docker Compose, debe realizar alguna configuración adicional para recuperar las variables de entorno en los contenedores. Para que los ejecutables que se ejecutan en su contenedor tengan acceso a estas variables de entorno, debe hacer referencia a ellas en el archivo docker-compose.yml. Para obtener más información, consulte Referencia a variables de entorno en contenedores.

Referencia a variables de entorno en contenedores

Si utiliza la herramienta Docker Compose en la plataforma de Docker en Amazon Linux 2, Elastic Beanstalk genera un archivo de entorno de Docker Compose llamado .env en el directorio raíz del proyecto de aplicación. Este archivo almacena las variables de entorno que ha configurado para Elastic Beanstalk.

nota

Si incluye un archivo .env en el paquete de la aplicación, Elastic Beanstalk no generará un archivo .env.

Para que un contenedor haga referencia a las variables de entorno que define en Elastic Beanstalk, debe seguir uno o ambos de estos enfoques de configuración.

  • Agregue el archivo .env generado por Elastic Beanstalk a la opción de configuración env_file del archivo docker-compose.yml.

  • Defina directamente las variables de entorno en el archivo docker-compose.yml.

Los siguientes archivos proporcionan un ejemplo. El archivo docker-compose.yml de ejemplo muestra ambos enfoques.

  • Si define las propiedades del entorno DEBUG_LEVEL=1 y LOG_LEVEL=error, Elastic Beanstalk genera el siguiente archivo .env automáticamente:

    DEBUG_LEVEL=1
LOG_LEVEL=error

  • En este archivo docker-compose.yml, la opción de configuración env_file apunta al archivo .env y también define la variable de entorno DEBUG=1 directamente en el archivo docker-compose.yml.

    services:
  web:
    build: .
    environment:
      - DEBUG=1
    env_file:
      - .env
Notas

  • Si establece la misma variable de entorno en ambos archivos, la variable definida en el archivo docker-compose.yml prevalece sobre la variable definida en el archivo .env.

  • Tenga cuidado de no dejar espacios entre el signo igual (=) y el valor asignado a la variable para evitar que se agreguen espacios a la cadena.

Para obtener más información sobre las variables de entorno en Docker Compose, consulte Environment variables in Compose.

Uso de la característica de interpolación para variables de entorno (Docker Compose)

A partir de la versión de plataforma del 28 de julio de 2023, la ramificación de la plataforma Docker Amazon Linux 2 ofrece la característica de interpolación de Docker Compose. Con esta característica, los valores de un archivo de Compose se pueden establecer mediante variables e interpolarlos en el tiempo de ejecución. Para obtener más información sobre esta característica, consulte Interpolación en el sitio web de documentación de Docker.

importante

Si quiere utilizar esta característica con sus aplicaciones, tenga en cuenta que tendrá que implementar un enfoque que utilice enlaces de plataforma.

Esto es necesario debido a una mitigación que implementamos en el motor de la plataforma. La mitigación garantiza la compatibilidad con versiones anteriores para los clientes que no conocen la nueva característica de interpolación y que ya tienen aplicaciones que utilizan variables de entorno con el carácter $. El motor de plataforma actualizado evita la interpolación de forma predeterminada al reemplazar el personaje $ por caracteres $$.

El siguiente es un ejemplo de un script de enlace de plataforma que puede configurar para permitir el uso de la característica de interpolación.

#!/bin/bash

: '
example data format in .env file
key1=value1
key2=value2
'
envfile="/var/app/staging/.env"
tempfile=$(mktemp)

while IFS= read -r line; do
  # split each env var string at '='
  split_str=(${line//=/ })
  if [ ${#split_str[@]} -eq 2 ]; then
    # replace '$$' with '$'
    replaced_str=${split_str[1]//\$\$/\$}
    # update the value of env var using ${replaced_str}
    line="${split_str[0]}=${replaced_str}"
  fi
  # append the updated env var to the tempfile
  echo "${line}" ≫"${tempfile}"
done < "${envfile}"
# replace the original .env file with the tempfile
mv "${tempfile}" "${envfile}"

Coloque los enlaces de la plataforma en estos dos directorios:

  • .platform/confighooks/predeploy/

  • .platform/hooks/predeploy/

Para obtener más información, consulte Enlaces de la plataforma en el tema Ampliar las plataformas Linux de esta guía.

Creación de registros para informes de estado avanzados (Docker Compose)

El agente de salud de Elastic Beanstalk proporciona métricas de estado del sistema operativo y de las aplicaciones para entornos de Elastic Beanstalk. Se basa en los formatos de registro del servidor web que transmiten información en un formato específico.

Elastic Beanstalk presupone que ejecuta un proxy de servidor web como un contenedor. Por consiguiente, el proxy del servidor web NGINX está deshabilitado para los entornos de Docker que ejecutan Docker Compose. Debe configurar el servidor para que escriba registros en la ubicación y con el formato que utiliza el agente de estado de Elastic Beanstalk. De esta forma, podrá aprovechar al máximo los informes de estado mejorados, aunque el proxy del servidor web esté deshabilitado.

Para obtener instrucciones al respecto, consulte Configuración de los registros de servidor web

Registro personalizado del contenedor de Docker (Docker Compose)

Para solucionar problemas de manera eficiente y monitorear sus servicios en contenedores, puede solicitar registros de instancias de Elastic Beanstalk desde la consola de administración del entorno o desde la CLI de EB. Los registros de instancias se componen de registros de paquetes y registros de cola, combinados y empaquetados, para permitirle ver registros y eventos recientes de una manera eficiente y rápida.

Elastic Beanstalk crea los directorios de registro en la instancia del contenedor, uno para cada servicio definido en el archivo docker-compose.yml, en /var/log/eb-docker/containers/<service name>. Si utiliza la característica Docker Compose en la plataforma de Docker en Amazon Linux 2, puede montar estos directorios en la ubicación dentro de la estructura de archivos del contenedor donde se escriben los registros. Si monta directorios de registro para escribir datos de registro, Elastic Beanstalk podrá recopilar datos de registro de estos directorios.

Si sus aplicaciones están en una plataforma de Docker que no utiliza Docker Compose, puede seguir el procedimiento estándar descrito en Registro personalizado del contenedor de Docker (Docker Compose).

Para configurar los archivos de registros del servicio como archivos de cola y registros de paquetes recuperables

  1. Edite el archivo docker-compose.yml.

  2. Debajo de la clave volumes de su servicio, agregue un montaje de enlace de la manera siguiente:

    "${EB_LOG_BASE_DIR}/<service name>:<log directory inside container>

    En el siguiente archivo docker-compose.yml de ejemplo:

    • nginx-proxy es <nombre del servicio>

    • /var/log/nginx es <directorio de registro dentro del contenedor> 

    services:
  nginx-proxy:
    image: "nginx"
    volumes:
      - "${EB_LOG_BASE_DIR}/nginx-proxy:/var/log/nginx"

  • El directorio var/log/nginx contiene los registros del servicio nginx-proxy en el contenedor y se corresponde con el directorio /var/log/eb-docker/containers/nginx-proxy del host.

  • Todos los registros de este directorio ahora se pueden recuperar como registros de paquete y cola a través de la funcionalidad Solicitar registros de instancia de Elastic Beanstalk.

Notas

  • ${EB_LOG_BASE_DIR} es una variable de entorno establecida por Elastic Beanstalk con el valor /var/log/eb-docker/containers.

  • Elastic Beanstalk crea automáticamente el directorio /var/log/eb-docker/containers/<service name> para cada servicio del archivo docker-compose.yml.

Imágenes de Docker

Las ramificaciones de la plataforma Docker administradas por Docker y ECS para Elastic Beanstalk admiten el uso de imágenes de Docker almacenadas en un repositorio de imágenes en línea público o privado.

Especifique las imágenes por su nombre en Dockerrun.aws.json. Tenga en cuenta estas convenciones:

  • Las imágenes de los repositorios oficiales de Docker Hub utilizan un solo nombre (por ejemplo, ubuntu o mongo).

  • Las imágenes de otros repositorios de Docker Hub se identifican con un nombre de organización (por ejemplo, amazon/amazon-ecs-agent).

  • Las imágenes de otros repositorios online se designan además con un nombre de dominio (por ejemplo, quay.io/assemblyline/ubuntu o account-id.dkr.ecr.us-east-2.amazonaws.com/ubuntu:trusty).

En entornos que utilizan únicamente la plataforma Docker, también puede crear su propia imagen durante la creación del entorno con un archivo Dockerfile. Para obtener más información, consulte Creación de imágenes personalizadas con un Dockerfile. La plataforma Multicontainer Docker no admite esta funcionalidad.

Puede almacenar imágenes personalizadas de Docker en AWS con Amazon Elastic Container Registry (Amazon ECR). Cuando guarda sus imágenes de Docker en Amazon ECR, Elastic Beanstalk se autentica automáticamente en el registro de Amazon ECR con el perfil de instancia del entorno para que no sea necesario generar un archivo de autenticación y cargarlo en Amazon Simple Storage Service (Amazon S3).

No obstante, sí es necesario que proporcione a las instancias permiso para obtener acceso a las imágenes del repositorio de Amazon ECR. Para ello, agregue permisos al perfil de instancia del entorno. Puede asociar la política administrada por AmazonEC2ContainerRegistryReadOnly al perfil de instancia para proporcionar acceso de solo lectura a todos los repositorios de Amazon ECR de la cuenta o conceder acceso a un único repositorio utilizando la siguiente plantilla para crear una política personalizada:

{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "AllowEbAuth",
        "Effect": "Allow",
        "Action": [
          "ecr:GetAuthorizationToken"
        ],
        "Resource": [
          "*"
        ]
      },
      {
        "Sid": "AllowPull",
        "Effect": "Allow",
        "Resource": [
          "arn:aws:ecr:us-east-2:account-id:repository/repository-name"
        ],
        "Action": [
          "ecr:GetAuthorizationToken",
          "ecr:BatchCheckLayerAvailability",
          "ecr:GetDownloadUrlForLayer",
          "ecr:GetRepositoryPolicy",
          "ecr:DescribeRepositories",
          "ecr:ListImages",
          "ecr:BatchGetImage"
        ]
      }
    ]
  }

Sustituya el nombre de recurso de Amazon (ARN) en la política anterior por el ARN del repositorio.

En el archivo Dockerrun.aws.json, haga referencia a la imagen utilizando la URL. En la plataforma Docker, la URL va en la definición de Image:

  "Image": {
      "Name": "account-id.dkr.ecr.us-east-2.amazonaws.com/repository-name:latest",
      "Update": "true"
    },

En la plataforma Multicontainer Docker, utilice la clave image en un objeto de la definición de contenedor:

"containerDefinitions": [
        {
        "name": "my-image",
        "image": "account-id.dkr.ecr.us-east-2.amazonaws.com/repository-name:latest",

Para utilizar una imagen de Docker de un repositorio privado hospedado por un registro online, debe proporcionar un archivo de autenticación que contenga la información necesaria para autenticarse con el registro.

Genere un archivo de autenticación con el comando docker login. En el caso de los repositorios de Docker Hub, ejecute docker login:

$ docker login

En el caso de otros registros, incluya la URL del servidor del registro:

$ docker login registry-server-url
nota

Si su entorno de Elastic Beanstalk utiliza una versión de la plataforma Docker AMI de Amazon Linux (anterior a Amazon Linux 2), lea la información adicional en Configuración de Docker en la AMI de Amazon Linux (anterior a Amazon Linux 2).

Cargue una copia llamada .dockercfg del archivo de autenticación en un bucket de Amazon S3 seguro. El bucket de Amazon S3 debe estar alojado en la misma región de AWS que el entorno que lo está utilizando. Elastic Beanstalk no puede descargar archivos desde un bucket de Amazon S3 alojado en otras regiones. Conceda permisos para la operación s3:GetObject al rol de IAM en el perfil de instancia. Para obtener más información, consulte Administración de perfiles de instancia de Elastic Beanstalk.

Incluya la información del bucket de Amazon S3 en el parámetro Authentication (v1) o authentication (v2) del archivo Dockerrun.aws.json.

Para obtener más información sobre el formato Dockerrun.aws.json de los entornos Docker, consulte Configuración de Docker. En el caso de entornos con varios contenedores, consulte Configuración de Docker administrado por ECS.

Para obtener más información sobre el archivo de autenticación, consulte Store images on Docker Hub y docker login en el sitio web de Docker.

Configuración de actualizaciones administradas para entornos de Docker

Con las actualizaciones de plataforma administradas, puede configurar el entorno para que se actualice automáticamente a la última versión de una plataforma de manera programada.

En el caso de los entornos de Docker, es posible que decida si una actualización de plataforma automática debe suceder en varias versiones de Docker, si la nueva versión de la plataforma incluye una nueva versión de Docker. Elastic Beanstalk admite actualizaciones de plataformas administradas en todas las versiones de Docker cuando se actualiza desde un entorno que ejecuta una versión de plataforma Docker más reciente que 2.9.0. Cuando una nueva versión de la plataforma incluye una nueva versión de Docker, Elastic Beanstalk aumenta el número de versión de actualización secundaria. Por lo tanto, para permitir las actualizaciones de plataforma administradas en diferentes versiones de Docker, habilítelas para las actualizaciones de versiones secundarias y de parche. Para evitar las actualizaciones de plataforma administradas en diferentes versiones de Docker, habilítelas para que solo apliquen las actualizaciones de versión de parche.

Por ejemplo, el siguiente archivo de configuración habilita las actualizaciones de plataforma administradas a las 9:00 h UTC cada martes para las actualizaciones de versiones secundarias y de parche, lo que permite las actualizaciones administradas en diferentes versiones de Docker:

ejemplo .ebextensions/managed-platform-update.config
option_settings:
  aws:elasticbeanstalk:managedactions:
    ManagedActionsEnabled: true
    PreferredStartTime: "Tue:09:00"
  aws:elasticbeanstalk:managedactions:platformupdate:
    UpdateLevel: minor

En los entornos que ejecutan versiones de plataforma de Docker 2.9.0 o anteriores, Elastic Beanstalk nunca realiza las actualizaciones de plataforma administradas si la nueva versión de plataforma incluye una nueva versión de Docker.

Espacios de nombres de la configuración de Docker

Puede usar un archivo de configuración para definir opciones de configuración y realizar otras tareas de configuración en las instancias durante las implementaciones. Las opciones de configuración se pueden definir a través del servicio de Elastic Beanstalk o la plataforma que utilice y están organizadas por espacios de nombres.

nota

Esta información solo se aplica al entorno de Docker que no ejecuta Docker Compose. Esta opción tiene un comportamiento diferente con los entornos de Docker que ejecutan Docker Compose. Para obtener más información sobre los servicios proxy con Docker Compose, consulte Opciones de contenedor.

La plataforma Docker admite las opciones de los siguientes espacios de nombres, además de las opciones admitidas para todos los entornos de Elastic Beanstalk:

  • aws:elasticbeanstalk:environment:proxy: Elija el servidor proxy para su entorno. Docker admite que se ejecute Nginx o ningún servidor proxy.

El siguiente archivo de configuración de ejemplo configura un entorno de Docker de modo que no ejecute ningún servidor proxy.

ejemplo .ebextensions/docker-settings.config
option_settings:
  aws:elasticbeanstalk:environment:proxy:
    ProxyServer: none

Configuración de Docker en la AMI de Amazon Linux (anterior a Amazon Linux 2)

Si su entorno de Elastic Beanstalk Docker utiliza una versión de la plataforma AMI de Amazon Linux (anterior a Amazon Linux 2), lea la información adicional de esta sección.

Esta información le interesa si está usando imágenes de un repositorio privado. A partir de la versión 1.7 de Docker, el comando docker login cambió el nombre del archivo de autenticación y el formato del archivo. Las versiones de la plataforma Docker en la AMI de Amazon Linux (anteriores a Amazon Linux 2) requieren el archivo de configuración anterior en formato ~/.dockercfg.

Con la versión 1.7 de Docker y otras posteriores, el comando docker login crea el archivo de autenticación en ~/.docker/config.json con el siguiente formato.

{
    "auths":{
      "server":{
        "auth":"key"
      }
    }
  }

Con la versión 1.6.2 de Docker y anteriores, el comando docker login crea el archivo de autenticación en ~/.dockercfg con el siguiente formato.

{
    "server" :
    {
      "auth" : "auth_token",
      "email" : "email"
    }
  }

Para convertir un archivo config.json, elimine la clave auths externa, añada una clave email y adapte el documento JSON para que se ajuste al formato antiguo.

En las versiones de la plataforma Docker de Amazon Linux 2, Elastic Beanstalk utiliza el nombre y el formato más recientes del archivo de autenticación. Si está utilizando una versión de plataforma Docker de Amazon Linux 2, puede usar el archivo de autenticación que el comando docker login crea sin aplicar ninguna conversión.

Para mejorar el rendimiento de la AMI de Amazon Linux, Elastic Beanstalk configura dos volúmenes de almacenamiento de Amazon EBS para las instancias de Amazon EC2 del entorno de Docker. Además del volumen raíz que se aprovisiona para todos los entornos de Elastic Beanstalk, se aprovisiona un segundo volumen de 12 GB llamado xvdcz para el almacenamiento de imágenes en entornos de Docker.

Si necesita más espacio de almacenamiento o un mayor número de IOPS para las imágenes de Docker, puede personalizar el volumen de almacenamiento de imágenes utilizando la opción de configuración BlockDeviceMapping del espacio de nombres aws:autoscaling:launchconfiguration.

Por ejemplo, el siguiente archivo de configuración aumenta el tamaño del volumen de almacenamiento a 100 GB con 500 IOPS provisionadas:

ejemplo .ebextensions/blockdevice-xvdcz.config
option_settings:
  aws:autoscaling:launchconfiguration:
    BlockDeviceMappings: /dev/xvdcz=:100::io1:500

Si utiliza la opción BlockDeviceMappings para configurar volúmenes adicionales para la aplicación, debería incluir un mapeo de xvdcz para asegurarse de que se ha creado. En el siguiente ejemplo, se configuran dos volúmenes: el volumen de almacenamiento de imágenes xvdcz con la configuración predeterminada y un volumen de aplicaciones adicional de 24 GB llamado sdh:

ejemplo .ebextensions/blockdevice-sdh.config
option_settings:
  aws:autoscaling:launchconfiguration:
    BlockDeviceMappings: /dev/xvdcz=:12:true:gp2,/dev/sdh=:24
nota

Cuando cambie la configuración de este espacio de nombres, Elastic Beanstalk sustituirá todas las instancias del entorno por instancias que ejecuten la nueva configuración. Para obtener más información, consulte Cambios de configuración.