Add an AWS connector

Connect Harness to your AWS accounts and services.

Use a Harness AWS connector to authenticate and connect Harness to your AWS environment. The connector provides access to AWS services and resources for tasks such as obtaining artifacts, provisioning infrastructure, and deploying microservices and other workloads.

If you want to connect Harness to Elastic Kubernetes Service (Amazon EKS), you can use the platform-agnostic Kubernetes cluster connector or an AWS connector configured for EKS.

This topic explains how to set up an AWS connector.

---

What you will learn from this topic

• How to configure roles and policies required by the AWS connector.

• How to create an AWS connector, including credentials, backoff strategy, and connectivity mode settings.

• How to troubleshoot common AWS connector errors.

• How to define an AWS connector using a YAML example.

---

Before you begin

• Harness account and project: You need access to a Harness account and project. You can also create the connector at the account or organization scope.

• AWS account and IAM roles: You need an AWS account with the IAM roles and policies required for the AWS services you plan to use with Harness. For details, go to Configure roles and policies.

• Harness Delegate (optional): If you plan to connect through a Harness Delegate instead of connecting directly, you need a delegate installed in your infrastructure. For more information, go to Delegate overview.

---

Configure roles and policies

The necessary IAM roles and policies needed by the AWS account used in the connector depend on which AWS service you are using with Harness and which operations you want Harness to perform in AWS. For an extensive description of roles and policies, go to the AWS connector settings reference.

AWS connectors can also inherit IAM roles from Harness Delegates running in AWS. If you want your connector to inherit from a delegate, make sure the delegate has the necessary roles.

The DescribeRegions action is required for all AWS connectors by default, regardless of what AWS service you are using for your target infrastructure. This requirement can be removed by enabling the feature flag CDS_AWS_DESCRIBE_REGIONS_OPTIONAL. For details, go to DescribeRegions - Optional.

If the IAM role associated with your AWS connector does not have the policies required by the AWS service you want to access, you can modify or change the role assigned to the AWS account or the Harness Delegate that your AWS connector is using. You may need to wait up to five minutes for the change to take effect.

The AWS IAM Policy Simulator is a useful tool for evaluating policies and access.

---

Create an AWS connector

Perform the following steps to create the AWS connector.

The connector wizard guides you through six steps: Overview, Credentials, AWS Backoff Strategy, Select Connectivity Mode, Delegates Setup, and Connection Test.

Overview

Perform the following steps:

1. Go to Project Settings -> Connectors. You can also create connectors at the account or organization levels.

2. Select + New Connector -> Cloud Providers -> AWS - Cloud Provider.

3. Input a Name for the connector. Description and Tags are optional. Harness automatically creates an Id (entity identifier) for the connector based on the Name.

4. Select Continue to proceed to Credentials.

Credentials

Review the following information carefully to ensure you select the correct credentials configuration for your AWS connector.

1. Select one of the credential options:

   • AWS Access Key: Authenticate using an AWS Access Key and Secret Access Key stored as Harness secrets.

   • Assume IAM role on Delegate: Authenticate using the IAM role assigned to the Harness Delegate's underlying compute (for example, an EC2 instance profile or EKS node role), without storing separate AWS credentials in Harness.

   • Use IRSA: Authenticate using IAM Roles for Service Accounts (IRSA), for delegates running in an Amazon EKS cluster configured with an OIDC provider.

   • Use OIDC: Authenticate by having Harness act as an OIDC identity provider that AWS trusts to assume an IAM role, without storing long-lived AWS credentials.

   • Custom (Credential Broker), available when the feature flag CDS_AWS_CUSTOM_CREDENTIAL_BROKER_AUTHENTICATION is enabled on your account.

   

   For details about each option, go to Credentials options.

2. If you select AWS Access Key, select an Authentication method:

   • Individual Secrets: Provide separate Access Key, Secret Key, and an optional Session Key secrets.

   • JSON Secret: Provide a single JSON-formatted secret and map its fields to the access key, secret key, and session token. This option requires the feature flag PL_CONNECTOR_JSON_CREDENTIAL_MAPPING. For details, go to JSON secret mapping in the AWS connector settings reference.

