Prepare your environment

Procedure

1. Prepare the policy file by entering the following command in the rosa CLI:

   $ curl -o ./rosa-installer-core.json https://raw.githubusercontent.com/openshift/managed-cluster-config/master/resources/sts/4.18/sts_installer_core_permission_boundary_policy.json

2. Create the policy in AWS and gather its Amazon Resource Name (ARN) by entering the following command:

   $ aws iam create-policy \
   --policy-name rosa-core-permissions-boundary-policy \
   --policy-document file://./rosa-installer-core.json \
   --description "ROSA installer core permission boundary policy, the minimum permission set, allows BYO-VPC, disallows PrivateLink"

   Example output

   {
       "Policy": {
           "PolicyName": "rosa-core-permissions-boundary-policy",
           "PolicyId": "<Policy ID>",
           "Arn": "arn:aws:iam::<account ID>:policy/rosa-core-permissions-boundary-policy",
           "Path": "/",
           "DefaultVersionId": "v1",
           "AttachmentCount": 0,
           "PermissionsBoundaryUsageCount": 0,
           "IsAttachable": true,
           "CreateDate": "<CreateDate>",
           "UpdateDate": "<UpdateDate>"
       }
   }

3. Add the permission boundary policy to the installer role you want to restrict by entering the following command:

   $ aws iam put-role-permissions-boundary \
   --role-name ManagedOpenShift-Installer-Role \
   --permissions-boundary arn:aws:iam::<account ID>:policy/rosa-core-permissions-boundary-policy

4. Display the installer role to validate attached policies (including permissions boundary) by entering the following command in the rosa CLI:

   $ aws iam get-role --role-name ManagedOpenShift-Installer-Role \
   --output text | grep PERMISSIONSBOUNDARY

   Example output

   PERMISSIONSBOUNDARY	arn:aws:iam::<account ID>:policy/rosa-core-permissions-boundary-policy	Policy

   For more examples of PL and VPC permission boundary policies see:

   Example 3.2. sts_installer_privatelink_permission_boundary_policy.json

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "ec2:ModifyVpcEndpointServiceConfiguration",
           "route53:ListHostedZonesByVPC",
           "route53:CreateVPCAssociationAuthorization",
           "route53:AssociateVPCWithHostedZone",
           "route53:DeleteVPCAssociationAuthorization",
           "route53:DisassociateVPCFromHostedZone",
           "route53:ChangeResourceRecordSets"
         ],
         "Resource": "*"
       }
     ]
   }

   Example 3.3. sts_installer_vpc_permission_boundary_policy.json

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
   		    "ec2:AssociateDhcpOptions",
   		    "ec2:AssociateRouteTable",
   		    "ec2:AttachInternetGateway",
   		    "ec2:CreateDhcpOptions",
   		    "ec2:CreateInternetGateway",
   		    "ec2:CreateNatGateway",
   		    "ec2:CreateRouteTable",
   		    "ec2:CreateSubnet",
   		    "ec2:CreateVpc",
   		    "ec2:DeleteDhcpOptions",
   		    "ec2:DeleteInternetGateway",
   		    "ec2:DeleteNatGateway",
   		    "ec2:DeleteRouteTable",
   		    "ec2:DeleteSubnet",
   		    "ec2:DeleteVpc",
   		    "ec2:DetachInternetGateway",
   		    "ec2:DisassociateRouteTable",
   		    "ec2:ModifySubnetAttribute",
   		    "ec2:ModifyVpcAttribute",
   		    "ec2:ReplaceRouteTableAssociation"
               ],
               "Resource": "*"
           }
       ]
   }

1. The pod count displayed here is the number of test pods. The actual number of pods depends on the memory, CPU, and storage requirements of the application.
2. When there are a large number of active projects, etcd can suffer from poor performance if the keyspace grows excessively large and exceeds the space quota. Periodic maintenance of etcd, including defragmentation, is highly recommended to make etcd storage available.
3. There are several control loops in the system that must iterate over all objects in a given namespace as a reaction to some changes in state. Having a large number of objects of a type, in a single namespace, can make those loops expensive and slow down processing the state changes. The limit assumes that the system has enough CPU, memory, and disk to satisfy the application requirements.
4. Each service port and each service back end has a corresponding entry in iptables. The number of back ends of a given service impacts the size of the endpoints objects, which then impacts the size of data sent throughout the system.

1. io1 disks are used for control plane/etcd nodes in all versions prior to 4.10.
2. Infrastructure nodes are used to host monitoring components because Prometheus can claim a large amount of memory, depending on usage patterns.
3. Workload nodes are dedicated to run performance and scalability workload generators.

1. The pod count displayed here is the number of test pods. The actual number of pods depends on the memory, CPU, and storage requirements of the application.
2. When there are a large number of active projects, etcd can suffer from poor performance if the keyspace grows excessively large and exceeds the space quota. Periodic maintenance of etcd, including defragmentation, is highly recommended to make etcd storage available.
3. There are several control loops in the system that must iterate over all objects in a given namespace as a reaction to some changes in state. Having a large number of objects of a type, in a single namespace, can make those loops expensive and slow down processing the state changes. The limit assumes that the system has enough CPU, memory, and disk to satisfy the application requirements.
4. Each service port and each service back end has a corresponding entry in iptables. The number of back ends of a given service impacts the size of the endpoints objects, which then impacts the size of data sent throughout the system.

