The following sections describe how to get started with ROSA with hosted control planes (ROSA with HCP) using AWS STS and the ROSA CLI.
For steps to create a ROSA with HCP cluster using Terraform, see the Red Hat documentation
The ROSA CLI uses auto
mode or manual
mode to create the IAM resources and OpenID Connect (OIDC) configuration required to create a ROSA
cluster.
auto
mode automatically creates the required IAM roles and policies and OIDC provider.
manual
mode outputs the AWS CLI commands that are needed to create the IAM resources manually.
By using manual
mode, you can review the generated AWS CLI commands before running them manually.
With manual
mode, you can also pass the commands to another administrator or group in your organization so they can create the resources.
The procedures in this document use the auto
mode of the ROSA CLI to create the required IAM resources and OIDC configuration for ROSA with HCP.
For more options to get started, see Get started with ROSA.
Topics
- Prerequisites
- Create Amazon VPC architecture
- Create the required IAM roles and OpenID Connect configuration
- Create a ROSA with HCP cluster using the ROSA CLI and AWS STS
- Configure an identity provider and grant cluster access
- Grant user access to a cluster
- Configure cluster-admin permissions
- Configure dedicated-admin permissions
- Access a cluster through the Red Hat Hybrid Cloud Console
- Deploy an application from the Developer Catalog
- Revoke cluster-admin permissions from a user
- Revoke dedicated-admin permissions from a user
- Revoke user access to a cluster
- Delete a cluster and AWS STS resources
Prerequisites
Complete the prerequisite actions listed in Set up to use ROSA.
Create Amazon VPC architecture
The following procedure creates Amazon VPC architecture that can be used to host a cluster.
All cluster resources are hosted in the private subnet.
The public subnet routes outbound traffic from the private subnet through a NAT gateway to the public internet.
This example uses the CIDR block 10.0.0.0/16
for the Amazon VPC.
However, you can choose a different CIDR block.
For more information, see VPC sizing.
Important
If Amazon VPC requirements are not met, cluster creation fails.
-
Install the Terraform CLI. For more information, see the install instructions in the Terraform documentation
. -
Open a terminal session and clone the Terraform VPC repository.
git clone https://github.com/openshift-cs/terraform-vpc-example
-
Navigate to the created directory.
cd terraform-vpc-example
-
Initiate the Terraform file.
terraform init
Once complete, the CLI returns a message that Terraform has been successfully initialized.
-
To build a Terraform plan based on the existing template, run the following command. The AWS Region must be specified. Optionally, you can choose to specify a cluster name.
terraform plan -out rosa.tfplan -var region=<region>
Once the command has run, a
rosa.tfplan
file is added to thehypershift-tf
directory. For more detailed options, see the Terraform VPC repository’s README file. -
Apply the plan file to build the VPC.
terraform apply rosa.tfplan
Once complete, the CLI returned a success message that verifies the added resources.
-
(Optional) Create environment variables for the Terraform-provisioned private, public, and machinepool subnet IDs to use when creating your ROSA with HCP cluster.
export SUBNET_IDS=$(terraform output -raw cluster-subnets-string)
-
(Optional) Verify that the environment variables were correctly set.
echo $SUBNET_IDS
-
Create the required IAM roles and OpenID Connect configuration
Before creating a ROSA with HCP cluster, you must create the necessary IAM roles and policies and the OpenID Connect (OIDC) configuration. For more information about IAM roles and policies for ROSA with HCP, see AWS managed policies for ROSA.
This procedure uses the auto
mode of the ROSA CLI to automatically create the OIDC configuration necessary to create a ROSA with HCP cluster.
-
Create the required IAM account roles and policies. The
--force-policy-creation
parameter updates any existing roles and policies that are present. If no roles and policies are present, the command creates these resources instead.rosa create account-roles --force-policy-creation
Note
If your offline access token has expired, the ROSA CLI outputs an error message stating that your authorization token needs updated. For steps to troubleshoot, see Troubleshoot ROSA CLI expired offline access tokens.
-
Create the OpenID Connect (OIDC) configuration that enables user authentication to the cluster. This configuration is registered to be used with OpenShift Cluster Manager (OCM).
rosa create oidc-config --mode=auto
-
Copy the OIDC config ID provided in the ROSA CLI output. The OIDC config ID needs to be provided later to create the ROSA with HCP cluster.
-
To verify the OIDC configurations available for clusters associated with your user organization, run the following command.
rosa list oidc-config
-
Create the required IAM operator roles, replacing
<OIDC_CONFIG_ID>
with the OIDC config ID copied previously.Important
You must supply a prefix in
<PREFIX_NAME>
when creating the Operator roles. Failing to do so produces an error.rosa create operator-roles --prefix <PREFIX_NAME> --oidc-config-id <OIDC_CONFIG_ID> --hosted-cp
-
To verify the IAM operator roles were created, run the following command:
rosa list operator-roles
Create a ROSA with HCP cluster using the ROSA CLI and AWS STS
You can create a ROSA with HCP cluster using AWS Security Token Service (AWS STS) and the auto
mode that’s provided in the ROSA CLI.
You have the option to create a cluster with a public API and Ingress or a private API and Ingress.
You can create a cluster with a single Availability Zone (Single-AZ) or multiple Availability Zones (Multi-AZ). In either case, your machine’s CIDR value must match your VPC’s CIDR value.
The following procedure uses the rosa create cluster --hosted-cp
command to create a Single-AZ ROSA with HCP cluster.
To create a Multi-AZ cluster, specify multi-az
in the command and the private subnet IDs for each private subnet you want you to deploy to.
-
Create a ROSA with HCP cluster with one of the following commands.
-
Create a ROSA with HCP cluster with a public API and Ingress, specifying the cluster name, operator role prefix, OIDC config ID, and public and private subnet IDs.
rosa create cluster --cluster-name=<CLUSTER_NAME> --sts --mode=auto --hosted-cp --operator-roles-prefix <OPERATOR_ROLE_PREFIX> --oidc-config-id <OIDC_CONFIG_ID> --subnet-ids=<PUBLIC_SUBNET_ID>,<PRIVATE_SUBNET_ID>
-
Create a ROSA with HCP cluster with a private API and Ingress, specifying the cluster name, operator role prefix, OIDC config ID, and private subnet IDs.
rosa create cluster --private --cluster-name=<CLUSTER_NAME> --sts --mode=auto --hosted-cp --subnet-ids=<PRIVATE_SUBNET_ID>
-
-
Check the status of your cluster.
rosa describe cluster -c <CLUSTER_NAME>
Note
If the creation process fails or the
State
field doesn’t change to a ready status after 10 minutes, see Troubleshooting.To contact AWS Support or Red Hat support for assistance, see Getting ROSA support.
-
Track the progress of the cluster creation by watching the OpenShift installer logs.
rosa logs install -c <CLUSTER_NAME> --watch
Configure an identity provider and grant cluster access
ROSA includes a built-in OAuth server.
After your cluster is created, you must configure OAuth to use an identity provider.
You can then add users to your configured identity provider to grant them access to your cluster.
You can grant these users cluster-admin
or dedicated-admin
permissions as required.
You can configure different identity provider types for your ROSA cluster. Supported types include GitHub, GitHub Enterprise, GitLab, Google, LDAP, OpenID Connect, and HTPasswd identity providers.
Important
The HTPasswd identity provider is included only to enable a single, static administrator user to be created. HTPasswd isn’t supported as a general-use identity provider for ROSA.
The following procedure configures a GitHub identity provider as an example.
For instructions on how to configure each of the supported identity provider types, see Configuring identity providers for AWS STS
-
Navigate to github.com
and log in to your GitHub account. -
If you don’t have a GitHub organization to use for identity provisioning for your cluster, create one. For more information, see the steps in the GitHub documentation
. -
Using the ROSA CLI’s interactive mode, configure an identity provider for your cluster.
rosa create idp --cluster=<CLUSTER_NAME> --interactive
-
Follow the configuration prompts in the output to restrict cluster access to members of your GitHub organization.
I: Interactive mode enabled. Any optional fields can be left empty and a default will be selected. ? Type of identity provider: github ? Identity provider name: github-1 ? Restrict to members of: organizations ? GitHub organizations: <GITHUB_ORG_NAME> ? To use GitHub as an identity provider, you must first register the application: - Open the following URL: https://github.com/organizations/<GITHUB_ORG_NAME>/settings/applications/new?oauth_application%5Bcallback_url%5D=https%3A%2F%2Foauth-openshift.apps.<CLUSTER_NAME>/<RANDOM_STRING>.p1.openshiftapps.com%2Foauth2callback%2Fgithub-1&oauth_application%5Bname%5D=<CLUSTER_NAME>&oauth_application%5Burl%5D=https%3A%2F%2Fconsole-openshift-console.apps.<CLUSTER_NAME>/<RANDOM_STRING>.p1.openshiftapps.com - Click on 'Register application' ...
-
Open the URL in the output, replacing
<GITHUB_ORG_NAME>
with the name of your GitHub organization. -
On the GitHub web page, choose Register application to register a new OAuth application in your GitHub organization.
-
Use the information from the GitHub OAuth page to populate the remaining
rosa create idp
interactive prompts by running the following command. Replace<GITHUB_CLIENT_ID>
and<GITHUB_CLIENT_SECRET>
with the credentials from your GitHub OAuth application.... ? Client ID: <GITHUB_CLIENT_ID> ? Client Secret: [? for help] <GITHUB_CLIENT_SECRET> ? GitHub Enterprise Hostname (optional): ? Mapping method: claim I: Configuring IDP for cluster '<CLUSTER_NAME>' I: Identity Provider 'github-1' has been created. It will take up to 1 minute for this configuration to be enabled. To add cluster administrators, see 'rosa grant user --help'. To login into the console, open https://console-openshift-console.apps.<CLUSTER_NAME>.<RANDOM_STRING>.p1.openshiftapps.com and click on github-1.
Note
It might take approximately two minutes for the identity provider configuration to become active. If you configured a
cluster-admin
user, you can runoc get pods -n openshift-authentication --watch
to watch the OAuth pods redeploy with the updated configuration. -
Verify that the identity provider is configured correctly.
rosa list idps --cluster=<CLUSTER_NAME>
Grant user access to a cluster
You can grant a user access to your cluster by adding them to the configured identity provider.
The following procedure adds a user to a GitHub organization that’s configured for identity provisioning to the cluster.
-
Navigate to github.com
and log in to your GitHub account. -
Invite users that require cluster access to your GitHub organization. For more information, see Inviting users to join your organization
in the GitHub documentation.
Configure cluster-admin
permissions
-
Grant the
cluster-admin
permissions by running the following command. Replace<IDP_USER_NAME>
and<CLUSTER_NAME>
with your user and cluster name.rosa grant user cluster-admin --user=<IDP_USER_NAME> --cluster=<CLUSTER_NAME>
-
Verify that the user is listed as a member of the
cluster-admins
group.rosa list users --cluster=<CLUSTER_NAME>
Configure dedicated-admin
permissions
-
Grant the
dedicated-admin
permissions by using the following command. Replace<IDP_USER_NAME>
and<CLUSTER_NAME>
with your user and cluster name by running the following command.rosa grant user dedicated-admin --user=<IDP_USER_NAME> --cluster=<CLUSTER_NAME>
-
Verify that the user is listed as a member of the
cluster-admins
group.rosa list users --cluster=<CLUSTER_NAME>
Access a cluster through the Red Hat Hybrid Cloud Console
Log in to your cluster through the Red Hat Hybrid Cloud Console.
-
Obtain the console URL for your cluster using the following command. Replace
<CLUSTER_NAME>
with the name of your cluster.rosa describe cluster -c <CLUSTER_NAME> | grep Console
-
Navigate to the console URL in the output and log in.
In the Log in with… dialog, choose the identity provider name and complete any authorization requests presented by your provider.
Deploy an application from the Developer Catalog
From the Red Hat Hybrid Cloud Console, you can deploy a Developer Catalog test application and expose it with a route.
-
Navigate to Red Hat Hybrid Cloud Console
and choose the cluster you want to deploy the app into. -
On the cluster’s page, choose Open console.
-
In the Administrator perspective, choose Home > Projects > Create Project.
-
Enter a name for your project and optionally add a Display Name and Description.
-
Choose Create to create the project.
-
Switch to the Developer perspective and choose +Add. Make sure that the selected project is the one that was just created.
-
In the Developer Catalog dialog, choose All services.
-
In the Developer Catalog page, choose Languages > JavaScript from the menu.
-
Choose Node.js, and then choose Create Application to open the Create Source-to-Image Application page.
Note
You might need to choose Clear All Filters to display the Node.js option.
-
In the Git section, choose Try Sample.
-
In the Name field, add a unique name.
-
Choose Create.
Note
The new application takes several minutes to deploy.
-
When the deployment is complete, choose the route URL for the application.
A new tab in the browser opens with a message that’s similar to the following.
Welcome to your Node.js application on OpenShift
-
(Optional) Delete the application and clean up resources:
-
In the Administrator perspective, choose Home > Projects.
-
Open the action menu for your project and choose Delete Project.
-
Revoke cluster-admin
permissions from a user
-
Revoke the
cluster-admin
permissions using the following command. Replace<IDP_USER_NAME>
and<CLUSTER_NAME>
with your user and cluster name.rosa revoke user cluster-admin --user=<IDP_USER_NAME> --cluster=<CLUSTER_NAME>
-
Verify that the user isn’t listed as a member of the
cluster-admins
group.rosa list users --cluster=<CLUSTER_NAME>
Revoke dedicated-admin
permissions from a user
-
Revoke the
dedicated-admin
permissions by using the following command. Replace<IDP_USER_NAME>
and<CLUSTER_NAME>
with your user and cluster name.rosa revoke user dedicated-admin --user=<IDP_USER_NAME> --cluster=<CLUSTER_NAME>
-
Verify that the user isn’t listed as a member of the
dedicated-admins
group.rosa list users --cluster=<CLUSTER_NAME>
Revoke user access to a cluster
You can revoke cluster access for an identity provider user by removing them from the configured identity provider.
You can configure different types of identity providers for your cluster. The following procedure revokes cluster access for a member of a GitHub organization.
-
Navigate to github.com
and log in to your GitHub account. -
Remove the user from your GitHub organization. For more information, see Removing a member from your organization
in the GitHub documentation.
Delete a cluster and AWS STS resources
You can use the ROSA CLI to delete a cluster that uses AWS Security Token Service (AWS STS). You can also use the ROSA CLI to delete the IAM roles and OIDC provider created by ROSA. To delete the IAM policies created by ROSA, you can use the IAM console.
Note
IAM roles and policies created by ROSA might be used by other ROSA clusters in the same account.
-
Delete the cluster and watch the logs. Replace
<CLUSTER_NAME>
with the name or ID of your cluster.rosa delete cluster --cluster=<CLUSTER_NAME> --watch
Important
You must wait for the cluster to delete completely before you remove the IAM roles, policies, and OIDC provider. The account IAM roles are required to delete the resources created by the installer. The operator IAM roles are required to clean up the resources created by the OpenShift operators. The operators use the OIDC provider to authenticate.
-
Delete the OIDC provider that the cluster operators use to authenticate by running the following command.
rosa delete oidc-provider -c <CLUSTER_ID> --mode auto
-
Delete the cluster-specific operator IAM roles.
rosa delete operator-roles -c <CLUSTER_ID> --mode auto
-
Delete the account IAM roles using the following command. Replace
<PREFIX>
with the prefix of the account IAM roles to delete. If you specified a custom prefix when creating the account IAM roles, specify the defaultManagedOpenShift
prefix.rosa delete account-roles --prefix <PREFIX> --mode auto
-
Delete the IAM policies created by ROSA.
-
Log in to the IAM console
. -
On the left menu under Access management, choose Policies.
-
Select the policy that you want to delete and choose Actions > Delete.
-
Enter the policy name and choose Delete.
-
Repeat this step to delete each of the IAM policies for the cluster.
-