Getting started

This section provides information about how to install, set up, and use the AWS Toolkit for Microsoft Azure DevOps.

Set up an Azure DevOps account

To use Azure DevOps, you will first need to sign up for an Azure DevOps account.

Install the AWS Toolkit for Azure DevOps extension

This procedure outlines how to install the AWS Toolkit for Azure DevOps extension.

1. Go to the Extensions for Azure DevOps Visual Studio Marketplace and search for AWS Toolkit for Azure DevOps. (The following URL is a direct link to the AWS Toolkit for Azure DevOps: https://marketplace.visualstudio.com/items?itemName=AmazonWebServices.aws-vsts-tools.)

2. Choose Get it free and sign in to your Azure DevOps account, if prompted.

3. Choose Install to install the toolkit into your Azure DevOps account, or choose Download to install it on an on-premises server.

Establish AWS credentials for the AWS Toolkit for Azure DevOps

To allow the AWS Toolkit for Azure DevOps to access AWS services, you need an AWS account and AWS credentials. When build agents run the tasks contained in the tools, the tasks must be configured with, or have access to, those AWS credentials to enable them to call AWS service APIs.

To increase the security of your AWS account, we recommend that you don't use your root account credentials. You should create an IAM user to provide access credentials to the tasks running in the build agent processes.

For more information about creating an IAM user in your account, and copying that user's credentials, see Setting up the AWS Toolkit for Azure DevOps.

Supply task credentials

After you create an AWS account and IAM user, and you've made a copy of the access key and secret access key for that user, you can supply credentials to the tasks in the following ways.

Topics

• Supply task credentials using a service connection
• Supply credentials through named variables in your build
• Supply standard AWS environment variables in the build agent process
• Supply credentials with Amazon EC2 build agents

Supply task credentials using a service connection

You can create a link to your AWS subscription by using the Service connections section of the Project settings for your project. Note that a service connection expects long-lived AWS credentials consisting of an access-key and secret-key pair. You can also define Assume Role credentials to scope down the access. Service connections also support the use of a session token variable. You can rotate session tokens from the service connections. For more information, see Use personal access tokens in the Microsoft Azure DevOps online documentation.

To set up a service connection

1. Open Azure DevOps and access the project that you want to add a service connection to.

2. Choose the settings icon in the lower-left side of the screen, and then choose Service connections.

3. From New AWS service connection, choose AWS. This opens the Add AWS service connection form.

4. Provide a Connection name, Access key ID, and Secret key ID, and complete any other fields you want.

5. When you've completed the required and any optional fields in the form, choose OK.

You can test your credentials by creating a new AWS Toolkit for Azure DevOps task in an existing build pipeline and using the connection name you defined in the Add AWS service connection form.

Supply credentials through named variables in your build

You can specify credentials by using named variables. You can set these variables using values from previous jobs in the pipeline, or set them globally. Named variables can be used to get credentials from a custom credentials store.

The following are all the supported named variables:

• AWS.AccessKeyID – IAM access key ID.

• AWS.SecretAccessKey – IAM secret access key.

• AWS.SessionToken – IAM session token.

• AWS.Region – AWS Region code, for example, us-east-2.

To set up global pipeline variables

1. Open Azure DevOps, open the build definition, and then choose variables.

2. Choose Add new Variable.

3. Choose a variable name from one of the four supported names listed previously, and then choose the appropriate value based on your use case.

4. Once you save your changes, this variable will be used by all of your AWS tasks.

To set up dynamic pipeline variables

1. Create a job to get the variables.

2. Create a second job that uses your AWS credentials.

3. Give the first job an output variable that contains the credentials.

4. Make the second job rely on the first job.

For more information about Azure DevOps pipeline variables, see Define variables in the Microsoft Azure DevOps online documentation.

Supply standard AWS environment variables in the build agent process

You can specify credentials with standard named AWS environment variables. These variables can be used to get credentials from a custom credentials store.

The following are all the supported standard named AWS environment variables:

• AWS_ACCESS_KEY_ID – IAM access key ID.

• AWS_SECRET_ACCESS_KEY – IAM secret access key.

• AWS_SESSION_TOKEN – IAM session token.

• AWS_ROLE_ARN – Amazon Resource Name (ARN) of the role you want to assume.

• AWS_REGION – AWS Region code, for example, us-east-2.

For more information about Azure DevOps pipeline variables, see Define variables in the Microsoft Azure DevOps online documentation.

Supply credentials with Amazon EC2 build agents

For build agents running on Amazon Elastic Compute Cloud (Amazon EC2) instances, the tasks can automatically obtain credential and Region information from instance metadata associated with the Amazon EC2 instance.

To use Amazon EC2 instance metadata credentials, the instance must have started with an instance profile that references a role that grants permissions to the task. This allows the role to make calls to AWS on your behalf. For more information, see Using an IAM role to grant permissions to applications running on Amazon EC2 instances.

Set up an Amazon EC2 instance as a self-hosted Azure pipelines agent. For more infornmation, see Azure Pipelines agent in the Microsoft Azure DevOps online documentation. After that's completed, AWS tasks can be added without setting any credentials explicitly. When running on a build machine, your IAM credentials are picked up automatically.