Chapter 3. Managing CLI Profiles
3.1. Overview
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 Container Platform server information associated with a nickname.
3.2. Switching Between CLI Profiles
Contexts allow you to easily switch between multiple users across multiple OpenShift Container Platform 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 Container Platform 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:
Example 3.1. CLI 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
- 1
- The
clusters
section defines connection details for OpenShift Container Platform clusters, including the address for their master server. In this example, one cluster is nicknamed openshift1.example.com:8443 and another is nicknamed openshift2.example.com:8443. - 2
- This
contexts
section defines two contexts: one nicknamed alice-project/openshift1.example.com:8443/alice, using the alice-project project, openshift1.example.com:8443 cluster, and alice user, and another nicknamed joe-project/openshift1.example.com:8443/alice, using the joe-project project, openshift1.example.com:8443 cluster and alice user. - 3
- The
current-context
parameter shows that the joe-project/openshift1.example.com:8443/alice context is currently in use, allowing the alice user to work in the joe-project project on the openshift1.example.com:8443 cluster. - 4
- The
users
section defines user credentials. In this example, the user nickname alice/openshift1.example.com:8443 uses an access token.
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:
Example 3.2. Verifying the 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 output.
Additional CLI configuration commands are also available for more advanced usage.
If you have access to administrator credentials but are no longer logged in as the default system user system:admin, you can log back in as this user at any time as long as the credentials are still present in your CLI configuration file. The following command logs in and switches to the default project:
$ oc login -u system:admin -n default
3.3. Manually Configuring CLI Profiles
This section covers more advanced usage of CLI configurations. In most situations, you can simply use the oc login
and oc project
commands to log in and switch between contexts and projects.
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:
Subcommand | Usage |
---|---|
| Sets a cluster entry in the CLI configuration file. If the referenced cluster nickname already exists, the specified information is merged in. $ 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] |
| Sets a context entry in the CLI configuration file. If the referenced context nickname already exists, the specified information is merged in. $ oc config set-context <context_nickname> [--cluster=<cluster_nickname>] [--user=<user_nickname>] [--namespace=<namespace>] |
| Sets the current context using the specified context nickname. $ oc config use-context <context_nickname> |
| Sets an individual value in the CLI configuration file. $ oc config set <property_name> <property_value>
The |
| Unsets individual values in the CLI configuration file. $ oc config unset <property_name>
The |
| Displays the merged CLI configuration currently in use. $ oc config view Displays the result of the specified CLI configuration file. $ oc config view --config=<specific_filename> |
Example Usage
Consider the following configuration workflow. First, login as a user that uses an access token. This token is used by the alice user:
$ oc login https://openshift1.example.com --token=ns7yVhuRNpDM9cgzfhhxQ7bM5s7N2ZVrkZepSRf4LC0
View the cluster entry automatically created:
$ oc config view apiVersion: v1 clusters: - cluster: insecure-skip-tls-verify: true server: https://openshift1.example.com name: openshift1-example-com contexts: - context: cluster: openshift1-example-com namespace: default user: alice/openshift1-example-com name: default/openshift1-example-com/alice current-context: default/openshift1-example-com/alice kind: Config preferences: {} users: - name: alice/openshift1.example.com user: token: ns7yVhuRNpDM9cgzfhhxQ7bM5s7N2ZVrkZepSRf4LC0
Update the current context to have users login to the desired namespace:
$ oc config set-context `oc config current-context` --namespace=<project_name>
To confirm that the changes have taken effect, examine the current context:
$ oc whoami -c
All subsequent CLI operations will use the new context, unless otherwise specified by overriding CLI options or until the context is switched.
3.4. Loading and Merging Rules
When issuing CLI operations, the loading and merging order for the CLI configuration follows these rules:
CLI configuration files are retrieved from your workstation, using the following hierarchy and merge rules:
-
If the
--config
option is set, then only that file is loaded. The flag may only be set once and no merging takes place. -
If
$KUBECONFIG
environment variable is set, then it is used. The variable can be a list of paths, and if so the paths are merged together. When a value is modified, it is modified in the file that defines the stanza. When a value is created, it is created in the first file that exists. If no files in the chain exist, then it creates the last file in the list. -
Otherwise, the ~/.kube/config file is used and no merging takes place.
-
If the
The context to use is determined based on the first hit in the following chain:
-
The value of the
--context
option. -
The
current-context
value from the CLI configuration file. -
An empty value is allowed at this stage.
-
The value of the
The user and cluster to use is determined. At this point, you may or may not have a context; they are built based on the first hit in the following chain, which is run once for the user and once for the cluster:
-
The value of the
--user
option for user name and the--cluster
option for cluster name. -
If the
--context
option is present, then use the context’s value. -
An empty value is allowed at this stage.
-
The value of the
The actual cluster information to use is determined. At this point, you may or may not have cluster information. Each piece of the cluster information is built based on the first hit in the following chain:
The values of any of the following command line options:
-
--server
, -
--api-version
-
--certificate-authority
-
--insecure-skip-tls-verify
-
- If cluster information and a value for the attribute is present, then use it.
-
If you do not have a server location, then there is an error.
The actual user information to use is determined. Users are built using the same rules as clusters, except that you can only have one authentication technique per user; conflicting techniques cause the operation to fail. Command line options take precedence over configuration file values. Valid command line options are:
-
--auth-path
-
--client-certificate
-
--client-key
-
--token
-
- For any information that is still missing, default values are used and prompts are given for additional information.