Procedure

1. Log in to the Amazon Web Services (AWS) account that you want to use.

   It is recommended to use a dedicated AWS account to run 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, these policies must not be more restrictive than the roles and policies required by the cluster.

2. Enable the ROSA service in the AWS Management Console.

   1. Sign in to your AWS account.
   2. To enable ROSA, go to the ROSA service and select Enable OpenShift.

3. Install and configure the AWS CLI.

   1. Follow the AWS command-line interface documentation to install and configure the AWS CLI for your operating system.

      Specify the correct aws_access_key_id and aws_secret_access_key in the .aws/credentials file. See AWS Configuration basics in the AWS documentation.

   2. Set a default AWS region.

      Note

      You can use the environment variable to set the default AWS region.

      The ROSA service evaluates regions in the following priority order:

      1. The region specified when running the rosa command with the --region flag.
      2. The region set in the AWS_DEFAULT_REGION environment variable. See Environment variables to configure the AWS CLI in the AWS documentation.
      3. The default region set in your AWS configuration file. See Quick configuration with aws configure in the AWS documentation.

   3. Optional: Configure your AWS CLI settings and credentials by using an AWS named profile. rosa evaluates AWS named profiles in the following priority order:

      1. The profile specified when running the rosa command with the --profile flag.
      2. The profile set in the AWS_PROFILE environment variable. See Named profiles in the AWS documentation.

   4. Verify the AWS CLI is installed and configured correctly by running the following command to query the AWS API:

      $ aws sts get-caller-identity

4. Install the latest version of the ROSA CLI (rosa).

   1. Download the latest release of the ROSA CLI for your operating system.

   2. Optional: Rename the file you downloaded to rosa and make the file executable. This documentation uses rosa to refer to the executable file.

      $ chmod +x rosa

   3. Optional: Add rosa to your path.

      $ mv rosa /usr/local/bin/rosa

   4. Enter the following command to verify your installation:

      $ rosa

      Example output

      Command line tool for Red Hat OpenShift Service on AWS.
      For further documentation visit https://access.redhat.com/documentation/en-us/red_hat_openshift_service_on_aws
      
      Usage:
        rosa [command]
      
      Available Commands:
        completion  Generates completion scripts
        create      Create a resource from stdin
        delete      Delete a specific resource
        describe    Show details of a specific resource
        download    Download necessary tools for using your cluster
        edit        Edit a specific resource
        grant       Grant role to a specific resource
        help        Help about any command
        init        Applies templates to support Red Hat OpenShift Service on AWS
        install     Installs a resource into a cluster
        link        Link a ocm/user role from stdin
        list        List all resources of a specific type
        login       Log in to your Red Hat account
        logout      Log out
        logs        Show installation or uninstallation logs for a cluster
        revoke      Revoke role from a specific resource
        uninstall   Uninstalls a resource from a cluster
        unlink      UnLink a ocm/user role from stdin
        upgrade     Upgrade a resource
        verify      Verify resources are configured correctly for cluster install
        version     Prints the version of the tool
        whoami      Displays user account information
      
      Flags:
            --color string   Surround certain characters with escape sequences to display them in color on the terminal. Allowed options are [auto never always] (default "auto")
            --debug          Enable debug mode.
        -h, --help           help for rosa
      
      Use "rosa [command] --help" for more information about a command.

   5. Generate the command completion scripts for the ROSA CLI. The following example generates the Bash completion scripts for a Linux machine:

      $ rosa completion bash | sudo tee /etc/bash_completion.d/rosa

   6. Source the scripts to enable rosa command completion from your existing terminal. The following example sources the Bash completion scripts for rosa on a Linux machine:

      $ source /etc/bash_completion.d/rosa

5. Log in to your Red Hat account with the ROSA CLI.

   1. Enter the following command.

      $ rosa login

   2. Replace <my_offline_access_token> with your token.

      Example output

      To login to your Red Hat account, get an offline access token at https://console.redhat.com/openshift/token/rosa
      ? Copy the token and paste it here: <my-offline-access-token>

      Example output continued

      I: Logged in as '<rh-rosa-user>' on 'https://api.openshift.com'

6. Verify that your AWS account has the necessary quota to deploy a ROSA cluster.

   $ rosa verify quota [--region=<aws_region>]

   Example output

   I: Validating AWS quota...
   I: AWS quota ok

   Note

   Sometimes your AWS quota varies by region. If you receive any errors, try a different region.

   If you need to increase your quota, go to the AWS Management Console and request a quota increase for the service that failed.

   After the quota check succeeds, proceed to the next step.

7. Prepare your AWS account for cluster deployment:

   1. 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 OpenShift Cluster Manager for now.

      $ rosa whoami

      Example output

      AWS Account ID:               000000000000
      AWS Default Region:           us-east-1
      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

8. Install the OpenShift CLI (oc), version 4.7.9 or greater, from the ROSA (rosa) CLI.

   1. Enter this command to download the latest version of the oc CLI:

      $ rosa download openshift-client

   2. After downloading the oc CLI, unzip it and add it to your path.

   3. Enter this command to verify that the oc CLI is installed correctly:

      $ rosa verify openshift-client