Git Push to Deploy Your App on EKS

It’s a joyful experience for a developer when you can focus just on building an application, and rely on a tool to do the grunt work of pushing that application to a Kubernetes cluster. When the tool makes use of your existing knowledge of git, it only adds to the pleasure! In this post, Tirumarai Selvan of Hasura explains an open source project, Gitkube, that provides a seamless experience for deploying your applications to an Amazon Elastic Container Service for Kubernetes (EKS) cluster using git semantics. Installation steps and a deployment pipeline for a simple example are explained in detail.

– Arun

Gitkube is a tool used to deploy applications on a Kubernetes cluster by simply running a git push. In other words, you can go from your source code to a deployed application on a Kubernetes cluster in 60 seconds. This is the experience of git push to deploy, brought to your Kubernetes cluster.

Gitkube’s benefits include:

1. Very thin clients: The only thing you need to have installed on your machines is git.
2. Hardened security controls: Gitkube runs the build and deploy processes in the cluster, which can be managed according to your organizational security policies using RBAC and IAM.
3. Kubernetes native: It builds on the Kubernetes CRD and operator pattern to provide a reference implementation for git-based automation, aka GitOps. It’s easy to extend for your custom needs.

With over 2k stars on Github, Gitkube has proven to be a powerful tool that developers use for deploying their apps on Kubernetes.

Gitkube and EKS

You can get started with Gitkube on your EKS cluster in minutes. Gitkube runs on EKS as-is; no additional steps or external configurations are required to get started.

Here is a short video showing how to deploy your code on a bare EKS cluster using Gitkube:

Now let’s look at the steps in detail.

Getting Started

Set Up an EKS Cluster

Set up an EKS cluster by following the instructions in Getting Started with Amazon EKS.

Or use eksctl to get started very quickly with a basic cluster.

Configure kubectl

1. Install kubectl

Make sure you have kubectl installed with version at least 1.10:

kubectl version --client

If not, install the latest kubectl.

2. Install heptio-authenticator

EKS uses IAM to manage identities on your cluster. You need to install the heptio-authenticator so that kubectl can authenticate to your cluster via IAM.

curl -o heptio-authenticator-aws https://amazon-eks.s3-us-west-2.amazonaws.com/1.10.3/2018-06-05/bin/darwin/amd64/heptio-authenticator-aws

chmod +x ./heptio-authenticator-aws

sudo mv heptio-authenticator-aws /usr/local/bin/

Your ekskubeconfig is already configured to use heptio-authenticator, so you can start using kubectl right away.
3. Verify kubectl access

kubectl get nodes

Install Gitkube

Assuming you have set your kubeconfig to point to your EKS cluster, follow these instructions to install Gitkube on it.

1. Install gitkube-cli

Gitkube comes with a cli which can be used to automate many steps into a few commands. You can also use Gitkube without the cli, but in this example we will use the cli.

curl https://raw.githubusercontent.com/hasura/gitkube/master/gimme.sh | bash
gitkube version # check installation

2. Install Gitkube

gitkube install

The setup is now complete, you should see gitkube pods running in the kube-system namespace. You will also see a gitkubed service of type LoadBalancer in the kube-system namespace.

kubectl get svc -n kube-system
NAME       TYPE           CLUSTER-IP      EXTERNAL-IP                                                               PORT(S)      AGE
gitkubed   LoadBalancer   10.100.233.131  a6d8ba5cbaac011e89c06026b55b776d-1586547447.us-west-2.elb.amazonaws.com   22:32697/TCP 14s

Push Your Application

We will now describe a typical workflow for Gitkube in action.

1. Start with a git repo

Your application must live in a git repo and include Dockerfile(s) to build the container image(s). Let’s start with an example repo which includes a simple nginx application:

git clone https://github.com/hasura/gitkube-example

This repo has examples with different styles of code organization. For example, you can have your application in a single repo including the config files, or you can have a multi-repo organization with code and config kept separately. In the following demo, we will use the mono-repo example.

2. Generate a Remote spec

