Home pageGimlet
GitHub

Reference

Gimletd configuration reference

On this page you will see Gimletd's installation manifests.

The preferred method to install Gimletd is through the Gimlet Installer. This page is a full configuration reference should you need to adjust the configuration.

Installation yamls and configuration

You can get the Kubernetes yamls by rendering the Helm chart with the minimum configuration you can see below:

cat << EOF > values.yaml
image:
  repository: ghcr.io/gimlet-io/gimletd
  tag: latest
  pullPolicy: Always
containerPort: 8888
probe:
  enabled: true
  path: /
EOF


helm template gimletd onechart/onechart -f values.yaml

Ingress to expose the Gimletd API

image:
  repository: ghcr.io/gimlet-io/gimletd
  tag: latest
probe:
  enabled: true
  path: /
volumes:
  - name: data
    path: /var/lib/gimletd
    size: 1Gi
  - name: repo-cache
    path: /tmp/gimletd
    size: 5Gi
+ingress:
+  annotations:
+    kubernetes.io/ingress.class: nginx
+    cert-manager.io/cluster-issuer: letsencrypt
+  host: gimletd.mycompany.com
+  tlsEnabled: true

Once you did this basic configuration, time to run Gimletd for the first time. Shall we?

Admin token

When you first start Gimletd, it inits the database and prints the admin token to the logs.

{"level":"info","msg":"Admin token created: eyJhbGciOiJIUzI1NiIsInR5cCxxxs","time":"2021-11-11T09:04:03Z"}

Add this admin token in your password manager now, and make a user token for yourself:

curl -i \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -X POST -d '{"login":"my-user"}' \
  http://gimletd.mycompany.com:8888/api/user?access_token=$GIMLET_ADMIN_TOKEN

Save the returned user token from the result.

To get the admin token after the first start

If you want to print the admin token after the first start, add the PRINT_ADMIN_TOKEN: true environment variable to Gimletd's config.

Persistence

Volumes to back the state

image:
  repository: ghcr.io/gimlet-io/gimletd
  tag: latest
probe:
  enabled: true
  path: /
+volumes:
+  - name: data
+    path: /var/lib/gimletd
+    size: 1Gi
+  - name: repo-cache
+    path: /tmp/gimletd
+    size: 5Gi

The purpose of these volumes are:

  • the data volume is for the sqlite database to keep metadata in it.
  • the repo-cache volume is what Gimletd uses as scratch space for git operations. It is good practice to add a volume under it, so the high IO work Gimletd does is performed on a real disk, with measurable and controllable IO, and not on the operating system disk.

Using Postgresql

If you prefer, you can use Postgresql instead of SQLite.

image:
  repository: ghcr.io/gimlet-io/gimletd
  tag: latest
probe:
  enabled: true
  path: /
volumes:
-  - name: data
-    path: /var/lib/gimletd
-    size: 1Gi
  - name: repo-cache
    path: /tmp/gimletd
    size: 5Gi
+vars:
+  DATABASE_DRIVER: postgres
+  DATABASE_CONFIG: "postgres://gimletd:yourpassword@postgresql:5432/gimletd?sslmode=disable"

Notifications on gitops repo applies

This section you will configure Flux - the gitops controller - to notify Gimletd whenever it applies the latest changes.

  • Generate a Gimlet user for Flux:
curl -i \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -X POST -d '{"login":"flux"}' \
  http://gimletd.mycompany.com:8888/api/user\?access_token\=$GIMLET_ADMIN_TOKEN
  • Create the notifications.yaml file in your gitops repo under $your_env/flux/notifications.yaml
apiVersion: notification.toolkit.fluxcd.io/v1beta1
kind: Provider
metadata:
  name: gimletd
  namespace: flux-system
spec:
  type: generic
  address: https://gimletd.<your-company-com>/api/flux-events?access_token=<token>
---
apiVersion: notification.toolkit.fluxcd.io/v1beta1
kind: Alert
metadata:
  name: all-kustomizations
  namespace: flux-system
spec:
  providerRef:
    name: gimletd
  eventSeverity: info
  eventSources:
    - kind: Kustomization
      namespace: flux-system
      name: '*'
  suspend: false

You will see the notifications reaching Slack:

Notifications on gitops applies

Configure the gitops repository

Gimletd's main job is to work on the gitops repository. It encompasses all logic that write the gitops repository, and encapsulates the heavy audit log processing algorithms.

In this section you will configure the gitops repositories, so Gimletd can write deployment manifests upon deployment to environments.

You can use Gimlet Dashboard for this task

Remember, you can use Gimlet Dashboard for this task. There is a 1-click config option for each environment if there is no Gimletd config exists yet.

