Skip to content

Latest commit

 

History

History
416 lines (330 loc) · 28.2 KB

cs_users.md

File metadata and controls

416 lines (330 loc) · 28.2 KB
copyright lastupdated
years
2014, 2018
2018-03-23

{:new_window: target="_blank"} {:shortdesc: .shortdesc} {:screen: .screen} {:pre: .pre} {:table: .aria-labeledby="caption"} {:codeblock: .codeblock} {:tip: .tip} {:download: .download}

Assigning user access to clusters

{: #users}

You can grant access to a Kubernetes cluster to ensure that only authorized users can work with the cluster and deploy containers to the cluster in {{site.data.keyword.containerlong}}. {:shortdesc}

Planning communication processes

As a cluster administrator, consider how you might establish a communication process for the members of your organization to communicate access requests to you so that you can stay organized. {:shortdesc}

Provide instructions to your cluster users about how to request access to a cluster or how to get help with any kinds of common tasks from a cluster administrator. Because Kubernetes does not facilitate this kind of communication, each team can have variations on their preferred process.

You might choose any of the following methods or establish your own method.

  • Create a ticket system
  • Create a form template
  • Create a wiki page
  • Require an email request
  • Use the issue tracking method you already use to track your team's daily work

Managing cluster access

{: #managing}

Every user that works with {{site.data.keyword.containershort_notm}} must be assigned a combination of service-specific user roles that determine which actions the user can perform. {:shortdesc}

{{site.data.keyword.containershort_notm}} access policies
In Identity and Access Management, {{site.data.keyword.containershort_notm}} access policies determine the cluster management actions that you can perform on a cluster, such as creating or removing clusters, and adding or removing extra worker nodes. These policies must be set in conjunction with infrastructure policies. You can grant access to clusters on a regional basis.
Infrastructure access policies
In Identity and Access Management, infrastructure access policies allow the actions that are requested from the {{site.data.keyword.containershort_notm}} user interface or the CLI to be completed in IBM Cloud infrastructure (SoftLayer). These policies must be set in conjunction with {{site.data.keyword.containershort_notm}} access policies. [Learn more about the available infrastructure roles](/docs/iam/infrastructureaccess.html#infrapermission).
Resource groups
A resource group is a way to organize {{site.data.keyword.Bluemix_notm}} services into groupings so that you can quickly assign users access to more than one resource at a time. [Learn how to manage users by using resource groups](/docs/account/resourcegroups.html#rgs).
Cloud Foundry roles
In Identity and Access Management, every user must be assigned a Cloud Foundry user role. This role determines the actions that the user can perform on the {{site.data.keyword.Bluemix_notm}} account, such as inviting other users, or viewing the quota usage. [Learn more about the available Cloud Foundry roles](/docs/iam/cfaccess.html#cfaccess).
Kubernetes RBAC roles
Every user who is assigned an {{site.data.keyword.containershort_notm}} access policy is automatically assigned a Kubernetes RBAC role. In Kubernetes, RBAC roles determine the actions that you can perform on Kubernetes resources inside the cluster. RBAC roles are set up for the default namespace only. The cluster administrator can add RBAC roles for other namespaces in the cluster. See the following table in the [Access policies and permissions](#access_policies) section to see which RBAC role corresponds to which {{site.data.keyword.containershort_notm}} access policy. For more information about RBAC roles in general, see [Using RBAC Authorization ![External link icon](../icons/launch-glyph.svg "External link icon")](https://kubernetes.io/docs/admin/authorization/rbac/#api-overview) in the Kubernetes documentation.

To learn more, you can run through a tutorial about the best practices for organizing users, teams, and applications. {: tip}


Access policies and permissions

{: #access_policies}

Review the access policies and permissions that you can grant to users in your {{site.data.keyword.Bluemix_notm}} account. {:shortdesc}

The {{site.data.keyword.Bluemix_notm}} Identity Access and Management (IAM) operator and editor roles have separate permissions. If you want a user to, for example, add worker nodes and bind services, then you must assign the user both the operator and editor roles. For more details on corresponding infrastructure access policies, see Customizing infrastructure permissions for a user.

If you change a user's access policy, the RBAC policies associated with the change in your cluster are cleaned up for you.

Note: When you downgrade permissions, for example you want to assign viewer access to a former cluster admin, you must wait a few minutes for the downgrade to complete.

{{site.data.keyword.containershort_notm}} access policy Cluster management permissions Kubernetes resource permissions
Administrator This role inherits permissions from the Editor, Operator, and Viewer roles for all clusters in this account.

When set for all current service instances:
  • Create a free or standard cluster
  • Set credentials for an {{site.data.keyword.Bluemix_notm}} account to access the IBM Cloud infrastructure (SoftLayer) portfolio
  • Remove a cluster
  • Assign and change {{site.data.keyword.containershort_notm}} access policies for other existing users in this account.

When set for a specific cluster ID:

  • Remove a specific cluster

Corresponding infrastructure access policy: Super user

Note: To create resources such as machines, VLANs, and subnets, users need the Super user infrastructure role.
  • RBAC Role: cluster-admin
  • Read/write access to resources in every namespace
  • Create roles within a namespace
  • Access Kubernetes dashboard
  • Create an Ingress resource that makes apps publically available
Operator
  • Add additional worker nodes to a cluster
  • Remove worker nodes from a cluster
  • Reboot a worker node
  • Reload a worker node
  • Add a subnet to a cluster

Corresponding infrastructure access policy: Custom
  • RBAC Role: admin
  • Read/write access to resources inside the default namespace but not to the namespace itself
  • Create roles within a namespace
Editor

Tip: Use this role for app developers.
  • Bind an {{site.data.keyword.Bluemix_notm}} service to a cluster.
  • Unbind an {{site.data.keyword.Bluemix_notm}} service to a cluster.
  • Create a webhook.

Corresponding infrastructure access policy: Custom
  • RBAC Role: edit
  • Read/write access to resources inside the default namespace
Viewer
  • List a cluster
  • View details for a cluster

Corresponding infrastructure access policy: View only
  • RBAC Role: view
  • Read access to resources inside the default namespace
  • No read access to Kubernetes secrets
Cloud Foundry access policy Account management permissions
Organization role: Manager
  • Add additional users to an {{site.data.keyword.Bluemix_notm}} account
Space role: Developer
  • Create {{site.data.keyword.Bluemix_notm}} service instances
  • Bind {{site.data.keyword.Bluemix_notm}} service instances to clusters

Understanding the IAM API key and the bx cs credentials-set command

{: #api_key}

To succesfully provision and work with clusters in your account, you must ensure that your account is correctly set up to access the IBM Cloud infrastructure (SoftLayer) portfolio. Depending on your account setup, you either use the IAM API key or infrastructure credentials that you manually set by using the bx cs credentials-set command.

IAM API key
The Identity and Access Management (IAM) API key is automatically set for a region when the first action that requires the {{site.data.keyword.containershort_notm}} admin access policy is performed. For example, one of your admin users creates the first cluster in the us-south region. By doing that, the IAM API key for this user is stored in the account for this region. The API key is used to order IBM Cloud infrastructure (SoftLayer), such as new worker nodes or VLANs.

When a different user performs an action in this region that requires interaction with the IBM Cloud infrastructure (SoftLayer) portfolio, such as creating a new cluster or reloading a worker node, the stored API key is used to determine if sufficient permissions exist to perform that action. To make sure that infrastructure-related actions in your cluster can be successfully performed, assign your {{site.data.keyword.containershort_notm}} admin users the Super user infrastructure access policy.

You can find the current API key owner by running [bx cs api-key-info](cs_cli_reference.html#cs_api_key_info). If you find that you need to update the API key that is stored for a region, you can do so by running the [bx cs api-key-reset](cs_cli_reference.html#cs_api_key_reset) command. This command requires the {{site.data.keyword.containershort_notm}} admin access policy and stores the API key of the user that executes this command in the account.

Note: The API key that is stored for the region might not be used if IBM Cloud infrastructure (SoftLayer) credentials were manually set by using the bx cs credentials-set command.
IBM Cloud infrastructure (SoftLayer) credentials via bx cs credentials-set
If you have an {{site.data.keyword.Bluemix_notm}} Pay-As-You-Go account, you have access to the IBM Cloud infrastructure (SoftLayer) portfolio by default. However, you might want to use a different IBM Cloud infrastructure (SoftLayer) account that you already have to order infrastructure. You can link this infrastructure account to your {{site.data.keyword.Bluemix_notm}} account by using the [bx cs credentials-set](cs_cli_reference.html#cs_credentials_set) command.

If IBM Cloud infrastructure (SoftLayer) credentials are manually set, these credentials are used to order infrastructure, even if an IAM API key already exists for the account. If the user whose credentials are stored does not have the required permissions to order infrastructure, then infrastructure-related actions, such as creating a cluster or reloading a worker node can fail.

To remove IBM Cloud infrastructure (SoftLayer) credentials that were manually set, you can use the [bx cs credentials-unset](cs_cli_reference.html#cs_credentials_unset) command. After the credentials are removed, the IAM API key is used to order infrastructure.

Adding users to an {{site.data.keyword.Bluemix_notm}} account

{: #add_users}

You can add users to an {{site.data.keyword.Bluemix_notm}} account to grant access to your clusters. {:shortdesc}

Before you begin, verify that you have been assigned the Manager Cloud Foundry role for an {{site.data.keyword.Bluemix_notm}} account.

  1. Add the user to the account.
  2. In the Access section, expand Services.
  3. Assign an {{site.data.keyword.containershort_notm}} access role. From the Assign access to drop-down list, decide whether you want to grant access only to your {{site.data.keyword.containershort_notm}} account (Resource), or to a collection of various resources within your account (Resource group).
  • For Resource:
    1. From the Services drop-down list, select {{site.data.keyword.containershort_notm}}.
    2. From the Region drop-down list, select the region to invite the user to. Note: For access to clusters in the AP North region, see Granting IAM access to users for clusters within the AP North region.
    3. From the Service instance drop-down list, select the cluster to invite the user to. To find the ID of a specific cluster, run bx cs clusters.
    4. In the Select roles section, choose a role. To find a list of supported actions per role, see Access policies and permissions.
  • For Resource group:
    1. From the Resource group drop-down list, select the resource group that includes permissions for your account's {{site.data.keyword.containershort_notm}} resource.
    2. From the Assign access to a resource group drop-down list, select a role. To find a list of supported actions per role, see Access policies and permissions.
  1. Optional: Assign a Cloud Foundry role.
  2. Optional: Assign an infrastructure role.
  3. Click Invite users.

Granting IAM access to users for clusters within the AP North region

{: #iam_cluster_region}

When you add users to your {{site.data.keyword.Bluemix_notm}} account, you select the regions to which they are granted access. However, some regions, such as AP North, might not not be available in the console, and must be added by using the CLI. {:shortdesc}

Before you begin, verify that you are an admin for the {{site.data.keyword.Bluemix_notm}} account.

  1. Log in to the {{site.data.keyword.Bluemix_notm}} CLI. Select the account that you want to use.

    bx login [--sso]

    {: pre}

    Note: If you have a federated ID, use bx login --sso to log in to the {{site.data.keyword.Bluemix_notm}} CLI. Enter your user name and use the provided URL in your CLI output to retrieve your one-time passcode. You know you have a federated ID when the login fails without the --sso and succeeds with the --sso option.

  2. Target the environment that you want to grant permissions to, such as the AP North region (jp-tok). For more details about the command options such as organization and space, see the bluemix target command.

    bx target -r jp-tok

    {: pre}

  3. Get the name or IDs of the region's clusters that you want to grant access to.

    bx cs clusters

    {: pre}

  4. Get the user IDs that you want to grant access to.

    bx account users

    {: pre}

  5. Select the roles for the access policy.

    bx iam roles --service containers-kubernetes

    {: pre}

  6. Grant the user access to the cluster with the appropriate role. This example assigns [email protected] the Operator and Editor roles for three clusters.

    bx iam user-policy-create [email protected] --roles Operator,Editor --service-name containers-kubernetes --region jp-tok --service-instance cluster1,cluster2,cluster3

    {: pre}

    To grant access to existing and future clusters in the region, do not specify the --service-instance flag. For more information, see the bluemix iam user-policy-create command. {:tip}

Customizing infrastructure permissions for a user

{: #infra_access}

When you set infrastructure policies in Identity and Access Management, a user is given permissions that are associated with a role. To customize those permissions, you must log in to IBM Cloud infrastructure (SoftLayer) and adjust the permissions there. {: #view_access}

For example, Basic Users can reboot a worker node, but they cannot reload a worker node. Without giving that person Super User permissions, you can adjust the IBM Cloud infrastructure (SoftLayer) permissions and add the permission to run a reload command.

  1. Log in to your {{site.data.keyword.Bluemix_notm}} account, then from the menu select Infrastructure.

  2. Go to Account > Users > User List.

  3. To modify permissions, select a user profile's name or the Device Access column.

  4. In the Portal Permissions tab, customize the user's access. The permissions that users need depend on what infrastructure resources they need to use:

    • Use the Quick Permissions dropdown list to assign the Super User role, which gives the user all permissions.
    • Use the Quick Permissions dropdown list to assign the Basic User role, which gives the user some, but not all, needed permissions.
    • If you don't want to grant all permissions with the Super User role or need to add permissions beyond the Basic User role, review the following table that describes permissions needed to perform common tasks in {{site.data.keyword.containershort_notm}}.
    Commonly required infrastructure permissions for {{site.data.keyword.containershort_notm}}
    Common tasks in {{site.data.keyword.containershort_notm}} Required infrastructure permissions by tab
    Minimum permissions:
    • Create a cluster.
    		 Devices:
    • View Virtual Server Details
    • Reboot server and view IPMI system information
    • Issue OS Reloads and Initiate Rescue Kernel
    Account:
    • Add/Upgrade Cloud Instances
    • Add Server
    Cluster Administration:
    • Create, update, and delete clusters.
    • Add, reload, and reboot worker nodes.
    • View VLANs.
    • Create subnets.
    • Deploy pods and load balancer services.
    		 Support:
    • View Tickets
    • Add Tickets
    • Edit Tickets
    Devices:
    • View Virtual Server Details
    • Reboot server and view IPMI system information
    • Upgrade Server
    • Issue OS Reloads and Initiate Rescue Kernel
    Services:
    • Manage SSH Keys
    Account:
    • View Account Summary
    • Add/Upgrade Cloud Instances
    • Cancel Server
    • Add Server
    Storage:
    • Create persistent volume claims to provision persistent volumes.
    • Create and manage storage infrastructure resources.
    		 Services:
    • Manage Storage
    Account:
    • Add Storage
    Private Networking:
    • Manage private VLANs for in-cluster networking.
    • Set up VPN connectivity to private networks.
    		 Network:
    • Manage Network Subnet Routes
    • Manage Network VLAN Spanning
    • Manage IPSEC Network Tunnels
    • Manage Network Gateways
    • VPN Administration
    Public Networking:
    • Set up public load balancer or Ingress networking to expose apps.
    		 Devices:
    • Manage Load Balancers
    • Edit Hostname/Domain
    • Manage Port Control
    Network:
    • Add Compute with Public Network Port
    • Manage Network Subnet Routes
    • Manage Network VLAN Spanning
    • Add IP Addresses
    Services:
    • Manage DNS, Reverse DNS, and WHOIS
    • View Certificates (SSL)
    • Manage Certificates (SSL)

  5. To save your changes, click Edit Portal Permissions.

  6. In the Device Access tab, select the devices to grant access to.

    • In the Device Type dropdown, you can grant access to All Virtual Servers.
    • To allow users access to new devices that are created, check Automatically grant access when new devices are added.
    • To save your changes, click Update Device Access.

  7. Return to the user profile list and verify that Device Access is granted.

Authorizing users with custom Kubernetes RBAC roles

{: #rbac}

{{site.data.keyword.containershort_notm}} access policies correspond with certain Kubernetes role-based access control (RBAC) roles as described in Access policies and permissions. To authorize other Kubernetes roles that differ from the corresponding access policy, you can customize RBAC roles and then assign the roles to individuals or groups of users. {: shortdesc}

For example, you might want to grant permissions to a team of developers to work on a certain API group or with resources within a Kubernetes namespace in the cluster, but not across the entire cluster. You create a role and then bind the role to users, using a user name that is unique to {{site.data.keyword.containershort_notm}}. For more detailed information, see Using RBAC Authorization External link icon in the Kubernetes documentation.

Before you begin, target the Kubernetes CLI to the cluster.

  1. Create the role with the access that you want to assign.

    1. Make a .yaml file to define the role with the access that you want to assign.

      kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  namespace: default
  name: my_role
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "watch", "list"]
- apiGroups: ["apps", "extensions"]
  resources: ["daemonsets", "deployments"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

      {: codeblock}

      Table. Understanding this YAML components
      Idea icon Understanding this YAML components
      kind Use `Role` to grant access to resources within a single namespace, or `ClusterRole` for resources cluster-wide.
      apiVersion
      • For clusters that run Kubernetes 1.8 or later, use `rbac.authorization.k8s.io/v1`.
      • For earlier versions, use `apiVersion: rbac.authorization.k8s.io/v1beta1`.
      metadata/namespace
      • For `Role` kind: Specify the Kubernetes namespace to which access is granted.
      • Do not use the `namespace` field if you are creating a `ClusterRole` that applies at the cluster-level.
      metadata/name Name the role and use the name later when you bind the role.
      rules/apiGroups
      • Specify the Kubernetes API groups that you want users to be able to interact with, such as `"apps"`, `"batch"`, or `"extensions"`.
      • For access to the core API group at REST path `api/v1`, leave the group blank: `[""]`.
      • For more information, see [API groups![External link icon](../icons/launch-glyph.svg "External link icon")](https://kubernetes.io/docs/reference/api-overview/#api-groups) in the Kubernetes documentation.
      rules/resources
      • Specify the Kubernetes resources to which you want to grant access, such as `"daemonsets"`, `"deployments"`, `"events"`, or `"ingresses"`.
      • If you specify `"nodes"`, then the role kind must be `ClusterRole`.
      • For a list of resources, see the table of [Resource types![External link icon](../icons/launch-glyph.svg "External link icon")](https://kubernetes.io/docs/reference/kubectl/cheatsheet/) in the Kubernetes cheatsheet.
      rules/verbs

    2. Create the role in your cluster.

      kubectl apply -f <path_to_yaml_file>

      {: pre}

    3. Verify that the role is created.

      kubectl get roles

      {: pre}

  2. Bind users to the role.

    1. Make a .yaml file to bind users to your role. Note the unique URL to use for each subject's name.

      kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: my_role_team1
  namespace: default
subjects:
- kind: User
  name: https://iam.ng.bluemix.net/kubernetes#[email protected]
  apiGroup: rbac.authorization.k8s.io
- kind: User
  name: https://iam.ng.bluemix.net/kubernetes#[email protected]
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: custom-rbac-test
  apiGroup: rbac.authorization.k8s.io

      {: codeblock}

      Table. Understanding this YAML components
      Idea icon Understanding this YAML components
      kind Specify the `kind` as `RoleBinding` for both types of role `.yaml` files: namespace `Role` and cluster-wide `ClusterRole`.
      apiVersion
      • For clusters that run Kubernetes 1.8 or later, use `rbac.authorization.k8s.io/v1`.
      • For earlier versions, use `apiVersion: rbac.authorization.k8s.io/v1beta1`.
      metadata/namespace
      • For `Role` kind: Specify the Kubernetes namespace to which access is granted.
      • Do not use the `namespace` field if you are creating a `ClusterRole` that applies at the cluster-level.
      metadata/name Name the role binding.
      subjects/kind Specify the kind as `User`.
      subjects/name
      subjects/apiGroup Use `rbac.authorization.k8s.io`.
      roleRef/kind Enter the same value as the `kind` in the role `.yaml` file: `Role` or `ClusterRole`.
      roleRef/name Enter the name of the role `.yaml` file.
      roleRef/apiGroup Use `rbac.authorization.k8s.io`.

    2. Create the role binding resource in your cluster.

      kubectl apply -f <path_to_yaml_file>

      {: pre}

    3. Verify that the binding is created.

      kubectl get rolebinding

      {: pre}

Now that you created and bound a custom Kubernetes RBAC role, follow up with users. Ask them to test an action that they have permission to complete due to the role, such as deleting a pod.