Exposing multiple roles to Agents

It is possible to integrate more than a single role for a Kubiya Agent, facilitating seamless role switching and continuous credential rotation. This capability is achieved by setting environment variables that designate each role Kubiya should assume. By configuring multiple roles, Kubiya Agents can dynamically adapt to various AWS environments, equipped with the necessary permissions to execute their tasks effectively.


  1. Initial Role setup Ensure you have administrative access to your AWS account to create roles and policies by following the initial integration guide

  2. IAM Roles: You must have the IAM roles created in AWS that you want to expose to the Kubiya Agents.

Step 1: Define IAM Roles

Ensure that each IAM role you want to expose to the agents has the necessary permissions to perform required tasks. Each role should have a trust relationship that allows the master role (the initial role used during the Kubiya setup) to assume it.

Step 2: Set Environment Variables

For each role that you want Kubiya Agents to assume, set an environment variable in the format AWS_ROLE_X, where X is a sequential number starting from 1. The value of each variable should include the role's ARN and a friendly name for the account, separated by a colon.




  • AWS_ROLE_1=arn:aws:iam::123456789012:role/MyFirstRole:MyFirstAccount

  • AWS_ROLE_2=arn:aws:iam::123456789013:role/MySecondRole:MySecondAccount

Step 3: Configure the agent to Assume Roles

Modify the Agent configuration to read these environment variables and initiate role assumption. The initial role Kubiya uses (referred to as the master role) should have the permissions to assume additional roles specified in the environment variables:

Automatic Credential Rotation

Kubiya Agents are configured to continuously check the expiration of the current credentials and automatically renew them by re-assuming the respective roles. This ensures that the credentials are always valid without manual intervention. The process involves:

  • Monitoring the credential expiration.

  • Automatically re-assuming the role 10 minutes before the credentials expire.

  • Updating the local credential store with new credentials.

How does Agents knows about the available profiles?

Kubiya Agents use the provided role credentials to access AWS resources. The agents dynamically determine the available profiles based on the environment variables and can switch contexts based on operational needs. This setup allows for flexible, secure, and efficient resource management across multiple AWS accounts.

For example, an agent asked to scan for JIRA tickets releted to multiple AWS accounts could use the --profile flag dynamically and allow complex workflows such as being able to determine which role (profile) credentials to use based on the account alias being set on the configuration

Last updated