Skip to main content

Organization Deployment Guide

Chronom now supports automatic deployment of the CloudFormation stack across all accounts in your AWS organization. This guide explains how to use this feature through two options: using a Lambda function to auto-discover your root Organizational Unit (OU) Id, or manually supplying the root OU Id.

Feature Options​

During CloudFormation stack deployment you can choose one of the following mutually exclusive options:

  • Auto-Discover: Set the parameter EnableAutoDiscover to true. This option triggers a Lambda function that automatically discovers your organization’s root OU id (This is done by clicking the 'Take me to AWS - Auto Discover' button).
  • Manual Input: Supply the parameter RootOuId with your organization's root OU id during deployment.

Do not set both options simultaneously.

How It Works​

Auto-Discover Option​

When you enable EnableAutoDiscover, a Lambda function is triggered at deployment which:

  1. Connects to AWS Organizations.
  2. Discovers the root OU id automatically.
  3. Uses the discovered id to deploy the CloudFormation StackSet across all accounts.

Manual Input Option​

If you choose not to use auto-discovery, you must manually find and provide your organization’s root OU id. Follow these steps:

  1. Open the AWS Organizations Console:

  2. Locate Your Root OU:

    • In the left-hand navigation pane, click on "Organizational units."
    • Identify the root OU. It is usually labeled “Root” or it carries your organization’s name.

  3. Copy the Root OU Id:

    • Click on the root OU to view its details.
    • Copy the OU id provided in the details section.

Root OU Id

IAM Role Details​

The CloudFormation template creates an IAM role with the following permissions:

  • ReadOnlyAccess - A built-in AWS policy that grants read-only access to most of the AWS resources.
  • ChronomReadonlyAdditionalAccessPolicy - A custom policy to grant access to additional resources required by Chronom.
    (For more detailed information about the IAM role and its permissions, please refer to the Add an AWS account documentation.)

Pre-requisites and Warnings​

  • IAM Permissions: Ensure the deploying user has the necessary IAM permissions.
    (For a detailed list of required permissions, please refer to the Add an AWS account documentation.)
  • Understanding Your Organization: Only use this feature if you are familiar with your AWS organization’s structure. Incorrect OU ids could lead to deployment to unintended accounts and data leakage.
  • For Advanced Users: This feature is intended for Managed Service Provider employees or users with advanced knowledge of AWS organizational structures.
  • Configuration Validation: Always verify your parameter settings (either EnableAutoDiscover or RootOuId) before deploying the stack, to avoid configuration conflicts.
  • Target Account: Ensure that the account you are deploying to is the Management account or has the necessary permissions to deploy the stack across the organization.

Deployment Instructions​

Using the AWS Management Console​

  1. Open the CloudFormation service in the AWS Management Console.

  2. Click on Create stack and choose With new resources (standard).

  3. Select Template is ready and Amazon S3 URL, then paste:

    https://chronom-public-assets.s3.amazonaws.com/org-level-readonly-role.yaml

    and click Next.

  4. On the parameters page:

    • For auto-discovery, set EnableAutoDiscover to true and leave RootOuId blank.
    • For manual input, leave EnableAutoDiscover as false and enter your root OU id into RootOuId.

  5. Fill in the remaining required parameters (Stack name, ExternalId, etc.) as provided by Chronom.

  6. Click Next, review the stack details, acknowledge permissions warnings, and click Submit.

Using the AWS CLI​

If preferred, you can deploy using the AWS CLI by including your chosen parameter in the command:

  • For auto-discovery:

    aws cloudformation create-stack \
      --stack-name ChronomReadOnlyRole \
      --template-url https://chronom-public-assets.s3.amazonaws.com/org-level-readonly-role.yaml \
      --parameters ParameterKey=chronomExternalId,ParameterValue=EXTERNAL_ID ParameterKey=EnableAutoDiscover,ParameterValue=true \
      --capabilities CAPABILITY_NAMED_IAM \
      --region us-east-1

  • For manual input:

    YOUR_ROOT_OU_ID=$(aws organizations list-roots --query "Roots[0].Id" --output text)

    aws cloudformation create-stack \
        --stack-name ChronomReadOnlyRole \
        --template-url https://chronom-public-assets.s3.amazonaws.com/org-level-readonly-role.yaml \
        --parameters ParameterKey=chronomExternalId,ParameterValue=EXTERNAL_ID ParameterKey=RootOuId,ParameterValue=$YOUR_ROOT_OU_ID \
        --capabilities CAPABILITY_NAMED_IAM \
        --region us-east-1

Replace EXTERNAL_ID and YOUR_ROOT_OU_ID with your actual values.

Next Steps​

After deployment, monitor the CloudFormation stack progress:

  • If successful, retrieve the RoleArn from the Outputs tab.
  • Verify that the stack has been deployed across your intended accounts.

Ensure you review all configuration details and validate all permissions to avoid unintended access issues.