Skip to content

Commit 0624c12

Browse files
AedinCAedinC
committed
OSDOCS#9971:Added breakglass feature modules for HCP clusters
1 parent 608b682 commit 0624c12

11 files changed

+852
-8
lines changed

‎cli_reference/rosa_cli/rosa-manage-objects-cli.adoc

+1
Original file line numberDiff line numberDiff line change
@@ -24,4 +24,5 @@ include::modules/rosa-edit-objects.adoc[leveloffset=+1]
2424
include::modules/rosa-delete-objects.adoc[leveloffset=+1]
2525
include::modules/rosa-install-uninstall-addon.adoc[leveloffset=+1]
2626
include::modules/rosa-list-objects.adoc[leveloffset=+1]
27+
include::modules/rosa-revoke-objects.adoc[leveloffset=+1]
2728
include::modules/rosa-upgrade-cluster-cli.adoc[leveloffset=+1]

‎modules/rosa-create-objects.adoc

+67
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,73 @@ Create a cluster administrator that can log in to a cluster named `mycluster`.
9999
$ rosa create admin --cluster=mycluster
100100
----
101101

102+
[id="rosa-create-break-glass-credential_{context}"]
103+
== create break glass credential
104+
105+
Create a break glass credential for a hosted control plane cluster with external authentication enabled.
106+
107+
.Syntax
108+
[source,terminal]
109+
----
110+
$ rosa create break-glass-credential --cluster=<cluster_name> [arguments]
111+
----
112+
113+
.Arguments
114+
[cols="30,70"]
115+
|===
116+
|Option |Definition
117+
118+
|--cluster <cluster_name>\|<cluster_id>
119+
|Required. The name or ID of the cluster to which the break glass credential will be added.
120+
121+
|--expiration
122+
|Optional: How long a break glass credential can be used before expiring. The expiration duration must be a minimum of 10 minutes and a maximum of 24 hours. If you do not enter a value, the expiration duration defaults to 24 hours.
123+
124+
|--username
125+
|Optional. The username for the break glass credential. If you do not enter a value, a random username is generated for you.
126+
|===
127+
128+
.Optional arguments inherited from parent commands
129+
[cols="30,70"]
130+
|===
131+
|Option |Definition
132+
133+
|--help
134+
|Shows help for this command.
135+
136+
|--debug
137+
|Enables debug mode.
138+
139+
|--interactive
140+
|Enables interactive mode.
141+
142+
|--profile
143+
|Specifies an AWS profile (string) from your credentials file.
144+
145+
|--region
146+
|Specifies an AWS region, overriding the `AWS_REGION` environment variable.
147+
148+
|--yes
149+
|Automatically answers `yes` to confirm the operation.
150+
|===
151+
152+
.Examples
153+
Add a break glass credential to a cluster named `mycluster`.
154+
155+
.Syntax
156+
[source,terminal]
157+
----
158+
$ rosa create break-glass-credential --cluster=mycluster
159+
----
160+
161+
Add a break glass credential to a cluster named `mycluster` using the interactive mode.
162+
163+
.Syntax
164+
[source,terminal]
165+
----
166+
$ rosa create break-glass-credential --cluster=mycluster -i
167+
----
168+
102169
[id="rosa-create-cluster-command_{context}"]
103170
== create cluster
104171

