> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon S3

The Amazon S3 config source loads Orchestrator configuration from an object stored in an AWS S3 bucket. The source is configured entirely through the `MAVERICS_AWS_CONFIG` environment variable.

<Note>
  **Console terminology:** In the Maverics Console, Orchestrator instances and
  configuration delivery are managed through **Deployments**. When working directly
  with YAML, configuration is managed as files delivered via the `-config` flag or
  `MAVERICS_CONFIG` environment variable.
</Note>

## Prerequisites

* **An active AWS account** -- with an S3 bucket containing Orchestrator configuration
* **An IAM user or role with read access** -- with `s3:GetObject` permission on the bucket (see the [S3 deployment provider](/reference/console/config-publishing/s3) page for detailed IAM setup steps), or an EC2/EKS instance role configured for S3 access

## Overview

When the `MAVERICS_AWS_CONFIG` environment variable is set, the Orchestrator fetches its YAML configuration from the specified S3 bucket and object path. The variable contains a JSON payload with connection details and credentials. The Orchestrator supports ETag-based change detection for automatic hot-reload of configuration changes.

## Use Cases

* **AWS-native deployments** -- store configuration alongside other AWS infrastructure artifacts using native IAM authentication
* **CI/CD config delivery** -- push validated configuration to S3 from any CI/CD pipeline (Jenkins, GitHub Actions, CodePipeline) and let the Orchestrator pick it up automatically
* **Multi-region config distribution** -- leverage S3 cross-region replication to distribute configuration globally

## Configuration

The S3 config source is configured via the `MAVERICS_AWS_CONFIG` environment variable with a JSON payload:

```bash theme={null}
export MAVERICS_AWS_CONFIG='{
  "region": "us-west-2",
  "accessKeyID": "AKIA...",
  "secretAccessKey": "...",
  "bucketName": "my-config-bucket",
  "configurationFilePath": "path/to/config"
}'
maverics
```

<Note>
  When running on EC2 or ECS with an IAM role, omit `accessKeyID` and `secretAccessKey`. The Orchestrator uses the default AWS credential chain.
</Note>

**IAM role example (recommended for AWS-hosted deployments):**

```bash theme={null}
export MAVERICS_AWS_CONFIG='{
  "region": "us-west-2",
  "bucketName": "my-config-bucket",
  "configurationFilePath": "path/to/config"
}'
maverics
```

## Configuration Reference

The `MAVERICS_AWS_CONFIG` JSON payload supports the following fields:

| Field                   | Type   | Required    | Description                                                                                                                                                                                |
| ----------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `region`                | string | Yes         | AWS region (e.g., `us-west-2`)                                                                                                                                                             |
| `accessKeyID`           | string | Conditional | AWS access key ID (not needed with IAM role)                                                                                                                                               |
| `secretAccessKey`       | string | Conditional | AWS secret access key (not needed with IAM role)                                                                                                                                           |
| `bucketName`            | string | Yes         | S3 bucket name                                                                                                                                                                             |
| `configurationFilePath` | string | No          | Directory path prefix within the bucket where the config bundle is stored. The Orchestrator appends `maverics.tar.gz` to this path. If omitted, the bundle is expected at the bucket root. |

**ETag-based hot-reload:** When `MAVERICS_RELOAD_CONFIG=true` is set, the Orchestrator periodically checks the S3 object's ETag. When the ETag changes (indicating the file was updated), the Orchestrator reloads the configuration automatically.

## IAM Permissions

The Orchestrator requires read-only access to the S3 bucket. Attach the following IAM policy to the IAM role or user that the Orchestrator uses:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*"
    }
  ]
}
```

Replace `YOUR-BUCKET-NAME` with your actual bucket name. If you use a `configurationFilePath`, you can further restrict the `Resource` to the specific object path (e.g., `arn:aws:s3:::my-bucket/path/to/config/maverics.tar.gz`).

<Note>
  If the Maverics Console publishes bundles to the same S3 bucket, the Console's IAM role requires additional permissions (`s3:PutObject`, `s3:ListBucket`, `s3:DeleteObject`). See [Publishing Deployment Configs overview](/reference/console/config-publishing) for Console-side setup.
</Note>

<Tip>
  **EKS and EC2 deployments:** When running on Amazon EKS or EC2, you can use an IAM role attached to the instance or pod instead of embedding access keys. Omit `accessKeyID` and `secretAccessKey` from `MAVERICS_AWS_CONFIG` and the Orchestrator uses the default AWS credential chain. See [IAM roles for Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) and [IAM roles for service accounts on EKS](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) for setup details.
</Tip>

## Full Environment Example

A complete `maverics.env` file for an Orchestrator using Amazon S3 as its config source:

```bash maverics.env theme={null}
MAVERICS_DEBUG_MODE=true
MAVERICS_HTTP_ADDRESS=:443
MAVERICS_TLS_SERVER_CERT_FILE=your-cert.pem
MAVERICS_TLS_SERVER_KEY_FILE=your-private_key.pem
MAVERICS_RELOAD_CONFIG=true
MAVERICS_POLLING_INTERVAL_SECONDS=30
MAVERICS_BUNDLE_PUBLIC_KEY_FILE=./public_key.pem
MAVERICS_AWS_CONFIG='{"region":"<AWS_REGION>", "accessKeyID":"<ACCESS_KEY_ID>", "secretAccessKey":"<SECRET_ACCESS_KEY>", "bucketName":"<BUCKET_NAME>", "configurationFilePath":"<CONFIG_FILE_PATH>"}'
```

Replace the placeholder values with your actual certificate paths, AWS region, access key credentials, bucket name, and config file path. When using IAM roles (EC2/EKS), omit `accessKeyID` and `secretAccessKey`.

## Troubleshooting

* **Access denied** -- verify the IAM role or access key has `s3:GetObject` permission on the bucket and object path. Check the bucket policy as well.
* **Bucket not found** -- confirm the `region` matches the bucket's actual region. S3 bucket names are globally unique but region-specific for access.
* **Config not reloading** -- ensure `MAVERICS_RELOAD_CONFIG=true` is set. Check the Orchestrator logs for ETag change detection messages.

## Related Pages

<CardGroup cols={2}>
  <Card title="Config Sources" icon="folder-gear" href="/reference/orchestrator/configuration/config-sources">
    Overview of all configuration sources
  </Card>

  <Card title="Azure Blob Storage" icon="microsoft" href="/reference/orchestrator/configuration/config-sources/azure-blob">
    Load config from Azure Blob Storage
  </Card>

  <Card title="Configuration Reference" icon="code" href="/reference/orchestrator/configuration">
    Complete configuration field reference
  </Card>

  <Card title="S3 Deployment Provider" icon="aws" href="/reference/console/config-publishing/s3">
    Console-side S3 setup, IAM policies, and cross-account role creation
  </Card>
</CardGroup>