Skip to content

Latest commit

 

History

History
274 lines (200 loc) · 11.7 KB

1.1-InstallationPrerequisites.md

File metadata and controls

274 lines (200 loc) · 11.7 KB

1.1 - Prerequisites

Please ensure you have the following installed, or configured, on your machine before continuing:

1.1.1 - AWS Credentials and Secret

The operator requires a secret named aws-account-operator-credentials in the aws-account-operator namespace, containing credentials to the AWS Payer Account you wish to create accounts in. The Payer Account is the root account in an organization and can create linked accounts and manage them.

Credentials are obtained via temporary STS tokens using rh-aws-saml-login rather than permanent IAM user credentials. This provides enhanced security through short-lived credentials.

The secret should contain the data fields aws_access_key_id, aws_secret_access_key, and aws_session_token (for STS temporary credentials).

The credentials should have the following IAM permissions:

Permissions to allow assuming the OrganizationAccountAccessRole role in any account created:

{
   "Version": "2012-10-17",
   "Statement": {
       "Effect": "Allow",
       "Action": "sts:AssumeRole",
       "Resource": "arn:aws:iam::*:role/OrganizationAccountAccessRole"
   }
}

Permissions to interact with the support center:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "support:*"
            ],
            "Resource": "*"
        }
    ]
}

Setting up credentials for local development

Use the update_aws_credentials.sh script to obtain temporary credentials via rh-aws-saml-login:

./hack/scripts/update_aws_credentials.sh

This script will:

  1. Authenticate to both osd-staging-1 and osd-staging-2 profiles via SAML
  2. Update your ~/.aws/credentials file with temporary credentials including session tokens
  3. Create a backup of your credentials file

Once credentials are updated, deploy the secret using:

./hack/scripts/set_operator_credentials.sh osd-staging-2

Or use the make target:

make deploy-aws-account-operator-credentials

Note: Temporary credentials expire after a few hours. If you encounter authentication errors, re-run update_aws_credentials.sh.

Note: The aws credentials file will be in the following format after running the script:

[osd-staging-2]
aws_access_key_id = ASIA...
aws_secret_access_key = ...
aws_session_token = ...

1.1.2 AWS Accounts

For local development, you need access to three AWS accounts:

  1. osd-staging-1 (Shared):

    • Access via rh-aws-saml-login with profile osd-staging-1
    • Contains the centrally-managed JumpRole
    • Operator credentials come from this account
    • Same for all developers

  2. osd-staging-2 Payer Account (Shared):

    • Access via rh-aws-saml-login with profile osd-staging-2
    • This is the payer account that contains your assigned account
    • Same for all developers

  3. Your Assigned Account (Personal):

    • A dedicated account assigned to you under the osd-staging-2 Payer Account
    • You create an AccessRole in this account
    • Work with your manager to get this account assigned
    • Access via rh-aws-saml-login with your custom profile name

Once you have your assigned account, you can access its console via osdctl:

osdctl account console -p <your-profile> -i <your-account-id>

1.1.3 STS Roles

To run the operator tests for STS mode you will need to create an AccessRole in your assigned osd-staging-2 account. The architecture has been simplified:

  • osd-staging-1 (Shared Jump Host)

    • Contains a centrally-managed JumpRole
    • You do not need to create or manage this role
    • The JumpRole has a trust relationship that allows SRE users to assume it via SAML authentication
    • ARN: arn:aws:iam::<SHARED_ACCOUNT_ID>:role/JumpRole

  • osd-staging-2 (Your Assigned Account - Target)

    • You will create an AccessRole in this account
    • The AccessRole will trust the JumpRole from osd-staging-1
    • This allows the operator to assume into your account from the shared jump account

Architecture Diagram

The following diagram shows the updated Account relationship using the new shared account architecture:

Account Relationship Diagram

Note: The diagram source is available at images/jump-role-diagram.dot and can be regenerated using: dot -Tpng -Gdpi=300 jump-role-diagram.dot -o jump-role-diagram.png

Setting up the AccessRole

First, ensure you have a profile configured for your assigned account in ~/.aws/credentials. You can use rh-aws-saml-login to authenticate:

rh-aws-saml-login <your-profile-name>

Then run the setup script to create the AccessRole in your assigned account:

./hack/scripts/aws/setup_access_role.sh -a <Your Assigned Account ID> -p <your-profile-name>

Example:

./hack/scripts/aws/setup_access_role.sh -a <YOUR_ACCOUNT_ID> -p my-staging-account

Upon completion of the script you should have output with the following:

Add the following to your .envrc file:

export STS_ROLE_ARN=arn:aws:iam::<YOUR_ACCOUNT_ID>:role/AccessRole
export STS_JUMP_ARN=arn:aws:iam::<SHARED_ACCOUNT_ID>:role/JumpRole
export STS_JUMP_ROLE=arn:aws:iam::<SHARED_ACCOUNT_ID>:role/JumpRole
export OSD_STAGING_2_AWS_ACCOUNT_ID=<YOUR_ACCOUNT_ID>

Add these fields to your local .envrc file as instructed.

  • The Jump Role is a centrally-managed role in the shared osd-staging-1 account that acts as a bastion. For the STS Architecture, users authenticate via SAML (using rh-aws-saml-login), assume the Jump Role, and then use that role to assume into target accounts via the Access Role.
  • The Access Role simulates a role on a customer's account that gives us access to initialize regions and initialize a cluster. On external customer accounts this is assumed to be a very locked-down role with ONLY the necessary permissions needed to run the operator or install the cluster resources.