‎modules/rosa-hcp-sts-accessing-a-break-glass-cred-cli.adoc

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc
4+
// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-ext-auth.adoc
5+
6+
:_mod-docs-content-type: PROCEDURE
7+
[id="rosa-hcp-sts-accessing-a-break-glass-cred-cli_{context}"]
8+
= Accessing a {hcp-title} cluster by using a break glass credential
9+
10+
Use the new `kubeconfig` from the break glass credential to gain temporary admin access to a {hcp-title} cluster.
11+
12+
.Prerequisites
13+
14+
* You have access to a {hcp-title} cluster with external authentication enabled. For more information, see _Creating a {hcp-title} cluster that uses external authentication providers_.
15+
* You have installed the `oc` and the `kubectl` CLIs.
16+
* You have configured the new `kubeconfig`. For more information, see _Creating a break glass credential for a {hcp-title} cluster_.
17+
18+
.Procedure
19+
20+
. Access the details for the cluster:
21+
+
22+
[source,terminal]
23+
----
24+
$ rosa describe break-glass-credential <break_glass_credential_id> -c <cluster_name> --kubeconfig > $KUBECONFIG
25+
----
26+
+
27+
. List the nodes from the cluster:
28+
+
29+
[source,terminal]
30+
----
31+
$ oc get nodes
32+
----
33+
.Example output
34+
+
35+
[source,terminal]
36+
----
37+
NAME STATUS ROLES AGE VERSION
38+
ip-10-0-0-27.ec2.internal Ready worker 8m v1.28.7+f1b5f6c
39+
ip-10-0-0-67.ec2.internal Ready worker 9m v1.28.7+f1b5f6c
40+
----
41+
. Verify you have the correct credentials:
42+
+
43+
[source,terminal]
44+
----
45+
$ kubectl auth whoami
46+
----
47+
+
48+
.Example output
49+
+
50+
[source,terminal]
51+
----
52+
ATTRIBUTE VALUE
53+
Username system:customer-break-glass:test-user
54+
Groups [system:masters system:authenticated]
55+
----
56+
. Apply the `ClusterRoleBinding` for the groups defined in the external OIDC provider. The `ClusterRoleBinding` maps the `rosa-hcp-admins` group that is created in Microsoft Entra ID to a group in the {hcp-title} cluster.
57+
+
58+
[source,terminal]
59+
----
60+
$ oc apply -f - <<EOF
61+
apiVersion: rbac.authorization.k8s.io/v1
62+
kind: ClusterRoleBinding
63+
metadata:
64+
name: rosa-hcp-admins
65+
roleRef:
66+
apiGroup: rbac.authorization.k8s.io
67+
kind: ClusterRole
68+
name: cluster-admin
69+
subjects:
70+
- apiGroup: rbac.authorization.k8s.io
71+
kind: Group
72+
name: f715c264-ab90-45d5-8a29-2e91a609a895
73+
EOF
74+
----
75+
+
76+
.Example output
77+
+
78+
[source,terminal]
79+
----
80+
clusterrolebinding.rbac.authorization.k8s.io/rosa-hcp-admins created
81+
----
82+
+
83+
[NOTE]
84+
====
85+
After the `ClusterRoleBinding` has been applied, the {hcp-title} cluster is configured, and the `rosa` CLI and the {hybrid-console-url} are authenticated through the external OpenID Connect (OIDC) provider. You can now start assigning roles and deploying applications on the cluster.
86+
====

‎modules/rosa-hcp-sts-creating-a-break-glass-cred-cli.adoc

