Chapter 3. Managing CLI Profiles

A CLI configuration file allows you to configure different profiles, or contexts, for use with the OpenShift CLI. A context consists of user authentication and OpenShift Enterprise server information associated with a nickname.

Contexts allow you to easily switch between multiple users across multiple OpenShift Enterprise servers, or clusters, when using issuing CLI operations. Nicknames make managing CLI configuration easier by providing short-hand references to contexts, user credentials, and cluster details.

After logging in with the CLI for the first time, OpenShift Enterprise creates a ~/.kube/config file if one does not already exist. As more authentication and connection details are provided to the CLI, either automatically during an oc login operation or by setting them explicitly, the updated information is stored in the configuration file:

apiVersion: v1
clusters: 1
- cluster:
    insecure-skip-tls-verify: true
    server: https://openshift1.example.com:8443
  name: openshift1.example.com:8443
- cluster:
    insecure-skip-tls-verify: true
    server: https://openshift2.example.com:8443
  name: openshift2.example.com:8443
contexts: 2
- context:
    cluster: openshift1.example.com:8443
    namespace: alice-project
    user: alice/openshift1.example.com:8443
  name: alice-project/openshift1.example.com:8443/alice
- context:
    cluster: openshift1.example.com:8443
    namespace: joe-project
    user: alice/openshift1.example.com:8443
  name: joe-project/openshift1/alice
current-context: joe-project/openshift1.example.com:8443/alice 3
kind: Config
preferences: {}
users: 4
- name: alice/openshift1.example.com:8443
  user:
    token: xZHd2piv5_9vQrg-SKXRJ2Dsl9SceNJdhNTljEKTb8k

The CLI can support multiple configuration files; they are loaded at runtime and merged together along with any override options specified from the command line.

After you are logged in, you can use the oc status command or the oc project command to verify your current working environment:

$ oc status
oc status
In project Joe's Project (joe-project)

service database (172.30.43.12:5434 -> 3306)
  database deploys docker.io/openshift/mysql-55-centos7:latest
    #1 deployed 25 minutes ago - 1 pod

service frontend (172.30.159.137:5432 -> 8080)
  frontend deploys origin-ruby-sample:latest <-
    builds https://github.com/openshift/ruby-hello-world with joe-project/ruby-20-centos7:latest
    #1 deployed 22 minutes ago - 2 pods

To see more information about a service or deployment, use 'oc describe service <name>' or 'oc describe dc <name>'.
You can use 'oc get all' to see lists of each of the types described above.

$ oc project
Using project "joe-project" from context named "joe-project/openshift1.example.com:8443/alice" on server "https://openshift1.example.com:8443".

To log in using any other combination of user credentials and cluster details, run the oc login command again and supply the relevant information during the interactive process. A context is constructed based on the supplied information if one does not already exist.

If you are already logged in and want to switch to another project the current user already has access to, use the oc project command and supply the name of the project:

$ oc project alice-project
Now using project "alice-project" on server "https://openshift1.example.com:8443".

At any time, you can use the oc config view command to view your current, full CLI configuration, as seen in the above output.

Additional CLI configuration commands are also available for more advanced usage.

$ oc login -u system:admin -n default

If you want to manually configure your CLI configuration files, you can use the oc config command instead of modifying the files themselves. The oc config command includes a number of helpful subcommands for this purpose:

$ oc config set-credentials <user_nickname>
[--client-certificate=<path/to/certfile>] [--client-key=<path/to/keyfile>]
[--token=<bearer_token>] [--username=<basic_user>] [--password=<basic_password>]

$ oc config set-cluster <cluster_nickname> [--server=<master_ip_or_fqdn>]
[--certificate-authority=<path/to/certificate/authority>]
[--api-version=<apiversion>] [--insecure-skip-tls-verify=true]

$ oc config set-context <context_nickname> [--cluster=<cluster_nickname>]
[--user=<user_nickname>] [--namespace=<namespace>]

$ oc config use-context <context_nickname>

$ oc config set <property_name> <property_value>

$ oc config unset <property_name>

$ oc config view

$ oc config view --config=<specific_filename>

Example Usage

Consider the following configuration workflow. First, set credentials for a user nickname alice that uses an access token:

$ oc config set-credentials alice --token=NDM2N2MwODgtNjI1Yy10N3VhLTg1YmItYzI4NDEzZDUyYzVi

Set a cluster entry named openshift1:

$ oc config set-cluster openshift1 --server=https://openshift1.example.com

Set a context named alice that uses the alice user and the openshift1 cluster:

$ oc config set-context alice --cluster=openshift1 --user=alice

Now that the alice context has been created, switch to that context:

$ oc config use-context alice

Set the aliceproject namespace for the alice context:

$ oc config set contexts.alice.namespace aliceproject

You can now view the configuration that has been created:

$ oc config view
apiVersion: v1
clusters:
- cluster:
    server: https://openshift1.example.com
  name: openshift1
contexts:
- context:
    cluster: openshift1
    namespace: aliceproject
    user: alice
  name: alice
current-context: alice 1
kind: Config
preferences: {}
users:
- name: alice
  user:
    token: NDM2N2MwODgtNjI1Yy10N3VhLTg1YmItYzI4NDEzZDUyYzVi

All subsequent CLI operations will use the alice context, unless otherwise specified by overriding CLI options or until the context is switched.

When issuing CLI operations, the loading and merging order for the CLI configuration follows these rules: