diff --git a/_data/toc.yaml b/_data/toc.yaml index e0f13f9e19..1c3e0d25a7 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1510,6 +1510,8 @@ manuals: title: Deploy an app from the UI - path: /datacenter/ucp/2.2/guides/user/services/deploy-app-cli/ title: Deploy an app from the CLI + - path: /datacenter/ucp/2.2/guides/user/services/deploy-stack-to-collection/ + title: Deploy application resources to a collection - sectiontitle: Secrets section: - path: /datacenter/ucp/2.2/guides/user/secrets/ diff --git a/datacenter/ucp/2.2/guides/access-control/use-collections-on-stacks.md b/datacenter/ucp/2.2/guides/access-control/use-collections-on-stacks.md deleted file mode 100644 index 14cfe59e37..0000000000 --- a/datacenter/ucp/2.2/guides/access-control/use-collections-on-stacks.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Use collections to manage access to stacks -description: Learn how to manage user access to a stack by using collections -keywords: UCP, authentication, user management, stack, collection, role ---- - - A stack is a group of resources identified by a label. You can place the - resources in a stack on multiple collections. Resources are placed in the - user's default collection unless if an explicit `com.docker.ucp.access.label` - is specified within the stack/compose file. - - ## Where to go next - - - [Create and manage teams](create-and-manage-teams.md) diff --git a/datacenter/ucp/2.2/guides/images/deploy-stack-to-collection.png b/datacenter/ucp/2.2/guides/images/deploy-stack-to-collection.png new file mode 100644 index 0000000000..06e70f9c06 Binary files /dev/null and b/datacenter/ucp/2.2/guides/images/deploy-stack-to-collection.png differ diff --git a/datacenter/ucp/2.2/guides/user/services/deploy-stack-to-collection.md b/datacenter/ucp/2.2/guides/user/services/deploy-stack-to-collection.md new file mode 100644 index 0000000000..b06ae7b13f --- /dev/null +++ b/datacenter/ucp/2.2/guides/user/services/deploy-stack-to-collection.md @@ -0,0 +1,121 @@ +--- +title: Deploy application resources to a collection +description: Learn how to manage user access to application resources by using collections. +keywords: UCP, authentication, user management, stack, collection, role, application, resources +--- + +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](../../access-control/manage-access-with-collections.md). + +UCP defines a collection by its path. For example, a user's default collection +has the path `/Shared/Private/`. 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 `com.docker.ucp.access.label`. + +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](grant-permissions.md). 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 +to a `/Shared/database` collection: + +```bash +$ 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 `com.docker.ucp.access.label` key. + +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 `/Shared/wordpress`: + +```none +version: '3.1' + +services: + + wordpress: + image: wordpress + ports: + - 8080:80 + environment: + WORDPRESS_DB_PASSWORD: example + deploy: + labels: + com.docker.ucp.access.label: /Shared/wordpress + mysql: + image: mysql:5.7 + environment: + MYSQL_ROOT_PASSWORD: example + deploy: + labels: + com.docker.ucp.access.label: /Shared/wordpress + +``` + +To deploy the application: + +1. In the UCP web UI, navigate to the **Stacks** page and click **Create Stack**. +2. Name the app "wordpress". +3. From the **Mode** dropdown, select **Services**. +4. Copy and paste the previous compose file into the **Compose.yml** editor. +5. Click **Create** to deploy the application, and click **Done** when the + deployment completes. + +If the `/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 `/Shared/wordpress` collection: + +1. In the **Stacks** page, click **wordpress**. +2. In the details pane, click **Inspect Resource** and select **Services**. +3. On the **Services** page, click **wordpress_mysql**. In the details pane, + make sure that the **Collection** is `/Shared/wordpress`. + +![](../../images/deploy-stack-to-collection.png){: .with-border} + +## Compose files with legacy access labels + +If your Compose file has access labels for versions earlier than UCP 2.2.0, +you have three options: + +- **Keep the existing access labels.** In this case, UCP deploys resources + to the `/Shared/Legacy/` collection. An administrator must create + the legacy collection and grant permissions before you can deploy to it. + +- **Deploy to the default collection.** To specify the user's default + collection instead of a legacy collection, remove the + `com.docker.ucp.access.label` keys from the Compose file. In this case, + UCP deploys resources automatically to the default collection, and no + administrator action is required. + +- **Update the collection.** Change the access label to refer to a new + collection. Be sure to use path notation. For example, + `com.docker.ucp.access.label: /Shared/database` deploys to a child of the + built-in `/Shared` collection. An administrator must create the child + collection and grant permissions before you can deploy to it. + +## Where to go next + +- [Manage access to resources by using collections](../../access-control/manage-access-with-collections.md) +- [Set metadata on a service (-l, –label)](/engine/reference/commandline/service_create/#set-metadata-on-a-service--l-label) +- [Docker object labels](/engine/userguide/labels-custom-metadata.md)