[WIP] Create a service account for a Kubernetes app (#484)

* First draft of service account topic

* First draft of Kube service account topic

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

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

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

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}