diff --git a/_data/toc.yaml b/_data/toc.yaml index e50a238fbf..f7113f0a69 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -317,26 +317,26 @@ guides: title: Access control model overview - sectiontitle: The basics section: - - path: /deploy/rbac/basics-create-subjects/ + - path: /deploy/rbac/rbac-basics-create-subjects/ title: Create and users and teams - - path: /deploy/rbac/basics-define-roles/ + - path: /deploy/rbac/rbac-basics-define-roles/ title: Define roles with permissions - - path: /deploy/rbac/basics-group-resources/ + - path: /deploy/rbac/rbac-basics-group-resources/ title: Group cluster resources - - path: /deploy/rbac/basics-grant-permissions/ + - path: /deploy/rbac/rbac-basics-grant-permissions/ title: Grant access to resources - sectiontitle: Tutorials and use cases section: - - path: /deploy/rbac/howto-deploy-stateless-app/ + - path: /deploy/rbac/rbac-howto-deploy-stateless-app/ title: Deploy stateless app with RBAC - - path: /deploy/rbac/basics-isolate-volumes/ + - path: /deploy/rbac/rbac-howto-isolate-volumes/ title: Isolate volumes - - path: /deploy/rbac/basics-isolate-nodes/ + - path: /deploy/rbac/rbac-howto-isolate-nodes/ title: Isolate nodes - - path: /deploy/rbac/howto-orcabank1-standard/ - title: Orcabank example with Docker EE Standard - - path: /deploy/rbac/howto-orcabank2-advanced/ - title: Orcabank example with Docker EE Advanced + - path: /deploy/rbac/rbac-howto-orcabank1-standard/ + title: Docker EE Standard Use Case + - path: /deploy/rbac/rbac-howto-orcabank2-advanced/ + title: Docker EE Advanced Use Case - sectiontitle: User admin section: - path: /deploy/rbac/admin-sync-with-ldap/ diff --git a/deploy/rbac/howto-deploy-stateless-app.md b/deploy/rbac/howto-deploy-stateless-app.md deleted file mode 100644 index 11c9fac5b2..0000000000 --- a/deploy/rbac/howto-deploy-stateless-app.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: Deploy a simple stateless app 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 %} - -This tutorial explains how to create 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 secure access to -`acme-blog` and its component services, Wordpress and MySQL. The best way to do -this is to: - -- Build the organization with teams and users -- Create collections (directories) for storing the resources of each component. -- Create grants that specify which team can do what operations on which collection. -- Give the all-clear for the ops team to deploy the blog. - -## 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 -``` -See: [Create and configure users and teams](./usermgmt-create-subjects.md). - - -{% if include.version=="ucp-3.0" %} - -## Kubernetes deployment - -In this section, we deploy `acme-blog` with Kubernetes. See [Swarm stack](#swarm-stack) -for the same exercise with Swarm. - -### Generate Kubernetes secret - -For the Kubernetes part of the tutorial, we need to generate a Kubernetes secret -with kubectl. Download the client bundle in UCP to get it running. - -1. In the Docker EE UI: - a. Go to **My Profile**. - b. Click **New Client Bundle** > **Generate Client Bundle**. -2. On your localhost: - a. Open a new terminal and navigate to the bundle. - b. `mkdir bundle && cd bundle` - c. `unzip ucp-bundle-admin.zip` - d. Source the UCP environment: `eval "$( ./username.txt -echo -n "1f2d1e2e67df" > ./password.txt -kubectl create secret generic db-user-pass --from-file=./username.txt --from-file=./password.txt -``` - -4. Ensure the secret was generated: `kubectl get secrets` - -> To undo the eval setting, close the terminal. - - -### Create namespaces - -_Under construction_ - -``` -apiVersion: v1 -kind: Namespace -metadata: - name: mysql-namespace -``` - -test - -``` -apiVersion: v1 -kind: Namespace -metadata: - name: wordpress-namespace -``` - -### Grant roles - -_Under construction_ - -### Deploy Wordpress and MySQL with Kubernetes - -_Under construction_ - -### Test access - -_Under construction_ - - -## Swarm Stack - -In this section, we deploy `acme-blog` as a Swarm stack of two services. See -[Kubernetes Deployment](#kubernetes-deployment) for the same exercise with -Kubernetes. - - -### Create collection paths - -Create three nested Swarm collections. First, create a collection for -`acme-blog` in the `Shared` collection and then nest collections for wordpress -and mysql resources: - -``` -/ -├── System -└── Shared -   └── acme-blog - ├── wordpress-collection -   └── mysql-collection -``` - -> **Tip**: To drill into a collection, click **View Children**. - -See: [Group and isolate cluster resources](./resources-group-resources.md). - -### Grant roles - -Create three grants with built-in roles: - -- acme-datacenter/ops + Full Control + /Shared/acme-blog -- acme-datacenter/dev + Full Control + /Shared/acme-blog/wordpress-collection -- acme-datacenter/dba + Full Control + /Shared/acme-blog/mysql-collection - -> In this exercise we use built-in roles but you can create custom ones too. - -See: [Grant access to cluster resources](./usermgmt-grant-permissions.md). - -### Deploy Wordpress and MySQL with Swarm - -You've configured Docker EE. The `ops` team can now deploy `acme-blog`: - -1. Click **Shared Resources** > **Stacks**. -2. Click **Create Stack**. -3. Name it, `acme-blog` and select **Swarm Services** mode. -4. Paste the YAML code below. -5. Click **Create**, and when enabled, click **Done**. - -``` -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" -``` - -### Test access - -Log on to the Docker EE UI as each user and ensure that -- `dba` (alex) can only see and access `mysql-collection` -- `dev` (bett) can only see and access `wordpress-collection` -- `ops` (chad) can see and access both. - - For example: - - ![image](../images/rbac-howto-wpress-mysql-dba-30.png){: .with-border} - - -{% elsif include.version=="ucp-2.2" %} - -## Swarm Stack - -In this section, we deploy `acme-blog` as a Swarm stack of two services. - -You are the UCP admin at Acme Company and need to secure access to `acme-blog` -and its component services, Wordpress and MySQL. The best way to do this is to: - -- Add teams and users -- Create collections (directories) for storing the resources of each component. -- Create grants that specify which team can do what operations on which collection. -- Give the all-clear for the ops team to deploy the blog. - -### 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 -``` -See: [Create and configure users and teams](./usermgmt-create-subjects.md). - -### Create collection paths - -Create three nested Swarm collections. First, create a collection for -`acme-blog` in the `Shared` collection and then nest collections for wordpress -and mysql resources: - -``` -/ -├── System -└── Shared -   └── acme-blog - ├── wordpress-collection -   └── mysql-collection -``` - -> **Tip**: To drill into a collection, click **View Children**. - -See [Group and isolate cluster resources](./resources-group-resources.md) - -### Grant roles - -Create three grants with built-in roles: - -- acme-datacenter/ops + Full Control + /Shared/acme-blog -- acme-datacenter/dev + Full Control + /Shared/acme-blog/wordpress-collection -- acme-datacenter/dba + Full Control + /Shared/acme-blog/mysql-collection - -> In this exercise we use built-in roles but you can create custom ones too. - -See: [Grant access to cluster resources](./usermgmt-grant-permissions.md). - -### Deploy Wordpress and MySQL with Swarm - -You've configured UCP. The `ops` team can now deploy `acme-blog`: - -1. Click **Shared Resources** > **Stacks**. -2. Click **Create Stack**. -3. Name it, `acme-blog` and select **Services** mode. -4. Paste the YAML code below. -5. Click **Create**, and when enabled, click **Done**. - -``` -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" -``` - -### Test access - -Log on to UCP as each user and ensure that: -- `dba` (alex) can only see and access `mysql-collection` -- `dev` (bett) can only see and access `wordpress-collection` -- `ops` (chad) can see and access both. - - For example: - - ![image](../images/rbac-howto-wpress-mysql-dba-22.png){: .with-border} - -{% endif %} -{% endif %} diff --git a/deploy/rbac/index.md b/deploy/rbac/index.md index 4e86e9c375..ff412c952d 100644 --- a/deploy/rbac/index.md +++ b/deploy/rbac/index.md @@ -10,24 +10,25 @@ ui_tabs: - version: ucp-2.2 orlower: true next_steps: -- path: /deploy/rbac/basics-create-subjects/ +- path: /deploy/rbac/rbac-basics-create-subjects/ title: Create and configure users and teams -- path: /deploy/rbac/basics-define-roles/ +- path: /deploy/rbac/rbac-basics-define-roles/ title: Define roles with authorized API operations -- path: /deploy/rbac/basics-group-resources/ +- path: /deploy/rbac/rbac-basics-group-resources/ title: Group and isolate cluster resources -- path: /deploy/rbac/basics-grant-permissions/ +- path: /deploy/rbac/rbac-basics-grant-permissions/ title: Grant access to cluster resources --- {% if include.ui %} -Docker Univeral Control Plane (UCP), the UI for [Docker EE](https://www.docker.com/enterprise-edition), -lets you authorize users to view, edit, and use cluster resources by granting -role-based permissions against resource types. - {% if include.version=="ucp-3.0" %} +[Docker Univeral Control Plane (UCP)](https://docs.docker.com/datacenter/ucp/3.0/guides/), +the UI for [Docker EE](https://www.docker.com/enterprise-edition), lets you +authorize users to view, edit, and use cluster resources by granting role-based +permissions against resource types. + To authorize access to cluster resources across your organization, UCP administrators might take the following high-level steps: @@ -37,7 +38,7 @@ administrators might take the following high-level steps: - Group cluster **resources** into Swarm collections or Kubernetes namespaces. - Create **grants** by marrying subject + role + resource. -For a simple example, see _todo_ +For a simple example, see [Deploy stateless app with RBAC](./deploy/rbac/rbac-howto-deploy-stateless-app/). ## Subjects @@ -51,7 +52,7 @@ role that defines permitted operations against one or more resource types. - **Organization**: A group of teams that share a specific set of permissions, defined by the roles of the organization. -For more, see: [Create and configure users and teams](./basics-create-subjects.md) +For more, see: [Create and configure users and teams](./rbac-basics-create-subjects.md) ## Roles @@ -67,7 +68,7 @@ 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 resource they are accessing. -For more, see: [Define roles with authorized API operations](./basics-define-roles.md) +For more, see: [Define roles with authorized API operations](./rbac-basics-define-roles.md) ## Resources @@ -78,8 +79,6 @@ collections in UCP by both defining a directory path and moving resources into it. Or you can create the path in UCP and use *labels* in your YAML file to assign application resources to that path. -For an example, see _todo_ - > Resource types that can be placed into a Swarm collection include: Containers, > Networks, Nodes, Services, Secrets, and Volumes. @@ -93,7 +92,7 @@ namespaces _cannot be nested_. > Resource types that can be placed into a Kubernetes namespace include: Pods, > Deployments, NetworkPolcies, Nodes, Services, Secrets, and many more. -For more, see: [Group and isolate cluster resources](./basics-group-resources.md). +For more, see: [Group and isolate cluster resources](./rbac-basics-group-resources.md). ## Grants @@ -109,11 +108,16 @@ Only an administrator can manage grants, subjects, roles, and resources. > into directories or namespaces, define roles by selecting allowable operations, > and apply grants to users and teams. -For more, see: [Grant access to cluster resources](./basics-grant-permissions.md). +For more, see: [Grant access to cluster resources](./rbac-basics-grant-permissions.md). {% elsif include.version=="ucp-2.2" %} +[Docker Univeral Control Plane (UCP)](https://docs.docker.com/datacenter/ucp/2.2/guides/), +the UI for [Docker EE](https://www.docker.com/enterprise-edition), lets you +authorize users to view, edit, and use cluster resources by granting role-based +permissions against resource types. + To authorize access to cluster resources across your organization, UCP administrators might take the following high-level steps: @@ -135,7 +139,7 @@ role that defines permitted operations against one or more resource types. - **Organization**: A group of teams that share a specific set of permissions, defined by the roles of the organization. -For more, see: [Create and configure users and teams](./basics-create-subjects.md) +For more, see: [Create and configure users and teams](./rbac-basics-create-subjects.md) ## Roles @@ -151,7 +155,7 @@ 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 resource they are accessing. -For more, see: [Define roles with authorized API operations](./basics-define-roles.md) +For more, see: [Define roles with authorized API operations](./rbac-basics-define-roles.md) ## Resources @@ -162,12 +166,10 @@ collections in UCP by both defining a directory path and moving resources into it. Or you can create the path in UCP and use *labels* in your YAML file to assign application resources to that path. -For an example, see _todo_ - > Resource types that can be placed into a Swarm collection include: Containers, > Networks, Nodes, Services, Secrets, and Volumes. -For more, see: [Group and isolate cluster resources](./basics-group-resources.md). +For more, see: [Group and isolate cluster resources](./rbac-basics-group-resources.md). ## Grants @@ -183,7 +185,7 @@ Only an administrator can manage grants, subjects, roles, and resources. > into directories or namespaces, define roles by selecting allowable operations, > and apply grants to users and teams. -For more, see: [Grant access to cluster resources](./basics-grant-permissions.md). +For more, see: [Grant access to cluster resources](./rbac-basics-grant-permissions.md). ## Transition from UCP 2.1 access control diff --git a/deploy/rbac/basics-create-subjects.md b/deploy/rbac/rbac-basics-create-subjects.md similarity index 86% rename from deploy/rbac/basics-create-subjects.md rename to deploy/rbac/rbac-basics-create-subjects.md index 42a3fec5c3..5b55ad2a7c 100644 --- a/deploy/rbac/basics-create-subjects.md +++ b/deploy/rbac/rbac-basics-create-subjects.md @@ -10,15 +10,13 @@ ui_tabs: - version: ucp-2.2 orlower: true next_steps: -- path: /deploy/rbac/basics-sync-with-ldap/ +- path: /deploy/rbac/admin-sync-with-ldap/ title: Synchronize teams with LDAP -- path: /datacenter/ucp/2.2/guides/admin/configure/external-auth/ - title: Integrate with an LDAP Directory -- path: /deploy/rbac/basics-define-roles/ +- path: /deploy/rbac/rbac-basics-define-roles/ title: Define roles with authorized API operations -- path: /deploy/rbac/basics-group-resources/ +- path: /deploy/rbac/rbac-basics-group-resources/ title: Group and isolate cluster resources -- path: /deploy/rbac/basics-grant-permissions/ +- path: /deploy/rbac/rbac-basics-grant-permissions/ title: Grant access to cluster resources --- @@ -50,7 +48,7 @@ To use Docker EE's built-in authentication, you must [create users manually](#cr > 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](basics-sync-with-ldap.md) +> - [Synchronize users and teams with LDAP in the UI](admin-sync-with-ldap.md) > - [Integrate with an LDAP Directory](/datacenter/ucp/2.2/guides/admin/configure/external-auth/index.md). ## Build an organization architecture @@ -81,7 +79,7 @@ To create teams in the organization: - Click the team name and select **Actions** > **Add Users**. - Check the users to include and click **Add Users**. -> **Note**: To sync teams with groups in an LDAP server, see [Sync Teams with LDAP](./basics-sync-with-ldap). +> **Note**: To sync teams with groups in an LDAP server, see [Sync Teams with LDAP](./admin-sync-with-ldap). {% if include.version=="ucp-3.0" %} @@ -89,7 +87,7 @@ To create teams in the organization: ### Create users manually New users are assigned a default permission level so that they can access the -cluster. To extend a user's default permissions, add them to a team and [create grants](./basics-grant-permissions/). You can optionally grant them Docker EE +cluster. To extend a user's default permissions, add them to a team and [create grants](./rbac-basics-grant-permissions/). You can optionally grant them Docker EE administrator permissions. To manally create users in UCP: @@ -112,7 +110,7 @@ To manally create users in UCP: ### Create users manuallly New users are assigned a default permission level so that they can access the -cluster. To extend a user's default permissions, add them to a team and [create grants](/deploy/rbac/basics-grant-permissions/). You can optionally grant them Docker EE +cluster. To extend a user's default permissions, add them to a team and [create grants](/deploy/rbac/rbac-basics-grant-permissions/). You can optionally grant them Docker EE administrator permissions. To manally create users in UCP: diff --git a/deploy/rbac/basics-define-roles.md b/deploy/rbac/rbac-basics-define-roles.md similarity index 96% rename from deploy/rbac/basics-define-roles.md rename to deploy/rbac/rbac-basics-define-roles.md index 11e9c2667f..b134500ee3 100644 --- a/deploy/rbac/basics-define-roles.md +++ b/deploy/rbac/rbac-basics-define-roles.md @@ -10,9 +10,11 @@ ui_tabs: - version: ucp-2.2 orlower: true next_steps: -- path: /deploy/rbac/basics-create-subjects/ +- path: /deploy/rbac/rbac-basics-create-subjects/ title: Create and configure users and teams -- path: /deploy/rbac/basics-grant-permissions/ +- path: /deploy/rbac/rbac-basics-group-resources/ + title: Group and isolate cluster resources +- path: /deploy/rbac/rbac-basics-grant-permissions/ title: Grant access to cluster resources --- diff --git a/deploy/rbac/basics-grant-permissions.md b/deploy/rbac/rbac-basics-grant-permissions.md similarity index 100% rename from deploy/rbac/basics-grant-permissions.md rename to deploy/rbac/rbac-basics-grant-permissions.md diff --git a/deploy/rbac/basics-group-resources.md b/deploy/rbac/rbac-basics-group-resources.md similarity index 79% rename from deploy/rbac/basics-group-resources.md rename to deploy/rbac/rbac-basics-group-resources.md index fbde14d52b..bd1ede47ed 100644 --- a/deploy/rbac/basics-group-resources.md +++ b/deploy/rbac/rbac-basics-group-resources.md @@ -10,11 +10,11 @@ ui_tabs: - version: ucp-2.2 orlower: true next_steps: -- path: /deploy/rbac/basics-create-subjects/ +- path: /deploy/rbac/rbac-basics-create-subjects/ title: Create and configure users and teams -- path: /deploy/rbac/basics-define-roles/ - title: Create roles to authorize access -- path: /deploy/rbac/basics-grant-permissions/ +- path: /deploy/rbac/rbac-basics-define-roles/ + title: Define roles with authorized API operations +- path: /deploy/rbac/rbac-basics-grant-permissions/ title: Grant access to cluster resources --- @@ -34,6 +34,9 @@ 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. + ## Swarm collection A collection is a directory of grouped resources, such as services, containers, @@ -42,19 +45,20 @@ grants against directory branches. ![](../images/collections-and-resources.svg){: .with-border} -## Access label +### Access label Access to a collection is granted with a path defined in an access label. -For example, each user has a private collection (with default permisions) and -the path is `/Shared/Private/`. The private collection for user "hans" -would have the following 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`. -``` -com.docker.ucp.access.label = /Shared/Private/hans -``` +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. -## Nested collections +### Nested collections You can nest collections. If a user has a grant against a collection, the grant applies to all of its child collections. @@ -63,10 +67,7 @@ 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. -> **Note**: Permissions are concatenated from multiple roles into an "effective -> role". - -## Built-in collections +### Built-in collections Docker EE provides a number of built-in collections. @@ -78,21 +79,20 @@ Docker EE provides a number of built-in collections. | `/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). | - This diagram shows the `/System` and `/Shared` collections created by Docker EE. -User private collections are children of the `/Shared/private` collection. The -Docker EE administrator user created a `/prod` collection and a child +User private collections are children of the `/Shared/private` collection. Here, +the Docker EE administrator user created a `/prod` collection and a child collection, `/webserver`. ![](../images/collections-diagram.svg){: .with-border} -## Default collections +### Default collections 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 in the CLI without an access label, Docker EE automatically places the -resource in the user's default collection. +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/). @@ -108,19 +108,17 @@ set. > system, such as an adminitrator, might find it better to set custom labels for > each resource. -## Collections and labels +### 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. +types don't have editable labels, so you can't move them across collections. -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. +> Can edit labels: services, nodes, secrets, and configs +> Cannot edit labels: containers, networks, and volumes + +For editable resources, you can change the `com.docker.ucp.access.label` to move +resources to different collections. For example, you may need deploy resources +to a collection other than your default collection. The system uses the additional labels, `com.docker.ucp.collection.*`, to enable efficient resource lookups. By default, nodes have the @@ -136,7 +134,7 @@ 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 +### 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 @@ -165,7 +163,7 @@ 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](howto-isolate-notes.md). +permission, to the team. [Isolate swarm nodes to a specific team](./rbac-howto-isolate-nodes.md). {% elsif include.version=="ucp-2.2" %} @@ -178,19 +176,20 @@ grants against directory branches. ![](../images/collections-and-resources.svg){: .with-border} -## Access label +### Access label Access to a collection is granted with a path defined in an access label. -For example, each user has a private collection (with default permisions) and -the path is `/Shared/Private/`. The private collection for user "hans" -would have the following 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`. -``` -com.docker.ucp.access.label = /Shared/Private/hans -``` +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. -## Nested collections +### Nested collections You can nest collections. If a user has a grant against a collection, the grant applies to all of its child collections. @@ -199,10 +198,7 @@ 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. -> **Note**: Permissions are concatenated from multiple roles into an "effective -> role". - -## Built-in collections +### Built-in collections Docker EE provides a number of built-in collections. @@ -214,21 +210,20 @@ Docker EE provides a number of built-in collections. | `/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). | - This diagram shows the `/System` and `/Shared` collections created by Docker EE. -User private collections are children of the `/Shared/private` collection. The -Docker EE administrator user created a `/prod` collection and a child +User private collections are children of the `/Shared/private` collection. Here, +the Docker EE administrator user created a `/prod` collection and a child collection, `/webserver`. ![](../images/collections-diagram.svg){: .with-border} -## Default collections +### Default collections 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 in the CLI without an access label, Docker EE automatically places the -resource in the user's default collection. +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/). @@ -244,19 +239,17 @@ set. > system, such as an adminitrator, might find it better to set custom labels for > each resource. -## Collections and labels +### 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. +types don't have editable labels, so you can't move them across collections. -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. +> Can edit labels: services, nodes, secrets, and configs +> Cannot edit labels: containers, networks, and volumes + +For editable resources, you can change the `com.docker.ucp.access.label` to move +resources to different collections. For example, you may need deploy resources +to a collection other than your default collection. The system uses the additional labels, `com.docker.ucp.collection.*`, to enable efficient resource lookups. By default, nodes have the @@ -272,7 +265,7 @@ 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 +### 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 @@ -301,7 +294,7 @@ 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](howto-isolate-notes.md). +permission, to the team. [Isolate swarm nodes to a specific team](./rbac-howto-isolate-nodes.md). {% endif %} {% endif %} diff --git a/deploy/rbac/rbac-howto-deploy-stateless-app.md b/deploy/rbac/rbac-howto-deploy-stateless-app.md new file mode 100644 index 0000000000..b11a4c3329 --- /dev/null +++ b/deploy/rbac/rbac-howto-deploy-stateless-app.md @@ -0,0 +1,223 @@ +--- +title: Deploy a simple stateless app 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" %} + +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 or namespaces for storing resources. +- Create grants that specify which team can do what operations on which + collection or namespace. +- 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). + +## Kubernetes deployment + +In this section, we deploy `nginx` with Kubernetes. See [Swarm stack](#swarm-stack) +for the same exercise with Swarm. + +### Create namespace + +Create a namespace to logically store the nginx application: + +1. Click **Kubernetes** > **Namespaces**. +2. Paste the following manifest in the terminal window: + +``` +apiVersion: v1 +kind: Namespace +metadata: + name: nginx-namespace +``` + +2. Click **Create**. + + +### Grant roles + +Grant the ops team (and only the ops team) access to nginx-namespace with the +built-in role, **Full Control**. + +``` +acme-datacenter/ops + Full Control + nginx-namespace +``` + +### Deploy Nginx + +You've configured Docker EE. The `ops` team can now deploy `nginx`. + +1. Log on to UCP as chad (on the `ops`team). +2. Click **Kubernetes** > **Namespaces**. +3. Paste the following manifest in the terminal window and click **Create**. + +``` +apiVersion: apps/v1beta2 # for versions before 1.8.0 use apps/v1beta1 +kind: Deployment +metadata: + name: nginx-deployment +spec: + selector: + matchLabels: + app: nginx + replicas: 2 + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:1.7.9 + ports: + - containerPort: 80 +``` + +4. Log on to UCP as each user and ensure that: +- `dba` (alex) cannot see `nginx-namespace`. +- `dev` (bett) cannot see `nginx-namespace`. + + +## Swarm Stack + +In this section, we deploy `nginx` as a Swarm service. See [Kubernetes Deployment](#kubernetes-deployment) +for the same exercise with Swarm. + +### Create collection paths + +Create a collection for nginx resources, nested under the `/Shared` collection: + +``` +/ +├── System +└── Shared +   └── nginx-collection +``` + +> **Tip**: To drill into a collection, click **View Children**. + +See: [Group and isolate cluster resources](./resources-group-resources.md). + +### Grant roles + +Grant the ops team (and only the ops team) access to nginx-collection with the +built-in role, **Full Control**. + +``` +acme-datacenter/ops + Full Control + /Shared/nginx-collection +``` + +See: [Grant access to cluster resources](./usermgmt-grant-permissions.md). + +### Deploy Wordpress and MySQL with Swarm + +You've configured Docker EE. The `ops` team can now deploy an `nginx` Swarm +service. + +1. Log on to UCP as chad (on the `ops`team). +2. Click **Swarm** > **Services**. +3. Click **Create Stack**. +4. On the Details tab, enter: + - Name: `nginx-service` + - Image: nginx:latest +4. 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: + - `dba` (alex) cannot see `nginx-collection`. + - `dev` (bett) cannot see `nginx-collection`. + + +{% elsif include.version=="ucp-2.2" %} + +## Swarm Stack + +In this section, we deploy `nginx` as a Swarm service. See [Kubernetes Deployment](#kubernetes-deployment) +for the same exercise with Swarm. + +### Create collection paths + +Create a collection for nginx resources, nested under the `/Shared` collection: + +``` +/ +├── System +└── Shared +   └── nginx-collection +``` + +> **Tip**: To drill into a collection, click **View Children**. + +See: [Group and isolate cluster resources](./resources-group-resources.md). + +### Grant roles + +Grant the ops team (and only the ops team) access to nginx-collection with the +built-in role, **Full Control**. + +``` +acme-datacenter/ops + Full Control + /Shared/nginx-collection +``` + +See: [Grant access to cluster resources](./usermgmt-grant-permissions.md). + +### Deploy Wordpress and MySQL with Swarm + +You've configured Docker EE. The `ops` team can now deploy an `nginx` Swarm +service. + +1. Log on to UCP as chad (on the `ops`team). +2. Click **Swarm** > **Services**. +3. Click **Create Stack**. +4. On the Details tab, enter: + - Name: `nginx-service` + - Image: nginx:latest +4. 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: + - `dba` (alex) cannot see `nginx-collection`. + - `dev` (bett) cannot see `nginx-collection`. + +{% endif %} +{% endif %} diff --git a/deploy/rbac/howto-isolate-nodes.md b/deploy/rbac/rbac-howto-isolate-nodes.md similarity index 96% rename from deploy/rbac/howto-isolate-nodes.md rename to deploy/rbac/rbac-howto-isolate-nodes.md index e4b117ce18..3638181370 100644 --- a/deploy/rbac/howto-isolate-nodes.md +++ b/deploy/rbac/rbac-howto-isolate-nodes.md @@ -1,5 +1,5 @@ --- -title: Isolate swarm nodes to a specific team +title: Isolate Swarm nodes in Docker Advanced description: Create grants that limit access to nodes to specific teams. keywords: ucp, grant, role, permission, authentication redirect_from: @@ -9,6 +9,9 @@ ui_tabs: orhigher: true - version: ucp-2.2 orlower: true +next_steps: +- path: /deploy/rbac/rbac-howto-isolate-volumes/ + title: Isolate Volumes --- {% if include.ui %} @@ -177,12 +180,6 @@ 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" %} @@ -348,11 +345,5 @@ 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) - {% endif %} {% endif %} diff --git a/deploy/rbac/howto-isolate-volumes.md b/deploy/rbac/rbac-howto-isolate-volumes.md similarity index 50% rename from deploy/rbac/howto-isolate-volumes.md rename to deploy/rbac/rbac-howto-isolate-volumes.md index dc128055e3..59a61242d3 100644 --- a/deploy/rbac/howto-isolate-volumes.md +++ b/deploy/rbac/rbac-howto-isolate-volumes.md @@ -9,13 +9,14 @@ ui_tabs: orhigher: true - version: ucp-2.2 orlower: true +next_steps: +- path: /deploy/rbac/rbac-howto-isolate-nodes/ + title: Isolate Swarm nodes in Docker Advanced --- {% if include.ui %} -{% if include.version=="ucp-3.0" %} -This topic is under construction. -{% elsif include.version=="ucp-2.2" %} +{% if include.version=="ucp-3.0" %} In this example, two teams are granted access to volumes in two different resource collections. UCP access control prevents the teams from viewing and @@ -34,7 +35,7 @@ nodes. Navigate to the **Organizations & Teams** page to create two teams in your organization, named "Dev" and "Prod". Add a user who's not a UCP administrator to the Dev team, and add another non-admin user to the Prod team. -[Learn how to create and manage teams](create-and-manage-teams.md). +[Learn how to create and manage teams](./rbac-basics-create-subjects.md). ## Create resource collections @@ -104,9 +105,95 @@ created by the Dev and Prod users. ![](../images/isolate-volumes-4.png){: .with-border} -## Where to go next -- [Isolate swarm nodes to a specific team](howto-isolate-nodes.md) +{% elsif include.version=="ucp-2.2" %} + +In this example, two teams are granted access to volumes in two different +resource collections. UCP access control prevents the teams from viewing and +accessing each other's volumes, even though they may be located in the same +nodes. + +1. Create two teams. +2. Create two collections, one for either team. +3. Create grants to manage access to the collections. +4. Team members create volumes that are specific to their team. + +![](../images/isolate-volumes-diagram.svg){: .with-border} + +## Create two teams + +Navigate to the **Organizations & Teams** page to create two teams in your +organization, named "Dev" and "Prod". Add a user who's not a UCP administrator +to the Dev team, and add another non-admin user to the Prod team. +[Learn how to create and manage teams](./rbac-basics-create-subjects.md). + +## Create resource collections + +In this example, the Dev and Prod teams use two different volumes, which they +access through two corresponding resource collections. The collections are +placed under the `/Shared` collection. + +1. In the left pane, click **Collections** to show all of the resource + collections in the swarm. +2. Find the **/Shared** collection and click **View children**. +2. Click **Create collection** and name the new collection "dev-volumes". +3. Click **Create** to create the collection. +4. Click **Create collection** again, name the new collection "prod-volumes", + and click **Create**. + +## Create grants for controlling access to the new volumes + +In this example, the Dev team gets access to its volumes from a grant that +associates the team with the `/Shared/dev-volumes` collection, and the Prod +team gets access to its volumes from another grant that associates the team +with the `/Shared/prod-volumes` 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 **Shared** collection, click **View Children**. +4. In the list, find **/Shared/dev-volumes** and click **Select Collection**. +3. Click **Roles**, and in the dropdown, select **Restricted Control**. +4. Click **Subjects**, and under **Select subject type**, click **Organizations**. + In the dropdown, pick your organization, and in the **Team** dropdown, + select **Dev**. +5. Click **Create** to grant permissions to the Dev team. +6. Click **Create Grant** and repeat the previous steps for the **/Shared/prod-volumes** + collection and the Prod team. + +![](../images/isolate-volumes-1.png){: .with-border} + +With the collections and grants in place, users can sign in and create volumes +in their assigned collections. + +## Create a volume as a team member + +Team members have permission to create volumes in their assigned collection. + +1. Log in as one of the users on the Dev team. +2. Navigate to the **Volumes** page to view all of the volumes in the swarm + that the user can access. +2. Click **Create volume** and name the new volume "dev-data". +3. In the left pane, click **Collections**. The default collection appears. + At the top of the page, click **Shared**, find the **dev-volumes** + collection in the list, and click **Select Collection**. +4. Click **Create** to add the "dev-data" volume to the collection. +5. Log in as one of the users on the Prod team, and repeat the previous steps + to create a "prod-data" volume assigned to the `/Shared/prod-volumes` + collection. + +![](../images/isolate-volumes-2.png){: .with-border} + +Now you can see role-based access control in action for volumes. The user on +the Prod team can't see the Dev team's volumes, and if you log in again as a +user on the Dev team, you won't see the Prod team's volumes. + +![](../images/isolate-volumes-3.png){: .with-border} + +Sign in with a UCP administrator account, and you see all of the volumes +created by the Dev and Prod users. + +![](../images/isolate-volumes-4.png){: .with-border} {% endif %} {% endif %} diff --git a/deploy/rbac/howto-orcabank1-standard.md b/deploy/rbac/rbac-howto-orcabank1-standard.md similarity index 98% rename from deploy/rbac/howto-orcabank1-standard.md rename to deploy/rbac/rbac-howto-orcabank1-standard.md index a7052c319b..59e4bd729e 100644 --- a/deploy/rbac/howto-orcabank1-standard.md +++ b/deploy/rbac/rbac-howto-orcabank1-standard.md @@ -9,6 +9,9 @@ ui_tabs: orhigher: true - version: ucp-2.2 orlower: true +next_steps: +- path: /deploy/rbac/rbac-howto-orcabank1-advanced/ + title: Access control design with Docker EE Advanced --- {% if include.ui %} @@ -256,10 +259,6 @@ The `mobile` team is responsible for deploying their own application stack, minus the database tier that is managed by the `db` team. ![image](../images/design-access-control-adv-4.png){: .with-border} -{% endif %} - -## Where to go next - -- [Access control design with Docker EE Advanced](access-control-design-ee-advanced.md) {% endif %} +{% endif %} diff --git a/deploy/rbac/howto-orcabank2-advanced.md b/deploy/rbac/rbac-howto-orcabank2-advanced.md similarity index 98% rename from deploy/rbac/howto-orcabank2-advanced.md rename to deploy/rbac/rbac-howto-orcabank2-advanced.md index 701ada17d4..9c245439db 100644 --- a/deploy/rbac/howto-orcabank2-advanced.md +++ b/deploy/rbac/rbac-howto-orcabank2-advanced.md @@ -9,6 +9,9 @@ ui_tabs: orhigher: true - version: ucp-2.2 orlower: true +next_steps: +- path: /deploy/rbac/rbac-howto-orcabank1-standard/ + title: Access control design with Docker EE Standard --- {% if include.ui %} @@ -36,7 +39,9 @@ scheduling and access of applications with [Node Access Control](access-control- > can be placed in different collections so that resources can be scheduled and > isolated on disparate physical or virtual hardware resources. + {% if include.version=="ucp-3.0" %} + ## Team access requirements OrcaBank still has three application teams, `payments`, `mobile`, and `db` with