AWS

Prerequisites

To manage any Cloud Account using the instructions below, you need:

The humctl CLI installed
Authentication against the Platform Orchestrator via humctl login
The aws CLI installed

These environment variables set:

export HUMANITEC_ORG=<your-humanitec-org-id>

AWS Role Assumption

Credentials: temporary

Available Inputs/Outputs: see the Cloud Account types reference

How it works

AWS temporary credentials make use of the AssumeRole API operation . You need to first prepare the trust relationship on the AWS side and then create the actual Humanitec Cloud Account.

Create the Cloud Account for temporary credentials

Create a non-guessable ExternalId that will uniquely identify the Cloud Account in the Humanitec Platform Orchestrator. For a UUID, you can use the uuidgen tool.
```
export EXTERNAL_ID=$(uuidgen)
```

Create an IAM role to establish a trust relationship between your trusting account and the public Humanitec AWS user with the ARN “arn:aws:iam::767398028804:user/humanitec”. An additional trust policy expands the role to the ExternalId you created before. The Humanitec Cloud Account will later be configured with both elements so that it can effectively assume this IAM role.

First prepare the trust policy:

cat <<EOF > trust-policy.json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::767398028804:user/humanitec"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "${EXTERNAL_ID}"
        }
      }
    }
  ]
}
EOF

Define the name of the new role according to your own naming schema:

export ROLE_NAME=humanitec-access-tempcreds

Create the IAM role including the trust policy and capture its ARN:

export ROLE_ARN=$(aws iam create-role --role-name ${ROLE_NAME} \
  --assume-role-policy-document file://trust-policy.json \
  | jq .Role.Arn | tr -d "\"")
echo ${ROLE_ARN}

Create a Cloud Account in the Platform Orchestrator.

Define the name and id of the new Cloud Account:

export CLOUD_ACCOUNT_NAME="My AWS Temp Cred Account"
export CLOUD_ACCOUNT_ID=my-aws-temp-cred

(optional) If you use a regional AWS STS endpoint instead of the global endpoint, define the region in the environment variable (Humanitec uses STS endpoint for us-east-1 by default):

export STS_REGION="eu-west-1"

If you haven’t already done so (see Prerequisites ), define these environment variables:

export HUMANITEC_ORG=<your-humanitec-org-id>

Create the Cloud Account:

Create a file defining the Cloud Account you want to create:

cat << EOF > aws-role-cloudaccount.yaml
apiVersion: entity.humanitec.io/v1b1
kind: Account
metadata:
  id: ${CLOUD_ACCOUNT_ID}
entity:
  name: ${CLOUD_ACCOUNT_NAME}
  type: aws-role
  credentials:
    aws_role: ${ROLE_ARN}
    external_id: ${EXTERNAL_ID}
$(if ! [[ -z $STS_REGION ]]; then echo "    sts_region: ${STS_REGION}"; fi)
EOF

Use the humctl create command to create the Cloud Account in the Organization defined by your configured context:

humctl apply -f aws-role-cloudaccount.yaml
rm aws-role-cloudaccount.yaml

Using the Humanitec Terraform Provider :

resource "humanitec_resource_account" "aws-role" {
  id   = var.cloud_account_id
  name = var.cloud_account_name
  type = "aws-role"
  credentials = jsonencode({
    aws_role    = var.aws_iam_role_tempcreds_arn
    external_id = var.aws_temporary_credentials_external_id
    # Optional, remove if not needed
    sts_region  = var.aws_sts_region
  })
}

Inside the API, Cloud Accounts are called Resource Accounts, both represent the same entity.

Assign the required permissions to the IAM role.

The Cloud Account is now ready for use by any Drivers supporting the aws-role Account type. See the usage examples below to get started. Remember to assign the required permissions to the IAM Role on the target AWS services depending on the kind of operations it needs to perform.

For access to an EKS cluster, refer to the Kubernetes page for guidance.
Test the Cloud Account.

The Humanitec Platform Orchestrator provides a mechanism for testing the Cloud Account and ensuring that the credential meets the input and output schema requirements and that any token exchange succeeds. The output will provide any errors or warnings that prevent the Cloud Account from being used and will also include any identifiers of the token identity or target account. For accounts of type aws-role, the AWS account and the assumed role ARN will be displayed.
The check operation can be called using the specific CLI command.
```
humctl resources check-account ${CLOUD_ACCOUNT_ID}
```
Note that this check does not validate permissions assigned to the IAM role that may be used to provision or connect infrastructure during deployments.

