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

Update rbac docs (#298)

This commit is contained in:
Gwendolynne Barr 2017-11-19 22:02:17 -08:00 committed by Jim Galasyn
parent a21e7af29a
commit ced3bcbcd5
12 changed files with 855 additions and 346 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
_data/toc.yaml
View File

@ -310,42 +310,42 @@ guides:
title: Use the ZFS storage driver title: Use the ZFS storage driver
- path: /storage/storagedriver/vfs-driver/ - path: /storage/storagedriver/vfs-driver/
title: Use the VFS storage driver title: Use the VFS storage driver
- sectiontitle: Authorize user access
- sectiontitle: Configure user permissions
section: section:
- path: /deploy/access-control/ - path: /deploy/access-control/
title: Access control model overview title: Access control model overview
- sectiontitle: User Management - sectiontitle: User Management
section: section:
- path: /deploy/access-control/create-and-manage-users - path: /deploy/access-control/usermgmt-create-subjects.md
title: Create and manage users title: Create and users and teams
- path: /deploy/access-control/create-and-manage-teams - path: /deploy/access-control/usermgmt-sync-with-ldap.md
title: Create and manage teams title: Synchronize teams with LDAP
- path: /deploy/access-control/permission-levels - path: /deploy/access-control/usermgmt-create-roles.md
title: Learn about user permissions title: Create roles to authorize access
- path: /deploy/access-control/recover-a-user-password - path: /deploy/access-control/usermgmt-grant-permissions.md
title: Grant access to resources
- path: /deploy/access-control/usermgmt-recover-user-password
title: Reset a user password title: Reset a user password
- path: /deploy/access-control/grant-permissions.md
title: Grant role-based permissions to users and teams
- sectiontitle: Shared Resources - sectiontitle: Shared Resources
section: section:
- path: /deploy/access-control/manage-access-with-collections - path: /deploy/access-control/resources-create-collections-namespaces.md
title: Manage access to collections title: Group resources as collections or namespaces
- path: /deploy/access-control/node-access-control - path: /deploy/access-control/access-control-node.md
title: Learn node access controls title: Learn node access controls
- path: /deploy/access-control/isolate-nodes-between-teams - path: /deploy/access-control/isolate-nodes-between-teams
title: Isolate swarm nodes to specific teams title: Isolate Swarm nodes
- path: /deploy/access-control/isolate-volumes-between-teams - path: /deploy/access-control/isolate-volumes-between-teams
title: Isolate volumes to specific teams title: Isolate volumes
- path: /deploy/access-control/deploy-view-only-service - sectiontitle: Tutorials
title: Deploy a service with view-only access
- sectiontitle: OrcaBank Tutorial
section: section:
- path: /deploy/access-control/howto-deploy-wordpress-with-rbac.md
title: Wordpress and MySQL tutorial
- path: /deploy/access-control/deploy-view-only-service
title: Deploy service with view-only access
- path: /deploy/access-control/access-control-design-ee-standard - path: /deploy/access-control/access-control-design-ee-standard
title: Orcabank tutorial 1 title: Orcabank tutorial with Docker EE Standard
- path: /deploy/access-control/access-control-design-ee-advanced - path: /deploy/access-control/access-control-design-ee-advanced
title: Orcabank tutorial 2 title: Orcabank tutorial with Docker EE Advanced
- sectiontitle: Deploy your app in production - sectiontitle: Deploy your app in production
section: section:
- path: /deploy/ - path: /deploy/

130
deploy/access-control/create-and-manage-teams.md
View File

@ -1,130 +0,0 @@
---
title: Create and manage teams
description: Learn how to administer team permissions in Docker Universal Control Plane.
keywords: authorize, authentication, users, teams, groups, sync, UCP, Docker
redirect_from:
- /ucp/
ui_tabs:
- version: ucp-3.0
orhigher: true
- version: ucp-2.2
orlower: true
---
{% if include.ui %}
You can extend the user's default permissions by granting them fine-grained
permissions over resources. You do this by adding the user to a team.
To create a new team, go to the UCP web UI, and navigate to the
**Organizations** page.
![](../images/create-and-manage-teams-1.png){: .with-border}
If you want to put the team in a new organization, click
**Create Organization** and give the new organization a name, like
"engineering". Click **Create** to create it.
In the list, click the organization where you want to create the new team.
Name the team, give it an optional description, and click **Create** to
create a new team.
![](../images/create-and-manage-teams-2.png){: .with-border}
## Add users to a team
You can now add and remove users from the team. In the current organization's
teams list, click the new team, and in the details pane, click **Add Users**.
Choose the users that you want to add to the team, and when you're done, click
**Add Users**.
![](../images/create-and-manage-teams-3.png){: .with-border}
## Enable Sync Team Members
To sync the team with your organization's LDAP directory, click **Yes**.
If UCP is configured to sync users with your organization's LDAP directory
server, you have the option to enable syncing the new team's members when
creating a new team or when modifying settings of an existing team.
[Learn how to configure integration with an LDAP directory](../admin/configure/external-auth/index.md).
Enabling this option expands the form with additional fields for configuring
the sync of team members.
![](../images/create-and-manage-teams-5.png){: .with-border}
There are two methods for matching group members from an LDAP directory:
**Match Group Members**
This option specifies that team members should be synced directly with members
of a group in your organization's LDAP directory. The team's membership will by
synced to match the membership of the group.
| Field | Description |
|:-----------------------|:------------------------------------------------------------------------------------------------------|
| Group DN | This specifies the distinguished name of the group from which to select users. |
| Group Member Attribute | The value of this group attribute corresponds to the distinguished names of the members of the group. |
**Match Search Results**
This option specifies that team members should be synced using a search query
against your organization's LDAP directory. The team's membership will be
synced to match the users in the search results.
| Field | Description |
| :--------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Search Base DN | The distinguished name of the node in the directory tree where the search should start looking for users. |
| Search Filter | The LDAP search filter used to find users. If you leave this field empty, all existing users in the search scope will be added as members of the team. |
| Search subtree instead of just one level | Whether to perform the LDAP search on a single level of the LDAP tree, or search through the full LDAP tree starting at the Base DN. |
**Immediately Sync Team Members**
Select this option to run an LDAP sync operation immediately after saving the
configuration for the team. It may take a moment before the members of the team
are fully synced.
## Manage team permissions
Create a grant to manage the team's permissions.
[Learn how to grant permissions to users based on roles](grant-permissions.md).
In this example, you'll create a collection for the "Data Center" team,
where they can deploy services and resources, and you'll create a grant that
gives the team permission to access the collection.
![](../images/team-grant-diagram.svg){: .with-border}
1. Navigate to the **Organizations & Teams** page.
2. Select **docker-datacenter**, and click **Create Team**. Name the team
"Data Center", and click **Create**.
3. Navigate to the **Collections** page.
4. Click **Create Collection**, name the collection "Data Center Resources",
and click **Create**.
5. Navigate to the **Grants** page, and click **Create Grant**.
6. Find **Swarm** in the collections list, and click **View Children**.
7. Find **Data Center Resources**, and click **Select Collection**.
8. In the left pane, click **Roles** and in the **Role** dropdown, select
**Restricted Control**.
9. In the left pane, click **Subjects** and select the **Organizations**
subject type.
10. In the **Organization** dropdown, select **docker-datacenter**, and in the
**Teams** dropdown, select **Data Center**.
11. Click **Create** to create the grant.
![](../images/create-and-manage-teams-4.png){: .with-border}
In this example, you gave members of the `Data Center` team
`Restricted Control` permissions to create and edit resources in
the `Data Center Resources` collection.
## Where to go next
- [UCP permission levels](permission-levels.md)
- [Isolate volumes between two different teams](isolate-volumes-between-teams.md)
- [Isolate swarm nodes between two different teams](isolate-nodes-between-teams.md)
{% if include.version=="ucp-3.0" %}
{% elsif include.version=="ucp-2.2" %}
{% endif %}
{% endif %}

65
deploy/access-control/create-and-manage-users.md
View File

@ -1,65 +0,0 @@
---
title: Create and manage users
description: Learn how to administer user permissions in Docker Universal Control Plane.
keywords: authorize, authentication, users, teams, UCP, Docker
redirect_from:
- /ucp/
ui_tabs:
- version: ucp-3.0
orhigher: true
- version: ucp-2.2
orlower: true
---
{% if include.ui %}
Docker Universal Control Plane provides built-in authentication and also
integrates with LDAP directory services.
> To enable LDAP and manage users and groups from your organization's directory,
> go to Admin > Admin Settings > Authentication and Authorization.
> [Learn how to integrate with an LDAP directory](../configure/external-auth/index.md).
{% if include.version=="ucp-3.0" %}
To use UCP built-in authentication, you must manually create users. New users
are assigned a default permission level so that they can access the cluster.
You can optionally grant them UCP administrator permissions.
To create a new user in the UCP web UI:
1. Navigate to the **Users** page.
2. Click **Create User**.
3. Input username, password, and full name.
4. Click **Create**.
5. [optional] Check "Is a Docker EE Admin".
> Check `Is a Docker EE Admin` to grant a user permission to change the cluster
> configuration and manage grants, roles, and collections.
![](../images/ucp_usermgmt_users_create01.png){: .with-border}
![](../images/ucp_usermgmt_users_create02.png){: .with-border}
{% elsif include.version=="ucp-2.2" %}
To use UCP built-in authentication, you must manually create users. New users
are assigned a default permission level so that they can access the swarm.
You can optionally grant them UCP administrator permissions.
To create a new user in the UCP web UI:
1. Navigate to the **Users** page.
2. Click **Create User**.
3. Input username, password, and full name.
4. Click **Create**.
5. [optional] Check "Is a UCP admin?".
![](../images/create-users-1.png){: .with-border}
> Check `Is a UCP admin?` to grant a user permission to change the swarm
> configuration and manage grants, roles, and collections.
![](../images/create-users-2.png){: .with-border}
{% endif %}
## Where to go next
* [Create and manage teams](create-and-manage-teams.md)
* [UCP permission levels](permission-levels.md)
{% endif %}

90
deploy/access-control/howto-deploy-wordpress-with-rbac.md Normal file
View File

@ -0,0 +1,90 @@
---
title: Deploy simple Wordpress application with RBAC
description: Learn how to deploy a simple application and customize access to resources.
keywords: rbac, authorize, authentication, users, teams, UCP, Docker
redirect_from:
- /ucp/
ui_tabs:
- version: ucp-3.0
orhigher: true
- version: ucp-2.2
orlower: true
---
{% if include.ui %}
{% if include.version=="ucp-3.0" %}
{% elsif include.version=="ucp-2.2" %}
{% endif %}
This tutorial explains how to create a simple application with two services,
Worpress and MySQL, and use role-based access control (RBAC) to authorize access
across the organization.
## Build the organization
Acme company wants to start a blog to better communicate with its users.
```
Acme Datacenter
├── Dev
│   └── Alex Alutin
└── DBA
  └── Brad Bhatia
```
## Deploy Wordpress with MySQL
```
version: "3.1"
services:
db:
image: mysql:5.7
deploy:
replicas: 1
labels:
com.docker.ucp.access.label: "/Shared/acme-blog/mysql-collection"
restart_policy:
condition: on-failure
max_attempts: 3
volumes:
- db_data:/var/lib/mysql
networks:
- wordpress-net
environment:
MYSQL_ROOT_PASSWORD: wordpress
MYSQL_DATABASE: wordpress
MYSQL_USER: wordpress
MYSQL_PASSWORD: wordpress
wordpress:
depends_on:
- db
image: wordpress:latest
deploy:
replicas: 1
labels:
com.docker.ucp.access.label: "/Shared/acme-blog/wordpress-collection"
restart_policy:
condition: on-failure
max_attempts: 3
volumes:
- wordpress_data:/var/www/html
networks:
- wordpress-net
ports:
- "8000:80"
environment:
WORDPRESS_DB_HOST: db:3306
WORDPRESS_DB_PASSWORD: wordpress
volumes:
db_data:
wordpress_data:
networks:
wordpress-net:
labels:
com.docker.ucp.access.label: "/Shared/acme-blog"
```
{% endif %}

208
deploy/access-control/index.md
View File

@ -23,29 +23,18 @@ next_steps:
--- ---
{% if include.ui %} {% if include.ui %}
With Docker Universal Control Plane (UCP), you can configure how users access
resources by assigning role-based permissions with grants.
{% if include.version=="ucp-3.0" %} {% if include.version=="ucp-3.0" %}
UCP administrators can control who views, edits, and uses Swarm and Kubernetes With Docker Universal Control Plane (UCP), you can authorize how users view,
resources. They can grant and manage permissions to enforce fine-grained access edit, and use cluster resources by granting role-based permissions.
control as needed.
## Grants To authorize access to cluster resources across your organization, Docker
administrators should take the following high-level steps:
Grants define which users can access what resources. Grants are effectively - Add and configure subjects (users and teams)
Access Control Lists (ACLs), which, when grouped together, can provide - Define customer roles (or use defaults) by adding permissions resource types
comprehensive access policies for an entire organization. - Group cluster resources into Swarm collections or Kubernetes namespaces
- Create grants by marrying subject + role + resource
A grant is made up of a *subject*, *namespace*, and *role*.
Administrators are users who create subjects, define namespaces by labelling
resources, define roles by selecting allowable operations, and apply grants to
users and teams.
> Only an administrator can manage grants, subjects, roles, and resources.
## Subjects ## Subjects
@ -54,63 +43,80 @@ role that defines permitted operations against one or more resources.
- **User**: A person authenticated by the authentication backend. Users can - **User**: A person authenticated by the authentication backend. Users can
belong to one or more teams and one or more organizations. belong to one or more teams and one or more organizations.
- **Team**: A group of users that share permissions defined at the team level. - **Team**: A group of users that share permissions defined at the team level. A
A team exists only as part of an organization, and all of its members team can be in one organization only.
must be members of the organization. Team members share organization
permissions. A team can be in one organization only.
- **Organization**: A group of teams that share a specific set of permissions, - **Organization**: A group of teams that share a specific set of permissions,
defined by the roles of the organization. defined by the roles of the organization.
## Namespaces For more, see:
- [Create users and teams in UCP](./usermgmt-create-subjects.md)
A namespace is ... - [Synchronize users and teams with LDAP](./usermgmt-sync-teams-with-ldap.md)
## Roles ## Roles
Roles define what operations can be done by whom against which cluster Roles define what operations can be done by whom. A role is a set of permitted
resources. A role is a set of permitted operations against a resource that is operations (view, edit, use, etc.) against a *resource type* (such as an image,
assigned to a user or team with a grant. container, volume, etc.) that is assigned to a user or team with a grant.
For example, the built-in role, **Restricted Control**, includes permission to For example, the built-in role, **Restricted Control**, includes permission to
view and schedule a node (in a granted namespace) but not update it. view and schedule a node but not update it. A custom **DBA** role might include
permissions to create, attach, view, and remove volumes.
Most organizations use different roles to assign the right kind of access. A Most organizations use different roles to fine-tune the approprate access. A
given team or user may have different roles provided to them depending on what given team or user may have different roles provided to them depending on what
resource they are accessing. resource they are accessing.
You can build custom roles to meet your organizational needs or use the For more, see: [Create roles that define user access to resources](./usermgmt-create-roles.md)
following built-in roles:
- **View Only** - Users can see all cluster resources but not edit or use them. ## Resources
- **Restricted Control** - Users can view containers and run a shell inside a
container process (with `docker exec`) but not view or edit other resources.
- **Full Control** - Users can perform all operations against granted resources.
- **Scheduler** - Users can view and schedule nodes.
[Learn more about roles and permissions](permission-levels.md). Cluster resources are grouped into Swarm collections or Kubernetes namespaces.
A collection is a directory that holds Swarm resources. You can define and build
collections in UCP by assinging resources to a collection. Or you can create the
path in UCP and use *labels* in your YAML file to assign application resources to
that path.
> Swarm resources types that can be placed into a collection include: Containers,
> Networks, Nodes, Services, Secrets, and Volumes.
A [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
holds Kubernetes resources.
> Kubernetes resources types that can be placed into a namespace include: Pods,
> Deployments, NetworkPolcies, Nodes, Services, Secrets, and many more.
For more, see: [Group resources into collections or namespaces](resources-create-collections-namespaces.md).
## Grants
A grant is made up of a *subject*, *resource group*, and *role*.
Grants define which users can access what resources in what way. Grants are
effectively Access Control Lists (ACLs), and when grouped together, can
provide comprehensive access policies for an entire organization.
Only an administrator can manage grants, subjects, roles, and resources.
> Administrators are users who create subjects, group resources by moving them
> into directories or namespaces, define roles by selecting allowable operations,
> and apply grants to users and teams.
For more, see: [Create grants and authorize access to users and teams](usermgmt-grant-permissions.md).
{% elsif include.version=="ucp-2.2" %} {% elsif include.version=="ucp-2.2" %}
UCP administrators can control who views, edits, and uses resources such as With Docker Universal Control Plane (UCP), you can authorize how users view,
nodes, services, images, networks, and volumes. They can grant and manage edit, and use cluster resources by granting role-based permissions.
permissions to enforce fine-grained access control as needed.
To authorize access to cluster resources across your organization, Docker
administrators should take the following high-level steps:
## Grants - Add and configure subjects (users and teams)
Grants define which users can access what resources. Grants are effectively - Define customer roles (or use defaults) by adding permissions resource types
Access Control Lists (ACLs), which, when grouped together, can provide - Group cluster resources into Swarm collections
comprehensive access policies for an entire organization. - Create grants by marrying subject + role + resource
A grant is made up of a *subject*, *resource collection*, and *role*.
Administrators are users who create subjects, define collections by labelling
resources, define roles by selecting allowable operations, and apply grants to
users and teams.
> Only an administrator can manage grants, subjects, roles, and resources.
![](../images/ucp-grant-model.svg)
## Subjects ## Subjects
@ -119,84 +125,60 @@ role that defines permitted operations against one or more resources.
- **User**: A person authenticated by the authentication backend. Users can - **User**: A person authenticated by the authentication backend. Users can
belong to one or more teams and one or more organizations. belong to one or more teams and one or more organizations.
- **Team**: A group of users that share permissions defined at the team level. - **Team**: A group of users that share permissions defined at the team level. A
A team exists only as part of an organization, and all of its members team can be in one organization only.
must be members of the organization. Team members share organization
permissions. A team can be in one organization only.
- **Organization**: A group of teams that share a specific set of permissions, - **Organization**: A group of teams that share a specific set of permissions,
defined by the roles of the organization. defined by the roles of the organization.
## Collections For more, see:
- [Create users and teams in UCP](./usermgmt-create-subjects.md)
A collection is a group of resources that you define with labels and access by - [Synchronize users and teams with LDAP](./usermgmt-sync-teams-with-ldap.md)
specifying a directory-like path.
Swarm resources that can be placed into a collection include:
- Application configs
- Containers
- Networks
- Nodes (Physical or virtual)
- Services
- Secrets
- Volumes
## Roles ## Roles
Roles define what operations can be done by whom against which cluster Roles define what operations can be done by whom. A role is a set of permitted
resources. A role is a set of permitted operations against a resource that is operations (view, edit, use, etc.) against a *resource type* (such as an image,
assigned to a user or team with a grant. container, volume, etc.) that is assigned to a user or team with a grant.
For example, the built-in role, **Restricted Control**, includes permission to view For example, the built-in role, **Restricted Control**, includes permission to
and schedule a node (in a granted collection) but not update it. view and schedule a node but not update it. A custom **DBA** role might include
permissions to create, attach, view, and remove volumes.
Most organizations use different roles to assign the right kind of access. A Most organizations use different roles to fine-tune the approprate access. A
given team or user may have different roles provided to them depending on what given team or user may have different roles provided to them depending on what
resource they are accessing. resource they are accessing.
You can build custom roles to meet your organizational needs or use the following For more, see [Create roles that define user access to resources](./usermgmt-create-roles.md)
built-in roles:
- **View Only** - Users can see all cluster resources but not edit or use them. ## Resources
- **Restricted Control** - Users can view containers and run a shell inside a
container process (with `docker exec`) but not view or edit other resources.
- **Full Control** - Users can perform all operations against granted resources.
- **Scheduler** - Users can view and schedule nodes.
[Learn more about roles and permissions](permission-levels.md). Cluster resources are grouped into collections.
A collection is a directory that holds Swarm resources. You can define and build
collections in UCP by assinging resources to a collection. Or you can create the
path in UCP and use *labels* in your YAML file to assign application resources to
that path.
## Collection architecture > Swarm resources types that can be placed into a collection include: Containers,
> Networks, Nodes (physical or virtual), Services, Secrets, and Volumes.
Before grants can be implemented, collections must group resources in a way that For more, see: [Group resources into collections](resources-create-collections-namespaces.md).
makes sense for an organization.
For example, consider an organization with two application teams, Mobile and ## Grants
Payments, which share cluster hardware resources but segregate access to their
individual applications.
``` A grant is made up of a *subject*, *resource collection*, and *role*.
orcabank (organization)
├── ops (team)
├── security (team)
├── mobile-dev (team)
└── payments-dev (team)
```
To define a potential access policy, the collection architecture should map to Grants define which users can access what resources in what way. Grants are
the organizational structure. For a production UCP cluster, it might look like effectively Access Control Lists (ACLs), which when grouped together, can
this: provide comprehensive access policies for an entire organization.
``` Only an administrator can manage grants, subjects, roles, and resources.
prod (collection)
├── mobile (sub-collection)
└── payments (sub-collection)
```
> A subject that has access to any level in a collection hierarchy has the
> same access to any collections below it.
> Administrators are users who create subjects, group resources by moving them
> into directories or namespaces, define roles by selecting allowable operations,
> and apply grants to users and teams.
For more, see: [Create grants and authorize access to users and teams](usermgmt-grant-permissions.md).
## Transition from UCP 2.1 access control ## Transition from UCP 2.1 access control
@ -210,7 +192,5 @@ prod (collection)
[See a deeper tutorial on how to design access control architectures.](access-control-design-ee-standard.md) [See a deeper tutorial on how to design access control architectures.](access-control-design-ee-standard.md)
[Learn to manage access to resources by using collections.](manage-access-with-collections.md).
{% endif %} {% endif %}
{% endif %} {% endif %}

169
deploy/access-control/isolate-nodes-between-teams.md
View File

@ -13,7 +13,174 @@ ui_tabs:
{% if include.ui %} {% if include.ui %}
{% if include.version=="ucp-3.0" %} {% if include.version=="ucp-3.0" %}
This topic is under construction. With Docker EE Advanced, you can enable physical isolation of resources
by organizing nodes into collections and granting `Scheduler` access for
different users. To control access to nodes, move them to dedicated collections
where you can grant access to specific users, teams, and organizations.
In this example, a team gets access to a node collection and a resource
collection, and UCP access control ensures that the team members can't view
or use swarm resources that aren't in their collection.
You need a Docker EE Advanced license and at least two worker nodes to
complete this example.
1. Create an `Ops` team and assign a user to it.
2. Create a `/Prod` collection for the team's node.
3. Assign a worker node to the `/Prod` collection.
4. Grant the `Ops` teams access to its collection.
![](../images/isolate-nodes-diagram.svg){: .with-border}
## Create a team
In the web UI, navigate to the **Organizations & Teams** page to create a team
named "Ops" in your organization. Add a user who isn't a UCP administrator to
the team.
[Learn to create and manage teams](create-and-manage-teams.md).
## Create a node collection and a resource collection
In this example, the Ops team uses an assigned group of nodes, which it
accesses through a collection. Also, the team has a separate collection
for its resources.
Create two collections: one for the team's worker nodes and another for the
team's resources.
1. Navigate to the **Collections** page to view all of the resource
collections in the swarm.
2. Click **Create collection** and name the new collection "Prod".
3. Click **Create** to create the collection.
4. Find **Prod** in the list, and click **View children**.
5. Click **Create collection**, and name the child collection
"Webserver". This creates a sub-collection for access control.
You've created two new collections. The `/Prod` collection is for the worker
nodes, and the `/Prod/Webserver` sub-collection is for access control to
an application that you'll deploy on the corresponding worker nodes.
## Move a worker node to a collection
By default, worker nodes are located in the `/Shared` collection.
Worker nodes that are running DTR are assigned to the `/System` collection.
To control access to the team's nodes, move them to a dedicated collection.
Move a worker node by changing the value of its access label key,
`com.docker.ucp.access.label`, to a different collection.
1. Navigate to the **Nodes** page to view all of the nodes in the swarm.
2. Click a worker node, and in the details pane, find its **Collection**.
If it's in the `/System` collection, click another worker node,
because you can't move nodes that are in the `/System` collection. By
default, worker nodes are assigned to the `/Shared` collection.
3. When you've found an available node, in the details pane, click
**Configure**.
3. In the **Labels** section, find `com.docker.ucp.access.label` and change
its value from `/Shared` to `/Prod`.
4. Click **Save** to move the node to the `/Prod` collection.
> Docker EE Advanced required
>
> If you don't have a Docker EE Advanced license, you'll get the following
> error message when you try to change the access label:
> **Nodes must be in either the shared or system collection without an advanced license.**
> [Get a Docker EE Advanced license](https://www.docker.com/pricing).
![](../images/isolate-nodes-1.png){: .with-border}
## Grant access for a team
You'll need two grants to control access to nodes and container resources:
- Grant the `Ops` team the `Restricted Control` role for the `/Prod/Webserver`
resources.
- Grant the `Ops` team the `Scheduler` role against the nodes in the `/Prod`
collection.
Create two grants for team access to the two collections:
1. Navigate to the **Grants** page and click **Create Grant**.
2. In the left pane, click **Collections**, and in the **Swarm** collection,
click **View Children**.
3. In the **Prod** collection, click **View Children**.
4. In the **Webserver** collection, click **Select Collection**.
5. In the left pane, click **Roles**, and select **Restricted Control**
in the dropdown.
6. Click **Subjects**, and under **Select subject type**, click **Organizations**.
7. Select your organization, and in the **Team** dropdown, select **Ops**.
8. Click **Create** to grant the Ops team access to the `/Prod/Webserver`
collection.
The same steps apply for the nodes in the `/Prod` collection.
1. Navigate to the **Grants** page and click **Create Grant**.
2. In the left pane, click **Collections**, and in the **Swarm** collection,
click **View Children**.
3. In the **Prod** collection, click **Select Collection**.
4. In the left pane, click **Roles**, and in the dropdown, select **Scheduler**.
5. In the left pane, click **Subjects**, and under **Select subject type**, click
**Organizations**.
6. Select your organization, and in the **Team** dropdown, select **Ops** .
7. Click **Create** to grant the Ops team `Scheduler` access to the nodes in the
`/Prod` collection.
![](../images/isolate-nodes-2.png){: .with-border}
## Deploy a service as a team member
Your swarm is ready to show role-based access control in action. When a user
deploys a service, UCP assigns its resources to the user's default collection.
From the target collection of a resource, UCP walks up the ancestor collections
until it finds nodes that the user has `Scheduler` access to. In this example,
UCP assigns the user's service to the `/Prod/Webserver` collection and schedules
tasks on nodes in the `/Prod` collection.
As a user on the Ops team, set your default collection to `/Prod/Webserver`.
1. Log in as a user on the Ops team.
2. Navigate to the **Collections** page, and in the **Prod** collection,
click **View Children**.
3. In the **Webserver** collection, click the **More Options** icon and
select **Set to default**.
Deploy a service automatically to worker nodes in the `/Prod` collection.
All resources are deployed under the user's default collection,
`/Prod/Webserver`, and the containers are scheduled only on the nodes under
`/Prod`.
1. Navigate to the **Services** page, and click **Create Service**.
2. Name the service "NGINX", use the "nginx:latest" image, and click
**Create**.
3. When the **nginx** service status is green, click the service. In the
details view, click **Inspect Resource**, and in the dropdown, select
**Containers**.
4. Click the **NGINX** container, and in the details pane, confirm that its
**Collection** is **/Prod/Webserver**.
![](../../images/isolate-nodes-3.png){: .with-border}
5. Click **Inspect Resource**, and in the dropdown, select **Nodes**.
6. Click the node, and in the details pane, confirm that its **Collection**
is **/Prod**.
![](../images/isolate-nodes-4.png){: .with-border}
## Alternative: Use a grant instead of the default collection
Another approach is to use a grant instead of changing the user's default
collection. An administrator can create a grant for a role that has the
`Service Create` permission against the `/Prod/Webserver` collection or a child
collection. In this case, the user sets the value of the service's access label,
`com.docker.ucp.access.label`, to the new collection or one of its children
that has a `Service Create` grant for the user.
## Where to go next
- [Node access control in Docker EE Advanced](access-control-node.md)
- [Isolate volumes between two different teams](isolate-volumes-between-teams.md)
- [Deploy a service with view-only access across an organization](deploy-view-only-service.md)
{% elsif include.version=="ucp-2.2" %} {% elsif include.version=="ucp-2.2" %}

148
deploy/access-control/manage-access-with-collections.md → deploy/access-control/resources-create-collections-namespaces.md
View File

@ -1,7 +1,7 @@
--- ---
title: Manage access to resources by using collections title: Group resources into collections or namespaces
description: Use collections to enable access control for worker nodes and container resources. description: Learn how to group resources into collections or namespaces to control access.
keywords: ucp, grant, role, permission, authentication, resource collection keywords: rbac, ucp, grant, role, permission, authentication, resource collection
redirect_from: redirect_from:
- /ucp/ - /ucp/
ui_tabs: ui_tabs:
@ -13,7 +13,147 @@ ui_tabs:
{% if include.ui %} {% if include.ui %}
{% if include.version=="ucp-3.0" %} {% if include.version=="ucp-3.0" %}
This topic is under construction.
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.
![](../images/collections-and-resources.svg){: .with-border}
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.
![](../images/collections-diagram.svg){: .with-border}
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](../admin/configure/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:
![](../images/containers-and-nodes-diagram.svg)
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](isolate-nodes-between-teams.md).
{% elsif include.version=="ucp-2.2" %} {% elsif include.version=="ucp-2.2" %}

84
deploy/access-control/permission-levels.md → deploy/access-control/usermgmt-create-roles.md
View File

@ -1,7 +1,7 @@
--- ---
description: Learn about permissions in Docker Universal Control Plane. title: Create roles and set permission levels
keywords: authorization, authentication, users, teams, UCP description: Learn how to create roles and configure user authorization in Docker Universal Control Plane.
title: Roles and permission levels keywords: rbac, authorization, authentication, users, teams, UCP
redirect_from: redirect_from:
- /ucp/ - /ucp/
ui_tabs: ui_tabs:
@ -12,10 +12,86 @@ ui_tabs:
--- ---
{% if include.ui %} {% if include.ui %}
{% if include.version=="ucp-3.0" %} {% if include.version=="ucp-3.0" %}
This topic is under construction.
Docker Universal Control Plane has two types of users: administrators and
regular users. Administrators can make changes to the UCP swarm, while
regular users have permissions that range from no access to full control over
resources such as volumes, networks, images, and containers.
Users are grouped into teams and organizations.
![Diagram showing UCP permission levels](../images/role-diagram.svg)
Administrators apply *grants* to users, teams, and organizations to give
permissions to swarm resources.
## Administrator users
In Docker UCP, only users with administrator privileges can make changes to
swarm settings. This includes:
* Managing user permissions by creating grants.
* Managing swarm configurations, like adding and removing nodes.
## Roles
A role is a set of permitted API operations on a collection that you
can assign to a specific user, team, or organization by using a grant.
UCP administrators view and manage roles by navigating to the **Roles** page.
The system provides the following default roles:
| Built-in role | Description |
|----------------------|-------------|
| `None` | The user has no access to swarm resources. This maps to the `No Access` role in UCP 2.1.x. |
| `View Only` | The user can view resources like services, volumes, and networks but can't create them. |
| `Restricted Control` | The user can view and edit volumes, networks, and images but can't run a service or container in a way that might affect the node where it's running. The user can't mount a node directory and can't `exec` into containers. Also, The user can't run containers in privileged mode or with additional kernel capabilities. |
| `Scheduler` | The user can view nodes and schedule workloads on them. Worker nodes and manager nodes are affected by `Scheduler` grants. Having `Scheduler` access doesn't allow the user to view workloads on these nodes. They need the appropriate resource permissions, like `Container View`. By default, all users get a grant with the `Scheduler` role against the `/Shared` collection. |
| `Full Control` | The user can view and edit volumes, networks, and images, They can create containers without any restriction, but can't see other users' containers. |
![Diagram showing UCP permission levels](../images/permissions-ucp.svg)
Administrators can create a custom role that has Docker API permissions
that specify the API actions that a subject may perform.
The **Roles** page lists the available roles, including the default roles
and any custom roles that administrators have created. In the **Roles**
list, click a role to see the API operations that it uses. For example, the
`Scheduler` role has two of the node operations, `Schedule` and `View`.
## Create a custom role
Click **Create role** to create a custom role and define the API operations
that it uses. When you create a custom role, all of the APIs that you can use
are listed on the **Create Role** page. For example, you can create a custom
role that uses the node operations, `Schedule`, `Update`, and `View`, and you
might give it a name like "Node Operator".
![](../images/custom-role.png){: .with-border}
You can give a role a global name, like "Remove Images", which might enable
the **Remove** and **Force Remove** operations for images. You can apply a
role with the same name to different collections.
Only an administrator can create and remove roles. Roles are always enabled.
Roles can't be edited, so to change a role's API operations, you must delete it
and create it again.
You can't delete a custom role if it's used in a grant. You must first delete
the grants that use the role.
## Where to go next
* [Create and manage users](create-and-manage-users.md)
* [Create and manage teams](create-and-manage-teams.md)
* [Docker Reference Architecture: Securing Docker EE and Security Best Practices](https://success.docker.com/Architecture/Docker_Reference_Architecture%3A_Securing_Docker_EE_and_Security_Best_Practices)
{% elsif include.version=="ucp-2.2" %} {% elsif include.version=="ucp-2.2" %}
Docker Universal Control Plane has two types of users: administrators and Docker Universal Control Plane has two types of users: administrators and
regular users. Administrators can make changes to the UCP swarm, while regular users. Administrators can make changes to the UCP swarm, while
regular users have permissions that range from no access to full control over regular users have permissions that range from no access to full control over

131
deploy/access-control/usermgmt-create-subjects.md Normal file
View File

@ -0,0 +1,131 @@
---
title: Create and manage users and teams
description: Learn how to add users and define teams in Docker Universal Control Plane.
keywords: rbac, authorize, authentication, users, teams, UCP, Docker
redirect_from:
- /ucp/
ui_tabs:
- version: ucp-3.0
orhigher: true
- version: ucp-2.2
orlower: true
---
{% if include.ui %}
Users, teams, and organizations are referred to as subjects in Docker Universal
Control Plane (UCP).
Individual users can belong to one or more teams but each team can only be in
one ogranziation. At the fictional startup, Acme Company, some users are on
multiple teams; but all teams are necessarily unique.
```
Acme Organization
├── DevOps Team
│   ├── User Alex
│   └── User Brad
├── Infra Team
│ ├── User Alex
│  └── User Carl
└── Apps Team
   ├── User Doug
   └── User Evan
```
## Authentication
All users are authenticated on the backend. UCP provides built-in authentication
and also integrates with LDAP directory services.
> To enable LDAP and authenticate and synchronize UCP users and teams with your
> organization's LDAP directory, see:
> - [Synchronize users and teams with LDAP in the UI](./usermgmt-sync-teams-with-ldap.md)
> - [Synchronize users and teams with LDAP on the backend](../configure/external-auth/index.md).
To use UCP built-in authentication, you must manually create users.
New users are assigned a default permission level so that they can access the
cluster. You can optionally grant them UCP administrator permissions.
You can extend the user's default permissions by granting them fine-grained
permissions over resources. You do this by adding the user to a team.
## Build an organization architecture
The general flow of designing an organization of teams in UCP is:
1. Create an organization
2. Add users or configure UCP to sync with LDAP (in the UI or programmatically)
3. Create teams under the organization
4. Add users to teams manually or sync with LDAP
### Create organizations
To create an organzation in UCP:
1. Click **Organization & Teams** under **User Management**.
2. Click **Create Organization**.
3. Input the organization name.
4. Click **Create**.
### Create teams manually
1. Click **Organization & Teams** under **User Management**.
2. Click through an organization name.
3. Click **Create Team**.
4. Input a team name (and description).
5. Click **Create**.
6. Add existing users to the team. If they don't exist, see below.
- Click the team name.
- Select **Actions** > **Add Users**.
- Check users to include.
- Click **Add Users**.
> **Note**: To sync teams with groups in an LDAP server, see [Sync Teams with LDAP](./usermgmt-sync-teams-with-ldap).
{% if include.version=="ucp-3.0" %}
### Create users manuallly
To manally create users in UCP:
1. Click **Users** under **User Management**.
2. Click **Create User**.
3. Input username, password, and full name.
4. Click **Create**.
5. [optional] Check "Is a Docker EE Admin".
> A `Docker EE Admin` can grant users permission to change the cluster
> configuration and manage grants, roles, and collections.
![](../images/ucp_usermgmt_users_create01.png){: .with-border}
![](../images/ucp_usermgmt_users_create02.png){: .with-border}
{% elsif include.version=="ucp-2.2" %}
### Create users manuallly
To manally create users in UCP:
1. Navigate to the **Users** page.
2. Click **Create User**.
3. Input username, password, and full name.
4. Click **Create**.
5. [optional] Check "Is a UCP admin?".
![](../images/create-users-1.png){: .with-border}
> A `UCP Admin` can grant users permission to change the cluster configuration
> and manage grants, roles, and collections.
![](../images/create-users-2.png){: .with-border}
{% endif %}
## Where to go next
- [Synchronize users and teams with LDAP](./usermgmt-sync-teams-with-ldap.md)
- [Create grants and authorize access to users and teams](usermgmt-grant-permissions.md).
{% endif %}

9
deploy/access-control/grant-permissions.md → deploy/access-control/usermgmt-grant-permissions.md
View File

@ -1,7 +1,7 @@
--- ---
title: Grant permissions to users based on roles title: Create grants to authorize access to resources
description: Grant access to swarm resources by using role-based access control. description: Learn how to grant users and teams access to cluster resources with role-based access control.
keywords: ucp, grant, role, permission, authentication, authorization keywords: rbac, ucp, grant, role, permission, authentication, authorization
redirect_from: redirect_from:
- /ucp/ - /ucp/
ui_tabs: ui_tabs:
@ -12,10 +12,11 @@ ui_tabs:
--- ---
{% if include.ui %} {% if include.ui %}
{% if include.version=="ucp-3.0" %}
UCP administrators can create *grants* to control how users and organizations UCP administrators can create *grants* to control how users and organizations
access resources. access resources.
{% if include.version=="ucp-3.0" %}
## Kubernetes grants ## Kubernetes grants
With Kubernetes orchestration, a grant is made up of a *subject*, a *role*, and a With Kubernetes orchestration, a grant is made up of a *subject*, a *role*, and a
*namespace*. *namespace*.

4
deploy/access-control/recover-a-user-password.md → deploy/access-control/usermgmt-recover-user-password.md
View File

@ -1,6 +1,6 @@
--- ---
title: Reset a user password title: Reset a user password
description: Learn how to recover your Docker Datacenter credentials description: Learn how to recover your Docker Datacenter credentials.
keywords: ucp, authentication keywords: ucp, authentication
redirect_from: redirect_from:
- /ucp/ - /ucp/
@ -27,7 +27,7 @@ the **Users** page, and choose the user whose password you want to change.
In the details pane, click **Configure** and select **Security** from the In the details pane, click **Configure** and select **Security** from the
dropdown. dropdown.
![](../images/recover-a-user-password-1.png){: .with-border} ![](../images/recover-user-password-1.png){: .with-border}
Update the user's password and click **Save**. Update the user's password and click **Save**.

119
deploy/access-control/usermgmt-sync-with-ldap.md Normal file
View File

@ -0,0 +1,119 @@
---
title: Synchronize users and teams with LDAP
description: Learn how to enable LDAP and sync users and teams in Docker Universal Control Plane.
keywords: authorize, authentication, users, teams, UCP, Docker, LDAP
redirect_from:
- /ucp/
ui_tabs:
- version: ucp-3.0
orhigher: true
- version: ucp-2.2
orlower: true
---
{% if include.ui %}
{% if include.version=="ucp-3.0" %}
To enable LDAP in UCP and sync team members with your LDAP directory:
1. Click **Admin Settings** under your username drop down.
2. Click **Authentication & Authorization**.
3. Scroll down and click `Yes` by **LDAP Enabled**. A list of LDAP settings displays.
4. Input values to match your LDAP server installation.
5. Test your configuration in UCP.
6. Manually create teams in UCP to mirror those in LDAP.
6. Click **Sync Now**.
If UCP is configured to sync users with your organization's LDAP directory
server, you can enable syncing the new team's members when
creating a new team or when modifying settings of an existing team.
[Learn how to sync with LDAP at the backend](../configure/external-auth/index.md).
![](../images/create-and-manage-teams-5.png){: .with-border}
There are two methods for matching group members from an LDAP directory:
**Match Group Members**
This option specifies that team members should be synced directly with members
of a group in your organization's LDAP directory. The team's membership will by
synced to match the membership of the group.
| Field | Description |
|:-----------------------|:------------------------------------------------------------------------------------------------------|
| Group DN | The distinguished name of the group from which to select users. |
| Group Member Attribute | The value of this group attribute corresponds to the distinguished names of the members of the group. |
**Match Search Results**
This option specifies that team members should be synced using a search query
against your organization's LDAP directory. The team's membership will be
synced to match the users in the search results.
| Field | Description |
| :--------------------- | :---------------------------------------------------------------------------------------------------- |
| Search Base DN | Distinguished name of the node in the directory tree where the search should start looking for users. |
| Search Filter | Filter to find users. If null, existing users in the search scope are added as members of the team. |
| Search subtree | Defines search through the full LDAP tree, not just one level, starting at the Base DN. |
**Immediately Sync Team Members**
Select this option to run an LDAP sync operation immediately after saving the
configuration for the team. It may take a moment before the members of the team
are fully synced.
{% elsif include.version=="ucp-2.2" %}
To enable LDAP in UCP and sync team members with your LDAP directory:
1. Click **Admin Settings** under your username drop down.
2. Click **Authentication & Authorization**.
3. Scroll down and click `Yes` by **LDAP Enabled**. A list of LDAP settings displays.
4. Input values to match your LDAP server installation.
5. Test your configuration in UCP.
6. Manually create teams in UCP to mirror those in LDAP.
6. Click **Sync Now**.
If UCP is configured to sync users with your organization's LDAP directory
server, you can enable syncing the new team's members when
creating a new team or when modifying settings of an existing team.
[Learn how to sync with LDAP at the backend](../configure/external-auth/index.md).
![](../images/create-and-manage-teams-5.png){: .with-border}
There are two methods for matching group members from an LDAP directory:
**Match Group Members**
This option specifies that team members should be synced directly with members
of a group in your organization's LDAP directory. The team's membership will by
synced to match the membership of the group.
| Field | Description |
|:-----------------------|:------------------------------------------------------------------------------------------------------|
| Group DN | The distinguished name of the group from which to select users. |
| Group Member Attribute | The value of this group attribute corresponds to the distinguished names of the members of the group. |
**Match Search Results**
This option specifies that team members should be synced using a search query
against your organization's LDAP directory. The team's membership will be
synced to match the users in the search results.
| Field | Description |
| :--------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Search Base DN | The distinguished name of the node in the directory tree where the search should start looking for users. |
| Search Filter | The LDAP search filter used to find users. If you leave this field empty, all existing users in the search scope will be added as members of the team. |
| Search subtree instead of just one level | Whether to perform the LDAP search on a single level of the LDAP tree, or search through the full LDAP tree starting at the Base DN. |
**Immediately Sync Team Members**
Select this option to run an LDAP sync operation immediately after saving the
configuration for the team. It may take a moment before the members of the team
are fully synced.
{% endif %}
{% endif %}