Skip to main content

Run Airy on GCP

Run Airy Core on GCP with one command.

The goal of this document is to provide an overview of how to run Airy Core on Google Cloud Platform, using the GCP Kubernetes Engine.

Services used

Apart from an Google Kubernetes Engine cluster, airy create will create of all the necessary GCP resources for Airy Core to run:

ServiceResourcesPricingDescriptionOverwrite 1
VPC1 VPC, 36 subnets with allowed Public IPs, 1 additional route table, 1 Internet gateway, DNS enabled VPC pricing calculationVPC which will contain all the created compute and network resourcesYes
GKE1 GKE cluster GKE pricing calculationKubernetes cluster to store all the Airy Core resourcesNo
GCE6 Google Compute Engine InstancesGCE pricing calculationThe instances are a part of the Node Pool attached to the GKE cluster. The default instance type is: n1-standard-2, OS type: Container-Optimized OS.Yes
CLB1 Cloud Load BalancerCLB pricing calculationNetwork (target pool-based)Load Balancer created by the ingress controller Kubernetes serviceNo



Prior to starting this guide, you must create an GCP account. To create the cluster you must setup your local GCP environment, by configuring your local GCP profile for your GCP account where all the resources will be created.

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

gcloud init

Through gcloud init, the GCloud CLI will prompt you for four pieces of information.

gcloud init
Default region name [None]: us-central1
Default output format [None]: json


Download and install the Airy CLI.


If you want to use Airy Core with auto-generated HTTPS certificates, refer to the Let's Encrypt section for customizing your airy.yaml file before proceeding.

Now you can run the following command in your Airy workspace, which will create a Kubernetes cluster with Airy Core in your Google account:

airy create --provider=gcp

This will execute the following actions:

  1. Download two Terraform modules inside the terraform directory in the workspace. First module is for creating the GKE cluster, the second is for deploying Airy Core on that cluster.
  2. Run the bash script inside the terraform directory.
  3. Create an GKE cluster in your Google account (applying the gcp-gke state).
  4. Deploy Airy Core in that cluster (applying the airy-core state).
  5. Print URLs for accessing the UI and API.

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 WORKSPACE/terraform/kube.conf.


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

export KUBECONFIG=./terraform/kube.conf
kubectl get pods

HTTPS using Let's Encrypt

You can customize your installation of Airy Core to install an ingress controller which has an enabled Let's Encrypt capability. The ingress controller will register and renew the certificates for you automatically.

Setup your DNS

You should create an A DNS record for the specified public FQDN to point to the hostname of the LoadBalancer, created by GCP for the ingress service:

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

Then edit your airy.yaml file and add the following configuration

letsencrypt: true
https: true
letsencryptEmail: ""

The value should be set to your desired hostname. Configure the e-mail address you want to use for your Let's Encrypt registration under ingress.letsencryptEmail.

Upgrade the instance

If the ingress controller is started before the DNS record is added, the initial Let's Encrypt requests will fail and then all the following registration attempts will be blocked and throttled. That is why the generation of the Let's Encrypt certificates is disabled by default. In order to complete the setup, you must run the upgrade command.

airy upgrade

After this, your Airy Core will be reachable under HTTPS and on your desired hostname (for example

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 GCP Airy Core installation run:

airy api endpoint

Customize your Airy Core installation

To customize your Airy Core installation, you can create an initial config file using the following command:

airy create --provider gcp --init-only

Then edit the airy.yaml file to your prefferences before deploying Airy with:

airy create --provider gcp

Next steps

Now that you have a running installation of Airy Core on GCP 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

To uninstall Airy Core from GCP, run the script located in the WORKSPACE/terraform directory. This script will run terraform destroy on both the kubernetes (GKE) and the airy-core state.

  1. Options which can be overwritten with flags to the airy create command.