Configurazione degli ambienti Docker

Esistono diversi modi per configurare il comportamento dell'ambiente Docker per Elastic Beanstalk.

Nota

Se l'ambiente Elastic Beanstalk utilizza una versione della piattaforma AMI Amazon Linux (precedente ad Amazon Linux 2), leggi le informazioni aggiuntive presenti in Configurazione Docker su AMI Amazon Linux (precedente ad Amazon Linux 2).

Configurazione del software in ambienti Docker

È possibile utilizzare la console Elastic Beanstalk per configurare il software in esecuzione sulle istanze dell'ambiente.

Per configurare l'ambiente Docker nella console Elastic Beanstalk

1. Apri la console Elastic Beanstalk e, nell'elenco Regioni, seleziona la tua. Regione AWS

2. Nel pannello di navigazione selezionare Environments (Ambienti), quindi selezionare il nome dell'ambiente dall'elenco.

   Nota

   Se si dispone di molti ambienti, utilizzare la barra di ricerca per filtrare l'elenco degli ambienti.

3. Nel riquadro di navigazione, seleziona Configuration (Configurazione).

4. Nella categoria di configurazione Updates, monitoring, and logging (Aggiornamenti, monitoraggio e registrazione), scegli Edit (Modifica).

5. Apportare le modifiche necessarie alla configurazione.

6. Per salvare le modifiche scegli Apply (Applica) nella parte inferiore della pagina.

Per informazioni sulla configurazione delle impostazioni software in qualsiasi ambiente, consulta Proprietà dell'ambiente e altre impostazioni software. Le sezioni seguenti sono relative alle informazioni specifiche di Docker.

Opzioni del container

La sezione Container options (Opzioni container) contiene opzioni specifiche della piattaforma. Per gli ambienti Docker, consente di scegliere se l'ambiente include o meno il server proxy Nginx.

Ambienti con Docker Compose

Se si gestisce l'ambiente Docker con Docker Compose, Elastic Beanstalk presuppone che si esegua un server proxy come container. Pertanto, il valore predefinito è None (Nessuno) per l'impostazione del Proxy server (Server Proxy) e Elastic Beanstalk non fornisce una configurazione NGINX.

Nota

Anche se si seleziona NGINX come server proxy, questa impostazione viene ignorata in un ambiente con Docker Compose. L'impostazione predefinita del Proxy server (Server Proxy) continua a essere None (Nessuno).

Poiché il proxy del server Web NGINX è disabilitato per Docker sulla piattaforma Amazon Linux 2 con Docker Compose, è necessario seguire le istruzioni per la generazione dei log per la creazione di report sullo stato avanzato. Per ulteriori informazioni, consulta Generazione di log per il reporting sullo stato migliorato (Docker Compose).

Proprietà dell'ambiente e variabili d'ambiente

La sezione Environment Properties (Proprietà ambiente) consente di specificare le impostazioni di configurazione dell'ambiente nelle istanze Amazon Elastic Compute Cloud (Amazon EC2) che eseguono l'applicazione. Le proprietà di ambiente sono passate come coppie chiave-valore all'applicazione. In un ambiente Docker, Elastic Beanstalk passa le proprietà dell'ambiente ai container come variabili di ambiente.

Il codice dell'applicazione in esecuzione in un container può fare riferimento a una variabile di ambiente in base al nome e leggerne il valore. Il codice sorgente che legge queste variabili di ambiente varierà in base al linguaggio di programmazione. È possibile trovare istruzioni per la lettura dei valori delle variabili di ambiente nei linguaggi di programmazione supportati dalle piattaforme gestite da Elastic Beanstalk nell'argomento della piattaforma corrispondente. Per un elenco di collegamenti a questi argomenti, consulta Proprietà dell'ambiente e altre impostazioni software.

Ambienti con Docker Compose

Se si gestisce l'ambiente Docker con Docker Compose, è necessario creare alcune configurazioni aggiuntive per recuperare le variabili di ambiente nei container. Affinché gli eseguibili in esecuzione nel container accedano a queste variabili di ambiente, è necessario fare riferimento a tali variabili in docker-compose.yml. Per ulteriori informazioni, consulta Riferimento alle variabili di ambiente nei container.

Riferimento alle variabili di ambiente nei container

