.dockerignore
Création d’un fichier .dockerignore
A l’instar de Git, pour des gains de performance et des raisons de sécurité, il est préférable de créer un fichier .dockerignore (au même niveau que le Dockerfile) référençant les fichiers à écarter du contexte.
# comment */temp* */*/temp* temp? Dockerfile *.md !README.md README-secret.md
Dockerfile
FROM <image>[:<tag>|@<digest>]
FROM | Indique l’image de base utilisée pour le build |
FROM centos | |
FROM ubuntu:16.04 | |
FROM ubuntu@sha256:8e2324f2288c26e1393b63e680ee7844202391414dbd48497e9a4fd997cd3cbf |
MAINTAINER <author's detail>
MAINTAINER | Informations relatives à l’auteur du build |
MAINTAINER DarwinOS <darwinos@opensharing.fr> |
COPY <src> ... <dst>
COPY | Copier des fichiers de l’hôte Docker vers le système de fichiers de l’image construite. Les répertoires absents sur la destination seront créés. Si le chemin de destination est relatif, c’est par rapport à WORKDIR (par défaut la racine). |
COPY html /var/www/html | |
COPY httpd.conf magic /etc/httpd/conf/ |
ADD <src> ... <dst>
ADD | Semblable à la commande COPY mais prend en charge les archives tar (extraites sur la destination) et les URLs comme sources |
ADD archive.tar / | |
ADD rootfs.tar.xz / |
ENV <key> <value>
Les variables définies avec ENV pourront être utilisées avec les instructions ADD, COPY, ENV, EXPOSE, LABEL, USER, WORKDIR, VOLUME, STOPSIGNAL, et ONBUILD.
ENV | Définir une variable d’environnement accessible dans l’image construite |
ENV DEBUG_LVL 3 (sera appelée ${DEBUG_LVL}) | |
ENV APACHE_LOG_DIR /var/log/apache (sera appelée ${APACHE_LOG_DIR}) |
ARG <variable>[=<default value>]
Les variables définies avec ARG pourront être utilisées avec les instructions ADD, COPY, ENV, EXPOSE, LABEL, USER, WORKDIR, VOLUME, STOPSIGNAL, et ONBUILD.
ARG | Définir une variable qui sera affectée (sauf default value) lors de la construction de l’image |
ARG usr (sera appelée ${usr}) | |
ARG uid=1000 (sera appelée ${uid}) | |
docker build --build-arg usr=app --build-arg uid=100 . |
USER <UID>|<UName>
USER | Définir l’utilisateur effectif du processus (par défaut root), par UID ou son nom |
USER 33 | |
USER www-data |
WORKDIR <dirpath>
Souvent utilisée conjointement avec les commandes RUN, CMD et ENTRYPOINT.
Les commandes COPY et ADD l’utilise implicitement lors des copies vers une destination à chemin relatif. Relatif à WORKDIR justement.
WORKDIR <dirpath> est équivalent et préférable à RUN cd <dirpath>
WORKDIR | Définir le répertoire de travail sur l’image construite. Par défaut c’est la racine / (root). |
WORKDIR /var/log |
HEALTHCHECK [<options>] CMD <command>
Vérifie l’état de santé d’un container en lançant la commande spécifiée à l’intérieur du container.
Après le timeout indiqué, le container est considéré en échec.
Après le nombre d’essais indiqués par l’option retry, le container est considéré comme unhealthy.
Rmq : exit 1 peut être remplacé par false.
- --interval=DURATION : Time between running the check (default: 30s)
- --retries=N : Consecutive failures needed to report unhealthy (default:3)
- --timeout=DURATION : Maximum time to allow one check to run (default: 30s)
- --start-period=DURATION : Start period for the container to initialize before starting health-retries countdown (default: 0s)
HEALTHCHECK | Vérifier l’état de santé d’un container. |
HEALTHCHECK --interval=5m --timeout=3s CMD curl -f http://localhost/ || exit 1 | |
HEALTHCHECK --interval=5s --timeout=3s CMD pg_isready -U postgres || exit 1 |
VOLUME ["<mountpoint>"]
ou
VOLUME <mountpoint>
VOLUME | Créer un répertoire sur l’image construite qui servira de point de montage depuis l’hôte Docker ou d’autres containers |
VOLUME ["/var/www", "/var/db"] | |
VOLUME /var/www /var/db |
EXPOSE <port>[/<proto>] [<port>[/<proto>]...]
Si le protocole n’est pas spécifié, c’est TCP par défaut.
Plusieurs ports/protocoles peuvent être exposés et spécifiés sur une seule instruction.
EXPOSE | Exposer un port d’écoute pour la communication entre le container et l’extérieur. Exposer n’est pas publier |
EXPOSE 7373/udp 8080 |
LABEL <key-1>=<val-1> <key-2>=<val-2> ... <key-n>=<val-n>
Il est préférable (mais non obligatoire) d’utiliser une seule instruction LABEL, quitte à déclarer plusieurs paires key=value pour la même instruction.
LABEL | Définir des métadonnées pour l’image construite |
LABEL "org.label-schema.vendor"="ACME Incorporated" "org.label-schema.version"="1.0" |
RUN <command>
Forme Shell : Commande exécutée dans un Shell : /bin/sh -c sous Linux, cmd /S /C sous Windows.
ou
RUN ["<exec>", "<arg-1>", ..., "<arg-n>"]
Forme Exec : Commande non exécutée dans un Shell.
RUN echo $HOME
équivaut à RUN [ "sh", "-c", "echo $HOME" ]
Il est préférable (mais non obligatoire) d’utiliser une seule instruction RUN afin de réduire le nombre de layers lors de la construction de l’image.
RUN | Exécuter une ou plusieurs commandes dans une couche au-dessus de l’image de base lors de la construction de la nouvelle image |
RUN apt-get update && apt-get install -y apache2 && apt-get clean |
Même commande, sur plusieurs lignes :
RUN apt-get update && \ apt-get install -y apache2 && \ apt-get clean
CMD ["<exec>", "<arg-1>", ..., "<arg-n>"]
Forme Exec : Commande non exécutée dans un Shell.
ou
CMD <command>
Forme Shell : Commande exécutée dans un Shell : /bin/sh -c sous Linux, cmd /S /C sous Windows.
CMD echo $HOME
équivaut à CMD [ "sh", "-c", "echo $HOME" ]
Il est préférable (mais non obligatoire) d’utiliser une seule instruction CMD sachant que seule la dernière sera exécutée.
CMD | Exécuter une commande lors du lancement d’un container basé sur l’image construite, sauf si une autre commande est passée comme argument du container. |
CMD ["echo", "Commande par défaut"] | |
docker container run b905616e2e7b echo "Remplace la commande par défaut" |
ENTRYPOINT ["<exec>", "<arg-1>", ..., "<arg-n>"]
Forme Exec : Commande non exécutée dans un Shell.
ou
ENTRYPOINT <command>
Forme Shell : Commande exécutée dans un Shell : /bin/sh -c sous Linux, cmd /S /C sous Windows.
ENTRYPOINT echo $HOME
équivaut à ENTRYPOINT [ "sh", "-c", "echo $HOME" ]
Il est préférable (mais non obligatoire) d’utiliser une seule instruction ENTRYPOINT sachant que seule la dernière sera exécutée.
ENTRYPOINT | Exécuter une commande lors du lancement d’un container basé sur l’image construite en utilisant les arguments de l’instruction CMD comme arguments sauf si d’autres sont passés lors du lancement du container |
ENTRYPOINT ["echo", "Argument toujours affiché"]CMD ["Argument par défaut"] | |
docker container run b905616e2e7b "Remplace l’argument par défaut de CMD" | |
docker container run -it --entrypoint="/sur/bin/top" b905616e2e7b |
No ENTRYPOINT | ENTRYPOINT exec_entry p1_entry | ENTRYPOINT ["exec_entry", "p1_entry"] | |
---|---|---|---|
No CMD | error, not allowed | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry |
CMD ["exec_cmd", "p1_cmd"] | exec_cmd p1_cmd | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry exec_cmd p1_cmd |
CMD ["p1_cmd", "p2_cmd"] | p1_cmd p2_cmd | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry p1_cmd p2_cmd |
CMD exec_cmd p1_cmd | /bin/sh -c exec_cmd p1_cmd | /bin/sh -c exec_entry p1_entry | exec_entry p1_entry /bin/sh -c exec_cmd p1_cmd |
Construction de l’image à partir du Dockerfile
Généralement le Dockerfile se trouve à la racine du contexte (tout comme le .dockerignore).
$ docker image build .
ou
$ docker build .
ex :
Avec Dockerfile
FROM busybox RUN echo "hello world" COPY . /home/workfiles/
Avec .dockerignore
Dockerfile
$ docker image build . Sending build context to Docker daemon 2.048kB Step 1/3 : FROM busybox latest: Pulling from library/busybox 90e01955edcd: Pull complete Digest: sha256:2a03a6059f21e150ae84b0973863609494aad70f0a80eaeb64bddd8d92465812 Status: Downloaded newer image for busybox:latest ---> 59788edf1f3e Step 2/3 : RUN echo "hello world" ---> Running in af7de1f071bf hello world Removing intermediate container af7de1f071bf ---> 00778e2bdadf Step 3/3 : COPY . /home/workfiles/ ---> 14eedf0143d8 Successfully built 14eedf0143d8 $ docker image ls REPOSITORY TAG IMAGE ID CREATED SIZE <none> <none> 14eedf0143d8 10 seconds ago 1.15MB $ docker image history 14eedf0143d8 IMAGE CREATED CREATED BY SIZE COMMENT 14eedf0143d8 56 seconds ago /bin/sh -c #(nop) COPY dir:880576b49fa41beee… 60B 00778e2bdadf 56 seconds ago /bin/sh -c echo "hello world" 0B 59788edf1f3e 13 days ago /bin/sh -c #(nop) CMD ["sh"] 0B <missing> 13 days ago /bin/sh -c #(nop) ADD file:63eebd629a5f7558c… 1.15MB $ docker run -it --name busytest 14eedf0143d8 / # ls /home/workfiles/ essai.txt
Mais il est possible de spécifier le chemin vers le Dockerfile et le contexte, tout en définissant un tag pour l’image :
$ docker image build -f /path/to/Dockerfile -t image:tag /path/to/context-dir/
ou
$ docker build -f /path/to/Dockerfile -t image:tag /path/to/context-dir/
ex :
Avec dockerfiles/Dockerfile
FROM busybox RUN echo "hello world" COPY . /home/workfiles/
$ docker image build -f dockerfiles/Dockerfile -t darwinos/repotest:busybox-V1.2 docker/ Sending build context to Docker daemon 2.095kB Step 1/3 : FROM busybox latest: Pulling from library/busybox 07a152489297: Pull complete Digest: sha256:141c253bc4c3fd0a201d32dc1f493bcf3fff003b6df416dea4f41046e0f37d47 Status: Downloaded newer image for busybox:latest ---> 8c811b4aec35 Step 2/3 : RUN echo "hello world" ---> Running in 6b6bbf94efeb hello world Removing intermediate container 6b6bbf94efeb ---> 7d7ff4a1708b Step 3/3 : COPY . /home/workfiles/ ---> 79d9a58ba6da Successfully built 79d9a58ba6da Successfully tagged darwinos/repotest:busybox-V1.2 $ docker image ls darwinos/repotest:busybox-V1.2 REPOSITORY TAG IMAGE ID CREATED SIZE darwinos/repotest busybox-V1.2 79d9a58ba6da 29 seconds ago 1.15MB
On peut ensuite lancer un container à partir de cette image :
$ docker run -it --name busytest darwinos/repotest:busybox-V1.2 / # ls /home/workfiles/ essai.txt
docker-compose.yml
version
version | Version du format de fichier Compose |
version: "3" |
services
services | Regroupement des configurations de chaque container |
services: db: [...] wordpress: [...] |
Le format de définition de chaque service se fait selon le format suivant :
services: --> container name: ----> container options --> container name: ----> container options
Chaque container créé portera un nom généré selon le format : dossier-courant_service-name_X, sauf si la sous-instruction container_name: est présente.
image
image | Définit l’image de base du container à télécharger sur le Docker Registry. Aucune Dockerfile ne sera utilisée |
db: image: postgres:9.4 |
build
build | Utilisée seule, cette instruction définit le contexte de construction de l’image où se trouve le Dockerfile. Utilisée comme objet, elle permet de définir son contexte, un Dockerfile alternatif, des options utilisées pour la construction de l’image ou encore des labels. Si build et image sont utilisés, alors l’image construite aura le nom spécifié par l’instruction image. |
webapp: build: ./dir webapp: build: context: ./dir dockerfile: Dockerfile-alternate args: buildno: 1 |
context
context | Utilisée conjointement avec l’instruction build, elle définit le contexte de construction de l’image où se trouve le Dockerfile. Le chemin est absolu, ou relatif au fichier Compose |
worker: build: context: ./worker |
dockerfile
dockerfile | Utilisée conjointement avec l’instruction build, elle définit un Dockerfile alternatif |
worker: build: context: ./worker dockerfile: Dockerfile-alternate |
args
args | Utilisée conjointement avec l’instruction build, elle définit des valeurs de variables d’environnement passées à la construction et faisant référence à des variables du Dockerfile. On peut les définir sous forme de dictionnaire ou de liste |
#Dockerfile ARG buildno ARG gitcommithash RUN echo "Build number: ${buildno}" RUN echo "Based on commit: ${gitcommithash}" |
labels
labels | Utilisée conjointement avec l’instruction build, elle ajoute des métadonnées à l’image construite. Les étiquettes sont spécifiées en notation reverse-DNS sous forme de dictionnaire ou de liste |
#Labels sous forme de dictionnaire webapp: build: context: . labels: com.example.description: "Accounting webapp" com.example.department: "Finance" com.example.label-with-empty-value: "" |
command
command | Remplace la commande CMD par défaut de l’image |
command: bundle exec thin -p 3000 |
volumes
volumes | A l’intérieur de la définition d’un container, définit un volume à monter (de type volume (général) ou bind spécifique)). Au top level, définit les volumes de type volume (créés globalement ou via le fichier Compose par la commande docker volume create) utilisés par les containers |
#Volume de type volume : nouvelle notation web: image: nginx:alpine volumes: - type: volume source: mydata target: /data volumes: mydata: |
ports
ports | Définit les ports du container à exposer ou le mappage des ports entre l’hôte et le container |
#Nouvelle notation ports: - target: 80 published: 8080 protocol: tcp mode: host |
networks
networks | Au niveau de la définition d’un container, définit les réseaux auxquels il a accès ou sur lequel il est accessible. Au niveau top level, définit les réseaux utilisés par les containers et créés (manuellement ou automatiquement via le fichier Compose) avec la commande docker network create |
vote: build: ./vote command: python app.py volumes: - ./vote:/app ports: - "5000:80" networks: - front-tier - back-tier networks: front-tier: back-tier: |
container_name
container_name | Définit un nom pour le container créé, afin de remplacer le nom automatiquement créé |
redis: image: redis:alpine container_name: redis ports: ["6379"] networks: - back-tier |
depends_on
depends_on | Définit les dépendances des containers et donc les priorités lors de leur démarrage, les dépendances étant démarrées avant le container concerné |
version: '3' services: web: build: . depends_on: - db - redis redis: image: redis db: image: postgres |
environment
environment | Ajouter des variables d’environnement au container créé. Les variables sont définit sous forme d’un dictionnaire ou d’une liste. Les valeurs 'true', 'false', 'yes' et 'no' doivent être quotées. Pour des variables d’environnement utilisées lors de la construction de l’image avec l’instruction build, voir la sous-instruction args. |
#Sous forme d'un dictionnaire environment: RACK_ENV: development SHOW: 'true' SESSION_SECRET: |
restart
restart | Définit les conditions de redémarrage d’un service lorsque le démon Docker est lui-même redémarré : always (toujours), "no" (jamais, ici ne pas oublier les guillemets), on-failure (en cas d’erreur), unless-stopped (sauf s’il a été volontairement arrêté). |
redis: image: redis:alpine container_name: redis restart: always ports: ["6379"] networks: - back-tier |
healthcheck
- interval: DURATION : Time between running the check (default: 30s)
- retries: N : Consecutive failures needed to report unhealthy (default:3)
- timeout: DURATION : Maximum time to allow one check to run (default: 30s)
- start_period: DURATION : Start period for the container to initialize before starting health-retries countdown (default: 0s)
healthcheck | Vérifie l’état de santé d’un container en lançant la commande spécifiée à l’intérieur du container. |
web: image: nginx healthcheck: test: ["CMD", "curl", "-f", "http://localhost"] interval: 1m30s timeout: 10s retries: 3 start_period: 1m |
docker-stack.yml
deploy
deploy | Spécifie la configuration relative au déploiement et aux services en exécution. |
version: '3' services: redis: image: redis:alpine deploy: replicas: 6 update_config: parallelism: 2 delay: 10s restart_policy: condition: on-failure |
mode
mode | Soit "global" (un container par node), soit "replicated" (un nombre défini de containers par node) |
version: '3' services: worker: image: dockersamples/examplevotingapp_worker deploy: mode: global |
replicas
replicas | Le service est répliqué (mode "replicated", mode par défaut), spécifie le nombre de containers à exécuter au lancement du service |
version: '3' services: worker: image: dockersamples/examplevotingapp_worker networks: - frontend - backend deploy: mode: replicated replicas: 6 |
restart_policy
restart_policy | Spécifie les paramètres de redémarrage des containers |
version: "3" services: redis: image: redis:alpine deploy: restart_policy: condition: on-failure delay: 5s max_attempts: 3 window: 120s |
condition
condition | Dans le cadre de la directive "restart_policy", spécifie les conditions de redémarrage des containers : any (par défaut), on-failure, none |
version: "3" services: redis: image: redis:alpine deploy: restart_policy: condition: on-failure delay: 5s max_attempts: 3 window: 120s |
delay
delay | Dans le cadre de la directive "restart_policy", temps d’attente en secondes entre deux tentative de redémarrage (par défaut 0). |
version: "3" services: redis: image: redis:alpine deploy: restart_policy: condition: on-failure delay: 5s max_attempts: 3 window: 120s |
max_attempts
max_attempts | Dans le cadre de la directive "restart_policy", définit le nombre de tentative de redémarrage du service avant d’abandonner (par défaut ne jamais abandonner). |
version: "3" services: redis: image: redis:alpine deploy: restart_policy: condition: on-failure delay: 5s max_attempts: 3 window: 120s |
window
window | Dans le cadre de la directive "restart_policy", définit le temps d’attente en secondes avant de considérer un redémarrage comme réussi (par défaut immédiatement). |
version: "3" services: redis: image: redis:alpine deploy: restart_policy: condition: on-failure delay: 5s max_attempts: 3 window: 120s |
update_config
update_config | Spécifie les paramètres de mise à jour du service. |
version: '3.4' services: vote: image: dockersamples/examplevotingapp_vote:before depends_on: - redis deploy: replicas: 2 update_config: parallelism: 2 delay: 10s |
rollback_config
rollback_config | Spécifie les paramètres de rollback du service dans le cas d’une mise à jour ayant échoué. |
version: '3.7' services: vote: image: dockersamples/examplevotingapp_vote:before depends_on: - redis deploy: replicas: 2 rollback_config: parallelism: 2 delay: 10s |
parallelism
parallelism | Dans le cadre des directives "update_config" et "rollback_config", définit le nombre de containers à mettre à jour ou rollbacker en une fois. |
version: '3.4' services: vote: image: dockersamples/examplevotingapp_vote:before depends_on: - redis deploy: replicas: 2 update_config: parallelism: 2 delay: 10s |
delay
delay | Dans le cadre des directives "update_config" et "rollback_config", définit le temps d’attente avant de mettre à jour ou rollbacker un groupe de containers spécifié par la directive parallelism. |
version: '3.4' services: vote: image: dockersamples/examplevotingapp_vote:before depends_on: - redis deploy: replicas: 2 update_config: parallelism: 2 delay: 10s |
configs (syntaxe courte)
configs | Donne accès à une configuration existante (external, créée avec docker config create) ou nouvelle via un montage depuis l’hôte. Seul le service concerné accède à la configuration définie. La syntaxe courte offre moins d’options de paramétrage. |
version: "3.3" services: redis: image: redis:latest deploy: replicas: 1 configs: - my_config - my_other_config configs: my_config: file: ./my_config.txt my_other_config: external: true |
configs (syntaxe longue)
configs | Donne accès à une configuration existante (external, créée avec docker config create) ou nouvelle via un montage depuis l’hôte. Seul le service concerné accède à la configuration définie. La syntaxe longue offre plus d’options de paramétrage. |
version: "3.3" services: redis: image: redis:latest deploy: replicas: 1 configs: - source: my_config target: /redis_config uid: '103' gid: '103' mode: 0440 configs: my_config: file: ./my_config.txt my_other_config: external: true |
secrets (syntaxe courte)
secrets | Donne accès à un secret existant (external, créé avec docker secret create) ou nouveau via un montage depuis l’hôte. Seul le service concerné accède au secret défini. La syntaxe courte offre moins d’options de paramétrage. |
version: "3.1" services: redis: image: redis:latest deploy: replicas: 1 secrets: - my_secret - my_other_secret secrets: my_secret: file: ./my_secret.txt my_other_secret: external: true |
secrets (syntaxe longue)
secrets | Donne accès à un secret existant (external, créé avec docker secret create) ou nouveau via un montage depuis l’hôte. Seul le service concerné accède au secret défini. La syntaxe longue offre plus d’options de paramétrage. |
version: "3.1" services: redis: image: redis:latest deploy: replicas: 1 secrets: - source: my_secret target: redis_secret uid: '103' gid: '103' mode: 0440 secrets: my_secret: file: ./my_secret.txt my_other_secret: external: true |
Pour aller plus loin