Skip to main content

Manually Create IAMbic Configuration

Configuration File Reference​

You can run iambic setup to bootstrap your configuration if desired, but you can also create your configuration manually. This guide will walk you through the process of creating a configuration for your use case.

The configuration file is written in YAML and needs to be created before IAMbic can be used the first time. It stores all the information about your environment and provides credentials to cloud services and GitHub. We recommend that you use the Setup Wizard to quickly start creating your configuration file.

This document provides an overview of the YAML configuration for Noq's core configuration, which has template_type: NOQ::Core::Config . This configuration is used to specify AWS accounts and organizations that IAMbic has access to, via Hub and Spoke roles.

The following is an example configuration for AWS Organizations:

template_type: NOQ::Core::Config
version: '1'

aws:
  organizations:
    - default_rule:
        iambic_managed: read_and_write
      hub_role_arn: arn:aws:iam::123456789012:role/IambicHubRole
      identity_center:
        region: us-east-1
      org_account_id: '123456789012'
      org_id: o-yabc0a10zs

For information about the Iambic configuration model, please visit this link.

AWS​

Tell IAMbic how to connect to your AWS account or AWS organization. IAMbic can connect to your AWS accounts or AWS organizations via a number of different methods, Including using a predefined AWS profile, performing assume role operations, or a combination of these. This guide will walk you through the basic configuration. For anything more advanced, please consult the Configuration Reference.

AWS Organizations​

The AWS Organizations configuration enables you to set up your organization(s) once, and instruct IAMbic to populate your current and new AWS accounts when it is run. If you choose not to configure your entire organization, you may configure accounts on an individual basis. In that case, skip to the AWS Accounts section below.

Before starting, you need your AWS Organizations ID, Organizations name, and administrative-level credentials for your Organization management account.

If you have credentials to your AWS Organizations management account, run aws organizations describe-organization. Your Organizations ID is the value of the Id parameter.

Use these attributes to create a to create a YAML configuration tailored for your environment, such as the following.

We recommend placing this in your Git repository under config/config.yaml

An example configuration is included below:

template_type: NOQ::Core::Config
version: "1"
aws:
  organizations:
    - org_id: "o-12345"
      # aws_profile: 'profile_name' # Optional. If not provided, the default profile will be used
      # assume_role_arn: 'arn:aws:iam::123456:role/IambicSpokeRole' # Optional. The role assumed using credentials provided by `aws_profile`
      # `org_name` is a required friendly-name for the AWS organization
      org_name: "main"
      # identity_center_account:
      #   account_id: '123456789012'
      #   region: 'us-east-1'

Write the finished config file to config/config/yaml in your iambic-templates repository. Once this is written to disk, your repository should resemble this folder structure:

$ tree
.
├── config
│   └── config.yaml

AWS Accounts​

Follow these steps if you want to onboard AWS accounts individually, instead of an entire AWS Organization. If you have configured your entire organization, you may skip this section, and continue with the next section, entitled Import AWS Resources.

Before starting, you will need your AWS Account ID, Account Name, and a method to access the account (either via using an AWS profile, or assuming a role from your current credentials).

An example configuration is included below:

template_type: NOQ::Core::Config
version: "1"
aws:
  accounts:
    - account_name: "main"
      account_id: "123456789012"
      # aws_profile: 'profile_name' # Optional. If not provided, the default profile will be used. if the AWS_PROFILE environment variable is specified, it will be used.
      # assume_role_arn: 'arn:aws:iam::123456:role/IambicSpokeRole' # Optional. The role assumed using credentials provided by `aws_profile`

Write the finished config file to config/config/yaml in your iambic-templates repository. Once this is written to disk, your repository should resemble this folder structure:

$ tree
.
├── config
│   └── config.yaml

Okta​

Okta Organizations​

Okta settings contain API secrets and should be treated as sensitive. We recommend that you store them in a separate configuration file, and merge it into your main configuration file using the extends key. You can leverage AWS secrets manager, or use a separate configuration file to store this configuration.

  • OKTA_DOMAIN=<your_okta_domain> # ex: https://dev-12345.okta.com/, you get the dev-12345 portion, specific to your environment from the Okta portal.
  • OKTA_IDP_NAME=<your_okta_idp_name> # ex: development. This is a friendly name to identify your Okta organization. Any arbitrary string will work here.
  • OKTA_API_TOKEN=<your_okta_api_token> # An administrative API token for your Okta organization

An example configuration is included below:

secrets:
  okta:
    organizations:
      - idp_name: $OKTA_IDP_NAME
        org_url: $OKTA_DOMAIN
        api_token: $OKTA_API_TOKEN

Configuration Reference Keys​

template_type​

The template_type field specifies the type of template, which is NOQ::Core::Config.

extends​

The extends field can be used to merge an additional configuration into the current configuration. This is useful if you want to merge secrets from a separate configuration file into the current configuration, or if you want to leverage AWS Secrets Manager to store secrets.

version​

The version field specifies the version number of the YAML configuration.

aws​

The aws field is used to specify AWS accounts and organizations that IAMbic has access to. This field can contain two nested lists: organizations and/or accounts.

aws.organizations​

The organizations list is used to specify one or more organization entities within AWS. IAMbic can inspect organization entities to parse all attached accounts.

aws.accounts​

The accounts list is used to specify one or more AWS accounts that IAMbic should synchronize.

For more information about hub and spoke roles for AWS, see the Hub and Spoke roles documentation.