3. If you select Use IRSA as the credential type, the Harness Kubernetes delegate in AWS EKS uses a specific IAM role for authenticated requests to resources. For setup instructions, go to Use IRSA in the AWS connector settings reference.

4. If you select Use OIDC as the credential type, you can use delegate selectors in OIDC tokens to enforce AWS IAM policies based on which delegates execute tasks. For details, go to Delegate selectors as session tags.

5. To use cross-account ARN, select Enable cross-account access (STS Role). This option is supported for the AWS Access Key, Assume IAM Role on Delegate, and IRSA credential types. Cross-account access is not supported with the OIDC credential type. For more information about cross-account access in AWS connectors, go to the AWS connector settings reference.

6. By default, Harness uses the us-east-1 region to test the credentials for AWS connectors. If you want to use a different region or an AWS GovCloud account, select it in the Test Region field. For more information about AWS GovCloud support, go to the AWS connector settings reference.

7. Select Continue to proceed to AWS Backoff Strategy.

AWS Backoff Strategy

In some Harness CloudFormation and ECS deployments, AWS API calls can fail with ThrottlingException or Rate exceeded errors when requests exceed the maximum allowed rate for your AWS account and region. Use the AWS Backoff Strategy step to configure the Amazon SDK retry behavior for CloudFormation and ECS API calls and reduce the chance of throttling errors.

Select one of the following backoff strategies:

• Fixed Delay: Uses a fixed delay before each retry attempt.

• Equal Jitter: Uses equal jitter to compute the delay before each retry.

• Full Jitter: Uses full jitter to compute the delay before each retry.

Select Continue to proceed to Select Connectivity Mode. For the full list of backoff strategy parameters and the throttled and non-throttled error codes each strategy applies to, go to AWS backoff strategy in the AWS connector settings reference.

---

Select Connectivity Mode

Harness uses AWS connectors during pipeline runs to authenticate and perform operations with AWS.

On the Connect to the provider page, select how you want Harness to connect to AWS:

• Connect through Harness Platform: Use a direct, secure communication between Harness and AWS. All credentials are encrypted and stored in the Secret Manager configured in Harness. This connectivity mode is required for Harness Cloud build infrastructure.

• Connect through a Harness Delegate: Harness communicates with AWS through a Harness Delegate you install in your environment, behind your corporate firewall. You must choose this option if you chose Use IRSA or Assume IAM role on Delegate for the connector credentials.

A Harness Delegate is used for deployment operations even if you select Connect through Harness Platform.

Select Continue to proceed to Delegates Setup.

Delegates Setup

If you selected Connect through a Harness Delegate, select either:

• Use any available Delegate: Harness selects an available delegate at runtime. To learn how Harness selects delegates, go to Delegate overview.

• Only use Delegates with all of the following tags: Use Tags to match one or more suitable delegates.

  • Go to Use delegate selectors to learn about delegate tags.

  • Select Install new Delegate if you need to install a delegate without exiting connector configuration.

Select Save and Continue to run the connection test.

For private network connectivity options with Harness Cloud, go to Private network connectivity options.

Connection Test

Harness validates the AWS connector authentication and permissions and shows the delegate that executed the check.

Select View Delegate Tasks Logs to review the validation task logs. If validation succeeds, Harness displays Verification successful. Select Finish to complete the connector setup.

---

Troubleshooting

The connection test fails due to a credentials issue

Use the AWS CLI or console to check the credentials. The AWS IAM Policy Simulator is useful for evaluating policies and access.

Credentials pass the connection test but fail when used in a pipeline

Due to the limited scope of the initial connection test, credentials can pass the connection test and then fail when you use the connector in a pipeline. This can happen if the IAM role the connector uses does not have the roles and policies needed for the pipeline's operations. For example, if a pipeline has a Run step that uses an AWS connector, the connector might need specific roles or policies to be able to execute the operations required by the Run step.

If you experience any errors with AWS connectors, verify that the IAM roles and policies are correct, and that the connector credentials are correct. For example:

