Deploy application resources to a collectionEstimated reading time: 4 minutes
This topic applies to Docker Enterprise.
The Docker Enterprise platform business, including products, customers, and employees, has been acquired by Mirantis, inc., effective 13-November-2019. For more information on the acquisition and how it may affect you and your business, refer to the Docker Enterprise Customer FAQ.
Docker Universal Control Plane enforces role-based access control when you deploy services. By default, you don’t need to do anything, because UCP deploys your services to a default collection, unless you specify another one. You can customize the default collection in your UCP profile page. Learn more about access control and collections.
UCP defines a collection by its path. For example, a user’s default collection
has the path
/Shared/Private/<username>. To deploy a service to a collection
that you specify, assign the collection’s path to the access label of the
service. The access label is named
When UCP deploys a service, it doesn’t automatically create the collections that correspond with your access labels. An administrator must create these collections and grant users access to them. Deployment fails if UCP can’t find a specified collection or if the user doesn’t have access to it.
Deploy a service to a collection by using the CLI
Here’s an example of a
docker service create command that deploys a service
docker service create \ --name redis_2 \ --label com.docker.ucp.access.label="/Shared/database" redis:3.0.6
Deploy services to a collection by using a Compose file
You can also specify a target collection for a service in a Compose file.
In the service definition, add a
labels: dictionary, and assign the
collection’s path to the
If you don’t specify access labels in the Compose file, resources are placed in the user’s default collection when the stack is deployed.
You can place a stack’s resources into multiple collections, but most of the time, you won’t need to do this.
Here’s an example of a Compose file that specifies two services, WordPress and
MySQL, and gives them the access label
version: '3.1' services: wordpress: image: wordpress networks: - wp ports: - 8080:80 environment: WORDPRESS_DB_PASSWORD: example deploy: labels: com.docker.ucp.access.label: /Shared/wordpress mysql: image: mysql:5.7 networks: - wp environment: MYSQL_ROOT_PASSWORD: example deploy: labels: com.docker.ucp.access.label: /Shared/wordpress networks: wp: driver: overlay labels: com.docker.ucp.access.label: /Shared/wordpress
To deploy the application:
- In the UCP web UI, navigate to the Stacks page and click Create Stack.
- Name the app “wordpress”.
- From the Mode dropdown, select Swarm Services.
- Copy and paste the previous compose file into the docker-compose.yml editor.
Click Create to deploy the application, and click Done when the deployment completes.
/Shared/wordpress collection doesn’t exist, or if you don’t have
a grant for accessing it, UCP reports an error.
To confirm that the service deployed to the
- In the Stacks page, click wordpress.
- In the details pane, click Inspect Resource and select Services.
- On the Services page, click wordpress_mysql. In the details pane,
make sure that the Collection is
It is important to note that by default Docker Stacks will create a default
network for your stack. It will be
attached to each container that is deployed. This works if you have full control over
your Default Collection or are an administrator. If your administrators have locked
down UCP to only allow you access to specific collections and you manage multiple
collections, then it can get very difficult to manage the networks as well and you
might run into permissions errors. To fix this, you must define a custom network
and attach that to each service. The network must have the same
Label as your service. If configured correctly, then your network will correctly
be grouped with the other resources in your stack.
Where to go next
- Deploy a Compose-based app to a Kubernetes cluster
- Set metadata on a service (-l, –label)
- Docker object labels