Update tutorial, Test format (#296)

_data/toc.yaml

@@ -311,7 +311,7 @@ guides:
       - path: /storage/storagedriver/vfs-driver/
         title: Use the VFS storage driver
 
-- sectiontitle: Administer role-based access control
+- sectiontitle: Configure user permissions
   section:
     - path: /deploy/access-control/
       title: Access control model overview
@@ -339,13 +339,13 @@ guides:
         title: Isolate volumes to specific teams
       - path: /deploy/access-control/deploy-view-only-service
         title: Deploy a service with view-only access
-    - sectiontitle: Examples
+    - sectiontitle: OrcaBank Tutorial
       section:
       - path: /deploy/access-control/access-control-design-ee-standard
         title: Orcabank tutorial 1
       - path: /deploy/access-control/access-control-design-ee-advanced
         title: Orcabank tutorial 2
-        
+
 - sectiontitle: Deploy your app in production
   section:
     - path: /deploy/

deploy/access-control/access-control-design-ee-advanced.md

@@ -12,31 +12,23 @@ ui_tabs:
 ---
 
 {% if include.ui %}
+Go through the [Docker Enterprise Standard tutorial](access-control-design-ee-standard.md),
+before continuing here with Docker Enterprise Advanced.
 
+In the first tutorial, the fictional company, OrcaBank, designed an architecture
+with role-based access control (RBAC) to meet their organization's security
+needs. They assigned multiple grants to fine-tune access to resources across
+collection boundaries on a single platform.
 
-{% if include.version=="ucp-3.0" %}
+In this tutorial, OrcaBank implements new and more stringent security
-This topic is under construction.
+requirements for production applications:
 
-{% elsif include.version=="ucp-2.2" %}
+First, OrcaBank adds staging zone to their deployment model. They will no longer
-The previous tutorial, [Access Control Design with Docker EE
+move developed appliciatons directly in to production. Instead, they will deploy
-Standard](access-control-design-ee-standard.md), explains how the fictional
+apps from their dev cluster to staging for testing, and then to production.
-company, OrcaBank, designed an architecture with role-based access control
-(RBAC) to fit the specific security needs of their organization. OrcaBank used
-the ability to assign multiple grants to control access to resources across
-collection boundaries.
-
-Go through the [first OrcaBank tutorial](access-control-design-ee-standard.md),
-before continuing.
-
-In this tutorial, OrcaBank implements their new stringent security requirements
-for production applications:
-
-First, OrcaBank adds a staging zone to their deployment model. They no longer
-move developed applications directly in to production. Instead, they deploy apps
-from their dev cluster to staging for testing, and then to production.
 
 Second, production applications are no longer permitted to share any physical
-infrastructure with non-production infrastructure. Here, OrcaBank segments the
+infrastructure with non-production infrastructure. OrcaBank segments the
 scheduling and access of applications with [Node Access Control](access-control-node.md).
 
 > [Node Access Control](access-control-node.md) is a feature of Docker EE
@@ -44,14 +36,15 @@ 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
 varying levels of segmentation between them.
 
-Their RBAC redesign organizes their UCP cluster into two top-level collections,
+Their RBAC redesign is going to organize their UCP cluster into two top-level
-staging and production, which are completely separate security zones on separate
+collections, staging and production, which are completely separate security
-physical infrastructure.
+zones on separate physical infrastructure.
 
 OrcaBank's four teams now have different needs in production and staging:
 
@@ -72,12 +65,12 @@ OrcaBank has decided to replace their custom `Ops` role with the built-in
 
 - `View Only` (default role) allows users to see but not edit all Swarm
   resources.
-- `View & Use Networks + Secrets` (custom role) enables users to connect to
+- `Full Control` (default role) allows users complete control of all collections
-  networks and use secrets used by `db` containers, but prevents them from
+  granted to them. They can also create containers without restriction but
-  seeing or impacting the `db` applications themselves.
+  cannot see the containers of other users.
-- `Full Control` (default role) allows users to view and edit volumes, networks,
+- `View & Use Networks + Secrets` (custom role) enables users to view/connect
-  and images. They can also create containers without restriction but cannot see
+  to networks and view/use secrets used by `db` containers, but prevents them
-  the containers of other users.
+  from seeing or impacting the `db` applications themselves.
 
 ![image](../images/design-access-control-adv-0.png){: .with-border}
 
@@ -117,8 +110,116 @@ The collection architecture now has the following tree representation:
 OrcaBank must now diversify their grants further to ensure the proper division
 of access.
 
-The payments and mobile applications teams will have three grants each--one for
+The `payments` and `mobile` application teams will have three grants each--one
-deploying to production, one for deploying to staging, and the same grant to
+for deploying to production, one for deploying to staging, and the same grant to
+access shared `db` networks and secrets.
+
+![image](../images/design-access-control-adv-grant-composition.png){: .with-border}
+
+## OrcaBank access architecture
+
+The resulting access architecture, desgined with Docker EE Advanced, provides
+physical segmentation between production and staging using node access control.
+
+Applications are scheduled only on UCP worker nodes in the dedicated application
+collection. And applications use shared resources across collection boundaries
+to access the databases in the `/prod/db` collection.
+
+![image](../images/design-access-control-adv-architecture.png){: .with-border}
+
+### DB team
+
+The OrcaBank `db` team is responsible for deploying and managing the full
+lifecycle of the databases that are in production. They have the full set of
+operations against all database resources.
+
+![image](../images/design-access-control-adv-db.png){: .with-border}
+
+### Mobile team
+
+The `mobile` team is responsible for deploying their full application stack in
+staging. In production they deploy their own applications but use the databases
+that are provided by the `db` team.
+
+![image](../images/design-access-control-adv-mobile.png){: .with-border}
+
+
+{% elsif include.version=="ucp-2.2" %}
+## Team access requirements
+
+OrcaBank still has three application teams, `payments`, `mobile`, and `db` with
+varying levels of segmentation between them.
+
+Their RBAC redesign is going to organize their UCP cluster into two top-level
+collections, staging and production, which are completely separate security
+zones on separate physical infrastructure.
+
+OrcaBank's four teams now have different needs in production and staging:
+
+- `security` should have view-only access to all applications in production (but
+  not staging).
+- `db` should have full access to all database applications and resources in
+  production (but not staging). See [DB Team](#db-team).
+- `mobile` should have full access to their Mobile applications in both
+  production and staging and limited access to shared `db` services. See
+  [Mobile Team](#mobile-team).
+- `payments` should have full access to their Payments applications in both
+  production and staging and limited access to shared `db` services.
+
+## Role composition
+
+OrcaBank has decided to replace their custom `Ops` role with the built-in
+`Full Control` role.
+
+- `View Only` (default role) allows users to see but not edit all Swarm
+  resources.
+- `Full Control` (default role) allows users complete control of all collections
+  granted to them. They can also create containers without restriction but
+  cannot see the containers of other users.
+- `View & Use Networks + Secrets` (custom role) enables users to view/connect
+  to networks and view/use secrets used by `db` containers, but prevents them
+  from seeing or impacting the `db` applications themselves.
+
+![image](../images/design-access-control-adv-0.png){: .with-border}
+
+## Collection architecture
+
+In the previous tutorial, OrcaBank created separate collections for each
+application team and nested them all under `/Shared`.
+
+To meet their new security requirements for production, OrcaBank is redesigning
+collections in two ways:
+
+- Adding collections for both the production and staging zones, and nesting a
+  set of application collections under each.
+- Segmenting nodes. Both the production and staging zones will have dedicated
+  nodes; and in production, each application will be on a dedicated node.
+
+The collection architecture now has the following tree representation:
+
+```
+/
+├── System
+├── Shared
+├── prod
+│   ├── mobile
+│   ├── payments
+│   └── db
+│       ├── mobile
+│       └── payments
+|
+└── staging
+    ├── mobile
+    └── payments
+```
+
+## Grant composition
+
+OrcaBank must now diversify their grants further to ensure the proper division
+of access.
+
+The `payments` and `mobile` application teams will have three grants each--one
+for deploying to production, one for deploying to staging, and the same grant to
 access shared `db` networks and secrets.
 
 ![image](../images/design-access-control-adv-grant-composition.png){: .with-border}

deploy/access-control/access-control-design-ee-standard.md

@@ -12,65 +12,62 @@ ui_tabs:
 ---
 
 {% if include.ui %}
-{% if include.version=="ucp-3.0" %}
-This topic is under construction.
-
-{% elsif include.version=="ucp-2.2" %}
-
 [Collections and grants](index.md) are strong tools that can be used to control
 access and visibility to resources in UCP.
 
-This tutorial describes a fictitious company named OrcaBank that is designing an
+This tutorial describes a fictitious company named OrcaBank that needs to
-architecture with role-based access control (RBAC) for their application
+configure an  architecture in UCP with role-based access control (RBAC) for
-engineering group.
+their application engineering group.
 
+
+{% if include.version=="ucp-3.0" %}
 ## Team access requirements
 
-OrcaBank has organized their application teams by specialty with each team
+OrcaBank reorganized their application teams by product with each team providing
-providing shared services to other applications. Developers do their own DevOps
+shared services as necessary. Developers at OrcaBank do their own DevOps and
-and deploy and manage the lifecycle of their applications.
+deploy and manage the lifecycle of their applications.
 
-OrcaBank has four teams with the following needs:
+OrcaBank has four teams with the following resource needs:
 
-- `security` should have view-only access to all applications in the swarm.
+- `security` should have view-only access to all applications in the cluster.
 - `db` should have full access to all database applications and resources. See
   [DB Team](#db-team).
-- `mobile` should have full access to their Mobile applications and limited
+- `mobile` should have full access to their mobile applications and limited
   access to shared `db` services. See [Mobile Team](#mobile-team).
-- `payments` should have full access to their Payments applications and limited
+- `payments` should have full access to their payments applications and limited
   access to shared `db` services.
 
 ## Role composition
 
-To assign the proper access, OrcaBank is configuring a combination of default
+To assign the proper access, OrcaBank is employing a combination of default
 and custom roles:
 
-- `View Only` (default role) allows users to see but not edit all Swarm
+- `View Only` (default role) allows users to see all resources (but not edit or use).
-  resources.
+- `Ops` (custom role) allows users to perform all operations against configs,
-- `View & Use Networks + Secrets` (custom role) enables users to connect to
+  containers, images, networks, nodes, secrets, services, and volumes.
-  networks and use secrets used by `db` containers, but prevents them from
+- `View & Use Networks + Secrets` (custom role) enables users to view/connect to
+  networks and view/use secrets used by `db` containers, but prevents them from
   seeing or impacting the `db` applications themselves.
-- `Ops` (custom role) allows users to do almost all operations against all types
+
-  of resources.
 
 ![image](../images/design-access-control-adv-0.png){: .with-border}
 
 ## Collection architecture
 
-OrcaBank is also creating collections that fit their team structure.
+OrcaBank is also creating collections of resources to mirror their team
+structure.
 
-In their case, all applications share the same physical resources, so all nodes
+Currently, all OrcaBank applications share the same physical resources, so all
-and applications are being put into collections that nest under the built-in
+nodes and applications are being configured in collections that nest under the
-collection, `/Shared`.
+built-in collection, `/Shared`.
+
+Other collections are also being created to enable shared `db` applications.
+
+> **Note:** For increased security with node-based isolation, use Docker
+> Enterprise Advanced.
 
 - `/Shared/mobile` hosts all Mobile applications and resources.
 - `/Shared/payments` hosts all Payments applications and resources.
-
-> For Secure multi-tenancy with node-based isolation, use Docker Enterprise
-> Advanced. We cover this scenario in the [next tutorial](#).
-
-Other collections were also created to enable shared `db` applications.
-
 - `/Shared/db` is a top-level collection for all `db` resources.
 - `/Shared/db/payments` is a collection of `db` resources for Payments applications.
 - `/Shared/db/mobile` is a collection of `db` resources for Mobile applications.
@@ -88,7 +85,6 @@ The collection architecture has the following tree representation:
         └── payments
 ```
 
-
 OrcaBank's [Grant composition](#grant-composition) ensures that their collection
 architecture gives the `db` team access to _all_ `db` resources and  restricts
 app teams to _shared_ `db` resources.
@@ -121,9 +117,9 @@ collection boundaries. By assigning multiple grants per team, the Mobile and
 Payments applications teams can connect to dedicated Database resources through
 a secure and controlled interface, leveraging Database networks and secrets.
 
-> Note: Because this is Docker Enterprise Standard, all resources are deployed
+> **Note:** In Docker Enterprise Standard, all resources are deployed across the
-> across the same group of UCP worker nodes. Node segmentation is provided in
+> same  group of UCP worker nodes. Node segmentation is provided in Docker
-> Docker Enterprise Advanced and discussed in the [next tutorial](#).
+> Enterprise Advanced and discussed in the [next tutorial](#).
 
 ![image](../images/design-access-control-adv-2.png){: .with-border}
 
@@ -142,9 +138,128 @@ minus the database tier that is managed by the `db` team.
 
 ![image](../images/design-access-control-adv-4.png){: .with-border}
 
+
+{% elsif include.version=="ucp-2.2" %}
+## Team access requirements
+
+OrcaBank reorganized their application teams by product with each team providing
+shared services as necessary. Developers at OrcaBank do their own DevOps and
+deploy and manage the lifecycle of their applications.
+
+OrcaBank has four teams with the following resource needs:
+
+- `security` should have view-only access to all applications in the cluster.
+- `db` should have full access to all database applications and resources. See
+  [DB Team](#db-team).
+- `mobile` should have full access to their mobile applications and limited
+  access to shared `db` services. See [Mobile Team](#mobile-team).
+- `payments` should have full access to their payments applications and limited
+  access to shared `db` services.
+
+## Role composition
+
+To assign the proper access, OrcaBank is employing a combination of default
+and custom roles:
+
+- `View Only` (default role) allows users to see all resources (but not edit or use).
+- `Ops` (custom role) allows users to perform all operations against configs,
+  containers, images, networks, nodes, secrets, services, and volumes.
+- `View & Use Networks + Secrets` (custom role) enables users to view/connect to
+  networks and view/use secrets used by `db` containers, but prevents them from
+  seeing or impacting the `db` applications themselves.
+
+
+![image](../images/design-access-control-adv-0.png){: .with-border}
+
+## Collection architecture
+
+OrcaBank is also creating collections of resources to mirror their team
+structure.
+
+Currently, all OrcaBank applications share the same physical resources, so all
+nodes and applications are being configured in collections that nest under the
+built-in collection, `/Shared`.
+
+Other collections are also being created to enable shared `db` applications.
+
+> **Note:** For increased security with node-based isolation, use Docker
+> Enterprise Advanced.
+
+- `/Shared/mobile` hosts all Mobile applications and resources.
+- `/Shared/payments` hosts all Payments applications and resources.
+- `/Shared/db` is a top-level collection for all `db` resources.
+- `/Shared/db/payments` is a collection of `db` resources for Payments applications.
+- `/Shared/db/mobile` is a collection of `db` resources for Mobile applications.
+
+The collection architecture has the following tree representation:
+
+```
+/
+├── System
+└── Shared
+    ├── mobile
+    ├── payments
+    └── db
+        ├── mobile
+        └── payments
+```
+
+OrcaBank's [Grant composition](#grant-composition) ensures that their collection
+architecture gives the `db` team access to _all_ `db` resources and  restricts
+app teams to _shared_ `db` resources.
+
+## LDAP/AD integration
+
+OrcaBank has standardized on LDAP for centralized authentication to help their
+identity team scale across all the platforms they manage.
+
+To implement LDAP authenticaiton in UCP, OrcaBank is using UCP's native LDAP/AD
+integration to map LDAP groups directly to UCP teams. Users can be added to or
+removed from UCP teams via LDAP which can be managed centrally by OrcaBank's
+identity team.
+
+The following grant composition shows how LDAP groups are mapped to UCP teams.
+
+## Grant composition
+
+OrcaBank is taking advantage of the flexibility in UCP's grant model by applying
+two grants to each application team. One grant allows each team to fully
+manage the apps in their own collection, and the second grant gives them the
+(limited) access they need to networks and secrets within the `db` collection.
+
+![image](../images/design-access-control-adv-1.png){: .with-border}
+
+## OrcaBank access architecture
+
+OrcaBank's resulting access architecture shows applications connecting across
+collection boundaries. By assigning multiple grants per team, the Mobile and
+Payments applications teams can connect to dedicated Database resources through
+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](#).
+
+![image](../images/design-access-control-adv-2.png){: .with-border}
+
+### DB team
+
+The `db` team is responsible for deploying and managing the full lifecycle
+of the databases used by the application teams. They can execute the full set of
+operations against all database resources.
+
+![image](../images/design-access-control-adv-3.png){: .with-border}
+
+### Mobile team
+
+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 %}

deploy/access-control/access-control-node.md

@@ -13,31 +13,36 @@ ui_tabs:
 
 {% if include.ui %}
 {% if include.version=="ucp-3.0" %}
-This topic is under construction.
+
+*Node access control* lets you segment scheduling and visibility by node. Node access control is available in [Docker EE Advanced](https://www.docker.com/pricing) with Swarm orchestration only.
 
 {% elsif include.version=="ucp-2.2" %}
 
-The ability to segment scheduling and visibility by node is called
+*Node access control* lets you segment scheduling and visibility by node. Node access control is available in [Docker EE Advanced](https://www.docker.com/pricing).
-*node access control* and is a feature of Docker EE Advanced. By default,
-all nodes that aren't infrastructure nodes (UCP & DTR nodes) belong to a
-built-in collection called `/Shared`. By default, all application workloads
-in the cluster will get scheduled on nodes in the `/Shared` collection. This
-includes users that are deploying in their private collections
-(`/Shared/Private/`) and in any other collections under `/Shared`. This is
-enabled by a built-in grant that grants every UCP user the `scheduler`
-capability against the `/Shared` collection.
 
-Node Access Control works by placing nodes in to custom collections outside of
+{% endif %}
-`/Shared`. If the `scheduler` capability is granted via a role to a user or
-group of users against a collection then they will be able to schedule
-containers and services on these nodes. In the following example, users with
-`scheduler` capability against `/collection1` will be able to schedule
-applications on those nodes.
 
-Note that in the directory these collections lie outside of the `/Shared`
+By default, non-infrastructure nodes (non-UCP & DTR nodes) belong to a built-in
-collection so users without grants will not have access to these collections
+collection called `/Shared`. All application workloads in the cluster are
-unless explicitly granted access. These users will only be able to deploy
+scheduled on nodes in the `/Shared` collection. This includes those deployed in
-applications on the built-in `/Shared` collection nodes.
+private collections (`/Shared/Private/`) or any other collection under
+`/Shared`.
+
+This setting is enabled by a built-in grant that assigns every UCP user the
+`scheduler` capability against the `/Shared` collection.
+
+Node Access Control works by placing nodes in custom collections (outside of
+`/Shared`). If a user or team is granted a role with the `scheduler` capability
+against a collection, then they can schedule containers and services on these
+nodes.
+
+In the following example, users with `scheduler` capability against
+`/collection1` can schedule applications on those nodes.
+
+Again, these collections lie outside of the `/Shared` collection so users
+without grants do not have access to these collections unless it is explicitly
+granted. These users can only deploy applications on the built-in `/Shared`
+collection nodes.
 
 ![image](../images/design-access-control-adv-custom-grant.png){: .with-border}
 
@@ -57,9 +62,8 @@ With the use of default collections, users, teams, and organizations can be
 constrained to what nodes and physical infrastructure they are capable of
 deploying on.
 
+
 ## Where to go next
 
 - [Isolate swarm nodes to a specific team](isolate-nodes-between-teams.md)
-
-{% endif %}
 {% endif %}

deploy/access-control/create-and-manage-teams.md

@@ -12,10 +12,6 @@ ui_tabs:
 ---
 
 {% if include.ui %}
-{% if include.version=="ucp-3.0" %}
-This topic is under construction.
-
-{% elsif include.version=="ucp-2.2" %}
 
 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.
@@ -127,5 +123,8 @@ the `Data Center Resources` collection.
 -  [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 %}

deploy/access-control/create-and-manage-users.md

@@ -17,7 +17,7 @@ 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).
+> [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
@@ -31,12 +31,12 @@ To create a new user in the UCP web UI:
 4. Click **Create**.
 5. [optional] Check "Is a Docker EE Admin".
 
-![](../images/create-users-1-ucp3.png){: .with-border}
-
 > Check `Is a Docker EE Admin` to grant a user permission to change the cluster
 > configuration and manage grants, roles, and collections.
 
-![](../images/create-users-2-ucp3.png){: .with-border}
+![](../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

deploy/access-control/deploy-view-only-service.md

@@ -1,5 +1,5 @@
 ---
-title: Deploy a service with view-only access across an organization
+title: Deploy a service and restrict access with RBAC
 description: Create a grant to control access to a service.
 keywords: ucp, grant, role, permission, authentication
 redirect_from:
@@ -13,38 +13,47 @@ ui_tabs:
 
 {% if include.ui %}
 {% if include.version=="ucp-3.0" %}
-This topic is under construction.
+## Deploy Kubernetes workload and restrict access
+This section is under construction.
 
 {% elsif include.version=="ucp-2.2" %}
+{% endif %}
+
+## Deploy Swarm service and restrict access
 
 In this example, your organization is granted access to a new resource
-collection that contains one service.
+collection that contains one Swarm service.
 
 1. Create an organization and a team.
 2. Create a collection for the view-only service.
-3. Create a grant to manage user access to the collection.
+3. Deploy a Swarm serivce.
+4. Create a grant to manage user access to the collection.
+
 
 ![](../images/view-only-access-diagram.svg)
 
-## Create an organization
+### Create an organization
 
-In this example, you create an organization and a team, and you add one user
+Create an organization with one team, and add one user who isn't an administrator
-who isn't an administrator to the team.
+to the team.
-[Learn how to create and manage teams](create-and-manage-teams.md).
 
 1.  Log in to UCP as an administrator.
 2.  Navigate to the **Organizations & Teams** page and click
-    **Create Organization**. Name the new organization "engineering" and
+    **Create Organization**. Name the new organization `engineering` and
     click **Create**.
-3.  Click **Create Team**, name the new team "Dev", and click **Create**.
+3.  Click **Create Team**, name the new team `Dev`, and click **Create**.
 3.  Add a non-admin user to the Dev team.
 
-## Create a collection for the service
+For more, see:
+- [Learn how to create and manage users](create-and-manage-users.md).
+- [Learn how to create and manage teams](create-and-manage-teams.md).
+
+### Create a collection for the service
 
 1.  Navigate to the **Collections** page to view all of the resource
     collections in the swarm.
 2.  Find the **Shared** collection and click **View children**.
-3.  Click **Create collection** and name the collection "View-only services".
+3.  Click **Create collection** and name the collection `View-only services`.
 4.  Click **Create** to create the collection.
 
 ![](../images/deploy-view-only-service-1.png)
@@ -52,15 +61,15 @@ who isn't an administrator to the team.
 The `/Shared/View-only services` collection is ready to use for access
 control.
 
-## Deploy a service
+### Deploy a service
 
 Currently, the new collection has no resources assigned to it. To access
 resources through this collection, deploy a new service and add it to the
 collection.
 
 1.  Navigate to the **Services** page and create a new service, named
-    "WordPress".
+    `WordPress`.
-2.  In the **Image** textbox, enter "wordpress:latest". This identifies the
+2.  In the **Image** textbox, enter `wordpress:latest`. This identifies the
     most recent WordPress image in the Docker Store.
 3.  In the left pane, click **Collection**. The **Swarm** collection appears.
 4.  Click **View children** to list all of the collections. In **Shared**,
@@ -73,12 +82,14 @@ collection.
 
 You're ready to create a grant for controlling access to the "WordPress" service.
 
-## Create a grant
+### Create a grant
 
 Currently, users who aren't administrators can't access the
 `/Shared/View-only services` collection. Create a grant to give the
 `engineering` organization view-only access.
 
+> A grant is made up of a *subject*, a *role*, and a *resource collection*. 
+
 1.  Navigate to the **Grants** page and click **Create Grant**.
 2.  In the left pane, click **Collections**, navigate to **/Shared/View-only services**,
     and click **Select Collection**.
@@ -91,7 +102,7 @@ Currently, users who aren't administrators can't access the
 
 Everything is in place to show role-based access control in action.
 
-## Verify the user's permissions
+### Verify the user's permissions
 
 Users in the `engineering` organization have view-only access to the
 `/Shared/View-only services` collection. You can confirm this by logging in
@@ -108,9 +119,7 @@ as a non-admin user in the organization and trying to delete the service.
     and select **Remove**. You get an error message, because the user
     doesn't have `Service Delete` access to the collection.
 
-## Where to go next
+### Where to go next
 
 - [Isolate volumes between two different teams](isolate-volumes-between-teams.md)
-
-{% endif %}
 {% endif %}

deploy/access-control/grant-permissions.md

@@ -12,21 +12,29 @@ ui_tabs:
 ---
 
 {% if include.ui %}
+UCP administrators can create *grants* to control how users and organizations
+access resources.
+
 {% if include.version=="ucp-3.0" %}
-This topic is under construction.
+## Kubernetes grants
+With Kubernetes orchestration, a grant is made up of a *subject*, a *role*, and a
+*namespace*.
+
+This section is under construction.
 
 {% elsif include.version=="ucp-2.2" %}
+{% endif %}
 
-If you're a UCP administrator, you can create *grants* to control how users
+## Swarm grants
-and organizations access swarm resources.
+With Swarm orchestration, a grant is made up of a *subject*, a *role*, and a
+*resource collection*.
 
 ![](../images/ucp-grant-model-0.svg){: .with-border}
 
-A grant is made up of a *subject*, a *role*, and a *resource collection*.
+A grant defines who (subject) has how much access (role) to a set of resources
-A grant defines who (subject) has how much access (role)
+(collection). Each grant is a 1:1:1 mapping of subject, role, collection. For
-to a set of resources (collection). Each grant is a 1:1:1 mapping of
+example, you can grant the "Prod Team" "Restricted Control" permissions for the
-subject, role, collection. For example, you can grant the "Prod Team"
+"/Production" collection.
-"Restricted Control" permissions for the "/Production" collection.
 
 The usual workflow for creating grants has four steps.
 
@@ -38,10 +46,10 @@ The usual workflow for creating grants has four steps.
 
 ![](../images/ucp-grant-model.svg){: .with-border}
 
-## Create a grant
+### Create a Swarm grant
 
-When you have your users, collections, and roles set up, you can create
+When you have your users, collections, and roles set up, you can create grants.
-grants. Administrators create grants on the **Manage Grants** page.
+Administrators create grants on the **Manage Grants** page.
 
 1.  Click **Create Grant**. All of the collections in the system are listed.
 2.  Click **Select** on the collection you want to grant access to.
@@ -51,8 +59,8 @@ grants. Administrators create grants on the **Manage Grants** page.
     organization or a team.
 5.  Select a user, team, or organization and click **Create**.
 
-By default, all new users are placed in the `docker-datacenter` organization.
+By default, all new users are placed in the `docker-datacenter` organization. If
-If you want to apply a grant to all UCP users, create a grant with the
+you want to apply a grant to all UCP users, create a grant with the
 `docker-datacenter` org as a subject.
 
 ## Where to go next
@@ -60,4 +68,3 @@ If you want to apply a grant to all UCP users, create a grant with the
 - [Isolate volumes between two different teams](isolate-volumes-between-teams.md)
 
 {% endif %}
-{% endif %}

deploy/access-control/index.md

@@ -23,29 +23,86 @@ next_steps:
 ---
 
 {% 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" %}
-This topic is under construction.
-With Docker Universal Control Plane, you can control who creates and edits
-resources, such as nodes, services, images, networks, and volumes. You can grant
-and manage permissions to enforce fine-grained access control as needed.
 
-## Grant access to Swarm resources
+UCP administrators can control who views, edits, and uses Swarm and Kubernetes
-This topic is under construction.
+resources. They can grant and manage permissions to enforce fine-grained access
+control as needed.
 
-## Grant access to Kubernetes resources
+## Grants
-This topic is under construction.
 
-## Transition from UCP 2.2 access control
+Grants define which users can access what resources. Grants are effectively
-This topic is under construction.
+Access Control Lists (ACLs), which, when grouped together, can provide
+comprehensive access policies for an entire organization.
+
+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
+
+A subject represents a user, team, or organization. A subject is granted a
+role that defines permitted operations against one or more resources.
+
+- **User**: A person authenticated by the authentication backend. Users can
+  belong to one or more teams and one or more organizations.
+- **Team**: A group of users that share permissions defined at the team level.
+  A team exists only as part of an organization, and all of its members
+  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,
+  defined by the roles of the organization.
+
+## Namespaces
+
+A namespace is ...
+
+## Roles
+
+Roles define what operations can be done by whom against which cluster
+resources. A role is a set of permitted operations against a resource 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 (in a granted namespace) but not update it.
+
+Most organizations use different roles to assign the right kind of access. A
+given team or user may have different roles provided to them depending on what
+resource they are accessing.
+
+You can build custom roles to meet your organizational needs or use the
+following built-in roles:
+
+- **View Only** - Users can see all cluster resources but not edit or use them.
+- **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).
 
 
 {% elsif include.version=="ucp-2.2" %}
-## Grant access to Swarm resources
 
-UCP administrators control how subjects (users, teams, organizations) access
+UCP administrators can control who views, edits, and uses resources such as
-resources (collections) by assigning role-based permissions with *grants*.
+nodes, services, images, networks, and volumes. They can grant and manage
+permissions to enforce fine-grained access control as needed.
 
-A grant is made up of a *subject*, *role*, and *resource collection*.
+
+## Grants
+Grants define which users can access what resources. Grants are effectively
+Access Control Lists (ACLs), which, when grouped together, can provide
+comprehensive access policies for an entire organization.
+
+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
@@ -58,7 +115,7 @@ users and teams.
 ## Subjects
 
 A subject represents a user, team, or organization. A subject is granted a
-role for a collection of resources.
+role that defines permitted operations against one or more resources.
 
 - **User**: A person authenticated by the authentication backend. Users can
   belong to one or more teams and one or more organizations.
@@ -69,37 +126,50 @@ role for a collection of resources.
 - **Organization**: A group of teams that share a specific set of permissions,
   defined by the roles of the organization.
 
+## Collections
+
+A collection is a group of resources that you define with labels and access by
+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
 
-A role is a set of permitted API operations that you can assign to a specific
+Roles define what operations can be done by whom against which cluster
-subject and collection by using a grant. UCP administrators view and manage
+resources. A role is a set of permitted operations against a resource that is
-roles by navigating to the **Roles** page.
+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 (in a granted collection) but not update it.
+
+Most organizations use different roles to assign the right kind of access. A
+given team or user may have different roles provided to them depending on what
+resource they are accessing.
+
+You can build custom roles to meet your organizational needs or use the following
+built-in roles:
+
+- **View Only** - Users can see all cluster resources but not edit or use them.
+- **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).
 
-## Resource collections
-
-Docker EE allows you to control access to cluster resources with *collections*.
-A collection is a group of resources that you access by specifying a
-directory-like path.
-
-Resources that can be placed into a collection include:
-
-- Physical or virtual nodes
-- Containers
-- Services
-- Networks
-- Volumes
-- Secrets
-- Application configs
 
 ## Collection architecture
 
-Grants define which users can access what resources. Grants are effectively
+Before grants can be implemented, collections must group resources in a way that
-Access Control Lists (ACLs), which, when grouped together, can provide
+makes sense for an organization.
-comprehensive access policies for an entire organization.
-
-Before grants can be implemented, collections must be defined and group
-resources in a way that makes sense for an organization.
 
 For example, consider an organization with two application teams, Mobile and
 Payments, which share cluster hardware resources but segregate access to their
@@ -126,49 +196,7 @@ prod (collection)
 > A subject that has access to any level in a collection hierarchy has the
 > same access to any collections below it.
 
-## Role composition
 
-Roles define what operations can be done against cluster resources. Most
-organizations use different roles to assign the right kind of access. A given
-team or user may have different roles provided to them depending on what
-resource they are accessing.
-
-UCP provides default roles and lets you build custom roles. For example, here,
-three different roles are used:
-
-- **Full Control** (default role) - Allows users to perform all operations
-  against cluster resources.
-- **View Only** (default role) - Allows users to see all cluster resources but
-  not edit or delete them.
-- **Dev** (custom role) - Allows users to view containers and run a shell inside
-  a container process (with `docker exec`) but not to view or edit any other
-  cluster resources.
-
-## Grant composition
-
-The following four grants define the access policy for the entire organization
-for this cluster. They tie together the collections that were created, the
-default and custom roles, and also teams of users that are in UCP.
-
-![image](../images/access-control-grant-composition.png){: .with-border}
-
-## Access architecture
-
-The resulting access architecture defined by these grants is depicted below.
-
-![image](../images/access-control-collection-architecture.png){: .with-border}
-
-There are four teams that are given access to cluster resources:
-
-- The `ops` team has `Full Control` against the entire `/prod` collection. It
-  can deploy, view, edit, and remove applications and application resources.
-- The `security` team has the `View Only` role. They can see, but not edit, all
-  resources in the `/prod` collection.
-- The `mobile` team has the `Dev` role against the `/prod/mobile` collection
-  only. This team can see and `exec` into their own applications, but not the
-  `payments` applications.
-- The `payments` team has the `Dev` role for the `/prod/payments` collection
-  only.
 
 ## Transition from UCP 2.1 access control
 

deploy/access-control/manage-access-with-collections.md

@@ -18,37 +18,35 @@ This topic is under construction.
 {% elsif include.version=="ucp-2.2" %}
 
 Docker EE enables controlling access to container resources by using
-*collections*. A collection is a group of swarm resources,
+*collections*. A collection is a group of swarm resources, like services,
-like services, containers, volumes, networks, and secrets.
+containers, volumes, networks, and secrets.
 
 ![](../images/collections-and-resources.svg){: .with-border}
 
-Access to collections goes through a directory structure that arranges a
+Access to collections goes through a directory structure that arranges a swarm's
-swarm's resources. To assign permissions, administrators create grants
+resources. To assign permissions, administrators create grants against directory
-against directory branches.
+branches.
 
 ## Directory paths define access to collections
 
-Access to collections is based on a directory-like structure.
+Access to collections is based on a directory-like structure. For example, the
-For example, the path to a user's default collection is
+path to a user's default collection is `/Shared/Private/<username>`. Every user
-`/Shared/Private/<username>`. Every user has a private collection that
+has a private collection that has the default permission specified by the UCP
-has the default permission specified by the UCP administrator.
+administrator.
 
-Each collection has an access label that identifies its path.
+Each collection has an access label that identifies its path. For example, the
-For example, the private collection for user "hans" has a label that looks
+private collection for user "hans" has a label that looks like this:
-like this:
 
 ```
 com.docker.ucp.access.label = /Shared/Private/hans
 ```
 
-You can nest collections. If a user has a grant against a collection,
+You can nest collections. If a user has a grant against a collection, the grant
-the grant applies to all of its child collections.
+applies to all of its child collections.
 
-For a child collection, or for a user who belongs to more than one team,
+For a child collection, or for a user who belongs to more than one team, the
-the system concatenates permissions from multiple roles into an
+system concatenates permissions from multiple roles into an "effective role" for
-"effective role" for the user, which specifies the operations that are
+the user, which specifies the operations that are allowed against the target.
-allowed against the target.
 
 ## Built-in collections