diff --git a/ee/ucp/authorization/grant-permissions.md b/ee/ucp/authorization/grant-permissions.md index 148fc6d119..6253b3a8f1 100644 --- a/ee/ucp/authorization/grant-permissions.md +++ b/ee/ucp/authorization/grant-permissions.md @@ -25,7 +25,7 @@ collection. A common workflow for creating grants has four steps: -- Add and configure **subjects** (users and teams). +- Add and configure **subjects** (users, teams, and service accounts). - Define custom **roles** (or use defaults) by adding permitted API operations per type of resource. - Group cluster **resources** into Swarm collections or Kubernetes namespaces. @@ -38,21 +38,19 @@ With Kubernetes orchestration, a grant is made up of *subject*, *role*, and > This section assumes that you have created objects for the grant: subject, role, > namespace. +{: .important} To create a Kubernetes grant in UCP: 1. Click **Grants** under **User Management**. 2. Click **Create Grant**. 3. Click **Namespaces** under **Kubernetes**. -4. Click **View Children** until you get to the desired namespace and **Select**. +4. Find the desired namespace and click **Select Namespace**. 5. On the **Roles** tab, select a role. -6. On the **Subjects** tab, select a user, team, or organization to authorize. +6. On the **Subjects** tab, select a user, team, organization, or service + account to authorize. 7. Click **Create**. -> By default, all new users are placed in the `docker-datacenter` organization. -> To apply permissions to all Docker EE users, create a grant with the -> `docker-datacenter` org as a subject. - ## Swarm grants With Swarm orchestration, a grant is made up of *subject*, *role*, and @@ -77,6 +75,7 @@ To create a grant in UCP: > By default, all new users are placed in the `docker-datacenter` organization. > To apply permissions to all Docker EE users, create a grant with the > `docker-datacenter` org as a subject. +{: .important} {% elsif include.version=="ucp-2.2" %} diff --git a/ee/ucp/authorization/index.md b/ee/ucp/authorization/index.md index 115c23794f..10940131cf 100644 --- a/ee/ucp/authorization/index.md +++ b/ee/ucp/authorization/index.md @@ -27,18 +27,20 @@ permissions against resource sets. To authorize access to cluster resources across your organization, UCP administrators might take the following high-level steps: -- Add and configure **subjects** (users and teams). +- Add and configure **subjects** (users, teams, and service accounts). - Define custom **roles** (or use defaults) by adding permitted operations per type of resource. -- Group cluster **resources** into Swarm collections or Kubernetes namespaces. +- Group cluster **resources** into resource sets of Swarm collections or + Kubernetes namespaces. - Create **grants** by combining subject + role + resource set. For an example, see [Deploy stateless app with RBAC](deploy-stateless-app.md). ## Subjects -A subject represents a user, team, or organization. A subject can be granted a -role that defines permitted operations against one or more resource sets. +A subject represents a user, team, organization, or service account. A subject +can be granted a role that defines permitted operations against one or more +resource sets. - **User**: A person authenticated by the authentication backend. Users can belong to one or more teams and one or more organizations. @@ -46,6 +48,8 @@ role that defines permitted operations against one or more resource sets. 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. +- **Service account**: A Kubernetes object that enables a workload to access + cluster resources that are assigned to a namespace. Learn to [create and configure users and teams](create-users-and-teams-manually.md). @@ -67,8 +71,8 @@ Learn to [define roles with authorized API operations](define-roles.md). ## Resource sets -To control user access, cluster resources are grouped into Docker Swarm *collections* -or Kubernetes *namespaces*. +To control user access, cluster resources are grouped into Docker Swarm +*collections* or Kubernetes *namespaces*. - **Swarm collections**: A collection has a directory-like structure that holds Swarm resources. You can create collections in UCP by defining a directory path @@ -105,6 +109,7 @@ resources. > 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. +{: .important} {% elsif include.version=="ucp-2.2" %} diff --git a/ee/ucp/images/create-service-account-1.png b/ee/ucp/images/create-service-account-1.png new file mode 100644 index 0000000000..889d0d3d07 Binary files /dev/null and b/ee/ucp/images/create-service-account-1.png differ diff --git a/ee/ucp/images/create-service-account-2.png b/ee/ucp/images/create-service-account-2.png new file mode 100644 index 0000000000..28287257d1 Binary files /dev/null and b/ee/ucp/images/create-service-account-2.png differ diff --git a/ee/ucp/images/create-service-account-3.png b/ee/ucp/images/create-service-account-3.png new file mode 100644 index 0000000000..e6b64f7852 Binary files /dev/null and b/ee/ucp/images/create-service-account-3.png differ diff --git a/ee/ucp/kubernetes/create-service-account.md b/ee/ucp/kubernetes/create-service-account.md new file mode 100644 index 0000000000..e9d81b20d6 --- /dev/null +++ b/ee/ucp/kubernetes/create-service-account.md @@ -0,0 +1,92 @@ +--- +title: Create a service account for a Kubernetes app +description: Learn how to use a service account to give a Kubernetes workload access to cluster resources. +keywords: UCP, Docker EE, Kubernetes, authorization, access control, grant +ui_tabs: +- version: ucp-3.0 + orlower: false +next_steps: +- path: deploy-ingress-controller/ + title: Deploy an ingress controller for a Kubernetes app +--- + +{% if include.version=="ucp-3.0" %} + +Kubernetes enables access control for workloads by providing service accounts. +A service account represents an identity for processes that run in a pod. +When a process is authenticated through a service account, it can contact the +API server and access cluster resources. If a pod doesn't have an assigned +service account, it gets the `default` service account. +Learn about [managing service accounts](https://v1-8.docs.kubernetes.io/docs/admin/service-accounts-admin/). + +In Docker EE, you give a service account access to cluster resources by +creating a grant, the same way that you would give access to a user or a team. +Learn how to [grant access to cluster resources](../authorization/index.md). + +In this example, you create a service account and a grant that could be used +for an NGINX server. + +## Create the Kubernetes namespace + +A Kubernetes user account is global, but a service account is scoped to a +namespace, so you need to create a namespace before you create a service +account. + +1. Navigate to the **Namespaces** page and click **Create**. +2. In the **Object YAML** editor, append the following text. + ```yaml + metadata: + name: nginx + ``` +3. Click **Create**. +4. In the **nginx** namespace, click the **More options** icon, + and in the context menu, select **Set Context**, and click **Confirm**. + + ![](../images/create-service-account-1.png){: .with-border} + +## Create a service account + +Create a service account named `nginx-service-account` in the `nginx` +namespace. + +1. Navigate to the **Service Accounts** page and click **Create**. +2. In the **Object YAML** editor, paste the following text. + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: nginx-service-account + ``` +3. Click **Create**. + + ![](../images/create-service-account-2.png){: .with-border} + +## Create a grant + +To give the service account access to cluster resources, create a grant with +`Restricted Control` permissions. + +1. Navigate to the **Grants** page and click **Create Grant**. +2. In the left pane, click **Resource Sets**, and in the **Type** section, + click **Namespaces**. +3. Select the **nginx** namespace. +4. In the left pane, click **Roles**. In the **Role** dropdown, select + **Restricted Control**. +5. In the left pane, click **Subjects**, and select **Service Account**. + + > Service account subject type + > + > The **Service Account** option in the **Subject Type** section appears only + > when a Kubernetes namespace is present. + {: .important} + +6. In the **Namespace** dropdown, select **nginx**, and in the + **Service Account** dropdown, select **nginx-service-account**. +7. Click **Create**. + + ![](../images/create-service-account-3.png){: .with-border} + +Now `nginx-service-account` has access to all cluster resources that are +assigned to the `nginx` namespace. + +{% endif %} \ No newline at end of file diff --git a/ee/ucp/kubernetes/deploy-ingress-controller.md b/ee/ucp/kubernetes/deploy-ingress-controller.md index f31453053d..58390de213 100644 --- a/ee/ucp/kubernetes/deploy-ingress-controller.md +++ b/ee/ucp/kubernetes/deploy-ingress-controller.md @@ -290,7 +290,7 @@ at `/` and serves 200 on the `/healthz` endpoint. > > It may take several seconds for the HTTP backend and the ingress controller's > `Deployment` and `ReplicaSet` objects to be scheduled. - { .important } + {: .important} ![](../images/deploy-ingress-controller-2.png){: .with-border}