Demo: Deploying your first app with Gimlet (on a local cluster)

In this tutorial, you can learn how to install Gimlet on a Kubernetes cluster and deploy your first application.

Gimlet is an Open Source, GitOps based developer platform that makes deploying applications and infrastructure components into Kubernetes easy.

You can host it yourself, but if you plan to use it in production, check out the hosted version.

Prerequisites

For an optimal experience, it is recommended to install Nix and direnv.

This tutorial comes with a Nix-based setup. In addition to getting all tools installed, Nix (with the help of devenv) also keeps your global configuration files alone (ie. your global kube config and helm repos will not be affected).

You can follow this tutorial without using Nix, but you need to install the required tools on your own:

• Gimlet CLI
• kind
• kubectl
• kustomize
• Helm
• GitHub CLI
• Garden (optional)
• petname (optional)
• Ngrok

Additional requirements:

• Ngrok account
• GitHub account
• Internet access during the tutorial

[!NOTE] Ngrok is recommended because it can easily be installed into Kubernetes as well. However, you can use whatever tunneling solution you want to combined with port-forwarding from the cluster.

Preparations

Check out this repository:

git clone git@github.com:sagikazarmark/demo-gimlet.git

Choose a sufficiently unique, but friendly name for your demo application. You can go with something like demo-gimlet, but I suggest picking a more unique name (eg. generated by petname or a similar tool):

echo "GIMLET_APP_NAME=gimlet-$(petname)" >> .env

This name will be used to create resources (eg. GitHub repository).

Configure GitHub CLI following the documentation.

[!NOTE] Quick tip: Generate a new a new PAT here and then paste it in a file called .env:

echo "GITHUB_TOKEN=[TOKEN]" >> .env

Save your GitHub username for future use in .env:

echo "GITHUB_OWNER=$(gh api user -q ".login")" >> .env

Grab your Ngrok authentication details: - Access the ngrok Dashboard - Click Your Authtoken. Copy the Authtoken. - Click API and follow the instructions to create a new API key. Copy the API key.

Paste the credentials in .env:

echo "NGROK_AUTHTOKEN=[AUTHTOKEN]" >> .env
echo "NGROK_API_KEY=[API_KEY]" >> .env

[!IMPORTANT] .env is ignored in Git, so don't worry about committing it accidentally.

Next, head to the Domains section and create a new domain. If you have a free account, you can claim one free static domain which is more than enough for this tutorial.

Configure your domain in the .env file:

echo "NGROK_DOMAIN=[DOMAIN]" >> .env

Set up your Kubernetes cluster

Whether you install Gimlet on an existing cluster (running in the cloud or your machine) is up to you. This tutorial recommends (and comes equipped for) setting up a KinD cluster. K3d is another popular option. If you cannot run a cluster on your machine for some reasons, consider running vcluster on top of an existing cluster for easier cleanup at the end.

Create a new KinD cluster:

kind create cluster

Install Ngrok Ingress Controller (optional)

As mentioned above, using Ngrok is optional. It's recommended because it makes exposing Gimlet to the internet easier.

Start by adding Ngrok's Helm repository:

helm repo add ngrok https://ngrok.github.io/kubernetes-ingress-controller

Then install the Ingress Controller:

helm install ngrok-ingress-controller ngrok/kubernetes-ingress-controller \
  --namespace ngrok-ingress-controller \
  --create-namespace \
  --set credentials.authtoken=$NGROK_AUTHTOKEN \
  --set credentials.apiKey=$NGROK_API_KEY

[!NOTE] Pro tip: If you have Garden installed, you can run garden deploy ngrok-ingress-controller

Read more about installing and configuring the Ngrok Ingress Controller here.

Install Gimlet on the cluster

Set your Ngrok (or any other tunnel) domain:

cat << EOF > deploy/gimlet/ingress.patch.yaml
- op: replace
  path: /spec/rules/0/host
  value: $NGROK_DOMAIN
EOF

Install Gimlet:

kustomize build deploy/gimlet | kubectl apply -f -
kubectl wait deploy gimlet --for condition=Available=true --timeout=60s

[!NOTE] Pro tip: If you have Garden installed, you can run garden deploy gimlet

Configuring Gimlet

Grab the admin key from Gimlet's logs:

kubectl -n gimlet logs deploy/gimlet | grep "Admin auth key"

Head over to your Gimlet instance and log in with the Admin key:

open https://$NGROK_DOMAIN

First, let's create an API key:

• Click on your profile picture in the right upper corner of the page
• Click on Settings
• Enter a name for your API key (eg. demo)
• Click on Create

Copy the generated token and save it in .env (along with the server URL):

