Skip to content



It is possible to make your OpenAPI schema the real source of truth for your K8s configurations with Kusk - by using it as an ArgoCD's custom tool!

GitOps approach will allow you to use ArgoCD to automatically generate configurations in a determinative way based off your OpenAPI schema that you can store in Git to easily version, review and rollback your APIs. ArgoCD will take care of automatically syncing your configurations, while Kusk will happily generate it for you every time you make a change.

This guide will help you setup Kusk in ArgoCD.

Table of Contents


  1. Have a working ArgoCD installation - ArgoCD quick start.
  2. Have a repository with OpenAPI schema configured within ArgoCD - for this example we will use Kusk's example folder.

Install Kusk as a custom tool

To install a custom tool in ArgoCD, we will follow the official guide. We will add an initContainer to argocd-repo-server and a volume to download Kusk's binary to:

--- a/argocd-repo-server.yaml
+++ b/argocd-repo-server.yaml
@@ -31,6 +31,16 @@ spec:
               weight: 5
       automountServiceAccountToken: false
+      initContainers:
+        - name: download-kusk-gen
+          image: alpine:3.8
+          command: [ sh, -c ]
+          args:
+            - wget -qO- | tar -xvzf - &&
+              mv kusk /custom-tools/
+          volumeMounts:
+            - mountPath: /custom-tools
+              name: kusk-gen
         - command:
@@ -72,7 +82,12 @@ spec:
               name: gpg-keyring
             - mountPath: /app/config/reposerver/tls
               name: argocd-repo-server-tls
+            - mountPath: /usr/local/bin/kusk-gen
+              name: kusk-gen
+              subPath: kusk-gen
+        - name: kusk-gen
+          emptyDir: {}
         - configMap:
             name: argocd-ssh-known-hosts-cm
           name: ssh-known-hosts

When installed, Kusk binary will be available during ArgoCD sync. To use that, we'll register a configuration management plugin:

--- a/argocd-cm.yaml
+++ b/argocd-cm.yaml
@@ -5,3 +5,9 @@ metadata: argocd-cm argocd
   name: argocd-cm
+  configManagementPlugins: |
+    - name: kusk-gen
+      generate:
+        command: ["/bin/sh", "-c"]
+        args: ["kusk-gen $KUSK_GENERATOR -i $KUSK_INPUT $KUSK_ARGS"]

Once these changes are applied to your ArgoCD installation, you can begin to use Kusk!

Use kusk-gen in ArgoCD UI

When you are creating an App via UI, scroll down and select "Plugin" as a configuration management tool: image

After that, select kusk-gen as a plugin and fill the environment variables to specify the generator you want to invoke and the input file with your OpenAPI schema: image

ArgoCD will sync your app and you will be able to see resources generated and applied to your cluster automatically 🪄: image

Use kusk-gen in ArgoCD CLI

It is also possible to create an App via CLI with Kusk - just specify --config-management-plugin kusk option:

argocd app create petstore-kusk \
    --config-management-plugin kusk \
    --plugin-env KUSK_GENERATOR=ambassador \
    --plugin-env KUSK_INPUT=petstore_extension.yaml \
    --repo \
    --path examples/petstore \
    --dest-server https://kubernetes.default.svc \
    --dest-namespace default

Use kusk-gen in ArgoCD App manifest

In ArgoCD it is possible to manage applications using App manifest and apply them using kubectl: documentation. To use Kusk in this setup, add Kusk in a plugin node:

kind: Application
  name: petstore-kusk
    namespace: default
    server: 'https://kubernetes.default.svc'
    path: examples/petstore
    repoURL: ''
    targetRevision: main
      name: kusk
        - name: KUSK_INPUT
          value: petstore_extension.yaml
        - name: KUSK_GENERATOR
          value: ambassador
  project: default
      prune: true
      selfHeal: true