Managing Cluster Access and Permissions
Page last updated:
This topic describes how to grant Kubernetes cluster access and namespace permissions to Kubernetes users in VMware Enterprise PKS.
Overview
Enterprise PKS admin users can grant Kubernetes users, such as developers, permissions to specific clusters.
If you are an Enterprise PKS admin user, you can do the following:
- Grant user access to a cluster with a
ClusterRole
or a namespace within a cluster with aRole
. See Grant Cluster Access to a User below. - Grant group access to a cluster with a
ClusterRole
or a namespace within a cluster with aRole
. See Grant Cluster Access to a Group below.
After you grant user or group access to an Enterprise PKS-provisioned cluster, Kubernetes users can connect to the cluster through the Kubernetes CLI (kubectl). Kubernetes users cannot create, resize, or delete clusters.
Example Workflow
The following diagram outlines the workflow to grant cluster access to users who belong to an identity provider group:
For more information, see RoleBinding and ClusterRoleBinding and Default Roles and Role Bindings in the Kubernetes documentation.
Prerequisites
Before setting up cluster access for users in Enterprise PKS, you must have the following:
- Access to an Enterprise PKS admin user account. For information about how to create Enterprise PKS admin users, see Managing Enterprise PKS Users with UAA.
- Fully qualified domain name (FQDN) of your PKS deployment.
- OpenID Connect (OIDC) provider for your Kubernetes clusters, configured using one or both of the following:
- Global OIDC provider configuration for all clusters in Ops Manager Installation Dashboard > Enterprise PKS > Settings > UAA > Configure created clusters to use UAA as the OIDC provider. For instructions, see UAA in the Installing topic for your IaaS.
- Custom OIDC provider configuration for individual clusters through a Kubernetes profile. For instructions, see Add an OIDC Provider.
Grant Cluster Access to a User
To grant cluster access to a user, do the following:
Log in to Enterprise 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.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.
Note: If your operator has configured Enterprise PKS to use a SAML identity provider, you must include an additional SSO flag to use the above command. For information about the SSO flags, see the section for the above command in PKS CLI. For information about configuring SAML, see Connecting Enterprise PKS to a SAML Identity Provider
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.Note: If your operator has configured Enterprise PKS to use a SAML identity provider, you must include an additional SSO flag to use the above command. For information about the SSO flags, see the section for the above command in PKS CLI. For information about configuring SAML, see Connecting Enterprise PKS to a SAML Identity Provider
When prompted, re-enter your password.
Create a YAML file for either
Role
orClusterRole
. 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 eitherRole
orClusterRole
.NAMESPACE
is the namespace within the cluster. This is omitted when creating aClusterRole
.ROLE-OR-CLUSTER-ROLE-NAME
is the name of theRole
orClusterRole
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 in the Kubernetes documentation.
Create the
Role
orClusterRole
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.Create a YAML file containing either a
ClusterRoleBinding
or aRoleBinding
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 eitherRoleBinding
orClusterRoleBinding
.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 aClusterRole
.USERNAME
is the Kubernetes end user username. This is the username created for your organization’s LDAP or SAML identity provider.Note: If you configured an OIDC username prefix in Ops Manager Installation Dashboard > Enterprise PKS > Settings > UAA or in a Kubernetes profile, you must prepend
USERNAME
with the prefix you configured. For more information, see UAA in the Installing topic for your IaaS and Add an OIDC Provider.ROLE-TYPE
is the type of role you created in the previous step. This must be eitherRole
orClusterRole
.ROLE-OR-CLUSTER-ROLE-NAME
is the name of theRole
orClusterRole
you created in the previous step.
Create the
RoleBinding
orClusterRoleBinding
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.Share the following information with your Kubernetes end users:
- PKS API FQDN
- Cluster name
Obtain Cluster Access as a User
To obtain access to a Enterprise PKS-provisioned cluster, the end user must do the following:
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:
$ pks get-kubeconfig my-cluster -u naomi -a api.pks.example.com \ --ca-cert /var/tempest/workspaces/default/root_ca_certificate
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:
$ pks get-kubeconfig my-cluster -u naomi -a api.pks.example.com -k
Note: If your operator has configured Enterprise PKS to use a SAML identity provider, you must include an additional SSO flag to use the above command. For information about the SSO flags, see the section for the above command in PKS CLI. For information about configuring SAML, see Connecting Enterprise PKS to a SAML Identity Provider
When prompted, enter your password.
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
Access the cluster using kubectl. For more information about kubectl commands, see Overview of kubectl in the Kubernetes documentation.
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 grant access to an identity provider group
only if you use a LDAP or SAML identity provider for UAA.
You can configure a LDAP or SAML identity provider in
Ops Manager Installation Dashboard >
Enterprise PKS > Settings > UAA.
Note: If you are using a LDAP group, you must confirm that the LDAP group you are giving access is in the allowlist in the Enterprise PKS tile. To do this, review External Groups Whitelist in Ops Manager Installation Dashboard > Enterprise PKS > Settings > UAA.
To grant cluster access to an identity provider group, do the procedure in Grant Cluster Access to a User above and replace step 6 with the following:
In the YAML file for a
ClusterRoleBinding
or aRoleBinding
, replace thesubjects
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-NAME apiGroup: rbac.authorization.k8s.io
Where:
ROLE-BINDING-TYPE
is the type of role binding you are creating. This must be eitherRoleBinding
orClusterRoleBinding
.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 aClusterRole
.NAME-OF-GROUP
is the identity provider group name. This name is case sensitive.Note: If you configured an OIDC groups prefix in Ops Manager Installation Dashboard > Enterprise PKS > Settings > UAA or in a Kubernetes profile, you must prepend
NAME-OF-GROUP
with the prefix you configured. For more information, see UAA in the Installing topic for your IaaS and Add an OIDC Provider.ROLE-TYPE
is the type of role you created in the previous step. This must be eitherRole
orClusterRole
.ROLE-OR-CLUSTER-ROLE-NAME
is the name of theRole
orClusterRole
you are binding the Group to.
Please send any feedback you have to pks-feedback@pivotal.io.