AWS Open Source Blog
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:
- Very thin clients: The only thing you need to have installed on your machines is git.
- 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.
- 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.