Skip to content

OSDOCS#9971:Added breakglass feature modules for HCP clusters #73863

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 9, 2024
Merged

OSDOCS#9971:Added breakglass feature modules for HCP clusters #73863

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions cli_reference/rosa_cli/rosa-manage-objects-cli.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,4 +24,5 @@ include::modules/rosa-edit-objects.adoc[leveloffset=+1]
include::modules/rosa-delete-objects.adoc[leveloffset=+1]
include::modules/rosa-install-uninstall-addon.adoc[leveloffset=+1]
include::modules/rosa-list-objects.adoc[leveloffset=+1]
include::modules/rosa-revoke-objects.adoc[leveloffset=+1]
include::modules/rosa-upgrade-cluster-cli.adoc[leveloffset=+1]
67 changes: 67 additions & 0 deletions modules/rosa-create-objects.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,73 @@ Create a cluster administrator that can log in to a cluster named `mycluster`.
$ rosa create admin --cluster=mycluster
----

[id="rosa-create-break-glass-credential_{context}"]
== create break glass credential

Create a break glass credential for a hosted control plane cluster with external authentication enabled.

.Syntax
[source,terminal]
----
$ rosa create break-glass-credential --cluster=<cluster_name> [arguments]
----

.Arguments
[cols="30,70"]
|===
|Option |Definition

|--cluster <cluster_name>\|<cluster_id>
|Required. The name or ID of the cluster to which the break glass credential will be added.

|--expiration
|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.

|--username
|Optional. The username for the break glass credential. If you do not enter a value, a random username is generated for you.
|===

.Optional arguments inherited from parent commands
[cols="30,70"]
|===
|Option |Definition

|--help
|Shows help for this command.

|--debug
|Enables debug mode.

|--interactive
|Enables interactive mode.

|--profile
|Specifies an AWS profile (string) from your credentials file.

|--region
|Specifies an AWS region, overriding the `AWS_REGION` environment variable.

|--yes
|Automatically answers `yes` to confirm the operation.
|===

.Examples
Add a break glass credential to a cluster named `mycluster`.

.Syntax
[source,terminal]
----
$ rosa create break-glass-credential --cluster=mycluster
----

Add a break glass credential to a cluster named `mycluster` using the interactive mode.

.Syntax
[source,terminal]
----
$ rosa create break-glass-credential --cluster=mycluster -i
----

[id="rosa-create-cluster-command_{context}"]
== create cluster

Expand Down
86 changes: 86 additions & 0 deletions modules/rosa-hcp-sts-accessing-a-break-glass-cred-cli.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
// Module included in the following assemblies:
//
// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc
// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-ext-auth.adoc

:_mod-docs-content-type: PROCEDURE
[id="rosa-hcp-sts-accessing-a-break-glass-cred-cli_{context}"]
= Accessing a {hcp-title} cluster by using a break glass credential

Use the new `kubeconfig` from the break glass credential to gain temporary admin access to a {hcp-title} cluster.

.Prerequisites

* 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_.
* You have installed the `oc` and the `kubectl` CLIs.
* You have configured the new `kubeconfig`. For more information, see _Creating a break glass credential for a {hcp-title} cluster_.

.Procedure

. Access the details for the cluster:
+
[source,terminal]
----
$ rosa describe break-glass-credential <break_glass_credential_id> -c <cluster_name> --kubeconfig > $KUBECONFIG
----
+
. List the nodes from the cluster:
+
[source,terminal]
----
$ oc get nodes
----
.Example output
+
[source,terminal]
----
NAME STATUS ROLES AGE VERSION
ip-10-0-0-27.ec2.internal Ready worker 8m v1.28.7+f1b5f6c
ip-10-0-0-67.ec2.internal Ready worker 9m v1.28.7+f1b5f6c
----
. Verify you have the correct credentials:
+
[source,terminal]
----
$ kubectl auth whoami
----
+
.Example output
+
[source,terminal]
----
ATTRIBUTE VALUE
Username system:customer-break-glass:test-user
Groups [system:masters system:authenticated]
----
. 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.
+
[source,terminal]
----
$ oc apply -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: rosa-hcp-admins
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: cluster-admin
subjects:
- apiGroup: rbac.authorization.k8s.io
kind: Group
name: f715c264-ab90-45d5-8a29-2e91a609a895
EOF
----
+
.Example output
+
[source,terminal]
----
clusterrolebinding.rbac.authorization.k8s.io/rosa-hcp-admins created
----
+
[NOTE]
====
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.
====
153 changes: 153 additions & 0 deletions modules/rosa-hcp-sts-creating-a-break-glass-cred-cli.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
// Module included in the following assemblies:
//
// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc
// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-ext-auth.adoc

