Skip to content

Commit d307f58

Browse files
author
Amrita
committed
added an assembly for managing CLI profiles from 3.11
1 parent bba4e12 commit d307f58

File tree

5 files changed

+305
-0
lines changed

5 files changed

+305
-0
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -562,6 +562,8 @@ Topics:
562562
File: getting-started-cli
563563
- Name: Configuring the OpenShift CLI
564564
File: configuring-cli
565+
- Name: Managing CLI profiles
566+
File: managing-cli-profiles
565567
- Name: Extending the OpenShift CLI with plug-ins
566568
File: extending-cli-plugins
567569
Distros: openshift-enterprise,openshift-origin

‎cli_reference/openshift_cli/managing-cli-profiles.adoc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
:_content-type: ASSEMBLY
2+
[id="managing-cli-profiles"]
3+
= Managing CLI profiles
4+
include::modules/common-attributes.adoc[]
5+
:context: managing-cli-profiles
6+
7+
toc::[]
8+
9+
A CLI configuration file allows you to configure different profiles, or contexts, for use with the xref:../../cli_reference/index.adoc#cli-tools-overview[CLI tools overview]. A context consists of xref:../../authentication/understanding-authentication.adoc#understanding-authentication[user authentication] and {product-title} server information associated with a _nickname_.
10+
11+
include::modules/about-cli-profiles-switch.adoc[leveloffset=+1]
12+
13+
include::modules/manual-configuration-of-cli-profiles.adoc[leveloffset=+1]
14+
15+
include::modules/load-and-merge-rules.adoc[leveloffset=+1]

‎modules/about-cli-profiles-switch.adoc‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * cli_reference/openshift_cli/managing-cli-profiles.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="about-switches-between-cli-profiles_{context}"]
7+
= About switches between CLI profiles
8+
9+
Contexts allow you to easily switch between multiple users across multiple {product-title} servers, or clusters, when using CLI operations. Nicknames make managing CLI configurations easier by providing short-hand references to contexts, user credentials, and cluster details.
10+
After logging in with the CLI for the first time, {product-title} 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 manually configuring CLI profiles, the updated information is stored in the configuration file:
11+
12+
.CLI config file
13+
14+
[source,yaml]
15+
----
16+
apiVersion: v1
17+
clusters: <1>
18+
- cluster:
19+
insecure-skip-tls-verify: true
20+
server: https://openshift1.example.com:8443
21+
name: openshift1.example.com:8443
22+
- cluster:
23+
insecure-skip-tls-verify: true
24+
server: https://openshift2.example.com:8443
25+
name: openshift2.example.com:8443
26+
contexts: <2>
27+
- context:
28+
cluster: openshift1.example.com:8443
29+
namespace: alice-project
30+
user: alice/openshift1.example.com:8443
31+
name: alice-project/openshift1.example.com:8443/alice
32+
- context:
33+
cluster: openshift1.example.com:8443
34+
namespace: joe-project
35+
user: alice/openshift1.example.com:8443
36+
name: joe-project/openshift1/alice
37+
current-context: joe-project/openshift1.example.com:8443/alice <3>
38+
kind: Config
39+
preferences: {}
40+
users: <4>
41+
- name: alice/openshift1.example.com:8443
42+
user:
43+
token: xZHd2piv5_9vQrg-SKXRJ2Dsl9SceNJdhNTljEKTb8k
44+
----
45+
46+
<1> The `clusters` section defines connection details for {product-title} 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`.
47+
<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.
48+
<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.
49+
<4> The `users` section defines user credentials. In this example, the user nickname `alice/openshift1.example.com:8443` uses an access token.
50+
51+
The CLI can support multiple configuration files which 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` or `oc project` command to verify your current working environment:
52+
53+
.Verify the current working environment
54+
55+
[source,terminal,options="nowrap"]
56+
----
57+
$ oc status
58+
----
59+
60+
.Example output
61+
[source,terminal]
62+
----
63+
oc status
64+
In project Joe's Project (joe-project)
65+
66+
service database (172.30.43.12:5434 -> 3306)
67+
database deploys docker.io/openshift/mysql-55-centos7:latest
68+
#1 deployed 25 minutes ago - 1 pod
69+
70+
service frontend (172.30.159.137:5432 -> 8080)
71+
frontend deploys origin-ruby-sample:latest <-
72+
builds https://github.com/openshift/ruby-hello-world with joe-project/ruby-20-centos7:latest
73+
#1 deployed 22 minutes ago - 2 pods
74+
75+
To see more information about a service or deployment, use 'oc describe service <name>' or 'oc describe dc <name>'.
76+
You can use 'oc get all' to see lists of each of the types described in this example.
77+
----
78+
79+
.List the current project
80+
[source,terminal,options="nowrap"]
81+
----
82+
$ oc project
83+
----
84+
85+
.Example output
86+
[source,terminal]
87+
----
88+
Using project "joe-project" from context named "joe-project/openshift1.example.com:8443/alice" on server "https://openshift1.example.com:8443".
89+
----
90+
91+
You can run the `oc login` command again and supply the required information during the interactive process, to log in using any other combination of user credentials and cluster details. 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 enter the name of the project:
92+
93+
[source,terminal,options="nowrap"]
94+
----
95+
$ oc project alice-project
96+
----
97+
98+
.Example output
99+
[source,terminal]
100+
----
101+
Now using project "alice-project" on server "https://openshift1.example.com:8443".
102+
----
103+
104+
At any time, you can use the `oc config view` command to view your current CLI configuration, as seen in the output. Additional CLI configuration commands are also available for more advanced usage.
105+
106+
[NOTE]
107+
====
108+
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 config file. The following command logs in and switches to the default project:
109+
110+
[source,terminal]
111+
----
112+
$ oc login -u system:admin -n default
113+
----
114+
====

