Skip to main content
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.
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.

​
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 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

Console UI documentation is coming soon. This section will walk you through configuring this component using the Maverics Console’s visual interface, including step-by-step screenshots and field descriptions.

​
Configuration Reference

The MAVERICS_AWS_CONFIG JSON payload supports the following fields:
FieldTypeRequiredDescription
regionstringYesAWS region (e.g., us-west-2)
accessKeyIDstringConditionalAWS access key ID (not needed with IAM role)
secretAccessKeystringConditionalAWS secret access key (not needed with IAM role)
bucketNamestringYesS3 bucket name
configurationFilePathstringNoPath to the config file within the bucket. Only needed if the file is not 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: 
{
  "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/config/maverics.yaml).
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 for Console-side setup.
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 and IAM roles for service accounts on EKS for setup details.

​
Full Environment Example

A complete maverics.env file for an Orchestrator using Amazon S3 as its config source:
maverics.env
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.

Config Sources

Overview of all configuration sources

Azure Blob Storage

Load config from Azure Blob Storage

Configuration Reference

Complete configuration field reference

S3 Deployment Provider

Console-side S3 setup, IAM policies, and cross-account role creation