Remote configuration and auto-reload

The Orchestrator can load and dynamically reload configuration bundles (maverics.tar.gz) published by the Maverics platform from shared storage providers such as AWS S3, Google Cloud Storage, Azure Blob Storage, GitHub, or GitLab.

Remote Configuration Bundle

To load a configuration bundle from a shared storage provider you must set environment variables on the orchestrator host for:

validating the bundle against the public key file for your environment
connecting to your storage provider

Signed Bundle Validation

Configuration bundles published by the Maverics platform are signed to ensure data integrity. The orchestrator cannot load remote configuration without validating the configuration file signatures against the public key for the specific remote configuration environment.

Download the public key file from the Maverics Environments page to the orchestrator host and set the path to the file in the MAVERICS_BUNDLE_PUBLIC_KEY_FILE environment variable.

AWS S3 Bucket

The MAVERICS_AWS_CONFIG environment variable takes a JSON string with the following attributes:

Region

region is the region where the S3 service is hosted.

Access Key ID

accessKeyID is the key’s identifier.

Secret Access Key

secretAccessKey is the secret key value.

Bucket Name

bucketName is the name of the S3 bucket.

Configuration File Path

configurationFilePath is the directory path in the bucket. This must not contain the file name. The orchestrator will automatically look for maverics.tar.gz in that folder. If maverics.tar.gz is at the top level of the bucket, this field can be ignored.

For example:

{
  "bucketName": "maverics-development",
  "accessKeyID": "aws-access-key-id",
  "secretAccessKey": "aws-secret-access-key",
  "region": "aws-region",
  "configurationFilePath": "folder1/folder2"
}

The accessKeyID and secretAccessKey can be omitted if the AWS credentials are already available in the environment (e.g. when AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are set).

AWS S3 Bucket Policy

The S3 bucket settings should block all public access and the bucket policy should allow only what Maverics needs in order to list, read, write, and delete objects from that bucket. The following JSON shows an appropriate policy for a bucket used for Maverics configuration:

{
  "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "Statement",
        "Effect": "Deny",
        "Principal": "*",
        "Action": [
          "s3:ListBucket",
          "s3:GetObject",
          "s3:PutObject",
          "s3:DeleteObject"
        ],
        "Resource": [
          "arn:aws:s3:::<bucket's name>",
          "arn:aws:s3:::<bucket's name>/*"
        ],
        "Condition": {
        "ArnNotEquals": {
        "aws:PrincipalArn": "<user's Arn>"
        }
      }
    }
  ]
}

AWS IAM User Permissions

Create access keys for an AWS IAM user with tightly scoped permissions. The following JSON shows an appropriate policy for an IAM user with access to just the Maverics configuration bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Policy",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:ListBucket",
        "s3:DeleteObject"
      ],
      "Resource": [
        "arn:aws:s3:::<bucket's name>",
        "arn:aws:s3:::<bucket's name>/*"
      ]
    }
  ]
}

Google Cloud Storage

The MAVERICS_GCP_CONFIG environment variable takes a JSON string with the following attributes:

Bucket Name

bucketName is the name of the bucket to read from GCS.

Key

key is the GCP key authorized to read from the cloud storage bucket.

Configuration File Path

For example:

{
  "bucketName": "maverics-development",
  "configurationFilePath": "folder1/folder2",
  "key":{
    "type": "service_account",
    "project_id": "google-cloud-project-id",
    "private_key_id": "",
    "private_key": "-----BEGIN PRIVATE KEY-----\n-----END PRIVATE KEY-----\n",
    "client_email": "google-cloud-project-id@google-cloud-project-id.iam.gserviceaccount.com",
    "client_id": "000000000000000000000",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/google-cloud-project-id%google-cloud-project-id.iam.gserviceaccount.com"
  }
}

GitHub Repository

The MAVERICS_GITHUB_CONFIG environment variable takes a JSON string with the following attributes.

Owner

owner is the owner of the repository.

Repo

repo is the name of the repository.

Token

token is a GitHub token that has read access to the contents of the repository. See the GitHub documentation for information on creating fine-grained personal access tokens with permissions for reading repository contents.

Configuration File Path

For example:

{
    "token": "github_pat_xxxxxxxxx_xxxxxxxxxxxxxx",
    "owner": "ownername",
    "repo": "reponame",
    "configurationFilePath": "folder1/folder2"
}

GitLab Repository

The MAVERICS_GITLAB_CONFIG environment variable takes a JSON string with the following attributes.

Namespace

namespace: The namespace that was generated for you by GitLab.

Repo

repo is the name of the repository.

Branch

branch is the branch name in the repository.

Token

token is A GitLab token that has read access to the contents of the repository. See the GitLab documentation for information on creating personal access tokens with permissions for reading repository contents. Alternatively, a project access token can be created. Minimum required scope is “read_repository”.

Configuration File Path

For example:

{
  "namespace": "user123456789",
  "repo": "reponame",
  "branch": "main",
  "token": "glpat_xxxxxxxxxxxx",
  "configurationFilePath": "folder1/folder2"
}

ℹ️

Use private repositories for storing configuration.

Azure Blob Storage

The MAVERICS_AZURE_CONFIG environment variable takes a JSON string with the following attributes.

Account

account is the storage account name.

Container

container is the name of the container or blob.

Token

token is a Azure Blob Storage SAS token. The query string that includes all of the information required to authenticate the SAS, as well as to specify the blob and permissions available for access, and the time interval over which the signature is valid.

Configuration File Path

For example:

{
  "account": "exampleStorage",
  "container": "exampleContainer",
  "token": "sp=r&st=2023-03-31T02:31:53Z&se=2023-07-14T10:31:53Z&spr=https&sv=2021-12-02&sr=c&sig=xxxxyxxxxxxxxx",
  "configurationFilePath": "folder1/folder2"
}

Setting JSON in Environment Variables

The values for these environment variables are JSON objects. Depending on how your operating system sets environment variables, you may need to fold this into a single line (e.g. when declared in the /etc/maverics/maverics.env file).

The export command will accept multiline input if it is single-quoted.

export MAVERICS_GITHUB_CONFIG='{
    "token": "github_pat_xxxxxxxxx_xxxxxxxxxxxxxx",
    "owner": "ownername",
    "repo": "reponame",
    "configurationFilePath": "folder1/folder2"

}'

The set command only accepts a single line of input.

set MAVERICS_GITHUB_CONFIG={"token": "github_pat_xxxxxxxxx_xxxxxxxxxxxxxx", "owner": "ownername", "repo": "reponame", "configurationFilePath": "folder1/folder2" }

Auto-Reload

The Orchestrator can be set to check configuration periodically, and reload it when it changes. If the Orchestrator detects a change to the version field, it reloads the updated configuration without restarting the process. During a successful reload, user sessions and tokens issued on behalf of resource owners are invalidated to ensure policy updates take effect.

To enable this behavior, set the following environment variables:

MAVERICS_RELOAD_CONFIG: Set to true to enable
MAVERICS_POLLING_INTERVAL_SECONDS (optional): The frequency of polling for configuration updates. If unset, the default is 30 seconds.

Command line interface Secrets management