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 theuuidgen
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 theExternalId
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
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