echo "GIMLET_SERVER=https://$NGROK_DOMAIN" >> .env
echo "GIMLET_TOKEN=[TOKEN]" >> .env

Gimlet creates a default environment for you with a unique name. You are going to need the name of this environment before configuring the demo application. Head over to the Environments section and grab the name of your environment. (Alternatively, you can create a new one with your preferred name)

As usual, save the name in .env:

echo "GIMLET_ENV=[ENV]" >> .env

Create demo app repository

Before moving onto configuring Gimlet, you should create a demo app repository. This repository will hold the Gimlet manifests as well as the source code for your demo application.

The Gimlet documentation lists a number of potential demo applications, but this tutorial uses one I prepared for this occasion: https://github.com/sagikazarmark/template-gimlet-http-echo2.

To create a new repository from this template, either click on the Use this template button on the repository page or run the following command:

gh repo create --public $GIMLET_APP_NAME --template sagikazarmark/template-gimlet-http-echo2

The above command creates a new public repository under your personal GitHub account.

In order to tell Gimlet about new versions of your application, you need to set a number of secrets and variables in your new repository:

gh secret set GIMLET_SERVER --body "$GIMLET_SERVER" --repo $GITHUB_OWNER/$GIMLET_APP_NAME
gh secret set GIMLET_TOKEN --body "$GIMLET_TOKEN" --repo $GITHUB_OWNER/$GIMLET_APP_NAME
gh variable set GIMLET_ENV --body "$GIMLET_ENV" --repo $GITHUB_OWNER/$GIMLET_APP_NAME
gh variable set GIMLET_APP --body "$GIMLET_APP_NAME" --repo $GITHUB_OWNER/$GIMLET_APP_NAME

Open up a new shell and check out the repository somewhere:

gh repo clone $GIMLET_APP_NAME

[!NOTE] Quick tip: Print the name of the repository, then copy and run the command: echo "gh repo clone $GIMLET_APP_NAME"

Configuring Gimlet

Let's continue by configuring Gimlet.

Go to the Repositories section and follow the instructions to set up GitHub authentication:

• Click on Click to integrate Github on the Settings page.
• Click on Create Github app & Integrate Gimlet
• Enter a name for your new GitHub app (Pro tip: add the unique portion of $GIMLET_APP_NAME to your app name)
• Click on Create GitHub App for ...
• Click on Only select repositories
• Select the repository you've created ($GIMLET_APP_NAME)
• Click Install and Authorize

After setting up the GitHub app, you should be redirected back to Gimlet and after a few seconds, your repository should show up on the screen.

The next step is setting up our Environment. An Environment is basically a Kubernetes cluster where you can install your applications.

Head over to the Environments section and find the gimlet environment connect command under your environment. Copy the command and run it. It should look something like this:

gimlet environment connect \
  --env YOUR_ENV_NAME \
  --server YOUR_SERVER_URL \
  --token SOME_TOKEN

Wait for a few minutes until Gimlet installs every necessary component.

Deploying your demo application

The last step to deploy your application is telling Gimlet about it.

Create a Gimlet manifest by running the following command:

cat << EOF > gimlet.yaml
env: "$GIMLET_ENV"
app: "$GIMLET_APP_NAME"
namespace: "default"
deploy:
  branch: "*"
  event: "push"
chart:
  repository: "https://chart.onechart.dev"
  name: "onechart"
  version: "0.57.0"
values:
  gitSha: "{{ .SHA }}"
  gitRepository: "$GITHUB_OWNER/$GIMLET_APP_NAME"
  image:
    repository: "ghcr.io/$GITHUB_OWNER/$GIMLET_APP_NAME"
    tag: "{{ .BRANCH }}-{{ .SHA }}"
  containerPort: 8080
  vars:
    HELLO: Gimlet
EOF

Copy the manifest to the demo repository you checked out earlier:

cp gimlet.yaml path/to/repository/gimlet

Head over to the repository and commit the manifest:

git add .gimlet
git commit -m 'add gimlet app manifest'
git push

Wait for the CI to run then check your application:

kubectl get deploy

Open a port-forward to the application:

kubectl port-forward deploy/$GIMLET_APP_NAME 8080

Check that the application is running:

curl http://127.0.0.1:8080/hello

Conclusion

In this tutorial, you installed Gimlet, created and deployed a demo application using Gimlet.

For more information and details, check out the documentation.

If you plan to use Gimlet in production, check out the hosted version.

Cleanup

The easiest way to cleanup is deleting the cluster:

kind delete cluster

In the unfortunate case you need to cleanup resources from the cluster manually, you can try deleting the following namespaces:

kubectl delete namespace gimlet
kubectl delete namespace ngrok-ingress-controller

Make sure to delete the GitHub application.