Logging in to Enterprise PKS
Page last updated:
This topic describes how to log in to VMware Enterprise PKS.
Overview
To manage Enterprise PKS-deployed clusters, you use the PKS Command
Line Interface (PKS CLI). When you log in to Enterprise PKS successfully
for the first time, the PKS CLI generates a local creds.yml
file that contains
the API endpoint, refresh token, access token, and CA certificate, if applicable.
By default, creds.yml
is saved in the ~/.pks
directory on your local system.
You can use the PKS_HOME
environment variable to override this location and
store creds.yml
in any directory on your system.
Prerequisites
Before you can log in to Enterprise PKS, you must have the following:
- A running Enterprise PKS environment, including an external load balancer configured to forward traffic to the PKS API endpoint. See the Installing Enterprise PKS section for your cloud provider.
- A username and password that has access to the PKS API. See Managing Enterprise PKS Users with UAA.
- The PKS CLI installed on your local system. See Installing the PKS CLI.
Log in to the PKS CLI
Use the command in this section to log in as an individual user. The login procedure is the same for users created in UAA or users from external LDAP groups.
On the command line, run the following command in your terminal to log in to the PKS CLI:
pks login -a PKS-API -u USERNAME -p PASSWORD --ca-cert CERT-PATH
Replace the placeholder values in the command as follows:
PKS-API
is the domain name for the PKS API that you entered in Ops Manager > Enterprise PKS > PKS API > API Hostname (FQDN). For example,api.pks.example.com
.USERNAME
andPASSWORD
belong to the account you created in the Grant Enterprise PKS Access to an Individual User section of Managing Enterprise PKS Users with UAA. If you do not use-p
to provide a password, the PKS CLI prompts for the password interactively. VMware recommends running the login command without the-p
flag for added security.CERT-PATH
is the path to your root CA certificate. Provide the certificate to validate the PKS API certificate with SSL.
For example:$ pks login -a api.pks.example.com -u alana \ --ca-cert /var/tempest/workspaces/default/root_ca_certificate
If you are logging in to a trusted environment, you can use
-k
to skip SSL verification instead of--ca-cert CERT-PATH
.
For example:$ pks login -a api.pks.example.com -u alana -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
Log in to the PKS CLI as an Automated Client
To log in to the PKS CLI as an automated client for a script or service, run the following command:
pks login -a PKS-API --client-name CLIENT-NAME --client-secret CLIENT-SECRET --ca-cert CERTIFICATE-PATH
Where:
PKS-API
is the domain name for the PKS API that you entered in Ops Manager > Enterprise PKS > PKS API > API Hostname (FQDN). For example,api.pks.example.com
.CLIENT-NAME
is an OAuth client ID for either:- A UAA admin client created with
--authorities "pks.clusters.admin"
- The default admin client Pks Uaa Management Admin Client
- A UAA admin client created with
CLIENT-SECRET
the OAuth client secret for the--client-name
value above.CERTIFICATE-PATH
is the path to your root CA certificate. Provide the certificate to validate the PKS API certificate with SSL.For example:
$ pks login -a api.pks.example.com \ --client-name automated-client \ --client-secret randomly-generated-secret \ --ca-cert /var/tempest/workspaces/default/root_ca_certificate
For information on how to create a UAA client, see Grant Enterprise PKS Access to a Client in Managing Enterprise PKS Users with UAA.
Export PKS API Access Token
This procedure stores a PKS API access token as an environment variable that you can use when executing PKS API calls on the command line.
To export your access token into an environment variable, run the following command:
pks login -a PKS-API -u USER-ID -p 'PASSWORD' -k; \ export YOUR-ACCESS-TOKEN=$(bosh int ~/.pks/creds.yml --path /access_token)
Where:
PKS-API
is the FQDN of your PKS API endpoint. For example,api.pks.example.com
.USER-ID
is your Enterprise PKS user ID.PASSWORD
is your Enterprise PKS password.YOUR-ACCESS-TOKEN
is the name of your access token environment variable.
For example:
$ pks login -a pks.my.lab -u alana -p 'psswrdabc123...!' -k; \ export my_token=$(bosh int ~/.pks/creds.yml --path /access_token)
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
Please send any feedback you have to pks-feedback@pivotal.io.