AWS Asset Discovery Guide

Step-by-step guide for setting up AWS Organisation and Account Discovery

Introduction

This guide provides a detailed walkthrough for setting up and using the AWS Organisation and Account Discovery feature in Nirmata’s Cloud Control Point. This feature allows for comprehensive discovery of AWS accounts and organisational units (OUs) within an AWS Organisation.

Prerequisites

Before you begin, ensure you meet the following prerequisites:

Access to Nirmata Control Point: Ensure you have access to the cluster where the Cloud Control Point is hosted, along with the necessary RBAC permissions to create an AWSOrgConfig Custom Resource.
IAM Role Creation Permissions in the Management Account: Verify that you have the permissions required to create an IAM role in the management account of the AWS Organisation.
Permissions in Discovered Accounts: Confirm that you have the permissions needed to create IAM roles within the AWS accounts that will be discovered.

AWSOrgConfig

AWSOrgConfig is a custom resource used in Cloud Control Point to facilitate the discovery of AWS Organisation Units (OUs) and accounts.

Purpose

The primary purpose of AWSOrgConfig is to enable the cloud controller to recursively discover all child OUs and AWS accounts within a specified AWS Organisation. This ensures that all resources are accounted for and managed effectively.

Key Fields

apiVersion: Specifies the API version, e.g., nirmata.io/v1alpha1.
kind: The type of resource, which is AWSOrgConfig.
metadata: Contains metadata about the resource, including:
- name: The name of the AWSOrgConfig instance.
spec: Defines the desired state of the resource, including:
- orgID: The ID of the organisation unit or root to be configured, assigned by AWS.
- orgName: The name of the organisation as desired by the user.
- regions: The AWS regions from which resources need to be scanned.
- roleARN: Enter the ARN of the role created in the management account. This role must have the necessary permissions to list AWS accounts and organizational units.
- customAssumeRoleName: Specify the name (not ARN) of the IAM role that is created in the AWS accounts. This role should have permissions to access resources in the configured services.
- scanInterval: The frequency of the scan.
- services: The AWS services in which resources need to be scanned.

Usage

To use AWSOrgConfig, create a new instance in the Cloud Control Point with the necessary fields filled out. Once configured, the cloud controller will automatically handle the discovery of OUs and accounts, creating additional AWSOrgConfig and AWSAccountConfig resources as needed.

Example

Here is an example of an AWSOrgConfig:

apiVersion: nirmata.io/v1alpha1
kind: AWSOrgConfig
metadata:
  name: root
spec:
  orgID: r-zyre
  orgName: Root
  regions:
  - us-west-1
  roleARN: arn:aws:iam::<account-id>:role/<role-name>
  customAssumeRoleName: <role-name-in-child-accounts>
  scanInterval: 1h
  services:
  - EKS
  - ECS
  - EC2
  - Lambda
  - RDS

This configuration will initiate the discovery process for the specified organisation, ensuring all child OUs and accounts are managed effectively.

Step-by-Step Setup

Step 1: Create an IAM Role in the Management Account

Navigate to the AWS Management Console: Log in to the AWS management account of the organisation and access the IAM service.

Create a New Policy:

Go to the Policies section and click on ‘Create policy’.

Choose the JSON tab and enter the following policy document:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "organizations:ListAccounts",
                "organizations:ListOrganizationalUnitsForParent",
                "organizations:ListAccountsForParent"
            ],
            "Resource": "*"
        },
    ]
}

Review and create the policy.

Create a New Role:

Go to the Roles section and click on ‘Create role’.
Attach the policy you just created.

Set up the trust relationship with the following JSON:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": <ARN of the IAM Role bound to cloud scanner through pod identity agent>
            },
            "Action": [
                "sts:AssumeRole",
                "sts:TagSession"
            ]
        }
    ]
}

Review and create the role.

This IAM role will have the necessary permissions to list AWS accounts and organizational units, and can be assumed by the IAM role attached to cloud scanner service account through pod identity agent.

Step 2: Create an IAM Role in Discovered AWS Accounts

Refer to Cross-Account Setup Documentation: For detailed instructions on setting up cross-account access, please refer to the Nirmata Cloud Scanner Cross-Account Setup.
Create IAM Role in Each Discovered Account:
- Ensure that each discovered AWS account has an IAM role with the necessary permissions to allow the cloud scanner to access resources in the configured services.

This step ensures that the cloud scanner can effectively access resources across all AWS accounts within the organisation.

Step 3: Create the AWSOrgConfig Custom Resource

Access the Cloud Control Point Cluster: Ensure you have access to the cluster where the Cloud Control Point is deployed.

Create AWSOrgConfig Custom Resource:

Prepare a YAML file with the necessary configuration for the AWSOrgConfig.

Example YAML:

apiVersion: nirmata.io/v1alpha1
kind: AWSOrgConfig
metadata:
  name: root
spec:
  orgID: r-zyre
  orgName: Root
  regions:
  - us-west-1
  roleARN: arn:aws:iam::<account-id>:role/<role-name>
  customAssumeRoleName: DevTestAccountAccessRole
  scanInterval: 1h
  services:
  - EKS
  - ECS
  - EC2
  - Lambda
  - RDS

This step sets up the AWSOrgConfig directly in the Cloud Control Point cluster.

Step 4: Verify Configuration

Monitor Discovery: The cloud controller will automatically discover child OUs and accounts.

Troubleshooting

Failure Records: Any failure during the discovery process is recorded in the status field of the AWSOrgConfig. Check this field for detailed error messages and troubleshooting information.

Conclusion

By following this guide, you should have successfully set up AWS Organisation and Account Discovery in Nirmata’s Cloud Control Point.