Getting started
Getting started with Amazon Managed Red Hat OpenShift 4
Abstract
Chapter 1. Getting started with Red Hat OpenShift Service on AWS
This guide walks you through setting up your first Red Hat OpenShift Service on AWS cluster using rosa
, the Red Hat OpenShift Service on AWS command-line utility.
1.1. Quick start instructions
If you have already installed the required prerequisites, here are the commands you need to create a cluster.
## Configures your AWS account and ensures everything is setup correctly $ rosa init ## Starts the cluster creation process (~30-40minutes) and watches the logs $ rosa create cluster --cluster-name <cluster_name> --watch ## Connect your IDP to your cluster $ rosa create idp --cluster <cluster_name> --interactive ## Promotes a user from your IDP to dedicated-admin level $ rosa grant user dedicated-admin --user <idp_user_name> --cluster <cluster_name> ## Checks if your install is ready (look for State: Ready), ## and provides your Console URL to login to the web console. $ rosa describe cluster <cluster_name>
For additional help, consult the rest of this guide. By the end of this guide, you will have an Red Hat OpenShift Service on AWS cluster running in your AWS account.
Chapter 2. Getting started with Red Hat OpenShift Service on AWS
2.1. Installing prerequisites
Complete the following prerequisites before creating your Red Hat OpenShift Service on AWS cluster.
Procedure
Select the AWS account you want to use.
Unless you are just testing out Red Hat OpenShift Service on AWS, it is recommended to use a dedicated AWS account to run any production clusters. If you are using AWS Organizations, you can use an AWS account within your organization or create a new one.
If you are using AWS organizations and you need to have a Service Control Policy (SCP) applied to the AWS account you plan to use, see the Red Hat Requirements for Customer Cloud Subscriptions for details on the minimum required SCP.
As part of the cluster creation process,
rosa
will create an osdCcsAdmin IAM user. This user will leverage the IAM credentials you provide when configuring the AWS CLI.NoteThis user will have Programmatic access enabled and the AdministratorAccess policy attached to it.
Install and configure the AWS CLI.
- Follow the AWS Command Line Interface documentation to install and configure the AWS CLI for your operating system.
Optional: Set a default AWS region.
rosa
evaluates regions in the following priority order:-
The region specified when running a
rosa
command with the--region
flag. -
The region set in the
AWS_DEFAULT_REGION
environment variable. See Environment variables to configure the AWS CLI in the AWS documentation. - The default region set in your AWS configuration file. See Quick configuration with aws configure in the AWS documentation.
-
The region specified when running a
Optional: Configure your AWS CLI settings and credentials by using an AWS named profile.
rosa
evaluates AWS named profiles in the following priority order:-
The profile specified when running a
rosa
command with the--profile
flag. -
The profile set in the
AWS_PROFILE
environment variable. See Named profiles in the AWS documentation.
-
The profile specified when running a
Verify the AWS CLI is installed and configured correctly by running the following command to query the AWS API:
$ aws ec2 describe-regions
Example output
--------------------------------------------------------------------------------- | DescribeRegions | +-------------------------------------------------------------------------------+ || Regions || |+-----------------------------------+-----------------------+-----------------+| || Endpoint | OptInStatus | RegionName || |+-----------------------------------+-----------------------+-----------------+| || ec2.eu-north-1.amazonaws.com | opt-in-not-required | eu-north-1 || || ec2.ap-south-1.amazonaws.com | opt-in-not-required | ap-south-1 || || ec2.eu-west-3.amazonaws.com | opt-in-not-required | eu-west-3 || || ec2.eu-west-2.amazonaws.com | opt-in-not-required | eu-west-2 || || ec2.eu-west-1.amazonaws.com | opt-in-not-required | eu-west-1 || || ec2.ap-northeast-2.amazonaws.com | opt-in-not-required | ap-northeast-2 || || ec2.ap-northeast-1.amazonaws.com | opt-in-not-required | ap-northeast-1 || || ec2.sa-east-1.amazonaws.com | opt-in-not-required | sa-east-1 || || ec2.ca-central-1.amazonaws.com | opt-in-not-required | ca-central-1 || || ec2.ap-southeast-1.amazonaws.com | opt-in-not-required | ap-southeast-1 || || ec2.ap-southeast-2.amazonaws.com | opt-in-not-required | ap-southeast-2 || || ec2.eu-central-1.amazonaws.com | opt-in-not-required | eu-central-1 || || ec2.us-east-1.amazonaws.com | opt-in-not-required | us-east-1 || || ec2.us-east-2.amazonaws.com | opt-in-not-required | us-east-2 || || ec2.us-west-1.amazonaws.com | opt-in-not-required | us-west-1 || || ec2.us-west-2.amazonaws.com | opt-in-not-required | us-west-2 || |+-----------------------------------+-----------------------+-----------------+|
Install
rosa
, the Red Hat OpenShift Service on AWS Command-line Interface (CLI).-
Download the latest release of
rosa
for your operating system. -
Optional: Rename the executable file you downloaded to
rosa
. This documentation usesrosa
to refer to the executable file. -
Optional: Add
rosa
to your path. Verify your installation by running the following command:
$ rosa
Example output
Command line tool for ROSA. Usage: rosa [command] Available Commands: completion Generates bash completion scripts create Create a resource from stdin delete Delete a specific resource describe Show details of a specific resource edit Edit a specific resource help Help about any command init Applies templates to support Managed OpenShift on AWS clusters list List all resources of a specific type login Log in to your Red Hat account logout Log out logs Show logs of a specific resource verify Verify resources are configured correctly for cluster install version Prints the version of the tool Flags: --debug Enable debug mode. -h, --help help for rosa -v, --v Level log level for V logs Use "rosa [command] --help" for more information about a command.
Optional: You can run the
rosa completion
command to generate a bash completion file.$ rosa completion > /etc/bash_completion.d/rosa
Add this file to the correct location for your operating system. For example, on a Linux machine run the following command to enable
rosa
bash completion:$ source /etc/bash_completion.d/rosa
-
Download the latest release of
Run the following command to verify that your AWS account has the necessary permissions:
$ rosa verify permissions
Example output
I: Validating SCP policies... I: AWS SCP policies ok
Verify that your AWS account has the necessary quota to deploy an Red Hat OpenShift Service on AWS cluster.
$ rosa verify quota --region=us-west-2
Example output
I: Validating AWS quota... I: AWS quota ok
NoteSometimes your AWS quota varies by region. If you receive any errors, try a different region.
If you need to increase your quota, navigate to your AWS console, and request a quota increase for the service that failed.
After both the permissions and quota checks pass, proceed to preparing your AWS account for cluster deployment.
Prepare your AWS account for cluster deployment
Run the following command to log in to your Red Hat account with
rosa
.$ rosa login
Replace
<my_offline_access_token>
with your token.Example output
To login to your Red Hat account, get an offline access token at https://cloud.redhat.com/openshift/token/rosa ? Copy the token and paste it here: <my-offline-access-token>
NoteIf you do not already have a Red Hat account, follow this link to create one. Accept the required terms and conditions. Then, check your email for a verification link.
Example output continued
I: Logged in as 'rh-rosa-user' on 'https://api.openshift.com'
Run the following command to verify your Red Hat and AWS credentials are setup correctly. Check that your AWS Account ID, Default Region and ARN match what you expect. You can safely ignore the rows beginning with OCM for now (OCM stands for OpenShift Cluster Manager).
$ rosa whoami
Example output
AWS Account ID: 000000000000 AWS Default Region: us-east-2 AWS ARN: arn:aws:iam::000000000000:user/hello OCM API: https://api.openshift.com OCM Account ID: 1DzGIdIhqEWyt8UUXQhSoWaaaaa OCM Account Name: Your Name OCM Account Username: you@domain.com OCM Account Email: you@domain.com OCM Organization ID: 1HopHfA2hcmhup5gCr2uH5aaaaa OCM Organization Name: Red Hat OCM Organization External ID: 0000000
Initialize your AWS account. This step runs a CloudFormation template that prepares your AWS account for cluster deployment and management. This step typically takes 1-2 minutes to complete.
$ rosa init
Example output
I: Logged in as 'rh-rosa-user' on 'https://api.openshift.com' I: Validating AWS credentials... I: AWS credentials are valid! I: Validating SCP policies... I: AWS SCP policies ok I: Validating AWS quota... I: AWS quota ok I: Ensuring cluster administrator user 'osdCcsAdmin'... I: Admin user 'osdCcsAdmin' created successfully! I: Verifying whether OpenShift command-line tool is available... E: OpenShift command-line tool is not installed. Run 'rosa download oc' to download the latest version, then add it to your PATH.
NoteIf you have not already installed the OpenShift Command-line Interface (CLI), also known as
oc
, runrosa download oc
to download the latest version, then add it to your PATH.
After completing these steps you are ready to create an Red Hat OpenShift Service on AWS cluster.
Chapter 3. Getting started with Red Hat OpenShift Service on AWS
3.1. Creating your cluster
You can create an Red Hat OpenShift Service on AWS cluster using rosa
.
Prerequisites
You have completed the installation prerequisites.
Procedure
Enter the following command to create your cluster with the default cluster settings.
To view other options when creating a cluster, enter rosa create cluster --help
.
To follow a set of interactive prompts, enter rosa create cluster --interactive
.
$ rosa create cluster --cluster-name=rh-rosa-test-cluster1
Example output
I: Creating cluster with identifier '1de87g7c30g75qechgh7l5b2bha6r04e' and name 'rh-rosa-test-cluster1' I: To view list of clusters and their status, run `rosa list clusters` I: Cluster 'rh-rosa-test-cluster1' has been created. I: Once the cluster is 'Ready' you will need to add an Identity Provider and define the list of cluster administrators. See `rosa create idp --help` and `rosa create user --help` for more information. I: To determine when your cluster is Ready, run `rosa describe cluster rh-rosa-test-cluster1`.
Creating a cluster can take up to 40 minutes.
Enter the following command to check the status of your cluster. During cluster creation the State
field from the output will transition from pending
to installing
, and finally to ready
.
$ rosa describe cluster rh-rosa-test-cluster1
Example output
Name: rh-rosa-test-cluster1 ID: 1de87g7c30g75qechgh7l5b2bha6r04e External ID: 34322be7-b2a7-45c2-af39-2c684ce624e1 API URL: https://api.rh-rosa-test-cluster1.j9n4.s1.devshift.org:6443 Console URL: https://console-openshift-console.apps.rh-rosa-test-cluster1.j9n4.s1.devshift.org Nodes: Master: 3, Infra: 3, Compute: 4 Region: us-east-2 State: ready Created: May 27, 2020
If installation fails or the State
field does not change to ready
after 40 minutes, check the installation troubleshooting documentation for more details.
Enter the following command to follow the OpenShift installer logs to track the progress of your cluster:
$ rosa logs install rh-rosa-test-cluster1 --watch
Chapter 4. Getting started with Red Hat OpenShift Service on AWS
4.1. Accessing your cluster
To log in to your cluster, you must configure an identity provider (IDP). This procedure uses GitHub as an example IDP. To view other supported IDPs, run rosa create idp --help
.
Procedure
Add an IDP.
The following command creates an IDP backed by GitHub. After running the command, follow the interactive prompts from the output to access your GitHub developer settings and configure a new OAuth application.
$ rosa create idp --cluster=rh-rosa-test-cluster --interactive
Enter the following values:
-
Type of identity provider:
github
-
Restrict to members of:
organizations
(if you do not have a GitHub Organization, you can create one now.) -
GitHub organizations:
rh-test-org
(enter the name of your org)
Example output
I: Interactive mode enabled. Any optional fields can be left empty and a default will be selected. ? Type of identity provider: github ? Restrict to members of: organizations ? GitHub organizations: rh-test-org ? To use GitHub as an identity provider, you must first register the application: - Open the following URL: https://github.com/organizations/rh-rosa-test-cluster/settings/applications/new?oauth_application%5Bcallback_url%5D=https%3A%2F%2Foauth-openshift.apps.rh-rosa-test-cluster.z7v0.s1.devshift.org%2Foauth2callback%2Fgithub-1&oauth_application%5Bname%5D=rh-rosa-test-cluster-stage&oauth_application%5Burl%5D=https%3A%2F%2Fconsole-openshift-console.apps.rh-rosa-test-cluster.z7v0.s1.devshift.org - Click on 'Register application' ...
-
Type of identity provider:
- Follow the URL from the output. This creates a new OAuth application in the GitHub organization you specified.
- Click Register applicaton to access your Client ID and Client Secret.
Use the information from the GitHub application you created and continue the prompts. Enter the following values:
-
Client ID:
<my_github_client_id>
-
Client Secret: [? for help]
<my_github_client_secret>
- Hostname: (optional, you can leave it blank for now)
-
Mapping method:
claim
Continued example output
... ? Client ID: <my_github_client_id> ? Client Secret: [? for help] <my_github_client_secret> ? Hostname: ? Mapping method: claim I: Configuring IDP for cluster 'rh_rosa_test_cluster' I: Identity Provider 'github-1' has been created. You need to ensure that there is a list of cluster administrators defined. See 'rosa create user --help' for more information. To login into the console, open https://console-openshift-console.apps.rh-test-org.z7v0.s1.devshift.org and click on github-1
The IDP can take 1-2 minutes to be configured within your cluster.
-
Client ID:
Enter the following command to verify that your IDP has been configured correctly:
$ rosa list idps --cluster rh-rosa-test-cluster1
Example output
NAME TYPE AUTH URL github-1 GitHub https://oauth-openshift.apps.rh-rosa-test-cluster1.j9n4.s1.devshift.org/oauth2callback/github-1
Log in to your cluster.
Enter the following command to get the
Console URL
of your cluster:$ rosa describe cluster rh-rosa-test-cluster1
Example output
Name: rh-rosa-test-cluster1 ID: 1de87g7c30g75qechgh7l5b2bha6r04e External ID: 34322be7-b2a7-45c2-af39-2c684ce624e1 API URL: https://api.rh-rosa-test-cluster1.j9n4.s1.devshift.org:6443 Console URL: https://console-openshift-console.apps.rh-rosa-test-cluster1.j9n4.s1.devshift.org Nodes: Master: 3, Infra: 3, Compute: 4 Region: us-east-2 State: ready Created: May 27, 2020
-
Navigate to the
Console URL
, and log in using your Github credentials. - In the top right of the OpenShift console, click your name and click Copy Login Command.
- Select the name of the IDP you added (in our case github-1), and click Display Token.
Copy and paste the
oc
login command into your terminal.$ oc login --token=z3sgOGVDk0k4vbqo_wFqBQQTnT-nA-nQLb8XEmWnw4X --server=https://api.rh-rosa-test-cluster1.j9n4.s1.devshift.org:6443
Example output
Logged into "https://api.rh-rosa-cluster1.j9n4.s1.devshift.org:6443" as "rh-rosa-test-user" using the token provided. You have access to 67 projects, the list has been suppressed. You can list all projects with 'oc projects' Using project "default".
Enter a simple
oc
command to verify everything is setup properly and that you are logged in.$ oc version
Example output
Client Version: 4.4.0-202005231254-4a4cd75 Server Version: 4.3.18 Kubernetes Version: v1.16.2
4.2. Granting cluster-admin
access
As the user who created the cluster, add the cluster-admin
user role to your account to have the maximum administrator privileges. These privileges are not automatically assigned to your user account when you create the cluster.
Additionally, only the user who created the cluster can grant cluster access to other cluster-admin
or dedicated-admin
users. Users with dedicated-admin
access have fewer privileges. As a best practice, limit the number of cluster-admin
users to as few as possible.
Prerequisites
- You have added an identity provider (IDP) to your cluster.
- You have the IDP user name for the user you are creating.
- You are logged in to the cluster.
Procedure
Enable
cluster-admin
capability on the cluster:$ rosa edit cluster <cluster_name> --enable-cluster-admins
Give your user
cluster-admin
privileges:$ rosa grant user cluster-admin --user <idp_user_name> --cluster <cluster_name>
Verify your user is listed as a cluster administrator:
$ rosa list users --cluster <cluster_name>
Example output
GROUP NAME cluster-admins rh-rosa-test-user dedicated-admins rh-rosa-test-user
Enter the following command to verify that your user now has
cluster-admin
access. A cluster administrator can run this command without errors, but a dedicated administrator cannot.$ oc get all -n openshift-apiserver
Example output
NAME READY STATUS RESTARTS AGE pod/apiserver-6ndg2 1/1 Running 0 17h pod/apiserver-lrmxs 1/1 Running 0 17h pod/apiserver-tsqhz 1/1 Running 0 17h NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/api ClusterIP 172.30.23.241 <none> 443/TCP 18h NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE daemonset.apps/apiserver 3 3 3 3 3 node-role.kubernetes.io/master= 18h
4.3. Granting dedicated-admin
access
Only the user who created the cluster can grant cluster access to other cluster-admin
or dedicated-admin
users. Users with dedicated-admin
access have fewer privileges. As a best practice, grant dedicated-admin
access to most of your administrators.
Prerequisites
- You have added an identity provider (IDP) to your cluster.
- You have the IDP user name for the user you are creating.
- You are logged in to the cluster.
Procedure
Enter the following command to promote your user to a
dedicated-admin
:$ rosa grant user dedicated-admin --user <idp_user_name> --cluster <cluster_name>
Enter the following command to verify that your user now has
dedicated-admin
access:$ oc get groups dedicated-admins
Example output
NAME USERS dedicated-admins rh-rosa-test-user
NoteA
Forbidden
error displays if user withoutdedicated-admin
privileges runs this command.
Chapter 5. Getting started with Red Hat OpenShift Service on AWS
5.1. Revoking dedicated-admin
access
Only the user who created the cluster can revoke access for a dedicated-admin
users.
Prerequisites
- You have added an Identity Provider (IDP) to your cluster.
- You have the IDP user name for the user whose privileges you are revoking.
- You are logged in to the cluster.
Procedure
Enter the following command to revoke access for a
dedicated-admin
:$ rosa revoke user dedicated-admin --user <idp_user_name> --cluster <cluster_name>
Enter the following command to verify that your user no longer has
dedicated-admin
access. The user will not be listed in the output.$ oc get groups dedicated-admins
NoteA
Forbidden
error displays if user withoutdedicated-admin
privileges runs this command.
5.2. Revoking cluster-admin
access
Only the user who created the cluster can revoke access for cluster-admin
users.
Prerequisites
- You have added an Identity Provider (IDP) to your cluster.
- You have the IDP user name for the user whose privileges you are revoking.
- You are logged in to the cluster.
Procedure
Revoke the user
cluster-admin
privileges:$ rosa revoke user --cluster <cluster_name> --cluster-admins <idp_user_name>
Verify your user is no longer listed as a
cluster-admin
:$ rosa list users --cluster <cluster_name>
Chapter 6. Getting started with Red Hat OpenShift Service on AWS
6.1. Deleting your cluster
You can delete an Red Hat OpenShift Service on AWS cluster using rosa
.
Procedure
Enter the following command to delete your cluster and watch the logs, replacing <my-cluster>
with the name of your cluster:
$ rosa delete cluster <my-cluster> --watch
To clean up your CloudFormation stack, enter the following command. Your CloudFormation stack is initially created when you run the rosa init
command as part of the prerequisites.
$ rosa init --delete-stack
Chapter 7. FAQ
This guide covers frequently asked questions (FAQs) about Red Hat OpenShift Service on AWS.
7.1. Installation troubleshooting
7.1.1. Inspect install or uninstall logs
To display install logs:
Run the following command, replacing
<my_cluster_name>
with the name of your cluster:$ rosa logs install <my_cluster_name>
To watch the logs, include the
--watch
flag:$ rosa logs install <my_cluster_name> --watch
To display uninstall logs:
Run the following command, replacing
<my_cluster_name>
with the name of your cluster:$ rosa logs uninstall <my_cluster_name>
To watch the logs, include the
--watch
flag:$ rosa logs uninstall <my_cluster_name> --watch
7.1.2. Verify your Amazon Web Services (AWS) account does not have an SCP
Run the following command to verify your AWS account has the correct permissions:
$ rosa verify permissions
If you receive any errors, double check to ensure than an SCP is not applied to your AWS account. If you are required to use an SCP, see Red Hat Requirements for Customer Cloud Subscriptions for details on the minimum required SCP.
7.1.3. Verify your AWS account and quota
Run the following command to verify you have the available quota on your AWS account:
$ rosa verify quota
AWS quotas change based on region. Be sure you are verifying your quota for the correct AWS region. If you need to increase your quota, navigate to your AWS console, and request a quota increase for the service that failed.
7.1.4. Deployment failures
Failures in deployment are shown by putting the cluster state in “error”.
Run the following command to get more information:
$ rosa describe cluster -c <my_cluster_name> --debug
7.1.5. AWS notification emails
When creating a cluster, the Red Hat OpenShift Service on AWS service creates small instances in all supported regions. This check ensures the AWS account being used can deploy to each supported region.
For AWS accounts that are not using all supported regions, AWS may send one or more emails confirming that "Your Request For Accessing AWS Resources Has Been Validated". Typically the sender of this email is aws-verification@amazon.com.
This is expected behavior as the Red Hat OpenShift Service on AWS service is validating your AWS account configuration.
Chapter 8. Required AWS service quotas
This guide covers the required AWS service quotas to run an Red Hat OpenShift Service on AWS cluster.
8.1. Required AWS service quotas
The table below describes the AWS service quotas and levels required to create and run an Red Hat OpenShift Service on AWS cluster.
If you need to modify or increase a specific quota, please refer to Amazon’s documentation on requesting a quota inscrease.
Quota name | Service code | Quota code | Required value |
---|---|---|---|
Number of EIPs - VPC EIPs | ec2 | L-0263D0A3 | 5 |
Running On-Demand Standard (A, C, D, H, I, M, R, T, Z) instances | ec2 | L-1216C47A | 100 |
VPCs per Region | vpc | L-F678F1CE | 5 |
Internet gateways per Region | vpc | L-A4707A72 | 5 |
Network interfaces per Region | vpc | L-DF5E4CA3 | 5000 |
General Purpose SSD (gp2) volume storage | ebs | L-D18FCD1D | 300 |
Number of EBS snapshots | ebs | L-309BACF6 | 300 |
Provisioned IOPS | ebs | L-B3A130E6 | 300000 |
Provisioned IOPS SSD (io1) volume storage | ebs | L-FD252861 | 300 |
Application Load Balancers per Region | elasticloadbalancing | L-53DA6B97 | 50 |
Classic Load Balancers per Region | elasticloadbalancing | L-E9E9831D | 20 |