:_mod-docs-content-type: PROCEDURE
[id="rosa-hcp-sts-creating-a-break-glass-cred-cli_{context}"]
= Creating a break glass credential for a {hcp-title} cluster

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.

.Prerequisites

* 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_.
* You have created an external authentication provider. For more information, see _Creating an external authentication provider_.
* You have an account with `cluster admin` permissions.

.Procedure

. Create a break glass credential by using one of the following commands:

** To create a break glass credential by using the interactive command interface to interactively specify custom settings, run the following command:
+
[source,terminal]
----
$ rosa create break-glass-credential -c <cluster_name> -i <1>
----
<1> Replace <cluster_name> with the name of your cluster.
+
This command starts an interactive CLI process:
+
.Example output
[source,terminal]
----
I: Enabling interactive mode
? Username (optional): <1>
? Expiration duration (optional): <2>
I: Successfully created a break glass credential for cluster 'ac-hcp-test'.
----
<1> If left blank, the value in the `username` will have a randomly generated username value.
<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.
+
** To create a break glass credential for cluster called `mycluster` with specified values:
+
[source,terminal]
----
$ rosa create break-glass-credential -c mycluster --username test-username --expiration 1h
----
+
. List the break glass credential IDs, status, and associated users that are available for a cluster called `mycluster` by running the following command:
+
[source,terminal]
----
$ rosa list break-glass-credential -c mycluster
----
+
.Example output
[source,terminal]
----
ID USERNAME STATUS
2a7jli9n4phe6c02ul7ti91djtv2o51d test-user issued
----
+
[NOTE]
====
You can also view the credentials in a JSON output by adding the `-o json` argument to the command.
====

. To view the status of a break glass credential, run the following command, replacing <break_glass_credential_id> with the break glass credential ID:
+
[source,terminal]
----
$ rosa describe break-glass-credential <break_glass_credential_id> -c <cluster_name>
----
+
.Example output
[source,terminal]
----
ID: 2a7jli9n4phe6c02ul7ti91djtv2o51d
Username: test-user
Expire at: Dec 28 2026 10:23:05 EDT
Status: issued
----
+
The following is a list of possible `Status` field values:
+
* `issued` The break glass credential has been issued and is ready to use.
* `expired` The break glass credential has expired and can no longer be used.
* `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_.
* `awaiting_revocation` The break glass credential is currently being revoked, meaning it cannot be used.
* `revoked` The break glass credential has been revoked and can no longer be used.
+
. To retrieve the `kubeconfig`, run the following commands:
** Create a `kubeconfigs` directory:
+
[source,terminal]
----
$ mkdir ~/kubeconfigs
----
+
** Export the newly generated `kubeconfig` file, replacing <cluster_name> with the name of your cluster:
+
[source,terminal]
----
$ export CLUSTER_NAME=<cluster_name> && export KUBECONFIG=~/kubeconfigs/break-glass-${CLUSTER_NAME}.kubeconfig
----
+
** View the `kubeconfig`:
+
[source,terminal]
----
$ rosa describe break-glass-credential <break_glass_credential_id> -c mycluster --kubeconfig
----
.Example output
+
[source,terminal]
----
apiVersion: v1
clusters:
- cluster:
server: <server_url>
name: cluster
contexts:
- context:
cluster: cluster
namespace: default
user: test-username
name: admin
current-context: admin
kind: Config
preferences: {}
users:
- name: test-user
user:
client-certificate-data: <client-certificate-data> <1>
client-key-data: <client-key-data> <2>
----
<1> The client-certificate contains a certificate for the user signed by the Kubernetes certificate authorities (CA).
<2> The client-key contains the key that signed the client certificate.
+
. Optional: To save the `kubeconfig`, run the following command :
+
[source,terminal]
----
$ rosa describe break-glass-credential <break_glass_credential_id> -c mycluster --kubeconfig > $KUBECONFIG
----







Loading