Se si utilizza lo strumento Docker sulla piattaforma Docker per Amazon Linux 2, Elastic Beanstalk genera un file di ambiente Docker Compose denominato .env nella directory principale del progetto dell'applicazione. Questo file memorizza le variabili di ambiente configurate per Elastic Beanstalk.

Nota

Se si include un file .env nel bundle di applicazioni, Elastic Beanstalk non genererà un file .env.

Affinché un container possa fare riferimento alle variabili di ambiente definite in Elastic Beanstalk, è necessario seguire uno o entrambi questi approcci di configurazione.

• Aggiungi il file .env generato da Elastic Beanstalk all'opzione di configurazione env_file nel file docker-compose.yml.

• Definisci direttamente le variabili di ambiente nel file docker-compose.yml.

I seguenti file forniscono un esempio. Il file di esempio docker-compose.yml illustra entrambi gli approcci.

• Se definisci le proprietà di ambiente DEBUG_LEVEL=1 e LOG_LEVEL=error, Elastic Beanstalk genera il seguente file .env:

  DEBUG_LEVEL=1
  LOG_LEVEL=error

• In questo file docker-compose.yml, l'opzione di configurazione env_file punta al file .env e definisce anche la variabile di ambiente DEBUG=1 direttamente nel file docker-compose.yml.

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

Note

• Se si imposta la stessa variabile di ambiente in entrambi i file, la variabile definita nel file docker-compose.yml ha la priorità sulla variabile definita nel file .env.

• Fare attenzione a non lasciare spazi tra il segno di uguale (=) e il valore assegnato alla variabile per evitare che gli spazi vengano aggiunti alla stringa.

Per ulteriori informazioni sulle variabili di ambiente in Docker Compose, vedere Variabili di ambiente in Compose

Utilizzo della funzionalità di interpolazione per le variabili di ambiente (Docker Compose)

A partire dal rilascio della piattaforma del 28 luglio 2023, la ramificazione della piattaforma Docker Amazon Linux 2 offre la funzionalità di interpolazione Docker Compose. Con questa funzionalità, i valori in un file Compose possono essere impostati da variabili e interpolati in fase di runtime. Per ulteriori informazioni su questa funzionalità, consulta la pagina Interpolation sul sito Web della documentazione di Docker.

Importante

Se desideri utilizzare questa funzionalità con le tue applicazioni, tieni presente che dovrai implementare un approccio che utilizzi gli hook della piattaforma.

Ciò è necessario a causa di una mitigazione che abbiamo implementato nel motore della piattaforma. Questa mitigazione garantisce la compatibilità con le versioni precedenti per i clienti che non sono a conoscenza della nuova funzionalità di interpolazione e dispongono di applicazioni esistenti che utilizzano variabili di ambiente con il carattere $. Il motore della piattaforma aggiornato evita l'interpolazione per impostazione predefinita sostituendo il carattere $ con i caratteri $$.

Di seguito è riportato un esempio di script hook della piattaforma che è possibile configurare per abilitare l'uso della funzionalità di interpolazione.

#!/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}"

Posiziona gli hook della piattaforma in entrambe queste directory:

• .platform/confighooks/predeploy/

• .platform/hooks/predeploy/

Per ulteriori informazioni, consulta Hook della piattaforma nell'argomento Estensione delle piattaforme Linux di questa guida.

Generazione di log per il reporting sullo stato migliorato (Docker Compose)

L'agente di integrità di Elastic Beanstalk fornisce parametri di integrità del sistema operativo e delle applicazioni per gli ambienti Elastic Beanstalk. Si basa sui formati di log del server Web che inoltrano le informazioni in un formato specifico.

Elastic Beanstalk presuppone l'esecuzione di un proxy del server Web come container. Di conseguenza, il proxy del server Web NGINX è disabilitato per gli ambienti Docker che eseguono Docker Compose. È necessario configurare il server per scrivere i log nel percorso e nel formato utilizzati dall'agente di integrità di Elastic Beanstalk. In questo modo è possibile utilizzare appieno i report sullo stato avanzato, anche se il proxy del server Web è disabilitato.

Per istruzioni su come eseguire questa operazione, consultare Configurazione dei log del server Web

Registrazione personalizzata del container Docker (Docker Compose)

