Hasura GraphQL Engine on Google Cloud Platform with Kubernetes Engine and Cloud SQL

.. contents:: Table of contents :backlinks: none :depth: 1 :local:

This is a guide about deploying Hasura GraphQL Engine on Google Cloud Platform <https://cloud.google.com/>__ using Kuberentes Engine <https://cloud.google.com/kubernetes-engine/>__ to run Hasura and PosgreSQL backed by Cloud SQL <https://cloud.google.com/sql/>__.

Prerequisites

Google Cloud account with billing enabled (or a free trial <https://cloud.google.com/free/>__)
gcloud CLI (install <https://cloud.google.com/sdk/>__)
kubectl CLI (install <https://kubernetes.io/docs/tasks/tools/install-kubectl/>__)

The actions mentioned below can be done using the Google Cloud Console and gcloud CLI. But, for the sake of simplicity in documentation, we are going to use gcloud CLI, so that commands can be easily copy pasted and executed.

Once the CLI is installed, initialize the SDK:

.. code-block:: bash

gcloud init

Create a Google Cloud Project

A Google Cloud Project is used to group together resources. We'll create a project called hasura for this guide.

.. code-block:: bash

gcloud projects create hasura

Create a Google Cloud SQL Postgres instance

Create a Cloud SQL Postgres instance called hasura-postgres at the asia-south1 region.

.. code-block:: bash

gcloud sql instances create hasura-postgres --database-version POSTGRES_9_6
--cpu 1 --memory 3840MiB --region asia-south1 --project hasura

Once the instance is created, set a password for the default postgres user. Make sure you substitute [PASSWORD] with a strong password.

.. code-block:: bash

gcloud sql users set-password postgres --instance hasura-postgres
--password [PASSWORD] --project hasura

Create a Kubernetes Cluster

Before creating the cluster, we need to enable the Kubernetes Engine API. Visit the following link in a browser to enable the API. Replace hasura at the end of the URL with your project name, in case you're not using the same name. Note that, you will need a billing account added to the project to enable the API.

.. code-block:: bash

https://console.cloud.google.com/apis/api/container.googleapis.com/overview?project=hasura

Once the API is enabled, create a new Kubernetes cluster called hasura-k8s in the asia-south1-a zone with 1 node.

.. code-block:: bash

gcloud container clusters create hasura-k8s --zone asia-south1-a
--num-nodes 1 --project hasura

Setup Cloud SQL Proxy Credentials

Inorder to connect to the Cloud SQL instance, we need to setup a proxy that will forward connections from Hasura to the database instance. For that purpose, the credentials to access the instance needs to be added to the cluster.

Create a service account and download the JSON key file by following this guide <https://cloud.google.com/sql/docs/postgres/sql-proxy#create-service-account>__.

Or if you're overwhelmed with that guide, ensure the following:

Enable Cloud SQL Admin API <https://console.developers.google.com/apis/api/sqladmin.googleapis.com/overview?project=hasura>__ for your project.
Create a new Service Account <https://console.cloud.google.com/iam-admin/serviceaccounts/?project=hasura>__.
Select Cloud SQL Admin as the role.
Click Create Key to download the JSON file.

Create a Kubernetes secret with this JSON key file; replace [JSON_KEY_FILE_PATH] with the filename including complete path of the download JSON key file.

.. code-block:: bash

kubectl create secret generic cloudsql-instance-credentials
--from-file=credentials.json=[JSON_KEY_FILE_PATH]

Create another secret with the database username and password (Use the [PASSWORD] used earlier):

.. code-block:: bash

kubectl create secret generic cloudsql-db-credentials
--from-literal=username=postgres --from-literal=password=[PASSWORD]

Deploy Hasura GraphQL Engine

Download the deployment.yaml file:

.. code-block:: bash

wget https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/google-cloud-k8s-sql/deployment.yaml

Get the [INSTANCE_CONNECTION_NAME] using the following command and note it down.

.. code-block:: bash

gcloud sql instances describe hasura-postgres
--format="value(connectionName)" --project hasura

Edit deployment.yaml and replace [INSTANCE_CONNECTION_NAME] with this value. It should look like hasura:asia-south1:hasura-postgres if you've followed this guide without modifying any names.

Create the deployment:

.. code-block:: bash

kubectl apply -f deployment.yaml

Ensure the pods are running:

.. code-block:: bash

kubectl get pods

If there are any errors, check the logs for GraphQL Engine:

.. code-block:: bash

kubectl logs deployment/hasura -c graphql-engine

Expose GraphQL Engine

Now that we have Hasura running, let's expose it on an IP using a LoadBalancer.

.. code-block:: bash

kubectl expose deploy/hasura
--port 80 --target-port 8080
--type LoadBalancer

Open Hasura Console

Wait for the external IP to be allocated, check status using the following command. It usually takes a couple of minutes.

.. code-block:: bash

kubectl get service

Once the IP is allocated, visit the IP in a browser and it should open the Console.

Troubleshooting

Check the status for pods to see if they are running. If there are any errors, check the logs for GraphQL Engine:

.. code-block:: bash

kubectl logs deployment/hasura -c graphql-engine

You might also want to check the logs for cloudsql-proxy:

.. code-block:: bash

kubectl logs deployment/hasura -c cloudsql-proxy

The username password used by Hasura to connect to the database comes from a Kubernetes secret object cloudsql-db-credentials that we created earlier.

Tearing down

To clean-up the resources created, just delete the Google Cloud Project:

.. code-block:: bash

gcloud projects delete hasura