Setting Organization Unit IDs

You need to set OSD_STAGING_1_OU_ROOT_ID and OSD_STAGING_1_OU_BASE_ID in your .envrc file. These refer to the organizational structure of the shared osd-staging-1 account, not your assigned account.

These values are the same for all developers and should be provided by your team lead or in onboarding documentation.

If you need to look them up yourself:

# Get the root OU ID (starts with r-)
aws organizations list-roots --profile osd-staging-1

# Get the base OU ID (starts with ou-)
aws organizations list-organizational-units-for-parent --parent-id <ROOT_OU_ID> --profile osd-staging-1

Note: You typically don't need to look these up - they're shared constants for the team. Ask your manager or check team documentation.

You can verify your setup using the verify-organization.sh script if you have access to create test accounts in the organization.

1.1.3.4 STS Role Validation

Making sense of the STS role chaining process can be confusing at first, so we've added a script to validate that the role chaining works before you try to run it through the operator. The script is located in the hack/scripts/aws directory, but for convenience you can run it from the make target: make check-sts-setup

1.1.4 Config Map

The operator needs a ConfigMap that has the following fields configured:

  • account-limit: The soft limit of AWS accounts which is the number compared against when creating new accounts
  • base: Base OU ID to place accounts in when claimed
  • root: Root OU ID to create new OUs under
  • sts-jump-role: The arn for the jump role created above
{
    "apiVersion": "v1",
    "data": {
        "account-limit": "4801",
        "base": "ou-0wd6-tmsbvahq",
        "root": "r-0wd6",
        "sts-jump-role": "[arn from the jump role created above]"
    },
    "kind": "ConfigMap",
    "metadata": {
        "name": "aws-account-operator-configmap",
        "namespace": "aws-account-operator",
    }
}

The ConfigMap could be generated and deployed with the hack/scripts/set_operator_configmap.sh script.

.hack/scripts/set_operator_configmap.sh -a ${ACCOUNT_LIMIT} -v ${VCPU_QUOTA} -r "${OSD_STAGING_1_OU_ROOT_ID}" -o "${OSD_STAGING_1_OU_BASE_ID}"

1.1.5 Environment Variables

Now we have all required Roles defined, set up your required environment variables:

export AWS_PAGER= # This is set so that it doesn't page out to less and block integration testing
export FORCE_DEV_MODE=local # This flags the operator for local development for some code paths

# Your personal assigned account (get from your manager)
# This is NOT the osd-staging-2 payer account!
# It's your assigned account UNDER that payer
export OSD_STAGING_2_AWS_ACCOUNT_ID=<YOUR_ACCOUNT_ID>

# Shared team constants (same for all developers - get from team documentation)
export OSD_STAGING_1_OU_ROOT_ID=<OU_ROOT_ID>
export OSD_STAGING_1_OU_BASE_ID=<OU_BASE_ID>

# STS roles
export STS_ROLE_ARN=arn:aws:iam::<YOUR_ACCOUNT_ID>:role/AccessRole
export STS_JUMP_ARN=arn:aws:iam::<SHARED_ACCOUNT_ID>:role/JumpRole # Centrally-managed (same for everyone)
export STS_JUMP_ROLE=arn:aws:iam::<SHARED_ACCOUNT_ID>:role/JumpRole # Same as STS_JUMP_ARN

# Optional: For integration tests that create accounts in the organization
export OSD_STAGING_1_AWS_ACCOUNT_ID=<SHARED_ACCOUNT_ID> # The shared osd-staging-1 account (same for everyone)

Note:

  • OSD_STAGING_2_AWS_ACCOUNT_ID should be your assigned account, not the shared payer account!
  • OSD_STAGING_1_AWS_ACCOUNT_ID is optional and only needed if running certain integration tests

Tip: You can use direnv and add the above block (with variables filled in) into a .envrc file (make sure .envrc is in your global git ignore as well). Upon entry to the aws-account-operator folder, the env vars inside the file will be loaded automatically, and unset when you leave the folder.

1.1.6 Quick Start Summary

The streamlined setup process:

Prerequisites & Information Gathering:

  1. Install prerequisites (Go, aws-cli, CRC, operator-sdk, rh-aws-saml-login, python3)
  2. Get from your manager/team lead:
    • Your assigned account ID (under osd-staging-2 payer account)
    • Your AWS profile name for this account
    • Shared OU_ROOT_ID and OU_BASE_ID (same for all developers)

Setup Steps: 3. Authenticate to your assigned account: rh-aws-saml-login <your-profile-name> 4. Create AccessRole: ./hack/scripts/aws/setup_access_role.sh -a <YOUR_ACCOUNT_ID> -p <your-profile-name> 5. Set environment variables in .envrc (see section 1.1.5) 6. Deploy operator credentials: make deploy-aws-account-operator-credentials 7. Configure ConfigMap: ./hack/scripts/set_operator_configmap.sh -a <ACCOUNT_LIMIT> -v <VCPU_QUOTA> -r "<OU_ROOT_ID>" -o "<OU_BASE_ID>"

What you need vs. what's shared:

  • ✅ Shared (same for all devs): osd-staging-1 account, JumpRole ARN, OU IDs
  • 🔑 Personal: Your assigned account ID, AWS profile name, AccessRole (created in step 4)

Now that those steps have been completed you can return to the Installation Workflow Section.