Per risolvere in modo efficiente i problemi e monitorare i servizi containerizzati, è possibile richiedere i log delle istanze da Elastic Beanstalk tramite la console di gestione dell'ambiente o la CLI EB. I registri delle istanze sono composti da log di bundle e log di coda, combinati e confezionati per consentire di visualizzare i registri e gli eventi recenti in modo efficiente e diretto.

Elastic Beanstalk crea directory di log sull'istanza di container, una per ogni servizio definito nel file docker-compose.yml, in /var/log/eb-docker/containers/<service name>. Se si utilizza la funzionalità Docker Compose sulla piattaforma Docker su Amazon Linux 2, è possibile montare queste directory nella posizione all'interno della struttura del file container in cui vengono scritti i log. Quando si montano le directory di log per la scrittura dei dati di log, Elastic Beanstalk può raccogliere i dati di log da queste directory.

Se le applicazioni si trovano su una piattaforma Docker che non utilizza Docker Compose, è possibile seguire la procedura standard descritta in Registrazione personalizzata del container Docker (Docker Compose).

Per configurare i file di log del servizio in modo che siano file di coda recuperabili e registri di bundle

1. Modificare il file docker-compose.yml.

2. Sotto la chiave volumes per il servizio aggiungere un mount bind come il seguente:

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

   Nel file di esempio docker-compose.yml seguente:

   • nginx-proxy è il <nome del servizio>

   • /var/log/nginx è il <container all'interno della directory di log>

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

• La directory var/log/nginx contiene i log per il servizio nginx-proxy nel container e verrà mappata alla directory /var/log/eb-docker/containers/nginx-proxy sull'host.

• Tutti i log in questa directory sono ora recuperabili come log di bundle e log di coda attraverso la funzionalità dei log di istanza della richiesta di Elastic Beanstalk.

Note

• ${EB_LOG_BASE_DIR} è una variabile di ambiente impostata da Elastic Beanstalk con il valore /var/log/eb-docker/containers.

• Elastic Beanstalk crea automaticamente la directory /var/log/eb-docker/containers/<service name> per ogni servizio nel file docker-compose.yml.

Immagini Docker

Le versioni della piattaforma Docker e ECS gestita da Docker per Elastic Beanstalk supportano l'uso di immagini Docker memorizzate in un repository di immagini online pubblico o privato.

Specifica le immagini per nome in Dockerrun.aws.json. Nota queste convenzioni:

• Le immagini in repository ufficiali su Docker Hub utilizzano un singolo nome (ad esempio ubuntu o mongo).

• Le immagini in altri repository su Docker Hub vengono qualificate con un nome di organizzazione (ad esempi, amazon/amazon-ecs-agent).

• Le immagini in altri repository online vengono ulteriormente qualificate tramite un nome di dominio (ad esempio quay.io/assemblyline/ubuntu o account-id.dkr.ecr.us-east-2.amazonaws.com/ubuntu:trusty).

Per gli ambienti che utilizzano solo la piattaforma Docker, è anche possibile creare una propria immagine durante la creazione dell'ambiente con un Dockerfile. Per informazioni dettagliate, consulta Creazione di immagini personalizzate con un Dockerfile. La piattaforma multicontainer Docker non supporta questa funzionalità.

Utilizzo di immagini da un repository Amazon ECR

Puoi archiviare le tue immagini Docker personalizzate AWS con Amazon Elastic Container Registry (Amazon ECR). Quando memorizzi le immagini Docker in Amazon ECR, Elastic Beanstalk si autentica automaticamente nel registro Amazon ECR con il profilo dell'istanza dell'ambiente. Non devi pertanto generare un file di autenticazione e caricarlo in Amazon Simple Storage Service (Amazon S3).

È tuttavia necessario fornire alle istanze l'autorizzazione di accedere alle immagini nel repository Amazon ECR aggiungendo le autorizzazioni necessarie per il profilo dell'istanza dell'ambiente. Puoi allegare la policy ContainerRegistryReadOnly gestita di AmazonEC2 al profilo dell'istanza per fornire l'accesso in sola lettura a tutti gli archivi Amazon ECR del tuo account o concedere l'accesso a un singolo repository utilizzando il seguente modello per creare una politica personalizzata:

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

Sostituisci l'Amazon Resource Name (ARN) nella policy sopra indicata con l'ARN del repository.

Nel file Dockerrun.aws.json, fai riferimento all'immagine in base all'URL. Per la piattaforma Docker, l'URL va nella definizione Image:

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

