Installing Hasura on Minikube

Minikube is the “go-to” tool by the Kubernetes community to run a single-node cluster locally as a Virtual Machine. It is the easiest way to get started with Kubernetes without depending on a cloud provider.

Step 1: Install Minikube

You can install the minikube CLI by following the instructions here.

Note

If this is the first time you’re running a virtual machine on your system, you will need to enable virtualization on your BIOS and install a Hypervisor like KVM or VirtualBox, as mentioned in the minikube install page.

Step 2: Start Minikube cluster

Once minikube is installed, you can start a local Kubernetes cluster by executing the following command.

minikube start

Once succeeded, the output will show the kube-context, Minikube IP etc.

Step 3: Create data directory

Once the minikube cluster starts running, you need to create a directory inside the VM to store Hasura platform’s data, such as Postgres, Filestore etc. You can do this by SSH-ing to the minikube VM.

minikube ssh

Once you’re in the minikube VM, you can create a directory:

sudo mkdir /data/hasura-data
# (Ctrl+D to exit)

Minikube is configured to persist files stored under /data directory. (see Persistent Volumes for reference)

Step 4: Install Hasura platform

Now, you can use Hasura CLI to install Hasura platform on this cluster.

hasura cluster install \
  --name=minikube-hasura-cluster \
  --provider=minikube \
  --kube-context=minikube \
  --data-path=/data/hasura-data \
  --domain=$(minikube ip).xip.io \
  --external-ip=$(minikube ip)

This could take around 5 minutes depending on your internet connection bandwidth.

Note

Hasura platform requires a domain associated with a cluster for the subdomain based routing to work. For minikube, we are making use of a service called xip.io which map domains with IP addresses in them to the given IP. We are getting the minikube VM’s IP using minikube ip and using it in the domain and as external IP address for the Hasura API gateway.

Step 5: Add this cluster to a project

Clone a new Hasura project using hasura clone or cd into an existing project. You can then use hasura cluster add command to add this minikube cluster to the project.

hasura cluster add minikube-hasura-cluster \
  -c minikube \
  --kube-context=minikube

This command will add the cluster called minikube-hasura-cluster (name we used with --name flag earlier in the install command), that can be contacted using the kube context minikube, to the current project with an alias minikube.

Step 6: Configure domains in the project

Your current Hasura project is most likely to have the domain configured as "{{ cluster.name }}.hasura-app.io" in conf/domains.yaml. This domain will only work for clusters provisioned through Hasura, not for user provisioned ones. Hence, you need to edit this file and change the domain configuration.

Edit conf/domains.yaml to make the following change:

- domain: "<insert-minikube-ip-here>.xip.io"
  ssl: null

You can get the minikube ip address by executing minikube ip.

Note

SSL will not be available on minikube clusters, as there is no public IP. Hence we disable SSL in the domain configuration.

Advanced: Handling multiple clusters in the same project

If you have multiple clusters in the same project, you will need the following template to handle domain configuration for minikube as well as Hasura provisioned clusters.

{% if cluster.infra.provider == "minikube" %}
- domain: "{{ cluster.metadata.gateway.externalIPs.0 }}.xip.io"
  ssl: null
{% else %}
- domain: "{{ cluster.name }}.hasura-app.io"
  ssl:
    type: LetsEncrypt
    conf: {}
{% endif %}

Step 7: Commit and push to the new cluster

Commit the files and push to the newly added minikube cluster:

git add clusters.yaml conf/domains.yaml
git commit -m "add new minikube cluster"
git push minikube master

That’s it! Your Hasura project is now deployed on the minikube cluster. You can see the microservices and their URLs by executing:

hasura microservices list -c minikube

Tearing down

The easiest way to tear down is to delete your minikube cluster and create another one when required.

minikube delete

If you don’t want to delete the minikube cluser, you can delete all the resources Hasura created by executing the following commands:

kubectl delete namespace hasura
kubectl delete configmap hasura-conf hasura-status ssh-authorized-keys
kubectl delete secret hasura-secrets
kubectl delete clusterrolebinding hasura-cluster-admin-binding

# Next, delete the data directory:

minikube ssh
# once inside the VM,
sudo rm -r /data/hasura-data
# Ctrl+D to exit

Note

The Hasura Kubernetes Platform is available under these Terms of Service.

« previous | next »
Want to contribute or report missing content? Check out the github repo for docs.
Powered by Sphinx. Copyright © 2019 Hasura.