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, organisational units (OUs), and EKS clusters within an AWS Organisation. The discovery process follows a hierarchical approach: OUs are discovered first, then accounts within those OUs, and finally EKS clusters within the discovered accounts.

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. For each discovered account, the system automatically creates AWSAccountConfig resources, then discovers EKS clusters within those accounts through ClusterConfig resources. This ensures that all resources are accounted for.

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. It will then discover EKS clusters within their respective accounts and create ClusterConfig resources for each discovered cluster.

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
  - us-east-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.

AWSAccountConfig

AWSAccountConfig is automatically created by the cloud controller for each discovered AWS account. This resource manages the scanning and discovery of resources within individual AWS accounts.

Purpose

The AWSAccountConfig resource enables the cloud controller to scan resources within a specific AWS account and discover EKS clusters. When EKS clusters are found, the system automatically creates ClusterConfig resources for each cluster.

Key Fields

  • apiVersion: Specifies the API version, e.g., nirmata.io/v1alpha1.
  • kind: The type of resource, which is AWSAccountConfig.
  • metadata: Contains metadata about the resource, including:
    • name: The name of the AWS account.
  • spec: Defines the desired state of the resource, including:
    • accountID: The AWS account ID.
    • accountName: The name of the AWS account.
    • roleARN: The ARN of the IAM role in the account for resource access.
    • regions: The AWS regions to scan for resources.
    • scanInterval: The frequency of the scan.
    • services: The AWS services to scan for resources.

Example

Here is an example of an AWSAccountConfig:

apiVersion: nirmata.io/v1alpha1
kind: AWSAccountConfig
metadata:
  name: aws-scan
spec:
  scanInterval: 1h
  accountID: "844333509XXX"
  accountName: "example-account"
  roleARN: "arn:aws:iam::844333509XXX:role/DevTestAccountAccessRole"
  regions:
    - us-east-1
    - us-west-1
  services:
    - EKS
    - ECS
    - EC2
    - Lambda
    - RDS
    - ApiGateway
    - ApiGatewayV2

ClusterConfig

ClusterConfig is automatically created by the cloud controller for each discovered EKS cluster within an AWS account.

Purpose

The ClusterConfig resource represents a discovered EKS cluster and contains the necessary information for the cloud controller to interact with and manage the cluster.

Key Fields

  • apiVersion: Specifies the API version, e.g., nirmata.io/v1alpha1.
  • kind: The type of resource, which is ClusterConfig.
  • metadata: Contains metadata about the resource, including:
    • name: The name of the EKS cluster.
    • labels: Contains cloud provider metadata such as account ID and account name.
    • ownerReferences: References the parent AWSAccountConfig resource.
  • spec: Defines the cluster configuration, including:
    • cloudProvider: The cloud provider (AWS).
    • clusterEndpoint: The API endpoint of the EKS cluster.
    • clusterName: The name of the EKS cluster.
    • region: The AWS region where the cluster is located.
    • scanInterval: The frequency of cluster scanning.

Example

Here is an example of a ClusterConfig:

apiVersion: nirmata.io/v1alpha1
kind: ClusterConfig
metadata:
  name: example-cluster
  labels:
    cloud.nirmata.io/account-id: "844333509XXX"
    cloud.nirmata.io/account-name: example-account
  ownerReferences:
  - apiVersion: nirmata.io/v1alpha1
    blockOwnerDeletion: true
    controller: true
    kind: AWSAccountConfig
    name: example-account
    uid: 808b9ff2-545b-401e-a038-0032e139c7a1
spec:
  cloudProvider: AWS
  clusterEndpoint: https://XXXXX.sk1.us-west-1.eks.amazonaws.com
  clusterName: example-cluster
  region: us-west-1
  scanInterval: 1h0m0s

Step-by-Step Setup

Step 1: Create an IAM Role in the Management Account

  1. Navigate to the AWS Management Console: Log in to the AWS management account of the organisation and access the IAM service.
  2. 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",
                "eks:ListClusters",
                "eks:DescribeCluster"
            ],
            "Resource": "*"
        },
    ]
}
    • Review and create the policy.
  3. 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, organizational units, and EKS clusters, 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

  1. 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.
  2. 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

  1. Access the Cloud Control Point Cluster: Ensure you have access to the cluster where the Cloud Control Point is deployed.
  2. 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
  - us-east-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

  1. Monitor Discovery: The cloud controller will automatically discover child OUs and accounts.
  2. Check Created Resources: Verify that AWSAccountConfig resources are created for discovered accounts:
    kubectl get awsaccountconfig
  3. Verify EKS Cluster Discovery: Check that ClusterConfig resources are created for discovered EKS clusters:
    kubectl get clusterconfig

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. The system will automatically discover your organizational structure, AWS accounts, and EKS clusters, creating the appropriate configuration resources for comprehensive cloud asset management.