Skip to main content

Terraform

Use nOps custom Terraform provider and module to easily integrate your AWS accounts. Manage project lifecycles and use your CICD pipelines to deploy the necessary infrastructure and communicate securely with the platform.

Prerequisites​

  • Admin role permissions in AWS in order to add the AWS Payer and/or child accounts to nOps using Terraform.

  • An API key generated from the nOps platform.

nOps Onboarding​

When you log in to your nOps account for the first time, a pop-up screen will appear. This pop-up screen will guide you on how you can add your AWS account(s) to nOps:

  1. Select the IaaC Multiple Accounts Setup option and click Next.

  2. This section informs you of the prerequisites needed to complete the process, it also includes the Terraform code necessary to add in your configuration. To generate an API key, click Proceed to Create API Key.

  3. In the Generate new API key section

  4. After you fill in all the information, click Generate.

note

nOps will generate and display an API key for you. Copy and save the API key for future use, and click OK.

At this point, it's time to move to Terraform to finish the process.

Terraform module​

The nOps provided public Terraform module contains the complete logic to quickly and seamlessly onboard AWS accounts into the nOps platform. Customers using Terraform as the IaC of choice can quickly integrate their account into nOps by calling this module. The module can be found in the Terraform registry, refer to it for additional details.

Features​

  • Automatic detection of existing nOps projects for the AWS accounts
  • Creation of new nOps projects if none exist
  • Handling of payer and child AWS accounts
  • Automatic setup of IAM roles and least privilege policies for nOps integration
  • S3 bucket creation and configuration for payer accounts
  • Integration with nOps APIs for project lifecycle management using a custom nOps Terraform provider

Prerequisites​

  • Terraform v1.0+
  • AWS CLI configured with appropriate permissions
  • nOps API key
note

For both Payer and Child accounts, it can take up to 24 hours before you start seeing the different nOps dashboards and compliance views populated with data from your workloads.

Onboarding Payer Account​

The example below shows how to add the payer (root) AWS account integration:

  1. Being authenticated on the Payer account of the AWS organization, add the following code:

    terraform {
      required_providers {
        nops = {
          source = "nops-io/nops"
        }
      }
    }

    provider "nops" {
      # nOps API key that will be used to authenticate with the nOps platform to onboard the account. 
      # It's recommended to not commit this value into VCS, to securely provide this value use a tfvars that isn't commited into any repository.
      # This value can also be provided as an environment variable NOPS_API_KEY
      nops_api_key            = "XXXXXXX"
    }

    provider "aws" {
      alias  = "root"
      region = "us-west-2"
      # Below is an example, you can use the authentication method of your choice to access AWS.
      assume_role {
        role_arn = "arn:aws:iam::123456789012:role/role"
      }
    }

    module tf_onboarding {
      providers = {
        aws = aws.root
      }
      source             = "nops-io/nops-integration/aws"
    }

  2. Initialize Terraform:

    terraform init
note

To get the latest version of the module use the -upgrade flag.

  1. Plan and apply the Terraform configuration:

    terraform plan -out=plan

    terraform apply plan

After the Terraform apply run has finished, your account should be listed within the nOps platform as payer.

Onboarding Child Accounts​

Onboarding a child account is achieved using the same module, it already contains the logic to react when its being applied on any account that is not root.

terraform {
  required_providers {
    nops = {
      source = "nops-io/nops"
    }
  }
}

provider "nops" {
  # nOps API key that will be used to authenticate with the nOps platform to onboard the account. 
  # It's recommended to not commit this value into VCS, to securely provide this value use a tfvars that isn't commited into any repository.
  # This value can also be provided as an environment variable NOPS_API_KEY
  nops_api_key            = "XXXXXXX"
}

provider "aws" {
  alias  = "child"
  region = "us-west-2"
  # Below is an example, you can use the authentication method of your choice to access AWS.
    assume_role {
      role_arn = "arn:aws:iam::xxxxxxxx:role/role"
    }
}

module tf_onboarding {
  providers = {
    aws = aws.child
  }
  source             = "nops-io/nops-integration/aws"
}

After applying, you should see the Child account in the projects list.

Importing existing nOps projects​

The nOps Terraform provider supports importing existing projects into the state as to allow already onboarded customers to manage their projects with IaC. In order to import a project follow the next steps:

  • First, grab the project ID from nOps. You can get it from the AWS accounts dashboard, each account has an ID below its name.
  • Then in your Terraform configuration run the following commands:
terraform import module.tf_onboarding.nops_project.project XXXXX

You should see the following output

module.tf_onboarding.nops_project.project: Importing from ID "XXXX"...
module.tf_onboarding.nops_project.project: Import prepared!
  Prepared nops_project for import
module.tf_onboarding.nops_project.project: Refreshing state...

Import successful!

The resources that were imported are shown above. These resources are now in
your Terraform state and will henceforth be managed by Terraform.

  • After the above, we need to import the integration with the AWS account, for this run the following replacing your AWS acconunt ID.
terraform import module.tf_onboarding.nops_integration.integration XXXXXX

You should see the following output, with the AWS account ID being imported into the state.

module.tf_onboarding.nops_integration.integration: Importing from ID "XXXXXX"...
module.tf_onboarding.nops_integration.integration: Import prepared!
  Prepared nops_integration for import
module.tf_onboarding.nops_integration.integration: Refreshing state...

Import successful!

The resources that were imported are shown above. These resources are now in
your Terraform state and will henceforth be managed by Terraform.

Minimum nOps required IAM policies​

A variable named min_required_permissions has been declared in the nOps terraform module that enabled customers choosing a more restricted setup to be able to use the platform. In order to enter this restricted mode, set the variable to true. Take into consideration that nOps will not be able to get the full metadata for AWS resources with this setup. To review these permissions, refer to the policies page or the Terraform module for the most recent updates.

Troubleshooting​

If you see an error like the following

Error: Error getting remote project data
 
  with module.tf_onboarding.data.nops_projects.current,
  on .terraform/modules/tf_onboarding/data.tf line 9, in data "nops_projects" "current":
  9: data "nops_projects" "current" {}

Check that the API key value being provided is valid and exists in your account. Your current API keys are listed here.

nOps supports onboarding unique AWS accounts per Client, onboarding the same AWS account multiple times for one Client isn't allowed. So if you see an error like the following

Error: Error: a project already exists for this AWS account "XXXXXX" with ID YYYY, please review or import.

  with module.tf_onboarding_should_fail.nops_project.project,
  on .terraform/modules/tf_onboarding_should_fail/main.tf line 1, in resource "nops_project" "project":
   1: resource "nops_project" "project" {}

Project found for AWS account "XXXX"

Then check that the credentials being used to deployed are correct. If they are, we support importing projects into the Terraform state. Please refer to the import section.

important

If you have any questions, please contact us at help@nops.io