Depending on your strategy, consider providing separate IAM roles tied to separate Cloud Accounts for different kinds of access.

For example, you may create one role/Cloud Account pair for accessing EKS clusters, and another role/Cloud Account pair for provisioning infrastructure resources. The first Cloud Account would then be used in k8s-cluster Resource Definitions like shown in the example below , the second one in Resource Definitions for other Resource Types.

A possible way of defining such roles is shown in these examples. They utilize additional security elements using tags and Humanitec SaaS source IPs :

EKS access: Terraform / CloudFormation
Resource access: Terraform / CloudFormation

Example: connect to an EKS cluster

This example Resource Definition is using the k8s-cluster-eks Driver to facilitate deployments to an Amazon EKS cluster. All it takes for this to work is to include a Cloud Account of type aws-role via the driver_account setting. Temporary credentials will be automatically generated and picked up by the Driver with no further configuration required.

eks-temporary-credentials.yaml ( view on GitHub ) :

# Connect to an EKS cluster using temporary credentials defined via a Cloud Account
apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: eks-temporary-credentials
entity:
  name: eks-temporary-credentials
  type: k8s-cluster
  # The driver_account references a Cloud Account of type "aws-role"
  # which needs to be configured for your Organization.
  driver_account: aws-temp-creds
  # The driver_type k8s-cluster-eks automatically handles the temporary credentials
  # injected via the driver_account.
  driver_type: humanitec/k8s-cluster-eks
  driver_inputs:
    values:
      region: eu-central-1
      name: demo-123
      loadbalancer: x111111xxx111111111x1xx1x111111x-x111x1x11xx111x1.elb.eu-central-1.amazonaws.com
      loadbalancer_hosted_zone: ABC0DEF5WYYZ00

Example: provision an S3 bucket

This example Resource Definition uses the Terraform Driver to provision S3 buckets. It includes a Cloud Account of type aws-role via the driver_account setting. Temporary credentials will be automatically generated and made available for passing into the Terraform code as required.

s3-temporary-credentials.yaml ( view on GitHub ) :

# Create S3 bucket using temporary credentials defined via a Cloud Account
apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: s3-temporary-credentials
entity:
  name: s3-temporary-credentials
  type: s3
  driver_type: humanitec/terraform
  # The driver_account references a Cloud Account of type "aws-role"
  # which needs to be configured for your Organization.
  driver_account: aws-temp-creds
  driver_inputs:
    values:
      variables:
        REGION: eu-central-1
      # Use the credentials injected via the driver_account
      # to set variables as expected by your Terraform code
      credentials_config:
        variables:
          ACCESS_KEY_ID: AccessKeyId
          ACCESS_KEY_VALUE: SecretAccessKey
          SESSION_TOKEN: SessionToken
      script: |
        # This provider block is using the Terraform variables
        # set through the credentials_config.
        # Variable declarations omitted for brevity.
        provider "aws" {
          region     = var.REGION
          access_key = var.ACCESS_KEY_ID
          secret_key = var.ACCESS_KEY_VALUE
          token      = var.SESSION_TOKEN
        }

        # ... Terraform code reduced for brevity

        resource "aws_s3_bucket" "bucket" {
          bucket = my-bucket
        }

AWS User with access key & secret

Credentials: static

Available Inputs/Outputs: see the Cloud Account types reference

This Cloud Account type uses static credentials. For superior security , we recommend using the AWS role assumption Cloud Account type with temporary credentials instead.

Create the Cloud Account for static credentials

Create an IAM user which will be used by the Humanitec Platform Orchestrator.

Define the name of the new user according to your own naming schema:
```
export USER_NAME=humanitec-user
```
Create a new IAM User:
```
aws iam create-user --user-name ${USER_NAME}
```

Create access keys.

export KEY_OUTPUT=$(aws iam create-access-key \
  --user-name ${USER_NAME})

Export the values, needed for the Cloud Account:

export AWS_ACCESS_KEY_ID=$(echo $KEY_OUTPUT | jq -rM .AccessKey.AccessKeyId )
export AWS_SECRET_ACCESS_KEY=$(echo $KEY_OUTPUT | jq -rM .AccessKey.SecretAccessKey )

Create a Cloud Account in the Platform Orchestrator.

Define the name and id of the new Cloud Account:

export CLOUD_ACCOUNT_NAME="My AWS User Account"
export CLOUD_ACCOUNT_ID=my-aws-user-cred

If you haven’t already done so (see Prerequisites ), define these environment variables:

export HUMANITEC_ORG=<your-humanitec-org-id>

Create the Cloud Account:

Create a file defining the Cloud Account you want to create:

cat << EOF > aws-cloudaccount.yaml
apiVersion: entity.humanitec.io/v1b1
kind: Account
metadata:
  id: ${CLOUD_ACCOUNT_ID}
entity:
  name: ${CLOUD_ACCOUNT_NAME}
  type: aws
  credentials:
    aws_access_key_id: ${AWS_ACCESS_KEY_ID}
    aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
EOF

Use the humctl create command to create the Cloud Account in the Organization defined by your configured context:

humctl apply -f aws-cloudaccount.yaml
rm aws-cloudaccount.yaml

Using the Humanitec Terraform Provider :

resource "humanitec_resource_account" "aws" {
  id   = var.cloud_account_id
  name = var.cloud_account_name
  type = "aws"
  credentials = jsonencode({
    aws_access_key_id     = var.aws_access_key_id
    aws_secret_access_key = var.aws_secret_access_key
  })
}

Inside the API, Cloud Accounts are called Resource Accounts, both represent the same entity.

Assign the required permissions to the IAM user.

The Cloud Account is now ready for use by any Drivers supporting the aws Account type. See the usage examples below to get started. Remember to assign the required permissions to the IAM User on the target AWS services depending on the kind of operations it needs to perform.

For access to an EKS cluster, refer to the Kubernetes page for guidance.
Test the Cloud Account.

The Humanitec Platform Orchestrator provides a mechanism for testing the Cloud Account and ensuring that the credential meets the input and output schema requirements and that any token exchange succeeds. The output will provide any errors or warnings that prevent the Cloud Account from being used and will also include any identifiers of the token identity or target account. For accounts of type aws, the AWS account and the IAM role ARN will be displayed.
The check operation can be called using the specific CLI command.
```
humctl resources check-account ${CLOUD_ACCOUNT_ID}
```
Note that this check does not validate permissions assigned to the IAM role that may be used to provision or connect infrastructure during deployments.

Example: connect to an EKS cluster

This example Resource Definition is using the k8s-cluster-eks Driver to facilitate deployments to an Amazon EKS cluster. All it takes for this to work is to include a Cloud Account of type aws via the driver_account setting. The Cloud Account credentials will be automatically generated and picked up by the Driver with no further configuration required.

eks-static-credentials-cloudaccount.yaml ( view on GitHub ) :

# Connect to an EKS cluster using static credentials defined via a Cloud Account
apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: eks-static-credentials-cloudaccount
entity:
  name: eks-static-credentials-cloudaccount
  type: k8s-cluster
  # The driver_account references a Cloud Account of type "aws"
  # which needs to be configured for your Organization.
  driver_account: aws-static-creds
  # The driver_type k8s-cluster-eks automatically handles the static credentials
  # injected via the driver_account.
  driver_type: humanitec/k8s-cluster-eks
  driver_inputs:
    values:
      region: eu-central-1
      name: demo-123
      loadbalancer: x111111xxx111111111x1xx1x111111x-x111x1x11xx111x1.elb.eu-central-1.amazonaws.com
      loadbalancer_hosted_zone: ABC0DEF5WYYZ00

AWS

Prerequisites #

AWS Role Assumption #

How it works #

Create the Cloud Account for temporary credentials #

Example: connect to an EKS cluster #

Example: provision an S3 bucket #

AWS User with access key & secret #

Create the Cloud Account for static credentials #

Example: connect to an EKS cluster #

Prerequisites

AWS Role Assumption

How it works

Create the Cloud Account for temporary credentials

Example: connect to an EKS cluster

Example: provision an S3 bucket

AWS User with access key & secret

Create the Cloud Account for static credentials

Example: connect to an EKS cluster