Setting Up Enterprise PKS Admin Users on vSphere

This topic describes how to create admin users in Enterprise Pivotal Container Service (Enterprise PKS) with User Account and Authentication (UAA). Creating at least one admin user is a necessary step during the initial set up of Enterprise PKS.

Overview

UAA is the identity management service for Pivotal Cloud Foundry. Enterprise PKS includes a UAA server, which is hosted on the PKS control plane VM.

To interact with the UAA server, you can use the UAA Command Line Interface (UAAC). You can either run UAAC commands from the Ops Manager VM or install UAAC on your local workstation.

Prerequisites

Before setting up admin users for Enterprise PKS, you must have one of the following:

  • SSH access to the Ops Manager VM

  • A machine that can connect to your PKS control plane VM

Step 1: Connect to the PKS Control Plane VM

You can connect to the PKS control plane VM from the Ops Manager VM or from a different machine such as your local workstation.

Option 1: Connect through the Ops Manager VM

You can connect to PKS control plane VM by logging in to the Ops Manager VM through SSH. To SSH into the Ops Manager VM on vSphere, do the following:

To SSH into the Ops Manager VM on vSphere, you need the credentials used to import the PCF .ova or .ovf file into your virtualization system. You set your credentials in the Prepare vSphere section of Deploying Ops Manager on vSphere for your Ops Manager version.

Note: If you lose your password, you must shut down the Ops Manager VM in the vSphere UI and reset the password. See vCenter Password Requirements and Lockout Behavior in the vSphere documentation for more information.

Warning: If you deployed Ops Manager v2.6 on vSphere, you can only SSH into the Ops Manager VM with a private SSH key. If you do not have a private SSH key, you must add a public key to your .ova or .ovf file and then use the private key to SSH onto the Ops Manager VM. If you do not add a key, Ops Manager shuts down automatically because it cannot find a key and may enter a reboot loop.

To SSH into the Ops Manager VM on vSphere, do one of the following:

  • If you set a password when you installed Ops Manager:

    1. SSH into the Ops Manager VM by running the following command:

      ssh ubuntu@OPS-MANAGER-FQDN
      

      Where OPS-MANAGER-FQDN is the fully qualified domain name (FQDN) of Ops Manager.

    2. When prompted, enter the password that you set during the .ova deployment into vCenter. For example:

      $ ssh ubuntu@my-opsmanager-fqdn.example.com
      Password: ***********
      

    3. Proceed to the Log in as a UAA Admin section to manage users with UAAC.

  • If you set a SSH key when you installed Ops Manager:

    1. Change the permissions for your private SSH key by running the following command:

        chmod 600 PRIVATE-KEY
      

      Where PRIVATE-KEY is the name of your private SSH key.

    2. SSH into the Ops Manager VM by running the following command:

        ssh -i PRIVATE-KEY ubuntu@OPS-MANAGER-FQDN
      

      Where OPS-MANAGER-FQDN is the fully qualified domain name (FQDN) of Ops Manager.

      For example:

      $ ssh -i id_rsa ubuntu@my-opsmanager-fqdn.example.com

    3. Proceed to the Log In as a UAA Admin section to create admin users with UAAC.

Option 2: Connect through a Non-Ops Manager Machine

To connect to the PKS control plane VM and run UAA commands, do the following:

  1. Install UAAC on your machine. For example:

    gem install cf-uaac
    
  2. Download a copy of your Ops Manager root CA certificate to the machine. To download the certificate, do the following:

    1. In a web browser, navigate to the FQDN of Ops Manager and log in.
    2. In Ops Manager, navigate to Settings in the drop-down menu under your username.
    3. Click Advanced Options.
    4. On the Advanced Options configuration page, click Download Root CA Cert.
    5. Move the certificate to a secure location on your machine and record the path.
  3. Proceed to the Log In as a UAA Admin section to create admin users with UAAC.

Step 2: Log In as a UAA Admin

Before creating PKS admin users, you must log in to the UAA server as a UAA admin. To log in to the UAA server, do the following:

  1. Retrieve the UAA management admin client secret:

    1. In a web browser, navigate to the Ops Manager Installation Dashboard and click the Enterprise PKS tile.
    2. Click the Credentials tab.
    3. Click Link to Credential next to Pks Uaa Management Admin Client and copy the value of secret.
  2. Target your UAA server by running the following command:

    uaac target https://PKS-API:8443 --ca-cert CERTIFICATE-PATH
    

    Where:

    • PKS-API is the domain name of your PKS API server. You entered this domain name in the Enterprise PKS tile > PKS API > API Hostname (FQDN).
    • CERTIFICATE-PATH is the path to your Ops Manager root CA certificate. Provide this certificate to validate the PKS API certificate with SSL.
      • If you are logged in to the Ops Manager VM, specify /var/tempest/workspaces/default/root_ca_certificate as the path. This is the default location of the root certificate on the Ops Manager VM.
      • If you downloaded the Ops Manager root CA certificate to your machine, specify the path where you stored the certificate.

    For example:

    $ uaac target api.pks.example.com:8443 --ca-cert /var/tempest/workspaces/default/root_ca_certificate

    Note: If you receive an Unknown key: Max-Age = 86400 warning message, you can ignore it because it has no impact.

  3. Authenticate with UAA by running the following command:

    uaac token client get admin -s ADMIN-CLIENT-SECRET
    

    Where ADMIN-CLIENT-SECRET is your UAA management admin client secret that you retrieved in a previous step. The client username is admin.

Step 3: Assign Enterprise PKS Cluster Scopes

By assigning PKS cluster scopes, you grant users the ability to create and manage Kubernetes clusters in Enterprise PKS.

As a UAA admin user, you can assign the following UAA scopes:

  • pks.clusters.manage: Accounts with this scope can create and access their own clusters.
  • pks.clusters.admin: Accounts with this scope can create and access all clusters.

You can assign these scopes to individual users, external identity provider groups, or clients for automation purposes.

Based on the needs of your deployment, perform one or more of the following procedures:

Next Step

After you create admin users in Enterprise PKS, the admin users can create and manage Kubernetes clusters in Enterprise PKS. For more information, see Managing Clusters.


Please send any feedback you have to pks-feedback@pivotal.io.