tyler.durden
/
compose
mirror of https://github.com/docker/compose.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #791 from gtardif/aci_doc_run 

Aci doc on single container run and flags
This commit is contained in:
Guillaume Tardif 2020-10-16 17:19:25 +02:00 committed by GitHub
parent 5dd4f9d2a8 487a4e485c
commit 7289f408ca
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 144 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
aci/convert/convert_test.go
View File

@ -761,17 +761,23 @@ func TestConvertSecrets(t *testing.T) {
},
},
}
vs, err := pSquashedDefaultAndAbs.getAciSecretVolumes()
volumes, err := pSquashedDefaultAndAbs.getAciSecretVolumes()
assert.NilError(t, err)
assert.Equal(t, len(vs), 2)
assert.Equal(t, len(volumes), 2)
defaultVolumeName := getServiceSecretKey(serviceName, defaultSecretsPath)
assert.Equal(t, *vs[0].Name, defaultVolumeName)
assert.Equal(t, len(vs[0].Secret), 3)
homeVolumeName := getServiceSecretKey(serviceName, absBasePath)
assert.Equal(t, *vs[1].Name, homeVolumeName)
assert.Equal(t, len(vs[1].Secret), 2)
// random order since this was created from a map...
for _, vol := range volumes {
switch *vol.Name {
case defaultVolumeName:
assert.Equal(t, len(vol.Secret), 3)
case homeVolumeName:
assert.Equal(t, len(vol.Secret), 2)
default:
assert.Assert(t, false, "unexpected volume name: "+*vol.Name)
}
}
s := serviceConfigAciHelper(pSquashedDefaultAndAbs.Services[0])
vms, err := s.getAciSecretsVolumeMounts()

127
docs/aci-compose-features.md
View File