Gitkube is configured using the concept of Remotes. A Remote is a Custom Resource in Kubernetes. Each Remote specifies the parameters used to manage the application. Parameters include authentication users for git push access, build definitions, image registry, and runtime arguments. The complete spec for a Remote is documented in the Gitkube repo.

You can quickly generate a Remote spec interactively using the gitkube-cli. Here's a sample run:

gitkube remote generate -f remote.yaml
✔ Remote name: myremote
✔ Namespace: default
✔ Public key file: /home/tselvan/.ssh/id_rsa.pub
✔ K8s Yaml Manifests
✔ Manifests/Chart directory: mono-repo/manifests
✔ Skip for now
✔ Deployment name: www
✔ Container name: www
✔ Dockerfile path: mono-repo/microservices/nginx/Dockerfile
✔ Build context path: mono-repo/microservices/nginx
✗ Add another container:
✗ Add another deployment:

This outputs the Remote spec into a remote.yaml file in the working directory. You may edit the the file to further configure the remote, for instance to add a Docker registry of your choice.

3. Create Remote

Use the generated remote.yaml file to create the Remote.

gitkube remote create -f remote.yaml

This outputs the git remote url to which you will push your branches.

4. Add git remote

Add the git remote from the previous step.

git remote add myremote ssh://default-myremote@aa6e862561005755.us-west-2.elb.amazonaws.com/~/git/default-myremote

Now, you are ready to deploy your app.

5. Commit and push

Make any changes to the code, commit, and push it.

git commit -am “hello world”
git push myremote master

On push, the Gitkube pipeline kicks in and does a build and deploy of your application to the cluster.

tselvan@t-work:~/gitkube-example$ git push myremote master
Counting objects: 4, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 418 bytes | 0 bytes/s, done.
Total 4 (delta 2), reused 0 (delta 0)
remote: Gitkube build system : Fri Jun 22 08:49:05 UTC 2018: Initialising
remote:
remote: Creating the build directory
remote: Checking out 'master:163c8b016955df4979c0a980f1a1696cc788adf0' to '/home/default-myremote/build/default-myremote'
remote:
remote: Found manifests directory
remote:
remote: Applying...
remote: deployment "www" configured
remote: service "www" configured
remote:
remote: 1 deployment(s) found in this repo
remote: Trying to build them...
remote:
remote: Building Docker image for : www
remote:
remote: Building Docker image : default-myremote-default.www-www:163c8b016955df4979c0a980f1a1696cc788adf0
remote: Sending build context to Docker daemon 6.144 kB
remote: Step 1/3 : FROM nginx:latest
remote:  ---> cd5239a0906a
remote: Step 2/3 : COPY app/conf/nginx.conf /etc/nginx
remote:  ---> Using cache
remote:  ---> 639a5ed55735
remote: Step 3/3 : COPY app/src/ /usr/share/nginx/html
remote:  ---> Using cache
remote:  ---> 50b320fd0004
remote: Successfully built 50b320fd0004
remote:
remote: Updating Kubernetes deployment: www
remote: deployment "www" image updated
remote: Waiting for rollout to finish: 0 of 1 updated replicas are available...
remote: deployment "www" successfully rolled out
remote: NAME      DESIRED CURRENT  UP-TO-DATE AVAILABLE   AGE
remote: www       1 1  1 1     2h
remote:
remote: Removing build directory
remote:
remote: Gitkube build system : Fri Jun 22 08:49:08 UTC 2018: Finished build

You can see your application live using kubectl proxy at http://localhost:8080/api/v1/namespaces/default/services/www/proxy/

6. What Next?

Just keep pushing your branch, and see your application go live everytime!

Final Remarks

This is just an example workflow for using Gitkube to deploy your app on EKS. You can use similar workflows with multiple repository configurations, such as:

• Single repo including the config (K8s yamls or helm chart)
• Multi repo with code and config separate

Check out the example repo for more walkthroughs.

To conclude: start git push-ing your apps to EKS using Gitkube today!

The content and opinions in this post are those of the third-party author and AWS is not responsible for the content or accuracy of this post.