From e705d4915cedb9195a283477fea49c51337e2db1 Mon Sep 17 00:00:00 2001 From: Guillaume Tardif Date: Thu, 15 Oct 2020 17:41:51 +0200 Subject: [PATCH] Adding documentation for single container run and `docker run flags` support in ACI Signed-off-by: Guillaume Tardif --- docs/aci-container-features.md | 68 ++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 docs/aci-container-features.md diff --git a/docs/aci-container-features.md b/docs/aci-container-features.md new file mode 100644 index 00000000..b3550860 --- /dev/null +++ b/docs/aci-container-features.md @@ -0,0 +1,68 @@ +# Azure Container Instances: running single containerrs + +Single containes can be executed on ACI with the `docker run` command. +A single container is executed in its own ACI container group, that will container only one container. + +Containers can be listed with the `docker ps` command, and stopped and removed with `docker stop ` and `docker rm `. + +# Docker run options for ACI containers + +The table below lists supported `docker run` flags and their ACI counterparts. + +__Legend:__ + +- __✓:__ Implemented +- __n:__ Not yet implemented +- __x:__ Not applicable / no available conversion + +| Flag |Map| Notes +|-----------------------|---|---------------------------------| +| --cpus | ✓ | See [Container Resources](#container-resources) +| -d, --detach | ✓ | Detach from container logs when container starts. By default, the command line stays attached and follow container logs +| --domainname | ✓ | See [Exposing ports](#exposing-ports) +| --e, --env | ✓ | Sets environment variable +| --envFile | ✓ | Sets environment variable from and external file +| -l, --label | x | Unsupported in Docker ACI integration, due to limitations of ACI Tags +| -m, --memory | ✓ | See [Container Resources](#container-resources) +| --name | ✓ | provide a name for the container. Name must be unique withing the ACI resource group. a name is generated by default. +| -p, --publish | ✓ | See [Exposing ports](#exposing-ports). Only symetrical por mapping is supported in ACI. +| --restart | ✓ | Restart policy, must be one of: `any`, `none`, `on-failure`. +| --rm | x | Not supported as [ACI does not support auto-delete containers](https://feedback.azure.com/forums/602224-azure-container-instances/suggestions/34066633-support-auto-delete-of-aci-when-container-exits-no) +| -v, --volume | ✓ | See [Persistent Volumes](#persistent-volumes) + +## Exposing ports + +You can expose one or several port of a container with `docker run -p :` +If exposing port(s) when running a container, the corresponding ACI container group will be exposed with a public IP allocated and the required port(s) accessible. +> Note: [ACI does not support port mapping](https://feedback.azure.com/forums/602224-azure-container-instances/suggestions/34082284-support-for-port-mapping), so the same port number must be specified when using `-p :`. + +When exposing ports, a container can also specify the service `--domainname` flag to set a DNS hostname. `domainname` will be used to specify the ACI DNS Label Name, and the ACI container group will be reachable at `..azurecontainer.io`. +`domainname` must be unique globally in .azurecontainer.io + +## Persistent volumes + +Docker volumes are mapped to Azure File shares, each file share is part of an Azure Storage Account. +Volume(s) can be specified with `docker run -v /:`. + +A run command can use the `-- volume`flag several times for different volumes, several volumes can use the same or different storage accounts. Tagret path for different volume mounts must be different and not overlap. +There is no support for mounting a single file, or mounting a subfolder from an Azure File Share. + +Credentials for storage accounts will be automatically fetched at deployment time using the Azure login to retrieve the storage account key for each storage account used. + +## Container Resources + +CPU and memory reservations can be set when running containers with `docker run --cpus 1.5 --memory 2G`. + +It is not possible to set resource limits different than resource reservation on single containers. +ACI allows setting resource limits for containers in a container group, but these limits must stay within the reserved resources for the entire group. In the case of a single container deployed in a container group, resource limits must be equal to resource reservation. + +## Logs + +You can view container logs with the command: +``` +docker logs +``` + +You can follow logs with the `--follow` (`-f`) option. +When running a container with `docker run`, by default the command line stays attached to container logs when the container starts. Use `docker run --detach` to not follow logs once the container starts. +> Note: following ACI logs might have display issues especialy when resizing a terminal that is following container logs. This is due to ACI providing raw log pullling but no streaming of logs. Logs are effectively pulled every 2 seconds when following logs. \ No newline at end of file