+153
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc
4+
// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-ext-auth.adoc
5+
6+
:_mod-docs-content-type: PROCEDURE
7+
[id="rosa-hcp-sts-creating-a-break-glass-cred-cli_{context}"]
8+
= Creating a break glass credential for a {hcp-title} cluster
9+
10+
As a {hcp-title} cluster owner, you can use the break glass credential to create temporary administrative client credentials to access your clusters that are configured with custom OpenID Connect (OIDC) token issuers. Creating a break glass credential generates a new cluster-admin `kubeconfig` file. The `kubeconfig` file contains information about the cluster that the CLI uses to connect a client to the correct cluster and API server. You can use the newly generated `kubeconfig` file to allow access to the {hcp-title} cluster.
11+
12+
.Prerequisites
13+
14+
* You have created a {hcp-title} cluster with external authentication enabled. For more information, see _Creating a {hcp-title} with HCP cluster that uses external authentication providers_.
15+
* You have created an external authentication provider. For more information, see _Creating an external authentication provider_.
16+
* You have an account with `cluster admin` permissions.
17+
18+
.Procedure
19+
20+
. Create a break glass credential by using one of the following commands:
21+
22+
** To create a break glass credential by using the interactive command interface to interactively specify custom settings, run the following command:
23+
+
24+
[source,terminal]
25+
----
26+
$ rosa create break-glass-credential -c <cluster_name> -i <1>
27+
----
28+
<1> Replace <cluster_name> with the name of your cluster.
29+
+
30+
This command starts an interactive CLI process:
31+
+
32+
.Example output
33+
[source,terminal]
34+
----
35+
I: Enabling interactive mode
36+
? Username (optional): <1>
37+
? Expiration duration (optional): <2>
38+
I: Successfully created a break glass credential for cluster 'ac-hcp-test'.
39+
----
40+
<1> If left blank, the value in the `username` will have a randomly generated username value.
41+
<2> The minimum validity of the break glass credential is 10 minutes, and the maximum validity is 24 hours. If left blank, the expiration duration value defaults to 24 hours.
42+
+
43+
** To create a break glass credential for cluster called `mycluster` with specified values:
44+
+
45+
[source,terminal]
46+
----
47+
$ rosa create break-glass-credential -c mycluster --username test-username --expiration 1h
48+
----
49+
+
50+
. List the break glass credential IDs, status, and associated users that are available for a cluster called `mycluster` by running the following command:
51+
+
52+
[source,terminal]
53+
----
54+
$ rosa list break-glass-credential -c mycluster
55+
----
56+
+
57+
.Example output
58+
[source,terminal]
59+
----
60+
ID USERNAME STATUS
61+
2a7jli9n4phe6c02ul7ti91djtv2o51d test-user issued
62+
----
63+
+
64+
[NOTE]
65+
====
66+
You can also view the credentials in a JSON output by adding the `-o json` argument to the command.
67+
====
68+
69+
. To view the status of a break glass credential, run the following command, replacing <break_glass_credential_id> with the break glass credential ID:
70+
+
71+
[source,terminal]
72+
----
73+
$ rosa describe break-glass-credential <break_glass_credential_id> -c <cluster_name>
74+
----
75+
+
76+
.Example output
77+
[source,terminal]
78+
----
79+
ID: 2a7jli9n4phe6c02ul7ti91djtv2o51d
80+
Username: test-user
81+
Expire at: Dec 28 2026 10:23:05 EDT
82+
Status: issued
83+
----
84+
+
85+
The following is a list of possible `Status` field values:
86+
+
87+
* `issued` The break glass credential has been issued and is ready to use.
88+
* `expired` The break glass credential has expired and can no longer be used.
89+
* `failed` The break glass credential has failed to create. In this case, you receive a service log detailing the failure. For more information about service logs, see _Accessing the service logs for Red Hat OpenShift Service on AWS clusters_. For steps to contact Red Hat Support for assistance, see _Getting support_.
90+
* `awaiting_revocation` The break glass credential is currently being revoked, meaning it cannot be used.
91+
* `revoked` The break glass credential has been revoked and can no longer be used.
92+
+
93+
. To retrieve the `kubeconfig`, run the following commands:
94+
** Create a `kubeconfigs` directory:
95+
+
96+
[source,terminal]
97+
----
98+
$ mkdir ~/kubeconfigs
99+
----
100+
+
101+
** Export the newly generated `kubeconfig` file, replacing <cluster_name> with the name of your cluster:
102+
+
103+
[source,terminal]
104+
----
105+
$ export CLUSTER_NAME=<cluster_name> && export KUBECONFIG=~/kubeconfigs/break-glass-${CLUSTER_NAME}.kubeconfig
106+
----
107+
+
108+
** View the `kubeconfig`:
109+
+
110+
[source,terminal]
111+
----
112+
$ rosa describe break-glass-credential <break_glass_credential_id> -c mycluster --kubeconfig
113+
----
114+
.Example output
115+
+
116+
[source,terminal]
117+
----
118+
apiVersion: v1
119+
clusters:
120+
- cluster:
121+
server: <server_url>
122+
name: cluster
123+
contexts:
124+
- context:
125+
cluster: cluster
126+
namespace: default
127+
user: test-username
128+
name: admin
129+
current-context: admin
130+
kind: Config
131+
preferences: {}
132+
users:
133+
- name: test-user
134+
user:
135+
client-certificate-data: <client-certificate-data> <1>
136+
client-key-data: <client-key-data> <2>
137+
----
138+
<1> The client-certificate contains a certificate for the user signed by the Kubernetes certificate authorities (CA).
139+
<2> The client-key contains the key that signed the client certificate.
140+
+
141+
. Optional: To save the `kubeconfig`, run the following command :
142+
+
143+
[source,terminal]
144+
----
145+
$ rosa describe break-glass-credential <break_glass_credential_id> -c mycluster --kubeconfig > $KUBECONFIG
146+
----
147+
148+
149+
150+
151+
152+
153+

0 commit comments

Comments
 (0)