Report Kubernetes environments to Kosli

Learn how to report running artifacts from a Kubernetes cluster to Kosli — using a Helm chart for production, the CLI for a quick test, or an externally scheduled cron job.

By the end of this tutorial, you will have reported a snapshot of your Kubernetes cluster to Kosli, making its running artifacts visible and trackable.

Prerequisites

• Have access to a Kubernetes cluster.
• Create a Kubernetes Kosli environment named k8s-tutorial.
• Get a Kosli API token.

Report a snapshot

Helm chart (recommended)

The Kosli K8S reporter Helm chart deploys a CronJob inside your cluster that automatically reports running artifacts to Kosli on a schedule. This is the recommended approach for production use.

Install Helm if you have not done so.

1. Create a Kubernetes secret containing your Kosli API token:

kubectl create secret generic kosli-api-token --from-literal=apikey=<your-kosli-api-token>

Make sure the secret value does not contain trailing whitespace.

2. Create a tutorial-values.yaml file to configure the chart:

# the cron schedule at which the reporter is triggered
cronSchedule: "*/5 * * * *"

kosliApiToken:
  # the name of the secret containing the Kosli API token
  secretName: "kosli-api-token"
  # the key in the secret data that contains the token
  secretKey: "apikey"

reporterConfig:
  # the name of the Kosli org
  kosliOrg: "<your-kosli-org-name>"
  # the name of the Kosli environment to report to
  kosliEnvironmentName: "k8s-tutorial"
  # comma-separated list of namespace name regex patterns to report
  # leave empty to report the entire cluster
  namespaces: ""

3. Install the chart:

helm repo add kosli https://charts.kosli.com/
helm repo update
helm install kosli-reporter kosli/k8s-reporter -f tutorial-values.yaml

4. Confirm the CronJob was created:

kubectl get cronjobs

The CronJob will now run every 5 minutes and report what is running in the cluster to Kosli.

Externally scheduled cron

If you cannot run the reporter inside the cluster, you can run kosli snapshot k8s from outside on a regular schedule. This requires network access to the cluster from wherever the CLI runs.

The example below uses a GitHub Actions scheduled workflow:

The workflow requires the following GitHub Actions secrets: MY_KOSLI_API_TOKEN, GKE_SA_KEY, GKE_PROJECT.

name: Regular Kubernetes reports to Kosli

on:
  workflow_dispatch:
  schedule:
    - cron: '0 * * * *' # every hour

jobs:
  k8s-report:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: write
    env:
      KOSLI_API_TOKEN: ${{ secrets.MY_KOSLI_API_TOKEN }}

    steps:
      - name: Install Kosli CLI
        uses: kosli-dev/setup-cli-action@v2

      # Replace this step with one that connects to your cluster if not using GKE
      - name: Connect to GKE
        uses: 'Swibi/connect-to-gke'
        with:
          GCP_SA_KEY: ${{ secrets.GKE_SA_KEY }}
          GCP_PROJECT_ID: ${{ secrets.GKE_PROJECT }}
          GKE_CLUSTER: <your-cluster-name>
          GKE_ZONE: <your-cluster-zone>

      - name: Report K8S snapshot to Kosli
        run: kosli snapshot k8s k8s-tutorial --org <your-kosli-org-name>

      - name: Notify Slack on failure
        if: ${{ failure() }}
        uses: rtCamp/action-slack-notify@v2
        env:
          SLACK_CHANNEL: kosli-reports-failure
          SLACK_COLOR: ${{ job.status }}
          SLACK_TITLE: Reporting K8S artifacts to Kosli has failed
          SLACK_USERNAME: GithubActions
          SLACK_WEBHOOK: ${{ secrets.SLACK_CI_FAILURES_WEBHOOK }}
          SLACK_MESSAGE: "Reporting K8S artifacts to Kosli has failed. Please check the logs for more details."

Kosli CLI (testing only)

This approach is intended for ad-hoc and local testing only. Do not use it in production — use the Helm chart instead.

Install Kosli CLI if you have not done so.

All commands below use the default kubeconfig context. Pass --kubeconfig to use a different one.

To report all artifacts running in the entire cluster:

kosli snapshot k8s k8s-tutorial \
    --api-token <your-api-token-here> \
    --org <your-kosli-org-name>

To report only artifacts running in specific namespaces:

kosli snapshot k8s k8s-tutorial \
    --namespaces namespace1,namespace2 \
    --api-token <your-api-token-here> \
    --org <your-kosli-org-name>

To report the entire cluster except for certain namespaces:

kosli snapshot k8s k8s-tutorial \
    --exclude-namespaces namespace1,namespace2 \
    --api-token <your-api-token-here> \
    --org <your-kosli-org-name>

Running multiple reporters

If you are considering running more than one reporter against the same cluster, the table below summarizes which setups produce meaningful snapshots and which don’t.

Scenario	Supported	Explanation
Two orgs, separate environments, overlapping namespaces	Yes	Different environments → independent snapshots.
One org, two environments, overlapping namespaces	Yes	Same as above.
One org, same environment, two reporters with overlapping namespaces	No	Snapshots toggle between each reporter’s view. No data is deleted, but diffs between consecutive snapshots become meaningless.
One org, same environment, two reporters with disjoint namespaces	No	Each snapshot only reflects one reporter’s namespaces, so diffs compare unrelated scopes.

A single Kosli environment must have exactly one reporter feeding it. Snapshots are never overwritten or deleted, but if two reporters take turns updating the same environment:

• Diffs between consecutive snapshots compare unrelated views of the cluster.
• The environment history shows artifacts continuously stopping and starting as each report toggles which namespaces are visible.

What you’ve accomplished

You have reported a snapshot of your Kubernetes cluster to Kosli. Kosli now tracks the running artifacts in that environment and will record changes as they happen.

From here you can:

• Query your environment with kosli list snapshots and kosli get snapshot
• Compare snapshots to see what changed
• Trace a running artifact back to its git commit with the From commit to production tutorial