Gimlet - Installating Gimlet on CIVO Cloud

On this page you can learn how to install Gimlet from the CIVO Marketplace, alongside with the built-in Traefik ingress controller from the CIVO Marketplace.

You can install Gimlet with an installer. The installer initiates a gitops environment and puts Gimlet into its gitops repository. This way Gimlet itself is managed by gitops.

You will access the dashboard through CIVO's built in Traefik ingress controller on your CIVO cluster's default DNS name. Later you can move to your preferred DNS name and HTTPS.

Prerequisites

A https://github.com personal or organization account.
A https://civo.com Kubernetes cluster
Using the built-in Traefik ingress controller either in NodePort or LoadBalancer configuration.

Starting the installer from the CIVO marketplace

Install Gimlet from the CIVO Marketplace. You can find it under civo.com > Kubernetes > your cluster > Marketplace > CI/CD.

Locate the installed installer and open it in your browser on http://gimlet.<your-cluster-id>.k8s.civo.com

$ kubectl get ing -n gimlet-installer


NAME                  HOSTS
gimlet-installer      gimlet.67885664-c931-48da-ba5d-0c122cb09879.k8s.civo.com

Follow the installer steps and follow along in the coming chapters.

Step 1: Creating a Github Application

First, the installer creates a Github Application to manage all Gimlet access with it.

Creating a Github application

Install the newly created Github Application and select what repositories Gimlet should have access to. It is most convenient to allow all repositories. If you prefer a smaller set of repositories, select a few application repositories you want deploy with Gimlet and remember to extend the repository list if you want to roll out Gimlet for new apps.

Step 3 screenshot

As a final step, you also need to authorize the newly created application. Keep in mind that you are granting this access to your own Github Application. You are not granting any access to any third-party nor the Gimlet creators.

Step 4 screenshot

Step 2: Bootstrapping a gitops environment

You have to provide information about the environment you are creating in this step.

You need to name the environment and set the approach to structure gitops resources. By default, Gimlet uses two gitops repositories per environment by convention, one for infrastructure components, one for application deployments.

Step 2 screenshot

Then, at the bottom of the screen, you need to select what components to install.

Component settings are prefilled with values, in general you should not change them.

For CIVO Cloud

Enable the CIVO component.
Since you use the built-in Traefik ingress controller, make sure the Nginx component is turned off.

Using an existing PostgreSQL database

The installer installs a containerized PostgreSQL database for Gimlet to store data in.

If you prefer to use an existing database, set the access parameters under:

Gimlet > Gimlet Dashboard > Config > Postgresql settings
Gimlet > Gimletd > Config > Postgresql settings

Step 3: Kickstarting the gitops automation

Step 2 screenshot

Once the boorstrapping is done, you have two new git repositories to store manifests in.

Follow the instructions to kickstart the automation: add deploy keys, and run kubectl commands.

Once you performed all the instructions, close the browser tab, and return to the terminal to finalize the install.

Wait until resources are up

To determine if the gitops automation is healthy, run the following script:

until [ $(kubectl get kustomizations.kustomize.toolkit.fluxcd.io -A | grep gitops-repo | grep True | wc -l) -eq 4 ]
do
  echo ""
  echo " 🧐 Waiting for all four gitops kustomizations become ready, ctrl+c to abort"
  echo ""
  echo "$ kubectl get kustomizations.kustomize.toolkit.fluxcd.io -A"
  kubectl get kustomizations.kustomize.toolkit.fluxcd.io -A | grep -w 'gitops-repo\|READY'
  sleep 3
done


echo ""
echo " ✅ Gitops loop is healthy"
echo ""

To see if Gimlet has started, run the following script:

until [ $(kubectl get pods -n infrastructure | grep gimlet | grep 1/1 | wc -l) -eq 3 ]
do
  echo ""
  echo " 🧐 Waiting for Gimlet to start up in the cluster, ctrl+c to abort"
  echo ""
  echo "$ kubectl get pods -n infrastructure | grep gimlet"
  kubectl get pods -n infrastructure | grep 'gimlet\|READY\|postgres'
  sleep 3
done


echo ""
echo " ✅ Gimlet is up"
echo ""

Accessing Gimlet

First, a bit of cleanup. It is safe to delete the installer now:

kubectl delete namespace gimlet-installer

Access Gimlet on the default CIVO DNS name: http://gimlet.<your-cluster-id>.k8s.civo.com

$ kubectl get ing -n infrastructure               
NAME               HOSTS
gimlet-dashboard   gimlet.67885664-c931-48da-ba5d-0c122cb09879.k8s.civo.com
gimletd            gimletd.67885664-c931-48da-ba5d-0c122cb09879.k8s.civo.com

Congratulations, now you have a fully functioning Gimlet dashboard available on your CIVO cluster.

Try it for size, and if it works for you, you might want to move the installation to your preferred domain and HTTPS

Moving the installation to your preferred domain and HTTPS

So far you accessed Gimlet through a CIVO's default DNS name. In this section, you can read about how to move to your preferred domain name secured by HTTPS. This step is optional, and can be skipped if you are evaulating.

The Gimlet Dashboard is currently reachable on http://gimlet.<your-cluster-id>.k8s.civo.com, the Gimletd API is accessible on http://gimletd.<your-cluster-id>.k8s.civo.com.

$ kubectl get ing -n infrastructure               
NAME               HOSTS
gimlet-dashboard   gimlet.67885664-c931-48da-ba5d-0c122cb09879.k8s.civo.com
gimletd            gimletd.67885664-c931-48da-ba5d-0c122cb09879.k8s.civo.com

It is time to reconfigure your Gimlet to be hosted on your preferred domain name. To reconfigure your stack, follow one of the methods described in Managing infrastructure components.

Update the ingress controller host name

Update the ingress controller host name from <your-cluster-id>.k8s.civo.com to testing.yourcompany.com given that you named your environment testing and your preferred domain name is yourcompany.com. You can skip the testing prefix if this is your production environment.

Your ingress controller host name is part of your cloud provider settings Infrastructure Components > Cloud Provider > CIVO.

Update the Gimlet Dashboard host name

Gimlet Dashboard should know about where it is hosted. Update the Gimlet > Gimlet Dashboard > Config > Host setting to your preferred domain name. Use a full domain name with the protocol included eg.: https://gimlet.testing.yourcompany.com.

Install Cert-Manager

Enable the Cert-Manager component under Infrastructure Components > Ingress > CertManager.

Write changes to the gitops repo

Press Infrastructure Components > Save components and watch the gitops commit manifest on the cluster.

Update Github OAuth configuration

For the Github OAuth authentication to work, you also need to update the URLs in your Github application settings on Github.com under Settings > Developer settings > GitHub Apps > Your Gimlet Application

Update Homepage URL from http://<your-cluster-id>.k8s.civo.com to https://gimlet.testing.yourcompany.com
Update Callback URL from http://<your-cluster-id>.k8s.civo.com/auth to https://gimlet.testing.yourcompany.com/auth
Update Webhook URL from http://<your-cluster-id>.k8s.civo.com/hook to https://gimlet.testing.yourcompany.com/hook