@ -1,7 +1,7 @@
# Compose - Azure Container Instances mapping
This document outlines the conversion of an application defined in a Compose file to ACI objects.
At a high-level, each Compose deployment is mapped to a single ACI container group.
At a high-level, each Compose deployment is mapped to a single ACI container group.
Each service is mapped to a container in the container group. The Docker ACI integration does not allow scaling of services.
## Compose fields mapping
@ -16,75 +16,80 @@ __Legend:__
| Keys |Map| Notes |
|--------------------------------|---|--------------------------------------------------------------|
| __Service__ | ✓ |
| __Service__ | ✓ |
| service.service.build | x | Ignored. No image build support on ACI.
| service.cap_add, cap_drop | x |
| service.cap_add, cap_drop | x |
| service.command | ✓ | Override container Command. On ACI, specifying `command` will override the image command and entrypoint, if the image has an command or entrypoint defined |
| service.configs | x |
| service.cgroup_parent | x |
| service.configs | x |
| service.cgroup_parent | x |
| service.container_name | x | Service name is used as container name on ACI.
| service.credential_spec | x |
| service.deploy | ✓ |
| service.deploy.endpoint_mode | x |
| service.deploy.mode | x |
| service.credential_spec | x |
| service.deploy | ✓ |
| service.deploy.endpoint_mode | x |
| service.deploy.mode | x |
| service.deploy.replicas | x | Only one replica is started for each service.
| service.deploy.placement | x |
| service.deploy.update_config | x |
| service.deploy.placement | x |
| service.deploy.update_config | x |
| service.deploy.resources | ✓ | Restriction: ACI resource limits cannot be greater than the sum of resource reservations for all containers in the container group. Using container limits that are greater than container reservations will cause containers in the same container group to compete with resources.
| service.deploy.restart_policy | ✓ | One of: `any`, `none`, `on-failure`. Restriction: All services must have the same restart policy. The entire ACI container group will be restarted if needed.
| service.deploy.restart_policy | ✓ | One of: `any`, `none`, `on-failure`. Restriction: All services must have the same restart policy. The entire ACI container group will be restarted if needed.
| service.deploy.labels | x | ACI does not have container-level labels.
| service.devices | x |
| service.depends_on | x |
| service.dns | x |
| service.dns_search | x |
| service.devices | x |
| service.depends_on | x |
| service.dns | x |
| service.dns_search | x |
| service.domainname | ✓ | Mapped to ACI DNSLabelName. Restriction: all services must specify the same `domainname`, if specified. `domainname` must be unique globally in <region>.azurecontainer.io
| service.tmpfs | x |
| service.tmpfs | x |
| service.entrypoint | x | ACI only supports overriding the container command.
| service.env_file | ✓ |
| service.environment | ✓ |
| service.expose | x |
| service.extends | x |
| service.external_links | x |
| service.extra_hosts | x |
| service.group_add | x |
| service.healthcheck | n |
| service.hostname | x |
| service.env_file | ✓ |
| service.environment | ✓ |
| service.expose | x |
| service.extends | x |
| service.external_links | x |
| service.extra_hosts | x |
| service.group_add | x |
| service.healthcheck | n |
| service.hostname | x |
| service.image | ✓ | Private images will be accessible if the user is logged into the corresponding registry at deploy time. Users will be automatically logged in to Azure Container Registry using their Azure login if possible.
| service.isolation | x |
| service.isolation | x |
| service.labels | x | ACI does not have container-level labels.
| service.links | x |
| service.logging | x |
| service.network_mode | x |
| service.links | x |
| service.logging | x |
| service.network_mode | x |
| service.networks | x | Communication between services is implemented by defining mapping for each service in the shared `/etc/hosts` file of the container group. Each service can resolve names for other services and the resulting network calls will be redirected to `localhost`.
| service.pid | x |
| service.ports | ✓ | Only symetrical por mapping is supported in ACI. See #exposing-ports.
| service.secrets | ✓ | See #secrets.
| service.security_opt | x |
| service.stop_grace_period | x |
| service.stop_signal | x |
| service.sysctls | x |
| service.ulimits | x |
| service.userns_mode | x |
| service.volumes | ✓ | Mapped to AZure File Shares. See #persistent-volumes.
| service.pid | x |
| service.ports | ✓ | Only symetrical port mapping is supported in ACI. See [Exposing ports](#exposing-ports).
| service.secrets | ✓ | See [Secrets](#secrets).
| service.security_opt | x |
| service.stop_grace_period | x |
| service.stop_signal | x |
| service.sysctls | x |
| service.ulimits | x |
| service.userns_mode | x |
| service.volumes | ✓ | Mapped to AZure File Shares. See [Persistent volumes](#persistent-volumes).
| service.restart | x | Replaced by service.deployment.restart_policy
| | |
| __Volume__ | x |
| driver | ✓ | See #persistent-volumes.
| driver_opts | ✓ |
| external | x |
| labels | x |
| | |
| __Secret__ | x |
| TBD | x |
| | |
| __Config__ | x |
| TBD | x |
| | |
| | |
| __Volume__ | x |
| driver | ✓ | See [Persistent volumes](#persistent-volumes).
| driver_opts | ✓ |
| external | x |
| labels | x |
| | |
| __Secret__ | x |
| TBD | x |
| | |
| __Config__ | x |
| TBD | x |
| | |
## Logs
Container logs can be obtained for each container with `docker logs <CONTAINER>`.
The Docker ACI integration does not currently support aggregated logs for containers in a Compose application, see https://github.com/docker/compose-cli/issues/803.
## Exposing ports
When one or more services expose ports, the entire ACI container group will be exposed and will get a public IP allocated.
When one or more services expose ports, the entire ACI container group will be exposed and will get a public IP allocated.
As all services are mapped to containers in the same container group, only one service cannot expose a given port number.
[ACI does not support port mapping](https://feedback.azure.com/forums/602224-azure-container-instances/suggestions/34082284-support-for-port-mapping), so the source and target ports defined in the Compose file must be the same.
@ -94,7 +99,7 @@ All services specifying a `domainname` must set the same value, as it is applied
## Persistent volumes
Docker volumes are mapped to Azure file shares. Only the long Compose volume format is supported meaning that volumes must be defined in the `volume` section.
Docker volumes are mapped to Azure file shares. Only the long Compose volume format is supported meaning that volumes must be defined in the `volume` section.
Volumes are defined with a name, the `driver` field must be set to `azure_file`, and `driver_options` must define the storage account and file share to use for the volume.
A service can then reference the volume by its name, and specify the target path to be mounted in the container.
@ -116,11 +121,11 @@ volumes:
The short volume syntax is not allowed for ACI volumes, as it was designed for local path bind mounting when running local containers.
A Compose file can define several volumes, with different Azure file shares or storage accounts.
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.
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.
## Secrets
Secrets can be defined in compose files, and will need secret files available at deploy time next to the compose file.
Secrets can be defined in compose files, and will need secret files available at deploy time next to the compose file.
The content of the secret file will be made available inside selected containers, under `/run/secrets/<SECRET_NAME>`.
External secrets are not supported with the ACI integration.
@ -134,7 +139,7 @@ services:
image: mysql
secrets:
- mysecret2
secrets:
mysecret1:
file: ./my_secret1.txt
@ -149,7 +154,7 @@ The nginx container will have secret1 mounted as `/run/secrets/mysecret1/mysecre
## Container Resources
CPU and memory reservations and limits can be set in compose.
Resource limits must be greater than reservation. In ACI, setting resource limits different from resource reservation will cause containers in the same container group to compete for resources. Resource limits cannot be greater than the total resource reservation for the container group. (Therefore single containers cannot have resoure limits different from resource reservations)
Resource limits must be greater than reservation. In ACI, setting resource limits different from resource reservation will cause containers in the same container group to compete for resources. Resource limits cannot be greater than the total resource reservation for the container group. (Therefore single containers cannot have resoure limits different from resource reservations)
```yaml
services:
@ -172,5 +177,5 @@ services:
memory: 1.5G
```
In this example, the db container will be allocated 2 CPUs and 2G of memory. It will be allowed to use up to 3 CPUs and 3G of memory, using some of the resources allocated to the web container.
In this example, the db container will be allocated 2 CPUs and 2G of memory. It will be allowed to use up to 3 CPUs and 3G of memory, using some of the resources allocated to the web container.
The web container will have its limits set to the same values as reservations, by default.

65
docs/aci-container-features.md Normal file
View File

@ -0,0 +1,65 @@
# Azure Container Instances: running single containerrs
Single containers 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 <CONTAINER>` and `docker rm <CONTAINER>`.
# 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 port 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 more ports of a container with `docker run -p <PORT>:<PORT>`
If ports are exposed 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 <PORT>:<PORT>`.
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 `<DOMAINNANE>.<REGION>.azurecontainer.io`.
`domainname` must be unique globally in <REGION>.azurecontainer.io
## Persistent volumes
Docker volumes are mapped to Azure File shares, each file share is part of an Azure Storage Account.
One or more volumes can be specified with `docker run -v <STORAGE-ACCOUNT>/<FILESHARE>:<TARGET-PATH>`.
A run command can use the `--volume` or `-v` flag several times for different volumes. The volumes can use the same or different storage accounts. The target paths 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 that differ from 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, the resource limits must be equal to the resource reservation.
## Logs
You can view container logs with the command `docker logs <CONTAINER-ID>`.
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 may have display issues especially when resizing a terminal that is following container logs. This is due to ACI providing raw log pulling but no streaming of logs. Logs are effectively pulled every 2 seconds when following logs.