Skip to main content

Run Airy on AWS

Run Airy Core on AWS with one command.

The goal of this document is to provide an overview of how to run Airy Core on AWS cloud platform, using the AWS Elastic Kubernetes Service.

Configure AWS#


Prior to starting this guide, you must create an AWS account. We also recommend installing the AWS CLI.

Once you have installed the AWS CLI, you now need to configure the application to be able to connect to your AWS account:

aws configure

Through aws configure, the AWS CLI will prompt you for four pieces of information. The first two are required. These are your AWS access key ID and AWS secret access key, which serve as your account credentials. You can generate new credentials within AWS Identity and Access Management (IAM), if you do not already have them. The other information you will need is region and output format, which you can leave as default for the time being.

aws configure
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-west-2
Default output format [None]: json

Apart from an EKS cluster, airy create will take care of all the necessary AWS resources, such as:

  • VPC resources (VPC, subnets, route tables, public gateways)
  • IAM roles and policy attachments
  • EKS cluster and EKS node groups
  • EC2 instances, as part of the created node group

Create a cluster#

To create the cluster you must setup your local AWS environment, by configuring your local AWS profile for the AWS account where all the resources will be created.

Download and install the Airy CLI.

Export your AWS_PROFILE and AWS_REGION as described in the AWS documentation.

Now you can run this command, which will create Airy Core in your AWS account:

airy create --provider=aws

You can also use an existing VPC, without creating additional VPC resources:

airy create --provider aws --provider-config vpcId=myExistingVpcId

By default the command creates an AWS NodeGroup with two c5.xlarge instances. For customizing the instance type run:

airy create --provider aws --provider-config instanceType=c5.large

This will execute the following actions:

  1. Create the my-airy directory and populate it with the configuration that the CLI will need. All subsequent commands need to either be run from this directory or use the --workspace flag.
  2. Start an Airy Core cluster in your AWS account.
  3. Print URLs for accessing the UIs and APIs (see recording).

By default, the installation will create a single EC2 Kubernetes node, as part of a single node group. You can scale your EKS cluster by adding more nodes or node groups through the AWS web console or the AWS CLI.

If you want to customize your Airy Core instance please see our Configuration Section.

After the installation, you can also interact with the components of Airy Core with the kubectl command line utility. You can find the kubeconfig of your Airy Core instance in ~/.airy/kube.conf.


After the installation process, you can verify that all the pods are running with

kubectl get pods --kubeconfig ./kube.conf

Common issues#

AWS has a limit on the number of objects you can create depending on your account.

Error creating vpc: operation error EC2: CreateVpc, https response error StatusCode: 400, RequestID: 64210ff5-9aca-4ab7-b993-3727637a59d6, api error VpcLimitExceeded: The maximum number of VPCs has been reached.

When encountering this, you can delete some of the resources just as described on here

Secure your Airy core#


Authentication and HTTPS are disabled by default in Airy Core.

As this is intended only for testing purposes, it is mandatory that you to secure your Airy Core installation as explained in this section.


To enable authenticaiton to the API and in the UI, refer to our Authentication configuration section

Enable HTTPS#

This section guides you through the necessary steps to configure HTTPS on your Airy Core instance.

Upload certificates to AWS ACM#

You should use a valid HTTPS certificate to secure your Airy Core instance. This certificate is created for and can only be used with a specific hostname. This hostname will be the FQDN on which Airy Core will be reachable.

Usually these HTTPS certificates come as a bundle of:

  • private key (private.key)
  • public certificate (public.crt)
  • public certificate authority bundle file (ca-bundle.crt)

Use the following command to upload your HTTPS certificate files to AWS ACM, so that they can be used by the AWS LoadBalancer.

aws acm import-certificate --certificate fileb://public.crt --certificate-chain fileb://ca-bundle.crt --private-key fileb://private.key --region us-east-1

After the certificate has been uploaded to AWS ACM, you will need the unique ARN of the certificate,for the next step.


If you don't have your own HTTPS certificate you can request one from AWS ACM.

If you want to use Let's Encrypt, have a look at the Following Traefik ingress guide on how to integrate the HTTPS certificates with the installed ingress controller.

Configure the ingress service#

Locate and set your KUBECONFIG file and set the other environment variables:

export KUBECONFIG="PATH/TO/DIR/kube.conf"
export ARN="Your-unique-ACM-ARN"
export HOSTNAME="public-FQDN"

Modify the existing ingress service to reconfigure the AWS LoadBalancer:

kubectl -n kube-system annotate service traefik "" "${ARN}"
kubectl -n kube-system patch service traefik --patch '{"spec": { "ports": [ { "name": "https", "port": 443, "protocol": "TCP", "targetPort": 80 } ] } }'

Update the hostnames configMap with the new https endpoint:

kubectl patch configmap hostnames --patch "{\"data\": { \"HOST\": \"https://${HOSTNAME}\"} }"

Update the existing ingress resources with the new hostname (for this you will additionally require the jq utility):

