> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/rumi-cli/installation/aws-setup.md).

# AWS Setup

{% hint style="info" %}
This setup is only required if you need to provision and manage Rumi private clouds in AWS. If you're only working with local deployments, you can skip this section.
{% endhint %}

## Overview

To deploy Rumi private clouds in AWS, you'll need:

1. AWS credentials with appropriate permissions
2. The AWS CLI v2 installed on your machine
3. An AWS CLI profile configured for the Rumi CLI to use

{% hint style="info" %}
**Your AWS Account:** Rumi uses your own AWS account and credentials. You maintain full control over your AWS infrastructure, resources, and costs. Rumi never has access to your AWS credentials or account.
{% endhint %}

## AWS Authentication Methods

The Rumi CLI supports multiple AWS authentication methods. You can use whichever method best fits your organization's security policies:

* **IAM User Credentials** (Access Key ID and Secret Access Key) - Most common for individual developers
* **IAM Identity Center (SSO)** - For organizations using centralized identity management
* **Cross-Account Roles** - For accessing AWS accounts across organizational boundaries
* **EC2 Instance Profiles** - For running the CLI from EC2 instances
* **Other AWS credential chain methods** - Any method supported by the AWS SDK

This guide focuses on the most common method: **IAM User Credentials**. For other authentication methods, consult the [AWS CLI Configuration Documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html).

## Install the AWS CLI

Install the AWS CLI **v2** by following the official installation guide:

[AWS CLI v2 Installation Guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)

### Verify AWS CLI Installation

After installation, verify the AWS CLI is available:

```bash
aws --version
```

You should see output similar to:

```
aws-cli/2.x.x Python/3.x.x ...
```

## Configure Your AWS Profile (IAM User Method)

This section covers the most common authentication method: IAM user credentials.

### Prerequisites

You'll need AWS credentials with specific permissions to provision and manage Rumi private clouds.

**Required AWS Permissions:**

The following IAM policy grants the necessary permissions:

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowEC2AndVPC",
            "Effect": "Allow",
            "Action": "ec2:*",
            "Resource": "*"
        },
        {
            "Sid": "AllowAllRoute53",
            "Effect": "Allow",
            "Action": "route53:*",
            "Resource": "*"
        }
    ]
}
```

These permissions are used for:

* **EC2 (including VPC)** - Creating and managing virtual machines, networking (VPCs, subnets, security groups), and storage volumes for the private cloud infrastructure
* **Route53** - Managing DNS records for private cloud endpoints

**Getting Credentials:**

Your AWS administrator should:

1. Create an IAM user for you (or assign you an IAM Identity Center user)
2. Attach the policy above to your user or role
3. Generate access credentials (Access Key ID and Secret Access Key for IAM users)
4. Provide you with the credentials

You'll need:

* **AWS Access Key ID**
* **AWS Secret Access Key**

### Create an AWS Profile

Open a terminal and run the following command to create a profile for Rumi:

```bash
aws configure --profile rumi
```

You'll be prompted to enter your credentials and preferences:

```bash
AWS Access Key ID [None]: <Your AWS Access Key ID>
AWS Secret Access Key [None]: <Your AWS Secret Access Key>
Default region name [None]: us-east-1
Default output format [None]: json
```

{% hint style="info" %}
You can use any profile name (not just "rumi"). You'll specify the profile name when provisioning private clouds with the `--profile` parameter.
{% endhint %}

**Region Selection:**

* Choose the AWS region where you want to provision Rumi private clouds
* Common choices: `us-east-1`, `us-west-2`, `eu-west-1`
* You can override the default region per deployment using the `--region` parameter

### Verify Your Profile

Test that your profile is configured correctly by running:

```bash
aws sts get-caller-identity --profile rumi
```

You should see output similar to:

```json
{
    "UserId": "AIDAEXAMPLEUSERID",
    "Account": "123456789012",
    "Arn": "arn:aws:iam::123456789012:user/your-username"
}
```

If you see this output with your user information, your AWS profile is set up correctly.

{% hint style="success" %}
**Setup complete!** You're now ready to provision and manage Rumi private clouds in AWS using the Rumi CLI.
{% endhint %}

## Using IAM Identity Center (SSO)

If your organization uses AWS IAM Identity Center (formerly AWS SSO), you can configure SSO authentication instead of using IAM user credentials.

### Configure SSO Profile

```bash
aws configure sso
```

Follow the prompts to:

1. Enter your SSO start URL
2. Choose your SSO region
3. Authenticate via your browser
4. Select the AWS account and role
5. Name your profile (e.g., "rumi-sso")

### Use SSO Profile with Rumi CLI

When provisioning, specify your SSO profile:

```bash
rumi cloud aws provision \
  --name my-cloud \
  --profile rumi-sso
