Manage access to resources by using collections

Docker EE enables controlling access to container resources by using
collections. A collection is a group of swarm resources,
like services, containers, volumes, networks, and secrets.

Access to collections goes through a directory structure that arranges a
swarm’s resources. To assign permissions, administrators create grants
against directory branches.

Directory paths define access to collections

Access to collections is based on a directory-like structure.
For example, the path to a user’s default collection is
/Shared/Private/<username>. Every user has a private collection that
has the default permission specified by the UCP administrator.

Each collection has an access label that identifies its path.
For example, the private collection for user “hans” has a label that looks
like this:

com.docker.ucp.access.label = /Shared/Private/hans

You can nest collections. If a user has a grant against a collection,
the grant applies to all of its child collections.

For a child collection, or for a user who belongs to more than one team,
the system concatenates permissions from multiple roles into an
“effective role” for the user, which specifies the operations that are
allowed against the target.

Built-in collections

UCP provides a number of built-in collections.

/ - The path to the Swarm collection. All resources in the
cluster are here. Resources that aren’t in a collection are assigned
to the / directory.

/System - The system collection, which contains UCP managers, DTR nodes,
and UCP/DTR system services. By default, only admins have access to the
system collection, but you can change this.

/Shared - All worker nodes are here by default, for scheduling.
In a system with a standard-tier license, all worker nodes are under
the /Shared collection. With the EE Advanced license, administrators
can move worker nodes to other collections and apply role-based access.

/Shared/Private - User private collections are stored here.

/Shared/Legacy - After updating from UCP 2.1, all legacy access control
labels are stored here.

This diagram shows the /System and /Shared collections that are created
by UCP. User private collections are children of the /Shared/private
collection. Also, an admin user has created a /prod collection and its
/webserver child collection.

Default collections

A user always has a default collection. The user can select the default
in UI preferences. When a user deploys a resource in the web UI, the
preselected option is the default collection, but this can be changed.

Users can’t deploy a resource without a collection. When deploying a
resource in CLI without an access label, UCP automatically places the
resource in the user’s default collection.
Learn how to add labels to cluster nodes.

When using Docker Compose, the system applies default collection labels
across all resources in the stack, unless the com.docker.ucp.access.label
has been set explicitly.

Default collections and collection labels

Setting a default collection is most helpful for users who deploy stacks
and don’t want to edit the contents of their compose files. Also, setting
a default collection is useful for users who work only on a well-defined
slice of the system. On the other hand, setting the collection label for
every resource works best for users who have versatile roles in the system,
like administrators.

Collections and labels

Resources are marked as being in a collection by using labels.
Some resource types don’t have editable labels, so you can’t move resources
like this across collections. You can’t modify collections after
resource creation for containers, networks, and volumes, but you can
update labels for services, nodes, secrets, and configs.

For editable resources, like services, secrets, nodes, and configs,
you can change the com.docker.ucp.access.label to move resources to
different collections. With the CLI, you can use this label to deploy
resources to a collection other than your default collection. Omitting this
label on the CLI deploys a resource on the user’s default resource collection.

The system uses the additional labels, com.docker.ucp.collection.*, to enable
efficient resource lookups. By default, nodes have the
com.docker.ucp.collection.root, com.docker.ucp.collection.shared, and
com.docker.ucp.collection.swarm labels set to true. UCP automatically
controls these labels, and you don’t need to manage them.

Collections get generic default names, but you can give them meaningful names,
like “Dev”, “Test”, and “Prod”.

A stack is a group of resources identified by a label. You can place the
stack’s resources in multiple collections. Resources are placed in the user’s
default collection unless you specify an explicit com.docker.ucp.access.label
within the stack/compose file.

Control access to nodes

The Docker EE Advanced license enables access control on worker nodes. Admin
users can move worker nodes from the default /Shared collection into other
collections and create corresponding grants for scheduling tasks.

In this example, an administrator has moved worker nodes to a /prod
collection:

When you deploy a resource with a collection, UCP sets a constraint implicitly
based on what nodes the collection, and any ancestor collections, can access.
The Scheduler role allows users to deploy resources on a node.
By default, all users have the Scheduler role against the /Shared
collection.

When deploying a resource that isn’t global, like local volumes, bridge
networks, containers, and services, the system identifies a set of
“schedulable nodes” for the user. The system identifies the target collection
of the resource, like /Shared/Private/hans, and it tries to find the parent
that’s closest to the root that the user has the Node Schedule permission on.

For example, when a user with a default configuration runs docker container run nginx,
the system interprets this to mean, “Create an NGINX container under the
user’s default collection, which is at /Shared/Private/hans, and deploy it
on one of the nodes under /Shared.

If you want to isolate nodes against other teams, place these nodes in
new collections, and assign the Scheduler role, which contains the
Node Schedule permission, to the team.
Isolate swarm nodes to a specific team.