Connect to AWS

[Image: Kubiya x AWS Banner]

How it works

When an agent needs to interact with AWS, the execution environment (i.e., the Teammate runner) will get temporary AWS credentials from the configured Kubiya AWS Integration automatically. This allows the agent to use AWS SDKs or the AWS CLI with the permissions defined by the assumed role.

Definitions

These are terms you will come across in Kubiya when integrating with AWS:

1. Role: An AWS IAM Role defining a set of permissions.
2. AWS Integration: A Kubiya entity representing one or more AWS IAM Roles. Grouping roles allows easy assignment to agents.
3. Default Role: Within an AWS Integration containing multiple roles, the default role is used by an agent if no specific role is requested.
4. Agent Access: You grant specific AWS Integrations (and thus, the roles within them) to your agents. See Creating Agents for more details.

Steps

Step 1: Decide Role Assumption Method

Kubiya offers two options for role assumption:

Option 1: Kubiya Assumes Role (Recommended)

• Advantages: Simpler setup, secure, allows Kubiya to validate role assumption.
• How: Establish a trust relationship in the IAM role allowing Kubiya's AWS account (564407622114) to assume it.

Option 2: Cluster Service Account Assumes Role

• Advantages: Required for organizations managing AWS access strictly via their cluster.
• Disadvantages: Kubiya cannot validate the configuration; requires setting up IAM Roles for Service Accounts (IRSA) if using EKS, or equivalent for other Kubernetes distributions.
• How: Configure your Kubernetes service account to assume the desired IAM role.

The configuration steps in AWS differ based on your chosen method.

Step 2: Configure Role Assumption in AWS

Log in to your AWS console and navigate to IAM > Roles.

Method A: Granting Kubiya Permission (Recommended)

If creating a new role:

1. Click Create Role.
2. Trusted entity type: AWS Account.
3. Select Another AWS account.
4. Account ID: 564407622114
5. Do not check "Require external ID" or "Require MFA".
6. Click Next. [Image: AWS Create Role - Trusted Entity]
7. Add necessary permissions for your agent's tasks. [Image: AWS Create Role - Add Permissions]
8. Name and describe the role, then click Create Role. [Image: AWS Create Role - Name and Review]

If using an existing role:

1. Go to the role > Trust relationships tab.
2. Click Edit trust policy.
3. Ensure the policy document allows Kubiya's account. Add or modify the Principal section like this:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:iam::564407622114:root"
         },
         "Action": "sts:AssumeRole"
       }
     ]
   }

4. Click Update policy.

Method B: Granting Cluster/Service Account Permission

1. Create or select an IAM role with the necessary permissions for your agent.
2. Configure a trust relationship allowing your Kubernetes cluster's OIDC provider to assume this role.
3. Associate this IAM role with the specific Kubernetes service account your Kubiya runner/agent pods will use. Refer to AWS documentation for IAM roles for service accounts (IRSA) or equivalent mechanisms.

Step 3: Add Roles to Kubiya Platform

Navigate to Integrations in the Kubiya Web App.

If creating a new AWS integration:

1. Click + New Integration. [Image: Kubiya Integrations List - New Integration Button]
2. Find AWS and click Add. [Image: Kubiya New Integration Modal - AWS]
3. Provide a descriptive Name and Description for the integration. [Image: Kubiya AWS Integration Config - Name/Description]
4. Select the Role Assumption Method (Kubiya or Runner Service Account) matching your Step 1 decision and Step 2 configuration.
5. Under AWS Roles, click Add Role. [Image: Kubiya AWS Integration Config - Add Role Button]
6. Enter:
   • Name: A friendly name for the role within Kubiya.
   • Role ARN: The full ARN of the IAM role (e.g., arn:aws:iam::123456789012:role/MyAgentRole).
   • Region: The AWS region associated with the role or where it will primarily be used. [Image: Kubiya AWS Integration Config - Role Details Modal]
7. Repeat Add Role for all necessary roles. [Image: Kubiya AWS Integration Config - Multiple Roles Added]

If adding to an existing AWS integration:

1. Find the existing AWS integration in the list.
2. Click the menu icon (⋮) and select Edit. [Image: Kubiya Integrations List - Edit Menu]
3. Under AWS Roles, click Add Role and provide the details as described above. [Image: Kubiya AWS Integration Edit - Add Role Button] [Image: Kubiya AWS Integration Edit - Role Details Modal]

Step 4: Validate Roles (Only if Kubiya Assumes Role)

If you selected "Kubiya" as the assumption method:

1. After adding role details, click the Validate button.
2. Kubiya will attempt to assume each role.
3. Success messages will appear for valid roles. [Image: Kubiya AWS Integration - Validation Success]
4. Errors will be shown for roles that Kubiya cannot assume. Double-check the Role ARN and the trust policy in AWS for those roles. [Image: Kubiya AWS Integration - Validation Error]

Step 5: Select Roles, Default Role, and Finish

1. In the AWS Roles dropdown, check the boxes next to the roles you want to include in this integration. [Image: Kubiya AWS Integration - Selecting Roles]
2. Select one role as the Default Role using the radio button. This role will be used if an agent using this integration doesn't specify a particular role ARN.
3. Click Create Integration or Update Integration.

You're done configuring the AWS Integration!

[Image: Kubiya AWS Integration - Final Saved State]

Now you can assign this integration to your Agents.

Editing or Removing a Role

1. Navigate to Integrations.
2. Find the AWS integration, click the menu icon (⋮), and select Edit.
3. Modify role details or click the trash icon next to a role to remove it.
4. To temporarily disable a role without deleting its configuration, uncheck its box in the dropdown.
5. Click Validate (if applicable).
6. Click Update Integration.