To configure a gitops repository, and thus a Gimlet environment, use the GITOPS_REPOS environment variable.

An example for it

GITOPS_REPOS=env=staging&repoPerEnv=false&gitopsRepo=gitops-staging-infra&deployKeyPath=/github/staging.key

You can set multiple environment configs by separating the entries by the ; ist separator.

Granting access with a deploy key

The above configuration refers to a deploy key that must be mounted under /github/staging.key.

  • Generate a keypair with
ssh-keygen -t ed25519 -C "your_email@example.com"
  • Open GitHub, navigate to your gitops repository, and under Settings > Deploy keys click on "Add deploy key"
  • Paste the generated public key
  • Make sure to check the "Allow write access" checkbox

Add the keys to the Gimletd installation config:

image:
  repository: ghcr.io/gimlet-io/gimletd
  tag: latest
probe:
  enabled: true
  path: /
[...]
+vars:
+  GITOPS_REPO: mycompany/gitops
+  GITOPS_REPO_DEPLOY_KEY_PATH: /github/deploy.key
+sealedFileSecrets:
+  - name: github-gitops-deploy-key
+    path: /github
+    filesToMount:
+      - name: deploy.key
+        source: AgA/7BnNhSkZAzbMqxMDidxK[...]

If you don't have Sealed Secrets running in your cluster, you can use your own secrets solution, or the following example that uses regular Kubernetes secrets stored in git (not for production use).

image:
  repository: ghcr.io/gimlet-io/gimletd
  tag: latest
probe:
  enabled: true
  path: /
[...]
vars:
[...]
+fileSecrets:
+  - name:  github-gitops-deploy-key
+    path: /github
+    secrets:
+      deploy.key: |
+        -----BEGIN OPENSSH PRIVATE KEY-----
+        b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAACFwAAAAdzc2gtcn
+        NhAAAAAwEAAQAAAgEA7BqMTFnDm6+C9FrRK5aoj[...]
EOF

Notifications

Sack

First, create a Slack app

To generate a new Slack token, visit the https://api.slack.com/apps page and follow these steps:

  • Create a new application. "App Name" is Gimlet, pick your workspace as "Development Slack Workspace"
  • Navigate to "OAuth & Permissions" on the left sidebar
  • Under "Bot Token Scopes", add scopes chat:write, chat:write.customize and chat:write.public
  • Click the "Install App to Workspace" button on the top of the page
  • Once you installed the app, save "Bot User OAuth Access Token" in Gimlet above
image:
  repository: ghcr.io/gimlet-io/gimletd
  tag: latest
probe:
  enabled: true
  path: /
[...]
+vars:
+  NOTIFICATIONS_PROVIDER: slack
+  NOTIFICATIONS_TOKEN: xoxb-41[...]
+  NOTIFICATIONS_DEFAULT_CHANNEL: gimletd

Discord

  • First, make sure you’re logged in on the Discord website.
  • Navigate to the application page: https://discord.com/developers/applications
  • Click on the “New Application” button.
  • Enter "Gimlet" and confirm the pop-up window by clicking the "Create" button.
  • Create a bot by navigating to the “Bot” tab, and clicking the “Build-A-Bot” button.
  • Click the "Add Bot" button on the right and confirm the pop-up window by clicking the "Yes, do it!" button.
  • After you received the "A wild bot has appeared!" message, copy your bot token from the "Build-A-Bot" submenu.
  • Navigate to "OAuth2" -> "URL Generator" on the left panel.
  • Check "Bot" in Scopes and check "Send Messages" in "Bot Permissions" -> "Text Permissions".
  • Copy your generated URL from the bottom of the page, and open it in a new tab.
  • Select the server you would like to add your bot to, and click "Continue". You can only select servers on which you have admin privileges. Make sure the "Send Messages" option is checked, before clicking on the "Authorize" button.
  • After the security check, your bot will automatically join the server.
  • The final step is to get the channel ID of the channel where you would like to get notifications. In order to do that, first you need to go to "User Settings" -> "Advanced", and enable "Developer Mode". This will allow you to see and copy your channel IDs.
  • Now you can copy your text channel ID on Discord's main page by right clicking on the desired channel in the left panel and choosing the "Copy ID" option.
  • Make sure that the newly created bot is a member of your channel. Use the "Add members or roles" button in the channel to invite your bot's role.
image:
  repository: ghcr.io/gimlet-io/gimletd
  tag: latest
probe:
  enabled: true
  path: /
[...]
+vars:
+  NOTIFICATIONS_PROVIDER: discord
+  NOTIFICATIONS_TOKEN: OTQwO[...]
+  NOTIFICATIONS_DEFAULT_CHANNEL: "140971232847884321"

