Skip to main content

Quickstart Guide

Welcome to the Nuvibit Terraform Collection (NTC) Quickstart Guide!

This guide will help you deploy your first NTC building block: NTC Organizations. This building block is designed to create and manage your AWS Organization, define the Organizational Unit (OU) structure, and apply guardrails such as Service Control Policies (SCPs).

Why NTC Organizations?​

The NTC Organizations building block manages AWS Organizations which is the first thing you need to configure when setting up an AWS multi-account environment.

Key goals include:

  • Creating an AWS Organization
    Set up a central management layer for governing multiple AWS accounts.

  • Defining OU Structures
    Organize accounts by workloads, environments, or business units.

  • Applying Guardrails
    Enforce policies and ensure compliance using SCPs.

Prerequisites​

Before deploying the NTC Organizations building block, ensure the following requirements are met:

  1. Valid NTC Subscription
    Ensure you have a valid NTC subscription and access to the NTC library. Otherwise, contact us.

  2. AWS Management Account
    A central AWS account to manage your AWS Organization. See Step 1.

  3. Terraform / OpenTofu Installed
    Install the latest version of Terraform or OpenTofu.
    We recommend using a version manager such as tenv to easily switch between versions.

  4. CI/CD Pipeline
    Set up a CI/CD pipeline with tools like Spacelift, GitHub Actions, or GitLab. See Step 2 for guidance.


info

While a CI/CD pipeline is not strictly required for deployment, it is strongly recommended. Using a CI/CD pipeline ensures quality, reliability, and consistency throughout your infrastructure provisioning and updates.

Step-by-Step Deployment​

Step 1: Create AWS Management Account​

  1. Access the AWS Management Console
    Open the AWS Management Console at https://console.aws.amazon.com/.

  2. Create a New AWS Account

    • Click Create a new AWS account and follow the instructions.
    • Provide account details, including a valid email address, payment information, and phone verification.
    • For detailed instructions, refer to the AWS Account Creation Guide.

  3. Enable Multi-Factor Authentication (MFA)

    • Configure MFA for the root user to enhance account security.
    • For detailed instructions, refer to the AWS MFA Setup Guide.

info

Define a consistent naming convention for AWS accounts and email addresses that reflect their purpose.
For example:

  • Account Name: aws-org-management
  • Email Address: aws-org-management@company.com
warning
  • Use a non-personal email address for the AWS Management Account to prevent losing access to the mailbox.
  • Regularly review and track who has access to the account and mailbox.
  • Maintain a valid and active phone number for recovery purposes, capable of receiving text messages or calls.

For additional best practices, refer to the AWS Organizations Guide.

Step 2: Set up a CI/CD Pipeline​

tip

Check out our CI/CD Pipelines for Infrastructure-as-Code Delivery whitepaper for detailed guidance and best practices.

  1. Choose a CI/CD Tool
    Use a CI/CD pipeline tool like Spacelift, GitHub Actions, or GitLab CI/CD to automate and streamline deployments.

  2. Set Up a Terraform / OpenTofu State Backend

    • Some CI/CD tools natively support Terraform / OpenTofu state management (e.g. Spacelift).
    • Otherwise, you can use Amazon S3 as state backend and DynamoDB for state locking.

  3. Create a Code Repository

    • Set up a Git repository to store your Terraform / OpenTofu configuration.
    • Keep consistent naming between AWS accounts, Git repositories and CI/CD pipelines for easier maintenance.
    • We recommend enabling branch protection on the main branch and push updates via pull request.

  4. Create a CI/CD Pipeline

    • Associate the code repository with the pipeline and define pipeline triggers (e.g. pull request triggers a plan run)
    • Define pipeline stages for checks, plan, apply, and testing operations.
    • Define pipeline triggers (when to trigger a plan run and when to trigger an apply run).
    • Define environment variables or integrate a secrets manager for sensitive data such as credentials or secrets.

  5. Set Up OpenID Connect (OIDC)

    • Configure OIDC for secure, short-lived authentication to AWS.
    • Follow the AWS OIDC Setup Documentation to integrate your chosen CI/CD tool.

  6. Grant Necessary Permissions

    • Assign pipeline permissions via the IAM role in the AWS Management Account.
    • Start with AdministratorAccess for simplicity and move towards least-privilege permissions as your setup matures.
    • Limit access to the pipeline to trusted users and maintain strict controls.

  7. Configure NTC Access

    • Your pipeline requires access to NTC. There are various options:

    Spacelift CI/CD Pipeline For a Spacelift pipeline, no credentials are required. Reference NTC directly from the Spacelift registry:

    module "ntc_organizations" {
       source  = "spacelift.io/nuvibit/ntc-organizations/aws"
       version = "1.3.1"

       # additional parameters
    }

