From b8e546b49ac522055cca75d516c38f7efff30493 Mon Sep 17 00:00:00 2001 From: Jim Galasyn Date: Tue, 23 Jan 2018 14:43:21 -0800 Subject: [PATCH] Review use of 'collection' and replace with 'resource set' where applicable (#464) --- ee/ucp/admin/backups-and-disaster-recovery.md | 2 +- .../configure/add-labels-to-cluster-nodes.md | 5 +- .../admin/configure/ucp-configuration-file.md | 2 +- .../create-users-and-teams-manually.md | 2 +- ee/ucp/authorization/define-roles.md | 10 +-- ee/ucp/authorization/deploy-stateless-app.md | 41 ++++++----- ee/ucp/authorization/grant-permissions.md | 14 +++- ee/ucp/authorization/group-resources.md | 12 ++- ee/ucp/authorization/index.md | 73 ++++++++++--------- ee/ucp/authorization/isolate-nodes.md | 10 +-- .../authorization/migrate-kubernetes-roles.md | 2 +- .../services/deploy-stack-to-collection.md | 4 +- 12 files changed, 99 insertions(+), 78 deletions(-) diff --git a/ee/ucp/admin/backups-and-disaster-recovery.md b/ee/ucp/admin/backups-and-disaster-recovery.md index d3b3fa0c28..dfc93c3cf1 100644 --- a/ee/ucp/admin/backups-and-disaster-recovery.md +++ b/ee/ucp/admin/backups-and-disaster-recovery.md @@ -29,7 +29,7 @@ UCP maintains data about: | Data | Description | | :-------------------- | :------------------------------------------------------------------------------------------------------------------- | | Configurations | The UCP cluster configurations, as shown by `docker config ls`, including Docker EE license and swarm and client CAs | -| Access control | Permissions for teams to swarm resources, including collections, grants, and roles | +| Access control | Permissions for teams to cluster resources, including resource sets, grants, and roles | | Certificates and keys | The certificates, public keys, and private keys that are used for authentication and mutual TLS communication | | Metrics data | Monitoring data gathered by UCP | | Organizations | Your users, teams, and orgs | diff --git a/ee/ucp/admin/configure/add-labels-to-cluster-nodes.md b/ee/ucp/admin/configure/add-labels-to-cluster-nodes.md index 68d707cbc4..1019dcbfa0 100644 --- a/ee/ucp/admin/configure/add-labels-to-cluster-nodes.md +++ b/ee/ucp/admin/configure/add-labels-to-cluster-nodes.md @@ -25,8 +25,9 @@ lifecycle, or the hardware resources they have. ![](../../images/add-labels-to-cluster-nodes-1.svg) Don't create labels for authorization and permissions to resources. -Instead, use collections to organize access to your swarm. -[Learn about managing access with collections](../../authorization/group-resources.md). +Instead, use resource sets, either UCP collections or Kubernetes namespaces, +to organize access to your cluster. +[Learn about managing access with resource sets](../../authorization/group-resources.md). ## Apply labels to a node diff --git a/ee/ucp/admin/configure/ucp-configuration-file.md b/ee/ucp/admin/configure/ucp-configuration-file.md index 60ffae11fc..1ce41275c1 100644 --- a/ee/ucp/admin/configure/ucp-configuration-file.md +++ b/ee/ucp/admin/configure/ucp-configuration-file.md @@ -83,7 +83,7 @@ for modifying this config file. | Parameter | Required | Description | | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `backend` | no | The name of the authorization backend to use, either `managed` or `ldap`. The default is `managed`. | -| `default_new_user_role` | no | The role that new users get for their private collections. Values are `admin`, `viewonly`, `scheduler`, `restrictedcontrol`, or `fullcontrol`. The default is `restrictedcontrol`. | +| `default_new_user_role` | no | The role that new users get for their private resource sets. Values are `admin`, `viewonly`, `scheduler`, `restrictedcontrol`, or `fullcontrol`. The default is `restrictedcontrol`. | ## auth.sessions diff --git a/ee/ucp/authorization/create-users-and-teams-manually.md b/ee/ucp/authorization/create-users-and-teams-manually.md index 471e982807..47b5bf3b86 100644 --- a/ee/ucp/authorization/create-users-and-teams-manually.md +++ b/ee/ucp/authorization/create-users-and-teams-manually.md @@ -93,7 +93,7 @@ To manually create users in UCP: 5. [optional] Check "Is a Docker EE Admin". > A `Docker EE Admin` can grant users permission to change the cluster -> configuration and manage grants, roles, and collections. +> configuration and manage grants, roles, and resource sets. ![](../images/ucp_usermgmt_users_create01.png){: .with-border} ![](../images/ucp_usermgmt_users_create02.png){: .with-border} diff --git a/ee/ucp/authorization/define-roles.md b/ee/ucp/authorization/define-roles.md index e509f41fa9..c1a2172785 100644 --- a/ee/ucp/authorization/define-roles.md +++ b/ee/ucp/authorization/define-roles.md @@ -15,8 +15,8 @@ next_steps: --- {% if include.version=="ucp-3.0" %} -A role defines a set of API operations permitted against a group of resources. -Roles are applied to users and teams with grants. +A role defines a set of API operations permitted against a resource set. +You apply roles to users and teams by creating grants. ![Diagram showing UCP permission levels](../images/permissions-ucp.svg) @@ -40,7 +40,7 @@ organization. You can give a role a global name, such as "Remove Images", which might enable the **Remove** and **Force Remove** operations for images. You can apply a role with -the same name to different collections or namespaces. +the same name to different resource sets. 1. Click **Roles** under **User Management**. 2. Click **Create Role**. @@ -53,8 +53,8 @@ the same name to different collections or namespaces. > **Some important rules regarding roles**: > - Roles are always enabled. -> - Roles cannot be edited--they must be deleted and recreated. -> - Roles used within a grant can only be deleted after first deleting the grant. +> - Roles can't be edited. To edit a role, you must delete and recreate it. +> - Roles used within a grant can be deleted only after first deleting the grant. > - Only administrators can create and delete roles. {% endif %} diff --git a/ee/ucp/authorization/deploy-stateless-app.md b/ee/ucp/authorization/deploy-stateless-app.md index c79aeded2f..8af6522369 100644 --- a/ee/ucp/authorization/deploy-stateless-app.md +++ b/ee/ucp/authorization/deploy-stateless-app.md @@ -1,14 +1,14 @@ --- 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 +keywords: rbac, authorize, authentication, user, team, UCP, Kubernetes ui_tabs: - version: ucp-3.0 orhigher: false --- {% if include.version=="ucp-3.0" %} -This tutorial explains how to deploy a nginx web server and limit access to one +This tutorial explains how to deploy a NGINX web server and limit access to one team with role-based access control (RBAC). ## Scenario @@ -17,9 +17,10 @@ You are the Docker EE system administrator 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. -- Define roles with allowable operations per resource types (can run containers, etc.). -- Create collections or namespaces for storing actual resources. -- Create grants that join team + role + resources. +- Define roles with allowable operations per resource types, like + permission to run containers. +- Create collections or namespaces for accessing actual resources. +- Create grants that join team + role + resource set. ## Build the organization @@ -36,16 +37,16 @@ acme-datacenter   └── Chad Chavez ``` -See: [Create and configure users and teams](create-users-and-teams-manually.md). +Learn to [create and configure users and teams](create-users-and-teams-manually.md). ## Kubernetes deployment -In this section, we deploy `nginx` with Kubernetes. See [Swarm stack](#swarm-stack) +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: +Create a namespace to logically store the NGINX application: 1. Click **Kubernetes** > **Namespaces**. 2. Paste the following manifest in the terminal window and click **Create**. @@ -68,7 +69,7 @@ simple role for the ops team: 4. On the **Operations** tab, check all **Kubernetes Deployment Operations**. 5. Click **Create**. -See: [Create and configure users and teams](create-users-and-teams-manually.md). +Learn to [create and configure users and teams](create-users-and-teams-manually.md). ### Grant access @@ -79,11 +80,11 @@ custom role, **Kube Deploy**. acme-datacenter/ops + Kube Deploy + nginx-namespace ``` -### Deploy Nginx +### 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). +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**. @@ -110,17 +111,17 @@ spec: ``` 4. Log on to UCP as each user and ensure that: -- `dba` (alex) cannot see `nginx-namespace`. -- `dev` (bett) cannot see `nginx-namespace`. +- `dba` (alex) can't see `nginx-namespace`. +- `dev` (bett) can't 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. +for the same exercise with Kubernetes. ### Create collection paths -Create a collection for nginx resources, nested under the `/Shared` collection: +Create a collection for NGINX resources, nested under the `/Shared` collection: ``` / @@ -131,7 +132,7 @@ Create a collection for nginx resources, nested under the `/Shared` collection: > **Tip**: To drill into a collection, click **View Children**. -See: [Group and isolate cluster resources](group-resources.md). +Learn to [group and isolate cluster resources](group-resources.md). ### Define roles @@ -144,18 +145,18 @@ simple role for the ops team: 4. On the **Operations** tab, check all **Service Operations**. 5. Click **Create**. -See: [Create and configure users and teams](define-roles.md). +Learn to [create and configure users and teams](define-roles.md). ### Grant access -Grant the ops team (and only the ops team) access to nginx-collection with the -built-in role, **Swarm Deploy**. +Grant the ops team (and only the ops team) access to `nginx-collection` with +the built-in role, **Swarm Deploy**. ``` acme-datacenter/ops + Swarm Deploy + /Shared/nginx-collection ``` -See: [Grant role-access to cluster resources](grant-permissions.md). +Learn to [grant role-access to cluster resources](grant-permissions.md). ### Deploy NGINX diff --git a/ee/ucp/authorization/grant-permissions.md b/ee/ucp/authorization/grant-permissions.md index dd66fdead9..777a30f396 100644 --- a/ee/ucp/authorization/grant-permissions.md +++ b/ee/ucp/authorization/grant-permissions.md @@ -1,10 +1,12 @@ --- title: Grant role-access to cluster resources description: Learn how to grant users and teams access to cluster resources with role-based access control. -keywords: rbac, ucp, grant, role, permission, authentication, authorization, namespace +keywords: rbac, ucp, grant, role, permission, authentication, authorization, namespace, Kubernetes ui_tabs: - version: ucp-3.0 orhigher: false +- version: ucp-2.2 + orlower: false next_steps: - path: deploy-stateless-app/ title: Deploy a simple stateless app with RBAC @@ -17,7 +19,7 @@ Docker EE administrators can create _grants_ to control how users and organizations access resources. A grant defines _who_ has _how much_ access to _what_ resources. Each grant is a -1:1:1 mapping of _subject_, _role_, and _resource group_. For example, you can +1:1:1 mapping of _subject_, _role_, and _resource set_. For example, you can grant the "Prod Team" "Restricted Control" of services in the "/Production" collection. @@ -34,8 +36,8 @@ A common workflow for creating grants has four steps: With Kubernetes orchestration, a grant is made up of *subject*, *role*, and *namespace*. -> This section assumes that you have created objects to grant (subject, role, -> namespace). +> This section assumes that you have created objects for the grant: subject, role, +> namespace. To create a Kubernetes grant in UCP: @@ -76,4 +78,8 @@ To create a grant in UCP: > To apply permissions to all Docker EE users, create a grant with the > `docker-datacenter` org as a subject. +{% elsif include.version=="ucp-2.2" %} + +Learn to [grant permissions to users based on roles](/datacenter/ucp/2.2/guides/access-control/grant-permissions.md). + {% endif %} diff --git a/ee/ucp/authorization/group-resources.md b/ee/ucp/authorization/group-resources.md index 0008b4d3bd..6a38b87140 100644 --- a/ee/ucp/authorization/group-resources.md +++ b/ee/ucp/authorization/group-resources.md @@ -1,10 +1,12 @@ --- title: Group and isolate cluster resources -description: Learn how to group resources into collections or namespaces to control access. -keywords: rbac, ucp, grant, role, permission, authentication, resource collection, namespace +description: Learn how to group resources into collections or namespaces to control user access. +keywords: rbac, ucp, grant, role, permission, authentication, resource set, collection, namespace, Kubernetes ui_tabs: - version: ucp-3.0 orhigher: false +- version: ucp-2.2 + orlower: false next_steps: - path: create-users-and-teams-manually/ title: Create and configure users and teams @@ -21,7 +23,7 @@ redirect_from: A [namespace](https://v1-8.docs.kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) -is a logical area for a Kubernetes cluster. Kubernetes comes with a "default" +is a logical area for a Kubernetes cluster. Kubernetes comes with a `default` namespace for your cluster objects (plus two more for system and public resources). You can create custom namespaces, but unlike Swarm collections, namespaces _cannot be nested_. @@ -158,4 +160,8 @@ If you want to isolate nodes against other teams, place these nodes in new collections, and assign the `Scheduler` role, which contains the `Node Schedule` permission, to the team. [Isolate swarm nodes to a specific team](isolate-nodes.md). +{% elsif include.version=="ucp-2.2" %} + +Learn to [manage access to resources by using collections](/datacenter/ucp/2.2/guides/access-control/manage-access-with-collections.md). + {% endif %} diff --git a/ee/ucp/authorization/index.md b/ee/ucp/authorization/index.md index 7ab9709a30..f5bd4f15f1 100644 --- a/ee/ucp/authorization/index.md +++ b/ee/ucp/authorization/index.md @@ -1,10 +1,12 @@ --- title: Access control model description: Manage access to resources with role-based access control. -keywords: ucp, grant, role, permission, authentication, authorization +keywords: ucp, grant, role, permission, authentication, authorization, resource, namespace, Kubernetes ui_tabs: - version: ucp-3.0 - orlower: true + orlower: false +- version: ucp-2.2 + orlower: false next_steps: - path: create-users-and-teams-manually/ title: Create and configure users and teams @@ -29,7 +31,7 @@ administrators might take the following high-level steps: - Define custom **roles** (or use defaults) by adding permitted operations per resource types. - Group cluster **resources** into Swarm collections or Kubernetes namespaces. -- Create **grants** by marrying subject + role + resource group. +- Create **grants** by combining subject + role + resource group. For an example, see [Deploy stateless app with RBAC](deploy-stateless-app.md). @@ -45,62 +47,67 @@ 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](create-users-and-teams-manually.md) +Learn to [create and configure users and teams](create-users-and-teams-manually.md) ## Roles Roles define what operations can be done by whom. A role is a set of permitted -operations against a *resource type* (such as an image, container, volume) that -is assigned to a user or team with a grant. +operations against a *resource type*, like a container or volume, that's +assigned to a user or team with a grant. For example, the built-in role, **Restricted Control**, includes permission to view and schedule nodes but not to update nodes. A custom **DBA** role might -include permissions to r-w-x volumes and secrets. +include permissions to `r-w-x` volumes and secrets. Most organizations use multiple roles to fine-tune the appropriate 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](define-roles.md) +Learn to [define roles with authorized API operations](define-roles.md) -## Resources +## Resource sets -Cluster resources are grouped into Swarm collections or Kubernetes namespaces. +To control user access, cluster resources are grouped into Docker Swarm *collections* +or Kubernetes *namespaces*. -A collection is a directory that holds Swarm resources. You can create -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. +- **Swarm collections**: A collection has a directory-like structure that holds + Swarm resources. You can create collections in UCP by defining a directory path + and moving resources into it. Also, you can create the path in UCP and use + *labels* in your YAML file to assign application resources to the path. + Resource types that users can access in a Swarm collection include containers, + networks, nodes, services, secrets, and volumes. -> Resource types that can be placed into a Swarm collection include: Containers, -> Networks, Nodes, Services, Secrets, and Volumes. - -A +- **Kubernetes namespaces**: A [namespace](https://v1-8.docs.kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) -is a logical area for a Kubernetes cluster. Kubernetes comes with a "default" -namespace for your cluster objects (plus two more for system and public -resources). You can create custom namespaces, but unlike Swarm collections, -namespaces _cannot be nested_. + is a logical area for a Kubernetes cluster. Kubernetes comes with a `default` + namespace for your cluster objects, plus two more namespaces for system and + public resources. You can create custom namespaces, but unlike Swarm + collections, namespaces _can't be nested_. Resource types that users can + access in a Kubernetes namespace include pods, deployments, network policies, + nodes, services, secrets, and many more. -> Resource types that can be placed into a Kubernetes namespace include: Pods, -> Deployments, NetworkPolicies, Nodes, Services, Secrets, and many more. - -For more, see: [Group and isolate cluster resources](group-resources.md). +Together, collections and namespaces are named *resource sets*. Learn to +[group and isolate cluster resources](group-resources.md). ## Grants -A grant is made up of *subject*, *role*, and *resource group*. +A grant is made up of *subject*, *role*, and *resource set*. Grants define which users can access what resources in what way. Grants are -effectively Access Control Lists (ACLs), and when grouped together, can +effectively Access Control Lists (ACLs), and when grouped together, they provide comprehensive access policies for an entire organization. -Only an administrator can manage grants, subjects, roles, and resources. +Only an administrator can manage grants, subjects, roles, and access to +resources. -> Administrators are users who create subjects, group resources by moving them -> into directories or namespaces, define roles by selecting allowable operations, -> and apply grants to users and teams. +> About administrators +> +> An administrator is a user who creates subjects, groups resources by moving them +> into collections or namespaces, defines roles by selecting allowable operations, +> and applies grants to users and teams. -For more info, see: [Grant access to cluster resources](grant-permissions.md). +{% elsif include.version=="ucp-2.2" %} + +Learn about [access control model in UCP](/datacenter/ucp/2.2/guides/access-control/index.md). {% endif %} diff --git a/ee/ucp/authorization/isolate-nodes.md b/ee/ucp/authorization/isolate-nodes.md index bcd27aa800..0fcc194369 100644 --- a/ee/ucp/authorization/isolate-nodes.md +++ b/ee/ucp/authorization/isolate-nodes.md @@ -91,7 +91,7 @@ Move a worker node by changing the value of its access label key, ## Grant access for a team -You'll need two grants to control access to nodes and container resources: +You need two grants to control access to nodes and container resources: - Grant the `Ops` team the `Restricted Control` role for the `/Prod/Webserver` resources. @@ -129,8 +129,8 @@ The same steps apply for the nodes in the `/Prod` collection. The cluster is set up for node isolation. Users with access to nodes in the `/Prod` collection can deploy [Swarm services](#deploy-a-swarm-service-as-a-team-member) -and [Kubernetes apps](#deploy-a-kubernetes-application), and their workloads won't be scheduled -on nodes that aren't in the collection. +and [Kubernetes apps](#deploy-a-kubernetes-application), and their workloads +won't be scheduled on nodes that aren't in the collection. ## Deploy a Swarm service as a team member @@ -181,8 +181,8 @@ that has a `Service Create` grant for the user. ## Deploy a Kubernetes application -Starting in Docker EE Platform 2.0, you can deploy a Kubernetes workload to -worker nodes, based on a Kubernetes namespace. +Starting in Docker Enterprise Edition 2.0, you can deploy a Kubernetes workload +to worker nodes, based on a Kubernetes namespace. 1. Convert a node to use the Kubernetes orchestrator. 2. Create a Kubernetes namespace. diff --git a/ee/ucp/authorization/migrate-kubernetes-roles.md b/ee/ucp/authorization/migrate-kubernetes-roles.md index 09b00b477d..0b05ace49e 100644 --- a/ee/ucp/authorization/migrate-kubernetes-roles.md +++ b/ee/ucp/authorization/migrate-kubernetes-roles.md @@ -24,7 +24,7 @@ Learn about [UCP roles and grants](grant-permissions.md). > Kubernetes yaml in UCP > -> The Docker EE authorization system isn't compatible with the Kubernetes +> Docker EE has its own RBAC system that's distinct from the Kubernetes > system, so you can't create any objects that are returned by the > `/apis/rbac.authorization.k8s.io` endpoints. If the yaml for your Kubernetes > app contains definitions for `Role`, `ClusterRole`, `RoleBinding` or diff --git a/ee/ucp/user/services/deploy-stack-to-collection.md b/ee/ucp/user/services/deploy-stack-to-collection.md index 081e71203f..6a92e8c899 100644 --- a/ee/ucp/user/services/deploy-stack-to-collection.md +++ b/ee/ucp/user/services/deploy-stack-to-collection.md @@ -6,8 +6,8 @@ ui_tabs: - version: ucp-3.0 orlower: true next_steps: -- path: ../../authorization/ - title: Access control model +- path: deploy-compose-on-kubernetes/ + title: Deploy a Compose-based app to a Kubernetes cluster - path: /engine/reference/commandline/service_create/#set-metadata-on-a-service--l-label/ title: Set metadata on a service (-l, –label) - path: /engine/userguide/labels-custom-metadata/