Per la piattaforma multicontainer Docker, utilizzare la chiave image in un oggetto di definizione del container:

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

Utilizzo di immagini da un repository privato

Per usare un'immagine Docker in un repository privato ospitato da un registro online, è necessario fornire un file di autenticazione che contenga le informazioni necessarie per eseguire l'autenticazione con il registro.

Genera un file di autenticazione con il comando docker login. Per repository su Docker Hub, esegui docker login:

$ docker login

Per gli altri registri, includi l'URL del server di registro:

$ docker login registry-server-url

Nota

Se l'ambiente Elastic Beanstalk utilizza una versione della piattaforma AMI Amazon Linux (precedente ad Amazon Linux 2), leggi le informazioni aggiuntive presenti in Configurazione Docker su AMI Amazon Linux (precedente ad Amazon Linux 2).

Carica una copia denominata .dockercfg del file di autenticazione in un bucket Amazon S3 sicuro. Il bucket Amazon S3 deve essere ospitato nella stessa AWS regione dell'ambiente che lo utilizza. Elastic Beanstalk non può scaricare file da un bucket Amazon S3 ospitato in altre regioni. Concedi le autorizzazioni per l'operazione s3:GetObject al ruolo IAM nel profilo dell'istanza. Per informazioni dettagliate, consulta Gestione dei profili dell'istanza Elastic Beanstalk.

Includi le informazioni sul bucket Amazon S3 nel parametro Authentication (v1) o authentication (v2) nel file Dockerrun.aws.json.

Per ulteriori informazioni sul formato Dockerrun.aws.json per gli ambienti Docker, consulta Configurazione di Docker. Per ambienti multicontainer, consulta Configurazione di Docker gestito da ECS.

Per ulteriori informazioni sul file di autenticazione, vedi Memorizzare le immagini in Docker Hub e login docker sul sito Web Docker.

Configurazione degli aggiornamenti gestiti per gli ambienti Docker

Grazie agli aggiornamenti gestiti della piattaforma, puoi configurare il tuo ambiente per eseguire automaticamente l'aggiornamento alla versione più recente in base a una pianificazione.

Per gli ambienti Docker, puoi decidere se eseguire un aggiornamento automatico della piattaforma su più versioni Docker, nel caso in cui la nuova versione della piattaforma includa una nuova versione Docker. Elastic Beanstalk supporta gli aggiornamenti della piattaforma gestita tra versioni Docker durante l'aggiornamento da un ambiente che esegue una versione della piattaforma Docker più recente della 2.9.0. Se una nuova versione della piattaforma include una nuova versione di Docker, Elastic Beanstalk incrementa il numero di versione dell'aggiornamento secondario. Di conseguenza, per consentire l'esecuzione di questa funzionalità su più versioni Docker, abilita gli aggiornamenti gestiti della piattaforma sia per la versione secondaria, sia per le patch. Per impedirla invece, abilita gli aggiornamenti gestiti della piattaforma per la sola applicazione degli aggiornamenti di versione delle patch.

Ad esempio, il seguente file di configurazione abilita gli aggiornamenti gestiti della piattaforma alle 9:00 UTC di ogni martedì, sia per la versione secondaria sia per le patch; di conseguenza, consente gli aggiornamenti gestiti su più versioni Docker:

Esempio .ebextensions/ .config managed-platform-update

option_settings:
  aws:elasticbeanstalk:managedactions:
    ManagedActionsEnabled: true
    PreferredStartTime: "Tue:09:00"
  aws:elasticbeanstalk:managedactions:platformupdate:
    UpdateLevel: minor

Se in un ambiente è in esecuzione la versione della piattaforma Docker 2.9.0 o precedente, Elastic Beanstalk non esegue mai gli aggiornamenti gestiti se la nuova versione di configurazione della piattaforma include una nuova versione Docker.

Spazio dei nomi di configurazione di Docker

Puoi utilizzare un file di configurazione per impostare le opzioni di configurazione ed eseguire alte attività di configurazione delle istanze durante le distribuzioni. Le opzioni di configurazione, che possono essere definite dal servizio Elastic Beanstalk o dalla piattaforma utilizzata, sono organizzate in spazi dei nomi.

Nota