‎modules/load-and-merge-rules.adoc‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * cli_reference/openshift_cli/managing-cli-profiles.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="load-and-merge-rules_{context}"]
7+
= Load and merge rules
8+
9+
You can follow these rules, when issuing CLI operations for the loading and merging order for the CLI configuration:
10+
11+
* CLI config files are retrieved from your workstation, using the following hierarchy and merge rules:
12+
13+
** If the `--config` option is set, then only that file is loaded. The flag is set once and no merging takes place.
14+
** If the `$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.
15+
** Otherwise, the `_~/.kube/config_` file is used and no merging takes place.
16+
17+
* The context to use is determined based on the first match in the following flow:
18+
19+
** The value of the `--context` option.
20+
** The `current-context` value from the CLI config file.
21+
** An empty value is allowed at this stage.
22+
23+
* 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 match in the following flow, which is run once for the user and once for the cluster:
24+
** The value of the `--user` for user name and `--cluster` option for
25+
cluster name.
26+
** If the `--context` option is present, then use the context's value.
27+
** An empty value is allowed at this stage.
28+
* 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 match in the following flow:
29+
** The values of any of the following command line options:
30+
*** `--server`,
31+
*** `--api-version`
32+
*** `--certificate-authority`
33+
*** `--insecure-skip-tls-verify`
34+
** If cluster information and a value for the attribute is present, then use it.
35+
** If you do not have a server location, then there is an error.
36+
* 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 config file values. Valid command line options are:
37+
** `--auth-path`
38+
** `--client-certificate`
39+
** `--client-key`
40+
** `--token`
41+
* For any information that is still missing, default values are used and prompts are given for additional information.

‎modules/manual-configuration-of-cli-profiles.adoc‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * cli_reference/openshift_cli/managing-cli-profiles.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="manual-configuration-of-cli-profiles_{context}"]
7+
= Manual configuration of CLI profiles
8+
9+
[NOTE]
10+
====
11+
This section covers more advanced usage of CLI configurations. In most situations, you can use the `oc login` and `oc project` commands to log in and switch between contexts and projects.
12+
====
13+
14+
If you want to manually configure your CLI config files, you can use the `oc config` command instead of directly modifying the files. The `oc config` command includes a number of helpful sub-commands for this purpose:
15+
16+
.CLI configuration subcommands
17+
[cols="1,8",options="header"]
18+
|===
19+
20+
|Subcommand |Usage
21+
22+
a|`set-cluster`
23+
a|Sets a cluster entry in the CLI config file. If the referenced cluster
24+
nickname already exists, the specified information is merged in.
25+
[source,terminal,options="nowrap"]
26+
----
27+
$ oc config set-cluster <cluster_nickname> [--server=<master_ip_or_fqdn>]
28+
[--certificate-authority=<path/to/certificate/authority>]
29+
[--api-version=<apiversion>] [--insecure-skip-tls-verify=true]
30+
----
31+
32+
a|`set-context`
33+
a|Sets a context entry in the CLI config file. If the referenced context
34+
nickname already exists, the specified information is merged in.
35+
[source,terminal,options="nowrap"]
36+
----
37+
$ oc config set-context <context_nickname> [--cluster=<cluster_nickname>]
38+
[--user=<user_nickname>] [--namespace=<namespace>]
39+
----
40+
41+
a|`use-context`
42+
a|Sets the current context using the specified context nickname.
43+
[source,terminal,options="nowrap"]
44+
----
45+
$ oc config use-context <context_nickname>
46+
----
47+
48+
a|`set`
49+
a|Sets an individual value in the CLI config file.
50+
[source,terminal,options="nowrap"]
51+
----
52+
$ oc config set <property_name> <property_value>
53+
----
54+
The `<property_name>` is a dot-delimited name where each token represents either an attribute name or a map key. The `<property_value>` is the new value being set.
55+
56+
a|`unset`
57+
a|Unsets individual values in the CLI config file.
58+
[source,terminal,options="nowrap"]
59+
----
60+
$ oc config unset <property_name>
61+
----
62+
The `<property_name>` is a dot-delimited name where each token represents either an attribute name or a map key.
63+
64+
a|`view`
65+
a|Displays the merged CLI configuration currently in use.
66+
[source,terminal,options="nowrap"]
67+
----
68+
$ oc config view
69+
----
70+
71+
Displays the result of the specified CLI config file.
72+
[source,terminal,options="nowrap"]
73+
----
74+
$ oc config view --config=<specific_filename>
75+
----
76+
|===
77+
78+
.Example usage
79+
80+
* Log in as a user that uses an access token.
81+
This token is used by the `alice` user:
82+
83+
[source,terminal,options="nowrap"]
84+
----
85+
$ oc login https://openshift1.example.com --token=ns7yVhuRNpDM9cgzfhhxQ7bM5s7N2ZVrkZepSRf4LC0
86+
----
87+
88+
* View the cluster entry automatically created:
89+
90+
[source,terminal,options="nowrap"]
91+
----
92+
$ oc config view
93+
----
94+
95+
.Example output
96+
[source,terminal]
97+
----
98+
apiVersion: v1
99+
clusters:
100+
- cluster:
101+
insecure-skip-tls-verify: true
102+
server: https://openshift1.example.com
103+
name: openshift1-example-com
104+
contexts:
105+
- context:
106+
cluster: openshift1-example-com
107+
namespace: default
108+
user: alice/openshift1-example-com
109+
name: default/openshift1-example-com/alice
110+
current-context: default/openshift1-example-com/alice
111+
kind: Config
112+
preferences: {}
113+
users:
114+
- name: alice/openshift1.example.com
115+
user:
116+
token: ns7yVhuRNpDM9cgzfhhxQ7bM5s7N2ZVrkZepSRf4LC0
117+
----
118+
119+
* Update the current context to have users log in to the desired namespace:
120+
121+
[source,terminal]
122+
----
123+
$ oc config set-context `oc config current-context` --namespace=<project_name>
124+
----
125+
126+
* Examine the current context, to confirm that the changes are implemented:
127+
128+
[source,terminal]
129+
----
130+
$ oc whoami -c
131+
----
132+
133+
All subsequent CLI operations uses the new context, unless otherwise specified by overriding CLI options or until the context is switched.

0 commit comments

Comments
 (0)