manage-cluster-permissions.html.md.erb

---
title: Managing Cluster Access and Permissions
owner: PKS
---

<strong><%= modified_date %></strong>

This topic describes how to grant Kubernetes cluster access and namespace permissions to users in <%= vars.product_full %>.

## <a id='overview'></a> Overview

<%= vars.product_short %> admin users can grant other users permissions to specific clusters
by using the PKS CLI and kubectl.

If you are an <%= vars.product_short %> admin user, you can do the following:

+ Grant user access to a cluster with a `ClusterRole` or a namespace within a cluster with a `Role`.
See [Grant Cluster Access to a User](#cluster-access-user) below.
+ Grant LDAP  or SAML group access to a cluster with a `ClusterRole` or a namespace within a cluster with a `Role`.
See [Grant Cluster Access to a Group](#cluster-access-group) below.

After you grant access, you must create a `ClusterRoleBinding` or a `RoleBinding` for the user you gave
access to the cluster.

For more information, see [RoleBinding and ClusterRoleBinding](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding) and [Default Roles and Role Bindings](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#default-roles-and-role-bindings) in the Kubernetes documentation.

## <a id='prerequisites'></a> Prerequisites

Before setting up cluster access for users in <%= vars.product_short %>, you must have the following:

* Access to an <%= vars.product_short %> admin user account. For information on how to create PKS admin users,
see [Managing Enterprise PKS Admin Users with UAA](manage-users.html).
* A PKS API fully qualified domain name (FQDN) of your PKS deployment.
* A LDAP or SAML identity provider configured by the operator in the <%= vars.product_tile %> tile.

## <a id='cluster-access-user'></a> Grant Cluster Access to a User

After the cluster admin grants cluster access to end users,
the Kubernetes end user can use the Kubernetes Command Line
Interface (kubectl) to connect to the cluster. End users can only do actions that are
permitted by the cluster admin. They cannot create, resize, or delete
clusters.

<p class='note'><strong>Note:</strong> Before you can grant cluster access to Kubernetes end users,
you must enable OpenID Connect (OIDC) by selecting
<strong>Enable UAA as OIDC provider
</strong> in <strong>Ops Manager Installation Dashboard</strong> > <strong>
  <%= vars.product_tile %> </strong> > <strong> Settings </strong> > <strong>UAA</strong>.
  After you enable OIDC, you must run <code>pks get-credentials</code>
  to update your existing kubeconfig file.</p>

The following diagram outlines the workflow to grant cluster access to a
user who belongs to an identity provider group:

<%# Edit the below file in Google Slides: https://docs.google.com/presentation/d/1ULHunAy-FNiY3NYlRnvmydHJE6QtBpvlO4j-9PBoYTE/edit?usp=sharing %>
<a href="images/enterprise-id.png" target="_blank"><img src="images/enterprise-id.png" alt="This diagram shows the workflow that operators and cluster admins use to grant cluster access to users."></a>

To grant cluster access to users, do the following:

1. Log in to PKS by running following command:

    ```
    pks login -u USERNAME -p PASSWORD -a PKS-API --ca-cert CERT-PATH
    ```
    Where:
    * `USERNAME` is your cluster admin username.
    This is the username created for your organization's LDAP or SAML identity provider.
    * `PASSWORD` is your cluster admin password.
    * `PKS-API` is the FQDN you use to access the PKS API.
    * `CERT-PATH` is the path to your root CA certificate.
    Provide the certificate to validate the PKS API certificate with SSL.   
    
    <%= partial "saml-sso-login" %>

1. Confirm that you can successfully connect to a cluster and use
kubectl as a cluster admin by running the following command:

    ```
    pks get-credentials CLUSTER-NAME
    ```
    This step creates a `ClusterRoleBinding` for the cluster admin.
    
    <%= partial "saml-sso-login" %>

1. When prompted, re-enter your password.

1. Create a YAML file with either the `Role` or `ClusterRole` for your Kubernetes end user.
Use the following example as a template:

    ```
    kind: ROLE-TYPE
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      namespace: NAMESPACE
      name: ROLE-OR-CLUSTER-ROLE-NAME
    rules:
    - apiGroups:
      resources: RESOURCE
      verbs: API-REQUEST-VERB
    ```
    Where:
    * `ROLE-TYPE` is the type of role you are creating. This must be either `Role` or `ClusterRole`.
    * `NAMESPACE` is the namespace within the cluster. This is omitted when creating a `ClusterRole`.
    * `ROLE-OR-CLUSTER-ROLE-NAME` is the name of the `Role` or `ClusterRole` you are creating.
    This name is created by the cluster admin.
    * `RESOURCE` is the resource you are granting access to.
    It must be specified in a comma-separated array. For example: `["pod-reader"]`
    * `API-REQUEST-VERB` is the request verb used to specify resource requests. For more information, see
	 [Determine the Request Verb](https://kubernetes.io/docs/reference/access-authn-authz/authorization/#determine-the-request-verb) in the Kubernetes documentation.

1. Create the `Role` or `ClusterRole` resource defined in your YAML file by running the following command:

    ```
    kubectl create -f ROLE-CONFIGURATION.yml
    ```

    Where `ROLE-CONFIGURATION.yml` is the YAML file you created in the above step.

1. Create a YAML file containing either a `ClusterRoleBinding` or a `RoleBinding`
for the Kubernetes end user.
Use the following example as a template:

    ```
    kind: ROLE-BINDING-TYPE
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      name: ROLE-OR-CLUSTER-ROLE-BINDING-NAME
      namespace: NAMESPACE
    subjects:
    - kind: User
      name: USERNAME
      apiGroup: rbac.authorization.k8s.io
    roleRef:
      kind: ROLE-TYPE
      name: ROLE-OR-CLUSTER-ROLE-BINDING-NAME
      apiGroup: rbac.authorization.k8s.io
    ```
    Where:
    * `ROLE-BINDING-TYPE` is the type of role binding you are creating.
    This must be either `RoleBinding` or `ClusterRoleBinding`.
    * `ROLE-OR-CLUSTER-ROLE-BINDING-NAME` is the name of the role binding.
    This is given by the cluster admin.
    * `NAMESPACE` is the namespace within the cluster.
    This is omitted when creating a `ClusterRole`.
    * `USERNAME` is the Kubernetes end user username.
    This is the username created for your organization's LDAP or SAML identity provider.  <br>If you configured 
    **UAA OIDC Username Prefix** in **Ops Manager Installation Dashboard** > **Enterprise PKS** > **Settings** 
    > **UAA**, you must prepend `USERNAME` with the prefix you configured. For more information, see [UAA](./installing-pks-vsphere.html#uaa) in the _Installing_ topic for your IaaS.
    * `ROLE-TYPE` is the type of role you created in the previous step.
    This must be either `Role` or `ClusterRole`.
    * `ROLE-OR-CLUSTER-ROLE-NAME` is the name of the `Role` or `ClusterRole` you are creating.

1. Create the `RoleBinding` or `ClusterRoleBinding` resource defined
in your YAML file by running following command:

    ```
    kubectl apply -f ROLE-BINDING-CONFIGURATION.yml
    ```
    Where `ROLE-BINDING-CONFIGURATION.yml` is the YAML file you created in the above step.

1. Share the following information with your Kubernetes end users:
  - PKS API FQDN
  - Cluster name

## <a id='obtain-cluster-access'></a> Obtain Cluster Access as a User

To obtain cluster access, the end user must perform the following actions:

1. Fetch the kubeconfig file by running one of the following command:
      + If you want to validate the PKS API certificate with SSL, run the following command:

          ```
        pks get-kubeconfig CLUSTER-NAME -u USERNAME -a PKS-API --ca-cert CERT-PATH
          ```
          Where:
          * `CLUSTER-NAME` is the cluster name provided by the cluster admin.
          * `USERNAME` is the Kubernetes end user username.
            This is the username created for your organization's LDAP or SAML identity provider.
          * `PKS-API` is the FQDN you use to access the PKS API.
          * `CERT-PATH` is the path to your root CA certificate.
          Provide the certificate to validate the PKS API certificate with SSL.

          For example:
          <pre class="terminal">$ pks get-kubeconfig my-cluster -u naomi -a api.pks.example.com \
          --ca-cert /var/tempest/workspaces/default/root_ca_certificate</pre>
      + If your CA is trusted and you want to skip SSL validation, run the following command:

          ```
        pks get-kubeconfig CLUSTER-NAME -u USERNAME -a PKS-API -k
          ```
          Where `-k` is the shortcut flag to skip SSL validation.

          For example:
          <pre class="terminal">$ pks get-kubeconfig my-cluster -u naomi -a api.pks.example.com -k</pre>  
          
    <%= partial "saml-sso-login" %>

1. When prompted, enter your password.

1. The PKS CLI generates a kubeconfig for the cluster you have access to.
  Review the following example kubeconfig file:

    ```
    apiVersion: v1
    clusters:
    - cluster:
        certificate-authority-data: PROVIDED-BY-ADMIN
        server: PROVIDED-BY-ADMIN
      name: PROVIDED-BY-ADMIN
    contexts:
    - context:
        cluster: PROVIDED-BY-ADMIN
        user: PROVIDED-BY-USER
      name:  PROVIDED-BY-ADMIN
    current-context: PROVIDED-BY-ADMIN
    kind: Config
    preferences: {}
    users:
    - name: PROVIDED-BY-USER
      user:
        auth-provider:
          config:
            client-id: pks_cluster_client
            cluster_client_secret: ""
            id-token: PROVIDED-BY-USER
            idp-issuer-url: https://PROVIDED-BY-ADMIN:8443/oauth/token
            refresh-token:  PROVIDED-BY-USER
          name: oidc
    ```

1. Access the cluster using kubectl. For more information about kubectl commands,
see [Overview of kubectl](https://kubernetes.io/docs/reference/kubectl/overview/)
in the Kubernetes documentation.

## <a id='cluster-access-group'></a> Grant Cluster Access to a Group

Cluster admins can grant access to an identity provider group by creating a `ClusterRoleBinding` or
`RoleBinding` for that  group. You can only grant access to an identity provider group
if you use a LDAP or SAML identity provider for UAA.
You can configure a LDAP or SAML identity provider in
<strong>Ops Manager Installation Dashboard</strong> >
<strong> <%= vars.product_tile %> </strong> > <strong> Settings </strong> > <strong>UAA</strong>.

<p class='note'><strong>Note:</strong> If you are using a LDAP group,
  you must confirm that the LDAP group you are
  giving access to has been whitelisted in the
  <%= vars.product_tile %> tile.
  To do this, review <strong>External Groups Whitelist</strong> in
  <strong>Ops Manager Installation Dashboard</strong> > <strong>
    <%= vars.product_tile %> </strong> > <strong> Settings </strong> > <strong>UAA</strong>.</p>

The procedure for granting cluster access to an identity provider group is similar to the
procedure in [Grant Cluster Access to a User](#cluster-access-user) above.

To grant cluster access to an identity provider group,
do the procedure in [Grant Cluster Access to a User](#cluster-access-user) above
and replace step 6 with the following:

1. In the YAML file for a `ClusterRoleBinding` or a `RoleBinding`, replace the `subjects` section
with the following:

    ```
    subjects:
    - kind: Group
      name: NAME-OF-GROUP
      apiGroup: rbac.authorization.k8s.io
    ```

    Use the following example as a template:

    ```
    kind: ROLE-BINDING-TYPE
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      name: ROLE-OR-CLUSTER-ROLE-BINDING-NAME
      namespace: NAMESPACE
    subjects:
    - kind: Group
      name: NAME-OF-GROUP
      apiGroup: rbac.authorization.k8s.io
    roleRef:
      kind: ROLE-TYPE
      name: ROLE-OR-CLUSTER-ROLE-BINDING-NAME
      apiGroup: rbac.authorization.k8s.io
    ```

    Where:
    * `ROLE-BINDING-TYPE` is the type of role binding you are creating. This must be either `RoleBinding` or `ClusterRoleBinding`.
    * `ROLE-OR-CLUSTER-ROLE-BINDING-NAME` is the name of the role binding. This is given by the cluster admin.
    * `NAMESPACE` is the namespace within the cluster. This is omitted when creating a `ClusterRole`.
    * `NAME-OF-GROUP` is the identity provider group name. This name is case sensitive. <br>If you configured 
    **UAA OIDC Groups Prefix** in **Ops Manager Installation Dashboard** > **Enterprise PKS** > **Settings** 
    > **UAA**, you must prepend `NAME-OF-GROUP` with the prefix you configured. For more information, see [UAA](./installing-pks-vsphere.html#uaa) in the _Installing_ topic for your IaaS.
    * `ROLE-TYPE` is the type of role you created in the previous step.
    This must be either `Role` or `ClusterRole`.
    * `ROLE-OR-CLUSTER-ROLE-NAME` is the name of the `Role` or `ClusterRole` you are creating.