Deploy to your own AWS cluster


The Humanitec platform is designed to integrate with your existing toolchain. You can use it to deploy your apps to your own Kubernetes cluster in Amazon Elastic Kubernetes Service (Amazon EKS). This page explains how.


  • You must set up an EKS Service Role that the platform will use to connect and deploy to your cluster. See the AWS documentation for instructions. It must include the following policies:
    • AWS managed policies: AmazonEKSClusterPolicy, AmazonEKSServicePolicy
    • Inline policies: EKS-list-full, EKS-read-full
  • You must provide the platform with access to an IAM user.
    • This IAM user must have your EKS Service Role attached.
    • You must provide an access key for the IAM user. The Platform needs both the access key ID and the secret access key.
  • If necessary, you must create a cluster with a node pool in Amazon EKS.
    • Note: We recommend using your Humanitec IAM user to create the cluster. We also recommend using eksctl.
    • If you must use a different IAM user to create the cluster, then make sure that your Humanitec IAM user has access to the cluster where you want to deploy your app. Note that in AWS, cluster access is managed separately from policies.

The platform has no resource requirements for the cluster where it will deploy your app. However, you must choose a machine type for the node pool that suits the needs of your app.

Prepare your cluster

We have created a bash script that prepares your cluster to support Humanitec app deployments. It uses kubectl to install NGINX Ingress Controller and cert-manager in your cluster with the respective namespaces, and it returns the IP of the load balancer.

  1. Install kubectl.
  2. Make sure it’s configured to communicate with your cluster.
  3. Run this script on your local machine:
#!/usr/bin/env bash

# Humanitec K8s cluster preparation script, AWS edition.
# Make sure you have kubectl installed, and that it's configured to connect to your cluster.

# Installs NGINX Ingress Controller and the network load balancer to the cluster.
# NOTE: If your Kubernetes version is older than 1.14, you must change to on line 217 of mandatory.yaml.
kubectl apply -f
kubectl apply -f

# Gets load balancer IP address.
LOADBALANCER_IP=$(kubectl get service -n ingress-nginx -o jsonpath="{.items[?('ingress-nginx')].status.loadBalancer.ingress[0].hostname}")

# Creates a namespace to run cert-manager in.
kubectl create namespace cert-manager
# Installs the CustomResourceDefinitions and cert-manager itself.
kubectl apply -f --validate=false

echo -e "Load balancer IP: $LOADBALANCER_IP"

Connect IAM user to the platform

Now that your cluster is ready, you must connect your AWS account to the platform.

  1. Log in to the Humanitec platform.
  2. Click the Profile icon in the top right.
    Screenshot: Profile icon
  3. Click Account Settings.
  4. On the Account Settings screen, click on your organization.
  5. Under Hosting Providers, click Amazon Web Services.
  6. Enter a name for the account in the Hosting provider account name field.
  7. Enter your IAM user secret ID and secret key in the respective fields.
  8. Click Authorize.

The platform will authorize with your AWS account and populate the list of clusters from the provided IAM user credentials.

Deploy your app to your AWS cluster

The last step is to change the cluster where your app will deploy.

  1. Go to your app.
  2. On the left, under Environments, you should see Pre-configured Humanitec cluster selected by default. Click the Change button. Screenshot: Change cluster
  3. In the modal window, find the EKS cluster where you want to deploy and click Set as current.
  4. Click Save.

Once you click Deploy, the platform will deploy your app to the chosen cluster as a workload. If you chose to expose your modules with public URLs, then the app will be exposed via the ingress to the load balancer URL with a * certificate.

Free trial limitations

The following limitations apply to the free trial of the Humanitec platform:

  • Both user access management and source code management are handled through GitHub.
  • You may create no more than 20 apps, with no more than 3 environments each.
    • If you deploy your app to a cluster managed by Humanitec, then each deployed module will have a lifespan of 1 day.
  • You may only create development environments with the free trial.
  • The free trial does not include the role-based access control model. Each member of an organization has full access to all applications for that organization and can delete and edit environments and applications.
  • For ingress, all deployed modules must use the * certificate.