First draft of Kube rbac topic (#436)

_data/toc.yaml

@@ -1669,6 +1669,8 @@ manuals:
           title: Isolate volumes
         - path: /ee/ucp/authorization/isolate-nodes/
           title: Isolate nodes
+        - path: /ee/ucp/authorization/migrate-kubernetes-roles/
+          title: Migrate Kubernetes roles to Docker EE authorization
         - path: /ee/ucp/authorization/ee-standard/
           title: Docker EE Standard use case
         - path: /ee/ucp/authorization/ee-advanced/

ee/ucp/authorization/migrate-kubernetes-roles.md

@@ -0,0 +1,112 @@
+---
+title: Migrate Kubernetes roles to Docker EE authorization
+description: Learn how to transfer Kubernetes Role and RoleBinding objects to UCP roles and grants.
+keywords: authorization, authentication, authorize, authenticate, user, team, UCP, Kubernetes, role, grant
+ui_tabs:
+- version: ucp-3.0
+  orlower: false
+---
+{% if include.version=="ucp-3.0" %}
+
+With Docker Enterprise Edition, you can create roles and grants
+that implement the permissions that are defined in your Kubernetes apps.
+Learn about [RBAC authorization in Kubernetes](https://v1-8.docs.kubernetes.io/docs/admin/authorization/rbac/).
+
+Docker EE has its own implementation of role-based access control, so you
+can't use Kubernetes RBAC objects directly. Instead, you create UCP roles
+and grants that correspond with the role objects and bindings in your
+Kubernetes app.
+
+- Kubernetes `Role` and `ClusterRole` objects become UCP roles.
+- Kubernetes `RoleBinding` and `ClusterRoleBinding` objects become UCP grants.  
+
+Learn about [UCP roles and grants](grant-permissions.md).
+
+> Kubernetes yaml in UCP
+> 
+> The Docker EE authorization system isn't compatible with 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
+> `ClusterRoleBinding` objects, UCP returns an error.
+{: .important}
+
+## Migrate a Kubernetes Role to a custom UCP role
+
+If you have `Role` and `ClusterRole` objects defined in the yaml for your
+Kubernetes app, you can realize the same authorization model by creating
+custom roles by using the UCP web UI.
+
+The following Kubernetes yaml defines a `pod-reader` role, which gives users
+access to the read-only `pods` resource APIs, `get`, `watch`, and `list`.
+
+```yaml
+kind: Role
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  namespace: default
+  name: pod-reader
+rules:
+- apiGroups: [""]
+  resources: ["pods"]
+  verbs: ["get", "watch", "list"]
+```
+
+Create a corresponding custom role by using the **Create Role** page in the 
+UCP web UI.
+
+1.  Log in to the UCP web UI with an administrator account.
+2.  Click **Roles** under **User Management**.
+3.  Click **Create Role**.
+4.  In the **Role Details** section, name the role "pod-reader".
+5.  In the left pane, click **Operations**.
+6.  Scroll to the **Kubernetes pod operations** section and expand the
+    **All Kubernetes Pod operations** dropdown. 
+7.  Select the **Pod Get**, **Pod List**, and **Pod Watch** operations.
+    ![](../images/migrate-kubernetes-roles-1.png){: .with-border}
+8.  Click **Create**.
+
+The `pod-reader` role is ready to use in grants that control access to 
+cluster resources.
+
+## Migrate a Kubernetes RoleBinding to a UCP grant
+
+If your Kubernetes app defines `RoleBinding` or `ClusterRoleBinding`
+objects for specific users, create corresponding grants by using the UCP web UI.
+
+The following Kubernetes yaml defines a `RoleBinding` that grants user "jane"
+read-only access to pods in the `default` namespace.
+
+```yaml
+kind: RoleBinding
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: read-pods
+  namespace: default
+subjects:
+- kind: User
+  name: jane
+  apiGroup: rbac.authorization.k8s.io
+roleRef:
+  kind: Role
+  name: pod-reader
+  apiGroup: rbac.authorization.k8s.io
+```  
+
+Crate a corresponding grant by using the **Create Grant** page in the 
+UCP web UI.
+
+1.  Create a non-admin user named "jane". [Learn to create users and teams](create-users-and-teams-manually.md). 
+1.  Click **Grants** under **User Management**.
+2.  Click **Create Grant**.
+3.  In the **Type** section, click **Namespaces** and ensure that **default** is selected.
+4.  In the left pane, click **Roles**, and in the **Role** dropdown, select **pod-reader**.
+5.  In the left pane, click **Subjects**, and click **All Users**.
+6.  In the **Users** dropdown, select **jane**.
+7.  Click **Create**. 
+
+![](../images/migrate-kubernetes-roles-2.png){: .with-border}
+
+User "jane" has access to inspect pods in the `default` namespace.
+
+{% endif %}