```

**Important:** Before running Rumi CLI commands, ensure your SSO session is active:

```bash
aws sso login --profile rumi-sso
```

## Multiple Profiles

You can configure multiple AWS profiles for different accounts or roles:

```bash
# Personal AWS account
aws configure --profile personal

# Work AWS account
aws configure --profile work

# Production AWS account
aws configure --profile prod
```

When provisioning, specify which profile to use:

```bash
rumi cloud aws provision \
  --name dev-cloud \
  --profile personal
```

## Troubleshooting

### Profile Not Found Error

If you receive a "profile not found" error when running commands, verify your profile exists:

```bash
aws configure list-profiles
```

You should see your profile name (e.g., `rumi`) in the list.

### Permission Denied Errors

If you encounter permission errors when provisioning private clouds:

1. Verify your credentials are valid:

   ```bash
   aws sts get-caller-identity --profile rumi
   ```
2. Check your IAM user has the required permissions:
   * Your AWS administrator should verify that the IAM policy shown in the Prerequisites section is attached to your user or role
   * Required permissions: `ec2:*` and `route53:*`
3. Contact your AWS administrator to verify and attach the necessary permissions

### Credential Expiration (SSO/Temporary Credentials)

If using IAM Identity Center or temporary credentials and you see authentication errors:

```bash
# For SSO profiles
aws sso login --profile rumi-sso

# For assumed role profiles, re-assume the role
aws sts assume-role --role-arn <role-arn> --role-session-name rumi-session
```

### Region Not Available

If you receive errors about services not being available in your region:

1. Verify the region supports the required AWS services
2. Try a different region (e.g., `us-east-1`)
3. Override region when provisioning:

   ```bash
   rumi cloud aws provision \
     --name my-cloud \
     --profile rumi \
     --region us-west-2
   ```

## Security Best Practices

### Credential Storage

* AWS credentials are stored in `~/.aws/credentials`
* This file should have restricted permissions: `chmod 600 ~/.aws/credentials`
* Never commit this file to version control

### Credential Rotation

* Regularly rotate your IAM user access keys
* If using temporary credentials (SSO, assumed roles), they expire automatically
* Monitor AWS CloudTrail for unauthorized API calls

### Least Privilege

* Request only the minimum AWS permissions needed for Rumi private cloud deployments
* Use separate credentials for development vs production deployments
* Consider using IAM roles with time-limited access

### Multi-Factor Authentication (MFA)

* Enable MFA on your IAM user for additional security
* If MFA is required, you'll need to use temporary credentials:

  ```bash
  aws sts get-session-token --serial-number <mfa-device-arn> --token-code <mfa-code>
  ```

## Next Steps

Now that your AWS access is configured:

* **Return to installation** — Complete CLI setup in [Installation](/rumi-cli/installation.md)
* **Learn about private clouds** — Read [Cloud Commands](/rumi-cli/commands/cloud.md) to understand Rumi's private cloud model
* **Browse commands** — See [CLI Commands](/rumi-cli/commands.md) for detailed command reference

***

*Last updated: 2025-01-04*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.rumi.systems/rumi-cli/installation/aws-setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.