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

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.

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.

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

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>

What gets reported

A snapshot lists the pods running in scope. The reporter is blind to workload kind — a Job pod is reported exactly like a Deployment pod — and only pods in the Running and Failed phases are reported; Succeeded and Pending pods are not.

That matters most for short-lived workloads. A Job or CronJob pod is captured only while it is running, so a job that starts and finishes between two snapshots never appears, and a successful run leaves no trace in the environment. A pod that fails is the exception — it keeps being reported until Kubernetes cleans it up.

For the full model — how job pods affect environment churn and compliance, and what to do about it — see Understand Kubernetes reporting.

Running multiple reporters

A single Kosli environment must have exactly one reporter feeding it. Pointing two reporters at the same environment does not delete data, but it makes diffs between consecutive snapshots meaningless. For the supported and unsupported topologies, see Running multiple reporters.

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
• See what snapshots do and don’t capture in Understand Kubernetes reporting