diff --git a/deploy/images/custom-role-30.png b/deploy/images/custom-role-30.png new file mode 100644 index 0000000000..59f9973872 Binary files /dev/null and b/deploy/images/custom-role-30.png differ diff --git a/deploy/rbac/index.md b/deploy/rbac/index.md index ff412c952d..b63de07c27 100644 --- a/deploy/rbac/index.md +++ b/deploy/rbac/index.md @@ -36,9 +36,9 @@ administrators might take the following high-level steps: - Define custom **roles** (or use defaults) by adding permitted operations per resource types. - Group cluster **resources** into Swarm collections or Kubernetes namespaces. -- Create **grants** by marrying subject + role + resource. +- Create **grants** by marrying subject + role + resource group. -For a simple example, see [Deploy stateless app with RBAC](./deploy/rbac/rbac-howto-deploy-stateless-app/). +For an example, see [Deploy stateless app with RBAC](./deploy/rbac/rbac-howto-deploy-stateless-app). ## Subjects @@ -61,8 +61,8 @@ operations against a *resource type* (such as an image, container, volume) that is assigned to a user or team with a grant. For example, the built-in role, **Restricted Control**, includes permission to -view and schedule a node but not update. A custom **DBA** role might include -permissions to create, attach, view, and remove volumes. +view and schedule nodes but not to update nodes. A custom **DBA** role might +include permissions to r-w-x volumes and secrets. Most organizations use multiple roles to fine-tune the approprate access. A given team or user may have different roles provided to them depending on what @@ -125,7 +125,9 @@ administrators might take the following high-level steps: - Define custom **roles** (or use defaults) by adding permitted operations per resource types. - Group cluster **resources** into Swarm collections. -- Create **grants** by marrying subject + role + resource. +- Create **grants** by marrying subject + role + resource group. + +For an example, see [Deploy stateless app with RBAC](./deploy/rbac/rbac-howto-deploy-stateless-app). ## Subjects @@ -148,8 +150,8 @@ operations against a *resource type* (such as an image, container, volume) that is assigned to a user or team with a grant. For example, the built-in role, **Restricted Control**, includes permission to -view and schedule a node but not update. A custom **DBA** role might include -permissions to create, attach, view, and remove volumes. +view and schedule nodes but not to update nodes. A custom **DBA** role might +include permissions to r-w-x volumes and secrets. 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 diff --git a/deploy/rbac/rbac-basics-create-subjects.md b/deploy/rbac/rbac-basics-create-subjects.md index 5b55ad2a7c..eed3c9c683 100644 --- a/deploy/rbac/rbac-basics-create-subjects.md +++ b/deploy/rbac/rbac-basics-create-subjects.md @@ -56,7 +56,7 @@ To use Docker EE's built-in authentication, you must [create users manually](#cr The general flow of designing an organization with teams in UCP is: 1. Create an organization. -2. Add users or enable LDAP. +2. Add users or enable LDAD (for syncing users). 3. Create teams under the organization. 4. Add users to teams manually or sync with LDAP. @@ -75,7 +75,7 @@ To create teams in the organization: 2. Click **Create Team**. 3. Input a team name (and description). 4. Click **Create**. -5. Add existing users to the team. If they don't exist, see [Integrate with an LDAP Directory](../../datacenter/ucp/2.2/guides/admin/configure/external-auth/index.md). +5. Add existing users to the team. To sync LDAP users, see: [Integrate with an LDAP Directory](../../datacenter/ucp/2.2/guides/admin/configure/external-auth/index.md). - Click the team name and select **Actions** > **Add Users**. - Check the users to include and click **Add Users**. diff --git a/deploy/rbac/rbac-basics-define-roles.md b/deploy/rbac/rbac-basics-define-roles.md index b134500ee3..bf229a2c1a 100644 --- a/deploy/rbac/rbac-basics-define-roles.md +++ b/deploy/rbac/rbac-basics-define-roles.md @@ -32,7 +32,7 @@ You can define custom roles or use the following built-in roles: | Built-in role | Description | | ---------------------| ------------------------------------------------------------------------------- | -| `None` | Users have no access to Swarm resources. Maps to `No Access` role in UCP 2.1.x. | +| `None` | Users have no access to Swarm or Kubernetes resources. Maps to `No Access` role in UCP 2.1.x. | | `View Only` | Users can view resources but can't create them. | | `Restricted Control` | Users can view and edit resources but can't run a service or container in a way that affects the node where it's running. Users _cannot_ mount a node directory, `exec` into containers, or run containers in privileged mode or with additional kernel capabilities. | | `Scheduler` | Users can view nodes (worker and manager) and schedule (not view) workloads on these nodes. By default, all users are granted the `Scheduler` role against the `/Shared` collection. (To view workloads, users need permissions such as `Container View`). | @@ -55,7 +55,7 @@ the same name to different collections or namespaces. 5. Select the permitted operations per resource type. 6. Click **Create**. -![](../images/custom-role.png){: .with-border} +![](../images/custom-role-30.png){: .with-border} > **Some important rules regarding roles**: > - Roles are always enabled. diff --git a/deploy/rbac/rbac-basics-grant-permissions.md b/deploy/rbac/rbac-basics-grant-permissions.md index 510d409387..e50b884557 100644 --- a/deploy/rbac/rbac-basics-grant-permissions.md +++ b/deploy/rbac/rbac-basics-grant-permissions.md @@ -10,42 +10,20 @@ ui_tabs: - version: ucp-2.2 orlower: true next_steps: -- path: /deploy/rbac/usermgmt-create-subjects/ - title: Create and configure users and teams -- path: /deploy/rbac/usermgmt-define-roles/ - title: Create roles to authorize access -- path: /deploy/rbac/resources-isolate-volumes/ - title: Isolate volumes +- path: /deploy/rbac/rbac-howto-deploy-stateless-app/ + title: Deploy a simple stateless app with RBAC --- {% if include.ui %} -Docker EE administrators can create *grants* to control how users and -organizations access resources. - -A grant is made up of *subject*, *role*, and *resource group*. - - {% if include.version=="ucp-3.0" %} -## Kubernetes grants +Docker EE administrators can create _grants_ to control how users and +organizations access resources. -With Kubernetes orchestration, a grant is made up of *subject*, *role*, and -*namespace*. - - - - -## Swarm grants - -With Swarm orchestration, a grant is made up of *subject*, *role*, and -*collection*. - -![](../images/ucp-grant-model-0.svg){: .with-border} - -A grant defines who (subject) has how much access (role) to a set of resources -(collection). Each grant is a 1:1:1 mapping of subject, role, collection. For -example, you can grant the "Prod Team" "Restricted Control"of the "/Production" +A grant defines _who_ has _how much_ access to _what_ resources. Each grant is a +1:1:1 mapping of _subject_, _role_, and _resource group_. For example, you can +grant the "Prod Team" "Restricted Control" of services in the "/Production" collection. A common workflow for creating grants has four steps: @@ -54,24 +32,50 @@ A common workflow for creating grants has four steps: - Define custom **roles** (or use defaults) by adding permitted API operations per resource type. - Group cluster **resources** into Swarm collections or Kubernetes namespaces. -- Create **grants** by marrying subject + role + resource. +- Create **grants** by marrying subject + role + resource group. +## Kubernetes grants + +With Kubernetes orchestration, a grant is made up of *subject*, *role*, and +*namespace*. + +> This section assumes that you have created objects to grant (subject, role, +> namespace). + +To create a Kubernetes grant in UCP: + +1. Click **Grants** under **User Management**. +2. Click **Create Grant**. +3. Click **Namespaces** under **Kubernetes**. +4. Click **View Children** until you get to the desired resource group and **Select**. +5. On the Roles tab, select a role. +6. On the Subjects tab, select a user, team, or organization to authorize. +7. Click **Create**. + +> By default, all new users are placed in the `docker-datacenter` organization. +> To apply permissions to all Docker EE users, create a grant with the +> `docker-datacenter` org as a subject. + +## Swarm grants + +With Swarm orchestration, a grant is made up of *subject*, *role*, and +*collection*. + +> This section assumes that you have created objects to grant: teams/users, +> roles (built-in or custom), and a collection. + +![](../images/ucp-grant-model-0.svg){: .with-border} ![](../images/ucp-grant-model.svg){: .with-border} -### Create a Swarm grant - -You can create grants after creating users, collections, and roles (if using -custom roles). - To create a grant in UCP: 1. Click **Grants** under **User Management**. 2. Click **Create Grant**. -3. On the Collections tab, click **Collections** (for Swarm) or **Namespaces** (for Kubernetes). +3. On the Collections tab, click **Collections** (for Swarm). 4. Click **View Children** until you get to the desired resource group and **Select**. 5. On the Roles tab, select a role. 6. On the Subjects tab, select a user, team, or organization to authorize. -4. Click **Create**. +7. Click **Create**. > By default, all new users are placed in the `docker-datacenter` organization. > To apply permissions to all Docker EE users, create a grant with the @@ -80,16 +84,12 @@ To create a grant in UCP: {% elsif include.version=="ucp-2.2" %} -## Swarm grants +Docker EE administrators can create _grants_ to control how users and +organizations access resources. -With Swarm orchestration, a grant is made up of *subject*, *role*, and -*collection*. - -![](../images/ucp-grant-model-0.svg){: .with-border} - -A grant defines who (subject) has how much access (role) to a set of resources -(collection). Each grant is a 1:1:1 mapping of subject, role, collection. For -example, you can grant the "Prod Team" "Restricted Control"of the "/Production" +A grant defines _who_ has _how much_ access to _what_ resources. Each grant is a +1:1:1 mapping of _subject_, _role_, and _resource group_. For example, you can +grant the "Prod Team" "Restricted Control" of services in the "/Production" collection. A common workflow for creating grants has four steps: @@ -98,23 +98,28 @@ A common workflow for creating grants has four steps: - Define custom **roles** (or use defaults) by adding permitted API operations per resource type. - Group cluster **resources** into Swarm collections. -- Create **grants** by marrying subject + role + resource. +- Create **grants** by marrying subject + role + resource group. +## Swarm grants + +With Swarm orchestration, a grant is made up of *subject*, *role*, and +*collection*. + +> This section assumes that you have created objects to grant: teams/users, +> roles (built-in or custom), and a collection. + +![](../images/ucp-grant-model-0.svg){: .with-border} ![](../images/ucp-grant-model.svg){: .with-border} -### Create a Swarm grant - -You can create grants after creating users, collections, and roles (if using custom roles). - To create a grant in UCP: 1. Click **Grants** under **User Management**. 2. Click **Create Grant**. -3. On the Collections tab, click **Collections**. +3. On the Collections tab, click **Collections** (for Swarm). 4. Click **View Children** until you get to the desired resource group and **Select**. 5. On the Roles tab, select a role. 6. On the Subjects tab, select a user, team, or organization to authorize. -4. Click **Create**. +7. Click **Create**. > By default, all new users are placed in the `docker-datacenter` organization. > To apply permissions to all Docker EE users, create a grant with the diff --git a/deploy/rbac/rbac-basics-group-resources.md b/deploy/rbac/rbac-basics-group-resources.md index bd1ede47ed..ec0bfcffd1 100644 --- a/deploy/rbac/rbac-basics-group-resources.md +++ b/deploy/rbac/rbac-basics-group-resources.md @@ -34,14 +34,14 @@ namespaces _cannot be nested_. > Resource types that can be placed into a Kubernetes namespace include: Pods, > Deployments, NetworkPolcies, Nodes, Services, Secrets, and many more. -Resources are placed into a namespace when creating a kubernetes object. A drop -down displays with all available namespaces and one must be selected. +Resources are placed into a namespace when you create a kubernetes object. A +drop down displays all available namespaces and one must be selected. ## Swarm collection A collection is a directory of grouped resources, such as services, containers, volumes, networks, and secrets. To authorize access, administrators create -grants against directory branches. +grants against these directory branches. ![](../images/collections-and-resources.svg){: .with-border} @@ -50,13 +50,13 @@ grants against directory branches. Access to a collection is granted with a path defined in an access label. For example, each user has a private collection with the path, -`/Shared/Private/`. The private collection for user "hans" would have -the access label: `com.docker.ucp.access.label = /Shared/Private/hans`. +`/Shared/Private/`. The private collection for user "molly" would have +the access label: `com.docker.ucp.access.label = /Shared/Private/molly`. To deploy applications into a custom collection, you must define the collection -first. For an example, see [Deploy stateless app with RBAC](./deploy/rbac/rbac-howto-deploy-stateless-app/#swarm-stack). When a user -deploys a resource without an access label, Docker EE automatically places the -resource in the user's default collection. +first. For an example, see [Deploy stateless app with RBAC](./deploy/rbac/rbac-howto-deploy-stateless-app). +When a user deploys a resource without an access label, Docker EE automatically +places the resource in the user's default collection. ### Nested collections @@ -75,7 +75,7 @@ Docker EE provides a number of built-in collections. | ------------------ | --------------------------------------------------------------------------------------- | | `/` | Path to all resources in the Swarm cluster. Resources not in a collection are put here. | | `/System` | Path to UCP managers, DTR nodes, and UCP/DTR system services. By default, only admins have access, but this is configurable. | -| `/Shared` | Default path to all worker nodes for scheduling. In Docker EE Standard, all worker nodes are located here. In [Docker EE Advanced](https://www.docker.com/enterprise-edition), worker nodes can be moved and [isolated](./howto-isolate-nodes/). | +| `/Shared` | Default path to all worker nodes for scheduling. In Docker EE Standard, all worker nodes are located here. In [Docker EE Advanced](https://www.docker.com/enterprise-edition), worker nodes can be moved and [isolated](./rbac-howto-isolate-nodes/). | | `/Shared/Private/` | Path to a user's private collection. | | `/Shared/Legacy` | Path to the access control labels of legacy versions (UCP 2.1 and lower). | @@ -92,9 +92,7 @@ Each user has a default collection which can be changed in UCP preferences. Users can't deploy a resource without a collection. When a user deploys a resource without an access label, Docker EE automatically places the resource in -the user's default collection. - -[Learn how to add labels to nodes](../../datacenter/ucp/2.2/guides/admin/configure/add-labels-to-cluster-nodes/). +the user's default collection. [Learn how to add labels to nodes](../../datacenter/ucp/2.2/guides/admin/configure/add-labels-to-cluster-nodes/). With Docker Compose, the system applies default collection labels across all resources in the stack unless `com.docker.ucp.access.label` has been explicitly @@ -153,12 +151,12 @@ 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 +resource, like `/Shared/Private/molly`, 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 +user's default collection, which is at `/Shared/Private/molly`, and deploy it on one of the nodes under `/Shared`. If you want to isolate nodes against other teams, place these nodes in new @@ -181,8 +179,8 @@ grants against directory branches. Access to a collection is granted with a path defined in an access label. For example, each user has a private collection with the path, -`/Shared/Private/`. The private collection for user "hans" would have -the access label: `com.docker.ucp.access.label = /Shared/Private/hans`. +`/Shared/Private/`. The private collection for user "molly" would have +the access label: `com.docker.ucp.access.label = /Shared/Private/molly`. To deploy applications into a custom collection, you must define the collection first. For an example, see [Deploy stateless app with RBAC](./deploy/rbac/rbac-howto-deploy-stateless-app/#swarm-stack). When a user @@ -206,7 +204,7 @@ Docker EE provides a number of built-in collections. | ------------------ | --------------------------------------------------------------------------------------- | | `/` | Path to all resources in the Swarm cluster. Resources not in a collection are put here. | | `/System` | Path to UCP managers, DTR nodes, and UCP/DTR system services. By default, only admins have access, but this is configurable. | -| `/Shared` | Default path to all worker nodes for scheduling. In Docker EE Standard, all worker nodes are located here. In [Docker EE Advanced](https://www.docker.com/enterprise-edition), worker nodes can be moved and [isolated](./howto-isolate-nodes/). | +| `/Shared` | Default path to all worker nodes for scheduling. In Docker EE Standard, all worker nodes are located here. In [Docker EE Advanced](https://www.docker.com/enterprise-edition), worker nodes can be moved and [isolated](./rbac-howto-isolate-nodes/). | | `/Shared/Private/` | Path to a user's private collection. | | `/Shared/Legacy` | Path to the access control labels of legacy versions (UCP 2.1 and lower). | @@ -223,9 +221,7 @@ Each user has a default collection which can be changed in UCP preferences. Users can't deploy a resource without a collection. When a user deploys a resource without an access label, Docker EE automatically places the resource in -the user's default collection. - -[Learn how to add labels to nodes](../../datacenter/ucp/2.2/guides/admin/configure/add-labels-to-cluster-nodes/). +the user's default collection. [Learn how to add labels to nodes](../../datacenter/ucp/2.2/guides/admin/configure/add-labels-to-cluster-nodes/). With Docker Compose, the system applies default collection labels across all resources in the stack unless `com.docker.ucp.access.label` has been explicitly @@ -284,12 +280,12 @@ 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 +resource, like `/Shared/Private/molly`, 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 +user's default collection, which is at `/Shared/Private/molly`, and deploy it on one of the nodes under `/Shared`. If you want to isolate nodes against other teams, place these nodes in new diff --git a/deploy/rbac/rbac-howto-deploy-stateless-app.md b/deploy/rbac/rbac-howto-deploy-stateless-app.md index b11a4c3329..a390394a45 100644 --- a/deploy/rbac/rbac-howto-deploy-stateless-app.md +++ b/deploy/rbac/rbac-howto-deploy-stateless-app.md @@ -158,17 +158,53 @@ service. 4. On the Details tab, enter: - Name: `nginx-service` - Image: nginx:latest -4. On the Collections tab: +5. On the Collections tab: - Click `/Shared` in the breadcrumbs. - Select `nginx-collection`. -5. Click **Create**. -6. Log on to UCP as each user and ensure that: +6. Click **Create**. +7. Log on to UCP as each user and ensure that: - `dba` (alex) cannot see `nginx-collection`. - `dev` (bett) cannot see `nginx-collection`. {% elsif include.version=="ucp-2.2" %} +This tutorial explains how to deploy a nginx web server and limit access to one +team with role-based access control (RBAC). + +## Scenario + +You are the Docker EE admin at Acme Company and need to configure permissions to +company resources. The best way to do this is to: + +- Build the organization with teams and users +- Create collections for storing resources. +- Create grants that specify which team can do what operations on which + collection. +- Give the `ops` team the all-clear to deploy nginx. + +## Build the organization + +Add the organization, `acme-datacenter`, and create three teams according to the +following structure: + +``` +acme-datacenter +├── dba +│   └── Alex Alutin +├── dev +│   └── Bett Bhatia +└── ops +   └── Chad Chavez +``` + +> Easy username / passwords: +> - alex / alexalutin +> - bett / bettbhatia +> - chad / chadchavez + +See: [Create and configure users and teams](./usermgmt-create-subjects.md). + ## Swarm Stack In this section, we deploy `nginx` as a Swarm service. See [Kubernetes Deployment](#kubernetes-deployment) @@ -211,11 +247,11 @@ service. 4. On the Details tab, enter: - Name: `nginx-service` - Image: nginx:latest -4. On the Collections tab: +5. On the Collections tab: - Click `/Shared` in the breadcrumbs. - Select `nginx-collection`. -5. Click **Create**. -6. Log on to UCP as each user and ensure that: +6. Click **Create**. +7. Log on to UCP as each user and ensure that: - `dba` (alex) cannot see `nginx-collection`. - `dev` (bett) cannot see `nginx-collection`. diff --git a/deploy/rbac/rbac-howto-orcabank1-standard.md b/deploy/rbac/rbac-howto-orcabank1-standard.md index 59e4bd729e..4ca030f2c0 100644 --- a/deploy/rbac/rbac-howto-orcabank1-standard.md +++ b/deploy/rbac/rbac-howto-orcabank1-standard.md @@ -122,7 +122,7 @@ a secure and controlled interface, leveraging Database networks and secrets. > **Note:** In Docker Enterprise Standard, all resources are deployed across the > same group of UCP worker nodes. Node segmentation is provided in Docker -> Enterprise Advanced and discussed in the [next tutorial](#). +> Enterprise Advanced and discussed in the [next tutorial](./deploy/rbac/rbac-howto-orcabank1-advanced). ![image](../images/design-access-control-adv-2.png){: .with-border} @@ -241,7 +241,7 @@ a secure and controlled interface, leveraging Database networks and secrets. > **Note:** In Docker Enterprise Standard, all resources are deployed across the > same group of UCP worker nodes. Node segmentation is provided in Docker -> Enterprise Advanced and discussed in the [next tutorial](#). +> Enterprise Advanced and discussed in the [next tutorial](./deploy/rbac/rbac-howto-orcabank1-advanced). ![image](../images/design-access-control-adv-2.png){: .with-border}