Report Kubernetes environments to Kosli

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)
Externally scheduled cron
Kosli CLI (testing only)

The Kosli K8S reporter Helm chart deploys a 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.

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.

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 Kosli environment(s) to report to
  environments:
    # omit the namespace fields to report the entire cluster
    - name: "k8s-tutorial"
      # optionally restrict to specific namespaces:
      # namespaces: [namespace1, namespace2]

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

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.

Running on EKS with Karpenter, or another node autoscaler? A reporter pod arriving every 5 minutes can stop nodes being consolidated. Pin the reporter to a stable node group, widen cronSchedule, or run it out of cluster. See Running on EKS with Karpenter.

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@v5

      # 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."

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 . 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

​Prerequisites

​Report a snapshot

​Running multiple reporters

​What you’ve accomplished

Prerequisites

Report a snapshot

Running multiple reporters

What you’ve accomplished