AWS Onboarding

Onboarding your AWS account to Klarity ImageFactory allows the platform to build, manage, and distribute Amazon Machine Images (AMIs) directly within your infrastructure. This guide covers the necessary prerequisites, authentication methods, and required permissions.

Prerequisites

Before you start the onboarding process, ensure you have the following:

1. An active AWS account.
2. IAM permissions to create roles, policies, and manage cross-account trust relationships (or permissions to deploy CloudFormation stacks).
3. Access to the Klarity ImageFactory console or API.

Onboarding via the UI (Recommended)

The fastest way to onboard an AWS account is through the ImageFactory UI, which provides a guided wizard with a ready-made CloudFormation template.

1. Navigate to Cloud Credentials in the sidebar and click Add Credentials.
2. Select AWS as the provider.
3. Enter your Account ID.
4. Download the CloudFormation template provided in the wizard and deploy it in your AWS account via the AWS Management Console. The template creates the ImageFactoryMasterRole IAM role with all required permissions and a trust relationship to Nordcloud's AWS account. We recommend deploying in eu-west-1, but any region works.
5. Enter a randomly generated External ID — this acts as a shared secret between ImageFactory and your AWS account. Use the same value both in the CloudFormation stack parameters and in the ImageFactory form.
6. After the stack completes, find the ImageFactoryMasterRole in IAM and copy its ARN back into the form.
7. Optionally configure image sharing destinations (accounts, organizations, OUs).

tip

The CloudFormation template handles all IAM permissions automatically — you don't need to manually create roles or policies.

Required IAM Permissions

The IAM entity (Role or User) used by ImageFactory must have permissions to manage EC2 resources. Below is a summary of the required actions:

Service	Actions	Purpose
EC2	DescribeImages, CreateImage, CopyImage, DeregisterImage	Manage AMI lifecycle
EC2	DescribeSnapshots, DeleteSnapshot, ModifySnapshotAttribute	Manage underlying storage
EC2	RunInstances, TerminateInstances, DescribeInstances	Provision build instances

China Region Support

If you are operating in AWS China (Beijing or Ningxia), you must onboard using the AWS China provider type. The UI wizard provides a separate CloudFormation template (ImageFactoryMasterUserAWSChina.yml) that creates an IAM user with access keys instead of a cross-account role.

Key differences from standard AWS onboarding:

• Uses IAM access keys (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY) instead of an IAM role.
• The CloudFormation stack must be deployed in the region where you will distribute images.
• If you need multiple AWS China regions, each must be onboarded as a separate account.

Image Sharing Features

ImageFactory can automatically share built AMIs with other accounts, organizations, or organizational units (OUs).

• awsShareAccounts: A list of individual AWS account IDs.
• awsShareOrganizations: Organization ARNs, for example arn:aws:organizations::*:organization/o-example.
• awsShareOus: Organizational Unit ARNs.

KMS Encryption

To encrypt your AMIs using a customer managed key, provide the kms_key_id in your configuration. Ensure that the ImageFactoryMasterRole has the kms:DescribeKey, kms:CreateGrant, and kms:Decrypt permissions for the specified key.

Adding Your AWS Account

To onboard your AWS account, navigate to Cloud Credentials in the sidebar and click Add Credentials. Select AWS as the provider and follow the guided wizard — the CloudFormation template handles the IAM role setup automatically.

For a detailed walkthrough of the onboarding interface, see the Cloud Credentials guide.

Via API

You can also onboard an account programmatically using the GraphQL API:

mutation CreateAwsAccount {
  createAccount(input: {
    name: "Production-AWS"
    provider: AWS
    awsConfig: {
      roleArn: "arn:aws:iam::123456789012:role/ImageFactoryMasterRole"
      externalId: "your-unique-external-id"
      region: "eu-west-1"
      kmsKeyId: "arn:aws:kms:eu-west-1:123456789012:key/your-key-id"
    }
  }) {
    id
    status
  }
}

Verifying the Connection

After adding the account, use the "Recheck" feature in the console or the recheckAccount mutation in the API. This triggers a validation process to ensure that the credentials are valid and the permissions are correctly configured. If the status changes to ACCESS_SUCCESS, your account is ready for image building.