Kubiya LogoKubiya Developer Docs
Integrations

Connect to AWS

Connect one or more AWS roles to the Kubiya platform for agent use.

Connect to AWS

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

Decide Role Assumption Method

Choose whether Kubiya assumes the role directly (recommended) or if your cluster's service account handles assumption.

Configure Role in AWS

Set up the IAM Role(s) with the necessary permissions and establish a trust relationship either with Kubiya's AWS account (564407622114) or your cluster's OIDC provider.

Add Role(s) to Kubiya

Create or update an AWS Integration in the Kubiya platform, adding the ARN and region for each role.

Validate Roles

If Kubiya assumes the role, use the 'Validate' button in the UI to confirm Kubiya can successfully assume each configured role.

Finalize Integration

Select the active roles for the integration and designate one as the default. Save the integration.

You can also manage AWS Integrations using the Kubiya Terraform Provider.

Step 1: Decide Role Assumption Method

Kubiya offers two options for role assumption:

  • 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.

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.

Method C: Using CloudFormation Template

You can also set up the AWS integration using a CloudFormation template, which automates the role creation process:

Access CloudFormation Template

  1. Log in to your Organization Root AWS account (the account with AWS SSO Service, not the target account where permissions will be set).
  2. Click the following link to access the CloudFormation template: Create Kubiya Role Stack

Create Stack

  1. Click Next to proceed with stack creation.
  2. Provide a stack name and optionally override the default role name.
  3. Click Next to continue.
  4. Acknowledge the IAM resource creation by selecting: "I acknowledge that AWS CloudFormation might create IAM resources with custom names."
  5. Review and add any additional tags if needed.
  6. Click Create stack to deploy.

Get Role ARN

  1. Once the stack is created, navigate to the Resources tab.
  2. Click on the newly created role.
  3. Copy the role's ARN from the top of the role details page.

Configure in Kubiya

  1. Log in to the Kubiya Platform.
  2. Create a new AWS integration.
  3. Provide a name for the integration.
  4. Click "Add Role" under the "AWS Roles" dropdown.
  5. Enter a name for the role and paste the ARN from the previous step.
  6. Save the integration.

Using CloudFormation provides a more automated and repeatable way to set up AWS integrations, especially when managing multiple environments or accounts.

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]

Validation is not possible if using the "Runner Service Account" assumption method. Ensure your cluster configuration is correct.

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.

Enable Users Auto-Sync

Automatically synchronize users from Okta to Kubiya

Connect to Microsoft Azure

Integrate Kubiya with Azure using service principals or runner-level authentication.

On this page