warning

We strongly recommend using OpenID Connect (OIDC) for pipeline authentication to AWS.
Limit access to the CI/CD pipeline and audit its usage to prevent unauthorized changes.

If OIDC is not feasible, an IAM user with an access key and secret access key can also be used.
Make sure to regularly rotate access keys to minimize security risks.

Step 3: Deploy NTC Organizations​

  1. Initialize Terraform / OpenTofu Configuration
    Configure requirements, backend and providers:

    # -----------------------------------------------------------------------------------------------
    # REQUIREMENTS
    # -----------------------------------------------------------------------------------------------
    terraform {
       # pin versions to only increment the patch to minimize the chance of breaking changes
       required_version = "~> 1.8.5"
       required_providers {
          aws = {
             source                = "hashicorp/aws"
             version               = "~> 5.80"
             configuration_aliases = []
          }
       }
    }

    # -----------------------------------------------------------------------------------------------
    # PROVIDERS
    # -----------------------------------------------------------------------------------------------
    /*
    use environment variables for authentication via OpenID Connect:
    AWS_ROLE_ARN, AWS_WEB_IDENTITY_TOKEN_FILE, AWS_ROLE_SESSION_NAME

    use environment variables for authentication via IAM user:
    AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
    */
    provider "aws" {
       region = "eu-central-1"
       # add default tags to all resources that the provider creates
       default_tags {
          tags = local.default_tags
       }
    }

    # add additional providers for other regions in use
    provider "aws" {
       alias  = "use1"
       region = "us-east-1"
       default_tags {
          tags = local.default_tags
       }
    }

    # -----------------------------------------------------------------------------------------------
    #  DATA
    # -----------------------------------------------------------------------------------------------
    data "aws_region" "default" {}
    data "aws_caller_identity" "current" {}

    # -----------------------------------------------------------------------------------------------
    # LOCALS
    # -----------------------------------------------------------------------------------------------
    locals {
       default_tags = {
          ManagedBy     = "opentofu"
          ProvisionedBy = "ntc-organizations"
       }
    }

  2. Test Pipeline Access to AWS
    If you configured OpenID Connect correctly, you should now be able to test your pipeline. You can either create a pull request or run a local plan with Terraform / OpenTofu (requires local credentials).

    # download and initialize providers and modules
    terraform init --upgrade
    # preview the changes that Terraform plans to make
    terraform plan

    If Terraform / OpenTofu outputs the “account_id” and “default_region”, you have successfully connected your pipeline to AWS.

    data.aws_caller_identity.current: Reading...
    data.aws_region.default: Reading...
    data.aws_region.default: Read complete after 0s [id=eu-central-1]
    data.aws_caller_identity.current: Read complete after 0s [id=012345678901]

    Changes to Outputs:
    + account_id     = "012345678901"
    + default_region = "eu-central-1"

    You can apply this plan to save these new output values to the OpenTofu state, without changing any real
    infrastructure.

  3. Explore Configuration Options
    Check the NTC Organizations documentation page to explore the full range of configuration options. The page includes:

    • A comprehensive list of parameters to tailor your setup.
    • A practical usage example for implementation guidance.
    • A detailed implementation blueprint to ensure alignment with best practices.

  4. Define your Organization Structure
    An organizational unit (OU) provides a means to group accounts. OUs are not meant to mirror your own organization’s reporting structure. Instead, OUs are intended to group accounts that have common overarching security policies and operational needs. The primary question to ask yourself is: How likely will the group need a set of similar policies?

    Use the following organizational structure as a blueprint and adapt it as needed: Organization Structure

  5. Apply Configuration
    Open a pull request with your customized configuration:

    # -----------------------------------------------------------------------------------------------
    # NTC ORGANIZATIONS
    # -----------------------------------------------------------------------------------------------
    module "ntc_organizations" {
       source = "github.com/nuvibit-terraform-collection/terraform-aws-ntc-organizations?ref=1.3.1"

       # list of services which should be enabled in Organizations
       service_access_principals = [
          "account.amazonaws.com",
          "cloudtrail.amazonaws.com",
          "securityhub.amazonaws.com",
          "config.amazonaws.com",
          "config-multiaccountsetup.amazonaws.com",
          "guardduty.amazonaws.com",
          "inspector2.amazonaws.com",
          "malware-protection.guardduty.amazonaws.com",
          "sso.amazonaws.com",
          "ipam.amazonaws.com",
          "servicequotas.amazonaws.com",
       ]

       # list of nested (up to 5 levels) organizational units
       organizational_unit_paths = [
          "/root/core",
          "/root/sandbox",
          "/root/exceptions",
          "/root/suspended",
          "/root/workloads",
          "/root/workloads/prod",
          "/root/workloads/dev",
       ]

       # guardrails which should be attached to multiple organizational units and/or accounts
       # NTC offers guardrail templates which can be directly referenced here
       service_control_policies = [
          # {
          #   policy_name        = "scp_deny_all_outside_eu_regions",
          #   target_ou_paths    = ["/root/workloads"]
          #   target_account_ids = []
          #   policy_json        = "INSERT_SCP_JSON"
          # }
          module.ntc_guardrail_templates.service_control_policies["scp_root_ou"],
          module.ntc_guardrail_templates.service_control_policies["scp_suspended_ou"],
          module.ntc_guardrail_templates.service_control_policies["scp_workloads_ou"],
       ]
    }

    Wait for pull request checks to complete and merge to start deployment

    Pull Request

  6. Verify Deployment

    • Check the AWS Management Console to ensure the organization, OUs, and SCPs have been created.

      AWS Organizations

      AWS Guardrails