Queste informazioni si applicano solo all'ambiente Docker in cui non è in esecuzione Docker Compose. Questa opzione ha un comportamento diverso con gli ambienti Docker che eseguono Docker Compose. Per ulteriori informazioni sui servizi proxy con Docker Compose, consulta Opzioni del container.

Oltre alle opzioni supportate per tutti gli ambienti Elastic Beanstalk, la piattaforma Docker supporta quelle incluse negli spazi dei nomi seguenti:

• aws:elasticbeanstalk:environment:proxy: scegliere il server proxy per l'ambiente in uso. Docker supporta l'esecuzione di Nginx oppure nessun server proxy.

Il seguente file di configurazione di esempio consente di configurare un ambiente Docker in modo che non venga eseguito alcun server proxy.

Esempio .ebextensions/docker-settings.config

option_settings:
  aws:elasticbeanstalk:environment:proxy:
    ProxyServer: none

Configurazione Docker su AMI Amazon Linux (precedente ad Amazon Linux 2)

Se l'ambiente Docker di Elastic Beanstalk utilizza una versione della piattaforma AMI Amazon Linux (precedente ad Amazon Linux 2), leggi le informazioni aggiuntive presenti in questa sezione.

Utilizzo di un file di autenticazione per un repository privato

Queste informazioni sono rilevanti per l'utente se si utilizzano immagini provenienti da un repository privato. A partire dalla versione Docker 1.7, il comando docker login ha modificato il nome del file di autenticazione e il formato del file. Le versioni della piattaforma Docker su AMI Amazon Linux (precedenti ad Amazon Linux 2) richiedono la versione precedente del file di configurazione del formato ~/.dockercfg.

Con Docker versione 1.7 e successive, il comando docker login crea il file di autenticazione in ~/.docker/config.json nel formato seguente.

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

Con Docker versione 1.6.2 e versioni precedenti, il comando docker login crea il file di autenticazione in ~/.dockercfg nel formato seguente.

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

Per convertire un file config.json, rimuovi la chiave auths esterna, aggiungi una chiave email e appiattisci il documento in formato JSON per farlo corrispondere al formato precedente.

Sulle versioni della piattaforma Docker per Amazon Linux 2, Elastic Beanstalk utilizza il nome e il formato del file di autenticazione più recenti. Se si utilizza una versione della piattaforma Docker per Amazon Linux 2, è possibile utilizzare il file di autenticazione creato dal comando docker login senza alcuna conversione.

Configurazione di volumi di storage aggiuntivi

Per migliorare le prestazioni su AMI Amazon Linux, Elastic Beanstalk configura due volumi di storage Amazon EBS per le istanze Amazon EC2 dell'ambiente Docker. Oltre al volume root assegnato per tutti gli ambienti Elastic Beanstalk, un secondo volume da 12 GB denominato xvdcz viene assegnato per lo storage delle immagini negli ambienti Docker.

Se hai bisogno di più spazio di archiviazione o i maggior IOPS per le immagini Docker, puoi personalizzare il volume dell'immagine dello storage utilizzando l'opzione di configurazione BlockDeviceMapping nel namespace aws:autoscaling:launchconfiguration.

Ad esempio, il seguente file di configurazione aumenta le dimensioni del volume di storage a 100 GB con 500 provisioned IOPS:

Esempio .ebextensions/blockdevice-xvdcz.config

option_settings:
  aws:autoscaling:launchconfiguration:
    BlockDeviceMappings: /dev/xvdcz=:100::io1:500

Se utilizzi l'opzione BlockDeviceMappings per configurare volumi aggiuntivi per la tua applicazione, devi includere una mappatura per xvdcz per essere certo che venga creato. L'esempio seguente consente di configurare due volumi, il volume di storage dell'immagine xvdcz con le impostazioni predefinite e ulteriori 24 GB di volume dell'applicazione con nome sdh:

Esempio .ebextensions/blockdevice-sdh.config

option_settings:
  aws:autoscaling:launchconfiguration:
    BlockDeviceMappings: /dev/xvdcz=:12:true:gp2,/dev/sdh=:24

Nota

Quando modifichi le impostazioni in questo spazio dei nomi, Elastic Beanstalk sostituisce tutte le istanze dell'ambiente con le istanze che eseguono la nuova configurazione. Per informazioni dettagliate, consulta Modifiche di configurazione.