Review use of 'collection' and replace with 'resource set' where applicable (#464)

This commit is contained in:
Jim Galasyn 2018-01-23 14:43:21 -08:00
parent 5f361aac23
commit b8e546b49a
12 changed files with 99 additions and 78 deletions

View File

@ -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 |

View File

@ -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

View File

@ -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

View File

@ -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}

View File

@ -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 %}

View File

@ -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

View File

@ -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 %}

View File

@ -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 %}

View File

@ -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 %}

View File

@ -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.

View File

@ -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

View File

@ -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/