• The DescribeRegions action is required for all AWS Cloud Providers by default, regardless of what AWS service you are using for your target infrastructure. This can be made optional with the feature flag CDS_AWS_DESCRIBE_REGIONS_OPTIONAL. For details, go to DescribeRegions - Optional.

• If the Harness Delegate in your EKS cluster uses IAM roles for service accounts, make sure the connector credentials are set to Use IRSA, not Assume IAM role on Delegate.

For a list of roles and policies, go to the AWS connector settings reference.

---

YAML examples

The following YAML examples show how to configure an AWS connector for each credential type.

AWS Access Key

The following YAML defines an AWS connector that uses the AWS Access Key credential type with the Individual Secrets authentication method, connects through a Harness Delegate, and runs the connection test on save.

AWS connector YAML

connector:
  name: AWS-AutomationAccount # Connector display name shown in the Harness UI
  identifier: AWSPlayground # Unique connector identifier, cannot be changed after creation
  accountIdentifier: <account-id> # Harness account identifier that owns the connector
  type: Aws # Connector type
  spec:
    credential:
      type: ManualConfig # Use the AWS Access Key credential type
      spec:
        ### AWS access key for the IAM user or role
        accessKey: "####################"
        secretKeyRef: account.awsLongPass # Identifier of the Harness secret storing the AWS secret key
        secretInputMethod: INDIVIDUAL # Use the Individual Secrets authentication method
    executeOnDelegate: true # Connect through a Harness Delegate
    proxy: false # Do not connect through a proxy
    ignoreTestConnection: false # Run the connection test when the connector is saved

Assume IAM Role on Delegate

The following YAML defines an AWS connector that uses the Assume IAM Role on Delegate credential type, selects a delegate by tag, and overrides the AWS backoff strategy with a fixed delay.

AWS connector YAML

connector:
  name: AWS connector # Connector display name shown in the Harness UI
  identifier: AWS_connector # Unique connector identifier, cannot be changed after creation
  description: "" # Optional connector description
  accountIdentifier: <account-id> # Harness account identifier that owns the connector
  orgIdentifier: default # Harness organization identifier
  projectIdentifier: <project-id> # Harness project identifier
  type: Aws # Connector type
  spec:
    credential:
      type: InheritFromDelegate # Use the Assume IAM Role on Delegate credential type
      region: us-east-1 # AWS region used to test the credentials
    awsSdkClientBackOffStrategyOverride:
      type: FixedDelayBackoffStrategy # AWS Backoff Strategy: Fixed Delay
      spec:
        fixedBackoff: 0 # Fixed delay, in milliseconds, before each retry attempt
        retryCount: 0 # Maximum number of retry attempts
    delegateSelectors:
      - aws-eks # Delegate tag used to select a delegate for this connector
    executeOnDelegate: true # Connect through a Harness Delegate
    proxy: false # Do not connect through a proxy
    ignoreTestConnection: false # Run the connection test when the connector is saved

Use OIDC

The following YAML defines an AWS connector that uses the Use OIDC credential type to assume an IAM role through an OIDC identity provider.

AWS connector YAML

connector:
  name: connector_Aws_be80 # Connector display name shown in the Harness UI
  identifier: connector_Aws_be80 # Unique connector identifier, cannot be changed after creation
  accountIdentifier: <account-id> # Harness account identifier that owns the connector
  type: Aws # Connector type
  spec:
    credential:
      type: OidcAuthentication # Use the Use OIDC credential type
      spec:
        iamRoleArn: arn:aws:iam::<aws-account-id>:role/<iam-role-name> # ARN of the IAM role Harness assumes using OIDC
      region: us-east-1 # AWS region used to test the credentials
    executeOnDelegate: true # Connect through a Harness Delegate
    proxy: false # Do not connect through a proxy
    ignoreTestConnection: false # Run the connection test when the connector is saved

---

Next steps

• AWS connector settings reference: Review AWS connector settings, credentials options, and required permissions.

• Delegate overview: Understand how Harness Delegates work and how they are selected.

• Use delegate selectors: Target specific delegates using tags.

• Install a Kubernetes delegate: Install a delegate in your Kubernetes cluster.

• Private network connectivity options: Review connectivity options for Harness Cloud.