openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 21:46:22 +01:00
Code Issues Releases Activity

OSDOCS-8373

Browse Source
This commit is contained in:
Janelle Neczypor
2023-11-17 10:33:35 -08:00
committed by openshift-cherrypick-robot
parent d0df64a73f
commit e625fd09b2
2 changed files with 430 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
_topic_maps/_topic_map_rosa.yml
View File

@@ -123,6 +123,8 @@ Topics:
Topics:
- Name: Simple CLI guide
File: cloud-experts-getting-started-simple-cli-guide
- Name: Detailed CLI guide
File: cloud-experts-getting-started-detailed-cli-guide
---
Name: Getting started
Dir: rosa_getting_started

428
cloud_experts_tutorials/cloud-experts-getting-started/cloud-experts-getting-started-deploying/cloud-experts-getting-started-detailed-cli-guide.adoc Normal file
View File

@@ -0,0 +1,428 @@
:_mod-docs-content-type: ASSEMBLY
[id="cloud-experts-getting-started-detailed-cli-guide"]
= Tutorial: Detailed CLI guide
include::_attributes/attributes-openshift-dedicated.adoc[]
:context: cloud-experts-getting-started-detailed-cli-guide
toc::[]
//rosaworkshop.io content metadata
//Brought into ROSA product docs 2023-11-17
This tutorial outlines the detailed steps to deploy a ROSA cluster using the ROSA CLI.
//For a guide to deploying with a user interface, see the *xref needed*[Detailed user interface] page.
== CLI deployment modes
There are two modes with which to deploy a ROSA cluster. One is automatic, which is quicker and performs the manual work for you. The other is manual, requires you to run extra commands, and allows you to inspect the roles and policies being created. This tutorial documents both options.
If you want to create a cluster quickly, use the automatic option. If you prefer exploring the roles and policies being created, use the manual option.
Choose the deployment mode by using the `--mode` flag in the relevant commands.
Valid options for `--mode` are:
* *`manual`:* Role and policies are created and saved in the current directory. You must manually run the provided commands as the next step. This option allows you to review the policy and roles before creating them.
* *`auto`:* Roles and policies are created and applied automatically using the current AWS account.
[TIP]
====
You can use either deployment method for this tutorial. The `auto` mode is faster and has less steps.
====
== Deployment workflow
The overall deployment workflow follows these steps:
. `rosa create account-roles` - This is executed only _once_ for each account. Once created, the account roles do *not* need to be created again for more clusters of the same y-stream version.
. `rosa create cluster`
. `rosa create operator-roles` - For manual mode only.
. `rosa create oidc-provider` - For manual mode only.
For each additional cluster in the same account for the same y-stream version, only step 2 is needed for automatic mode. Steps 2 through 4 are needed for manual mode.
== Automatic mode
Use this method if you want the ROSA CLI to automate the creation of the roles and policies to create your cluster quickly.
=== Creating account roles
If this is the _first time_ you are deploying ROSA in this account and you have _not_ yet created the account roles, then create the account-wide roles and policies, including Operator policies.
Run the following command to create the account-wide roles:
[source,terminal]
----
rosa create account-roles --mode auto --yes
----
.Example output
[source,terminal]
----
I: Creating roles using 'arn:aws:iam::000000000000:user/rosa-user'
I: Created role 'ManagedOpenShift-ControlPlane-Role' with ARN 'arn:aws:iam::000000000000:role/ManagedOpenShift-ControlPlane-Role'
I: Created role 'ManagedOpenShift-Worker-Role' with ARN 'arn:aws:iam::000000000000:role/ManagedOpenShift-Worker-Role'
I: Created role 'ManagedOpenShift-Support-Role' with ARN 'arn:aws:iam::000000000000:role/ManagedOpenShift-Support-Role'
I: Created role 'ManagedOpenShift-Installer-Role' with ARN 'arn:aws:iam::000000000000:role/ManagedOpenShift-Installer-Role'
I: Created policy with ARN 'arn:aws:iam::000000000000:policy/ManagedOpenShift-openshift-machine-api-aws-cloud-credentials'
I: Created policy with ARN 'arn:aws:iam::000000000000:policy/ManagedOpenShift-openshift-cloud-credential-operator-cloud-crede'
I: Created policy with ARN 'arn:aws:iam::000000000000:policy/ManagedOpenShift-openshift-image-registry-installer-cloud-creden'
I: Created policy with ARN 'arn:aws:iam::000000000000:policy/ManagedOpenShift-openshift-ingress-operator-cloud-credentials'
I: Created policy with ARN 'arn:aws:iam::000000000000:policy/ManagedOpenShift-openshift-cluster-csi-drivers-ebs-cloud-credent'
I: To create a cluster with these roles, run the following command:
rosa create cluster --sts
----
=== Creating a cluster
Run the following command to create a cluster with all the default options:
[source,terminal]
----
rosa create cluster --cluster-name <cluster-name> --sts --mode auto --yes
----
[NOTE]
====
This will also create the required Operator roles and OIDC provider. If you want to see all available options for your cluster use the `--help` flag or `--interactive` for interactive mode.
====
.Example input
[source,terminal]
----
$ rosa create cluster --cluster-name my-rosa-cluster --sts --mode auto --yes
----
.Example output
[source,terminal]
----
I: Creating cluster 'my-rosa-cluster'
I: To view a list of clusters and their status, run 'rosa list clusters'
I: Cluster 'my-rosa-cluster' has been created.
I: Once the cluster is installed you will need to add an Identity Provider before you can login into the cluster. See 'rosa create idp --help' for more information.
I: To determine when your cluster is Ready, run 'rosa describe cluster -c my-rosa-cluster'.
I: To watch your cluster installation logs, run 'rosa logs install -c my-rosa-cluster --watch'.
Name: my-rosa-cluster
ID: 1mlhulb3bo0l54ojd0ji000000000000
External ID:
OpenShift Version:
Channel Group: stable
DNS: my-rosa-cluster.ibhp.p1.openshiftapps.com
AWS Account: 000000000000
API URL:
Console URL:
Region: us-west-2
Multi-AZ: false
Nodes:
- Master: 3
- Infra: 2
- Compute: 2
Network:
- Service CIDR: 172.30.0.0/16
- Machine CIDR: 10.0.0.0/16
- Pod CIDR: 10.128.0.0/14
- Host Prefix: /23
STS Role ARN: arn:aws:iam::000000000000:role/ManagedOpenShift-Installer-Role
Support Role ARN: arn:aws:iam::000000000000:role/ManagedOpenShift-Support-Role
Instance IAM Roles:
- Master: arn:aws:iam::000000000000:role/ManagedOpenShift-ControlPlane-Role
- Worker: arn:aws:iam::000000000000:role/ManagedOpenShift-Worker-Role
Operator IAM Roles:
- arn:aws:iam::000000000000:role/my-rosa-cluster-openshift-image-registry-installer-cloud-credentials
- arn:aws:iam::000000000000:role/my-rosa-cluster-openshift-ingress-operator-cloud-credentials
- arn:aws:iam::000000000000:role/my-rosa-cluster-openshift-cluster-csi-drivers-ebs-cloud-credentials
- arn:aws:iam::000000000000:role/my-rosa-cluster-openshift-machine-api-aws-cloud-credentials
- arn:aws:iam::000000000000:role/my-rosa-cluster-openshift-cloud-credential-operator-cloud-credential-oper
State: waiting (Waiting for OIDC configuration)
Private: No
Created: Oct 28 2021 20:28:09 UTC
Details Page: https://console.redhat.com/openshift/details/s/1wupmiQy45xr1nN000000000000
OIDC Endpoint URL: https://rh-oidc.s3.us-east-1.amazonaws.com/1mlhulb3bo0l54ojd0ji000000000000
----
==== Default configuration
The default settings are as follows:
* Nodes:
** 3 control plane nodes
** 2 infrastructure nodes
** 2 worker nodes
** No autoscaling
** See the documentation on xref:../../../rosa_planning/rosa-sts-aws-prereqs.adoc#rosa-ec2-instances_rosa-sts-aws-prereqs[ec2 instances] for more details.
* Region: As configured for the `aws` CLI
* Networking IP ranges:
** Machine CIDR: 10.0.0.0/16
** Service CIDR: 172.30.0.0/16
** Pod CIDR: 10.128.0.0/14
* New VPC
* Default AWS KMS key for encryption
* The most recent version of OpenShift available to `rosa`
* A single availability zone
* Public cluster
=== Checking the installation status
. Run one of the following commands to check the status of your cluster:
+
* For a detailed view of the status, run:
+
[source,terminal]
----
rosa describe cluster --cluster <cluster-name>
----
* For an abridged view of the status, run:
+
[source,terminal]
----
rosa list clusters
----
. The cluster state will change from “waiting” to “installing” to "ready". This will take about 40 minutes.
. Once the state changes to “ready” your cluster is installed.
== Manual Mode
If you want to review the roles and policies before applying them to a cluster, use the manual method. This method requires running a few extra commands to create the roles and policies.
This section uses the `--interactive` mode. See the documentation on xref:../../../rosa_install_access_delete_clusters/rosa-sts-interactive-mode-reference.adoc#rosa-sts-interactive-mode-reference[interactive mode] for a description of the fields in this section.
=== Creating account roles
. If this is the _first time_ you are deploying ROSA in this account and you have _not_ yet created the account roles, create the account-wide roles and policies, including the Operator policies. The command creates the needed JSON files for the required roles and policies for your account in the current directory. It also outputs the `aws` CLI commands that you need to run to create these objects.
+
Run the following command to create the needed files and output the additional commands:
+
[source,terminal]
----
rosa create account-roles --mode manual
----
+
.Example output
[source,terminal]
----
I: All policy files saved to the current directory
I: Run the following commands to create the account roles and policies:
aws iam create-role \
--role-name ManagedOpenShift-Worker-Role \
--assume-role-policy-document file://sts_instance_worker_trust_policy.json \
--tags Key=rosa_openshift_version,Value=4.8 Key=rosa_role_prefix,Value=ManagedOpenShift Key=rosa_role_type,Value=instance_worker
aws iam put-role-policy \
--role-name ManagedOpenShift-Worker-Role \
--policy-name ManagedOpenShift-Worker-Role-Policy \
--policy-document file://sts_instance_worker_permission_policy.json
----
. Check the contents of your current directory to see the new files. Use the `aws` CLI to create each of these objects.
+
.Example output
[source,terminal]
----
$ ls
openshift_cloud_credential_operator_cloud_credential_operator_iam_ro_creds_policy.json
sts_instance_controlplane_permission_policy.json
openshift_cluster_csi_drivers_ebs_cloud_credentials_policy.json sts_instance_controlplane_trust_policy.json
openshift_image_registry_installer_cloud_credentials_policy.json sts_instance_worker_permission_policy.json
openshift_ingress_operator_cloud_credentials_policy.json sts_instance_worker_trust_policy.json
openshift_machine_api_aws_cloud_credentials_policy.json sts_support_permission_policy.json
sts_installer_permission_policy.json sts_support_trust_policy.json
sts_installer_trust_policy.json
----
. *Optional:* Open the files to review what you will create. For example, opening the `sts_installer_permission_policy.json` shows:
+
.Example output
+
[source,terminal]
----
$ cat sts_installer_permission_policy.json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"autoscaling:DescribeAutoScalingGroups",
"ec2:AllocateAddress",
"ec2:AssociateAddress",
"ec2:AssociateDhcpOptions",
"ec2:AssociateRouteTable",
"ec2:AttachInternetGateway",
"ec2:AttachNetworkInterface",
"ec2:AuthorizeSecurityGroupEgress",
"ec2:AuthorizeSecurityGroupIngress",
[...]
----
+
You can also see the contents in the xref:../../../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-account-wide-roles-and-policies-creation-methods_rosa-sts-about-iam-resources[About IAM resources for ROSA clusters] documentation.
. Run the `aws` commands listed in step 1. You can copy and paste if you are in the same directory as the JSON files you created.
=== Creating a cluster
. After the `aws` commands are executed successfully, run the following command to begin ROSA cluster creation in interactive mode:
+
[source,terminal]
----
rosa create cluster --interactive --sts
----
+
See the xref:../../../rosa_install_access_delete_clusters/rosa-sts-interactive-mode-reference.adoc#rosa-sts-interactive-mode-reference[ROSA documentation] for a description of the fields.
. For the purpose of this tutorial, copy and then input the following values:
+
[source,terminal]
----
Cluster name: **my-rosa-cluster** <br>
OpenShift version: **&lt;choose version&gt;** <br>
External ID (optional): **&lt;leave blank&gt;**<br>
Operator roles prefix: **&lt;accept default&gt;** <br>
Multiple availability zones: **No** <br>
AWS region: **&lt;choose region&gt;** <br>
PrivateLink cluster: **No** <br>
Install into an existing VPC: **No** <br>
Enable Customer Managed key: **No** <br>
Compute nodes instance type: **m5.xlarge** <br>
Enable autoscaling: **No** <br>
Compute nodes: **2** <br>
Machine CIDR: **&lt;accept default&gt;** <br>
Service CIDR: **&lt;accept default&gt;** <br>
Pod CIDR: **&lt;accept default&gt;** <br>
Host prefix: **&lt;accept default&gt;** <br>
Encrypt etcd data (optional): **No** <br>
Disable Workload monitoring: **No** <br>
----
+
.Example output
+
[source,terminal]
----
I: Creating cluster 'my-rosa-cluster'
I: To create this cluster again in the future, you can run:
rosa create cluster --cluster-name my-rosa-cluster --role-arn arn:aws:iam::000000000000:role/ManagedOpenShift-Installer-Role --support-role-arn arn:aws:iam::000000000000:role/ManagedOpenShift-Support-Role --master-iam-role arn:aws:iam::000000000000:role/ManagedOpenShift-ControlPlane-Role --worker-iam-role arn:aws:iam::000000000000:role/ManagedOpenShift-Worker-Role --operator-roles-prefix my-rosa-cluster --region us-west-2 --version 4.8.13 --compute-nodes 2 --machine-cidr 10.0.0.0/16 --service-cidr 172.30.0.0/16 --pod-cidr 10.128.0.0/14 --host-prefix 23
I: To view a list of clusters and their status, run 'rosa list clusters'
I: Cluster 'my-rosa-cluster' has been created.
I: Once the cluster is installed you will need to add an Identity Provider before you can login into the cluster. See 'rosa create idp --help' for more information.
Name: my-rosa-cluster
ID: 1t6i760dbum4mqltqh6o000000000000
External ID:
OpenShift Version:
Channel Group: stable
DNS: my-rosa-cluster.abcd.p1.openshiftapps.com
AWS Account: 000000000000
API URL:
Console URL:
Region: us-west-2
Multi-AZ: false
Nodes:
- Control plane: 3
- Infra: 2
- Compute: 2
Network:
- Service CIDR: 172.30.0.0/16
- Machine CIDR: 10.0.0.0/16
- Pod CIDR: 10.128.0.0/14
- Host Prefix: /23
STS Role ARN: arn:aws:iam::000000000000:role/ManagedOpenShift-Installer-Role
Support Role ARN: arn:aws:iam::000000000000:role/ManagedOpenShift-Support-Role
Instance IAM Roles:
- Control plane: arn:aws:iam::000000000000:role/ManagedOpenShift-ControlPlane-Role
- Worker: arn:aws:iam::000000000000:role/ManagedOpenShift-Worker-Role
Operator IAM Roles:
- arn:aws:iam::000000000000:role/my-rosa-cluster-w7i6-openshift-ingress-operator-cloud-credentials
- arn:aws:iam::000000000000:role/my-rosa-cluster-w7i6-openshift-cluster-csi-drivers-ebs-cloud-credentials
- arn:aws:iam::000000000000:role/my-rosa-cluster-w7i6-openshift-cloud-network-config-controller-cloud-cre
- arn:aws:iam::000000000000:role/my-rosa-cluster-openshift-machine-api-aws-cloud-credentials
- arn:aws:iam::000000000000:role/my-rosa-cluster-openshift-cloud-credential-operator-cloud-credentia
- arn:aws:iam::000000000000:role/my-rosa-cluster-openshift-image-registry-installer-cloud-credential
State: waiting (Waiting for OIDC configuration)
Private: No
Created: Jul 1 2022 22:13:50 UTC
Details Page: https://console.redhat.com/openshift/details/s/2BMQm8xz8Hq5yEN000000000000
OIDC Endpoint URL: https://rh-oidc.s3.us-east-1.amazonaws.com/1t6i760dbum4mqltqh6o000000000000
I: Run the following commands to continue the cluster creation:
rosa create operator-roles --cluster my-rosa-cluster
rosa create oidc-provider --cluster my-rosa-cluster
I: To determine when your cluster is Ready, run 'rosa describe cluster -c my-rosa-cluster'.
I: To watch your cluster installation logs, run 'rosa logs install -c my-rosa-cluster --watch'.
----
+
[NOTE]
====
The cluster state will remain as “waiting” until the next two steps are completed.
====
=== Creating Operator roles
. The above step outputs the next commands to run. These roles need to be created _once_ for _each_ cluster. To create the roles run the following command:
+
[source,terminal]
----
rosa create operator-roles --mode manual --cluster <cluster-name>
----
+
.Example output
+
[source,terminal]
----
I: Run the following commands to create the operator roles:
aws iam create-role \
--role-name my-rosa-cluster-openshift-image-registry-installer-cloud-credentials \
--assume-role-policy-document file://operator_image_registry_installer_cloud_credentials_policy.json \
--tags Key=rosa_cluster_id,Value=1mkesci269png3tck000000000000000 Key=rosa_openshift_version,Value=4.8 Key=rosa_role_prefix,Value= Key=operator_namespace,Value=openshift-image-registry Key=operator_name,Value=installer-cloud-credentials
aws iam attach-role-policy \
--role-name my-rosa-cluster-openshift-image-registry-installer-cloud-credentials \
--policy-arn arn:aws:iam::000000000000:policy/ManagedOpenShift-openshift-image-registry-installer-cloud-creden
[...]
----
. Run each of the `aws` commands.
=== Creating the OIDC provider
. Run the following command to create the OIDC provider:
+
[source,terminal]
----
rosa create oidc-provider --mode manual --cluster <cluster-name>
----
. This displays the `aws` commands that you need to run.
+
.Example output
+
[source,terminal]
----
I: Run the following commands to create the OIDC provider:
$ aws iam create-open-id-connect-provider \
--url https://rh-oidc.s3.us-east-1.amazonaws.com/1mkesci269png3tckknhh0rfs2da5fj9 \
--client-id-list openshift sts.amazonaws.com \
--thumbprint-list a9d53002e97e00e043244f3d170d000000000000
$ aws iam create-open-id-connect-provider \
--url https://rh-oidc.s3.us-east-1.amazonaws.com/1mkesci269png3tckknhh0rfs2da5fj9 \
--client-id-list openshift sts.amazonaws.com \
--thumbprint-list a9d53002e97e00e043244f3d170d000000000000
----
. Your cluster will now continue the installation process.
=== Checking the installation status
. Run one of the following commands to check the status of your cluster:
+
* For a detailed view of the status, run:
+
[source,terminal]
----
rosa describe cluster --cluster <cluster-name>
----
* For an abridged view of the status, run:
+
[source,terminal]
----
rosa list clusters
----
. The cluster state will change from “waiting” to “installing” to "ready". This will take about 40 minutes.
. Once the state changes to “ready” your cluster is installed.
== Obtaining the console URL
* To obtain the console URL, run the following command:
+
[source,terminal]
----
rosa describe cluster -c <cluster-name> | grep Console
----
The cluster has now been successfully deployed. The next tutorial shows how to create an admin user to be able to use the cluster immediately.