Github integration

Gimletd integrates with Github with a dedicated Github Application.

Gimletd uses this integration to:

  • detect deleted branches in your source code repositories
  • send commit statuses on gitops operations
  • read private Helm charts, should you use a custom Helm chart for your applications

Integrating through a Github Application

There are multiple ways that you can integrate with Github. Gimletd chooses to use a Github Application which has the most fine-grained access model. You can set which repositories Gimletd can access, and what it can do with those repositories.

You will use a dedicated Github Application, that you create. Practically you don't give access to any third-party, not even the makers of Gimlet.

Creating the Github Application

To create the Github Application, we provide a script that is writing an HTML file to your disk, and guides you through the creation process.

When you click the "Create Github app" button, you are forwarded to Github where you can confirm your application's name. All settings are sent to Github in a json structure, holding the required permission list, webhook URLs and so on, so you don't have to perform too many manual steps.

Now scan the source of the HTML file.



cat << EOF > create-app.html
<form action="https://github.com/settings/apps/new" method="post">
  <input type="hidden" name="manifest" id="manifest"><br>
  <input type="submit" value="Create Github app">
</form>


<script>
  var url = new URL(window.location);
  var code = url.searchParams.get("code");


  if (code) {
    var xhr = new XMLHttpRequest();
    xhr.onreadystatechange = function() {
    if (xhr.readyState === 4) {
      console.log(xhr.response)


      var responseObj = JSON.parse(xhr.response)


      document.open();


      document.write('<p>GITHUB_APP_ID: ' + responseObj.id + '</p>');
      document.write('<p>GITHUB_PRIVATE_KEY: <br/>' + responseObj.pem.replaceAll('\n', '<br/>') + '</p>');


      document.close();
      }
    }
    xhr.open("POST", "https://api.github.com/app-manifests/"+code+"/conversions", true);
    xhr.send();
  }
</script>


<script>
  input = document.getElementById("manifest")
  input.value = JSON.stringify({
  "name": "Gimletd",
  "url": "https://gimlet.mycompany.com",
  "callback_url": "https://gimlet.mycompany.com",
  "hook_attributes": {
    "url": "https://gimlet.mycompany.com/hook"
  },
  "redirect_url": "http://127.0.0.1:11111/create-app.html",
  "public": false,
  "default_permissions": {
    "contents": "read",
    "statuses": "write",
  },
  "default_events": []
  })
</script>
EOF


PORT=11111 npx http-server -o /create-app.html

Once you clicked the "Create Github app" button, and confirmed the app's name on Github, you are redirected to a page that shows all the required configuration values for Gimlet Dashboard.

Copy them to your Helm values file accordingly.

image:
  repository: ghcr.io/gimlet-io/gimletd
  tag: latest
probe:
  enabled: true
  path: /
+vars:
+  GITHUB_APP_ID: 123456789
+  GITHUB_INSTALLATION_ID: "987654321"
+  GITHUB_PRIVATE_KEY: |
+    -----BEGIN RSA PRIVATE KEY-----
+    MIIEowIBAAKCAQEAxpLdgC6KEDFPx5...
+    ...

To obtain the INSTALLATION_ID, navigate to https://github.com/settings/apps and edit your just created application. Click Install App in the sidebar to install it on the account that you want Gimletd to access.

You can copy the INSTALLATION_ID from your browsers address bar after installation. The URL will be in the following format: https://github.com/settings/installations/$INSTALLATION_ID

That's all.

Now you integrated Gimletd with Github.

If you are in doubt about the process, you can crosscheck our script with Github's general guide on how to create a Github Application here

You can also validate our script on Github's Creating a GitHub App from a manifest guide

Misc

Limiting resources

image:
  repository: ghcr.io/gimlet-io/gimletd
  tag: latest
probe:
  enabled: true
  path: /
[...]
+resources:
+  requests:
+    cpu: "50m"
+    memory: "200Mi"
+  limits:
+    cpu: "2000m"
+    memory: "1000Mi"

Debug sidecar container

In case you need tools to debug.

image:
  repository: ghcr.io/gimlet-io/gimletd
  tag: latest
probe:
  enabled: true
  path: /
[...]
+ sidecar:
+   repository: debian
+   tag: stable-slim
+   shell: "/bin/bash"
+   command: "while true; do sleep 30; done;"

Verifying the installation

To verify Gimletd, run the Bootstrap gitops automation with Gimlet CLI tutorial.

Previous
← Gimlet Dashboard configuration reference
Next
Gimlet Agent configuration reference →