Conclusion​

Congratulations 🎉 You have successfully deployed the NTC Organizations building block. This essential step sets up a structured AWS Organization with initial guardrails, providing a solid starting point to scale your AWS environment.

Next Steps​

The Nuvibit Terraform Collection (NTC) is designed with a modular approach, offering flexibility to adapt to your specific needs and requirements. Explore NTC building blocks by topic or the NTC library page for detailed information about NTC building blocks.

tip

Use the Nuvibit AWS Reference Architecture as a starting point and customize it to your specific requirements.

Nuvibit AWS Reference Architecture

Implementing the Nuvibit AWS Reference Architecture​

  1. NTC Account Factory (documentation) (implementation blueprint)

    • Serves as the cornerstone of your AWS foundation and Landing Zone.
    • Create the Log Archive, Security, and Connectivity core accounts.

  2. NTC Parameters (documentation) (implementation blueprint)

    • Simplifies multi-account orchestration by providing a streamlined way to share parameters across AWS accounts and pipelines.

  3. NTC Identity Center (documentation) (implementation blueprint)

    • Enables single sign-on (SSO) access to your AWS environment with fine-grained controls for users and groups.
    • When combined with the NTC Account Factory, SSO access management can be fully automated and orchestrated.

  4. NTC Log Archive (documentation) (implementation blueprint)

    • Provisions centralized S3 buckets to archive audit logs for regulatory compliance (e.g., CloudTrail, VPC FLow Logs).
    • After creating the CloudTrail S3 Log Archive, enable CloudTrail in NTC Organizations.

  5. NTC Security Tooling (documentation) (implementation blueprint)

    • Configure necessary admin delegations via NTC Organizations for the security account.
    • Configure the central Security Hub and additional security services of your choice (e.g., GuardDuty, Inspector, Macie).

  6. NTC Connectivity Building Blocks (implementation blueprint)


note

Check the latest NTC releases for new features and updates.