kubectl get ingress airy-core -o json | jq "(.spec.rules[0].host=\"${HOSTNAME}\")" | kubectl apply -f -
kubectl get ingress airy-core-ui -o json | jq "(.spec.rules[0].host=\"${HOSTNAME}\")" | kubectl -f -
kubectl get ingress airy-core-redirect -o json | jq "(.spec.rules[0].host=\"${HOSTNAME}\")" | kubectl -f -

Setup your DNS#

You should create a CNAME DNS record for the specified public FQDN to point to the hostname of the LoadBalancer, created by AWS for the ingress service:

kubectl get --namespace kube-system service traefik --output jsonpath='{.status.loadBalancer.ingress[0].hostname}{"\n"}'

Print HTTPS endpoint#

At this point, the frontend and the API services of Airy Core should be accessible through HTTPS on the specific hostname:

airy api endpoint

Integrate public webhooks#

The public webhooks will be accessible on the public hostname, at a path specific for each source individually. Refer to the sources documentation for more information.

To get the public URL of your AWS Airy Core installation run:

airy api endpoint

Next steps#

Now that you have a running installation of Airy Core on AWS you can connect it to messaging sources. Check out our Quickstart guide to learn more:

To the Quick Start

Learn the Airy Basics with our Quick Start

Third party tools#

Third party tools can be activated in the airy.yaml configuration file, under the tools section. For more details please see our Configuration Section.

Uninstall Airy Core#

You can remove the Airy Core AWS installation by deleting the Airy Core AWS resources with the AWS CLI.

Retrieve the ID of the installation, in this case my-airy is the name of the installation that was passed on the creation process:

cd my-airy
id=$(cat cli.yaml | grep contextname | awk '{ print $2; }')
echo ${id}

Make sure that the ID was printed back to you, before proceeding with the deletion of the resources.

Delete the EKS nodegroup:

node_group_name=$(aws eks list-nodegroups --cluster-name ${id} --query 'nodegroups[0]' --output text)
aws eks delete-nodegroup --nodegroup-name $node_group_name --cluster-name ${id}

Delete the EKS cluster:

while ! aws eks delete-cluster --name ${id}
echo "Waiting for EKS nodegroup to be deleted..."
sleep 15

Delete the created IAM Role:

for policy in $(aws iam list-attached-role-policies --role-name ${id} --query 'AttachedPolicies[].PolicyArn' --output text)
aws iam detach-role-policy --policy-arn ${policy} --role-name ${id}
aws iam delete-role --role-name ${id}

If you used an existing VPC, then you already removed Airy Core from your infrastructure and there is no need to run any additional commands. If not, you can proceed with removing all the VPC resources, created exclusively for Airy Core.

Get the ID of the VPC:

vpc_id=$(aws ec2 describe-vpcs --filters Name=tag:Name,Values=${id} --query 'Vpcs[0].VpcId' --output text)

Delete all the load-balancers:

for loadbalancer in $(aws elb describe-load-balancers --query "LoadBalancerDescriptions[?VPCId=='${vpc_id}'].LoadBalancerName" --output text)
aws elb delete-load-balancer --load-balancer-name ${loadbalancer}

Delete all used network interfaces (iIf the command fails, check if all the loadbalancers are deleted and run the previous command one more time):

for interface in $(aws ec2 describe-network-interfaces --filters Name=vpc-id,Values=${vpc_id} --query 'NetworkInterfaces[].NetworkInterfaceId' --output text)
aws ec2 delete-network-interface --network-interface-id ${interface}

Delete the security groups created by the load-balancers:

for group in $(aws ec2 describe-security-groups --filters Name=vpc-id,Values=${vpc_id} --filters Name=tag-key,${id} --query 'SecurityGroups[].GroupId' --output text)
aws ec2 delete-security-group --group-id ${group}

Delete all the subnets in the VPC:

for subnet in $(aws ec2 describe-subnets --filters Name=vpc-id,Values=${vpc_id} --query 'Subnets[].SubnetId' --output text)
aws ec2 delete-subnet --subnet-id ${subnet}

Delete the gateways and the routes in the VPC:

for gateway in $(aws ec2 describe-internet-gateways --filters Name=attachment.vpc-id,Values=${vpc_id} --query 'InternetGateways[].InternetGatewayId' --output text)
aws ec2 detach-internet-gateway --internet-gateway-id ${gateway} --vpc-id ${vpc_id}
aws ec2 delete-internet-gateway --internet-gateway-id ${gateway}

Delete the route tables (the command will always fail for the default route table, but you can still delete the VPC in the next step):

for route_table in $(aws ec2 describe-route-tables --filters Name=vpc-id,Values=${vpc_id} --query 'RouteTables[].RouteTableId' --output text)
aws ec2 delete-route-table --route-table-id ${route_table}

At the end, delete the VPC:

aws ec2 delete-vpc --vpc-id ${vpc_id}
Last updated on