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>

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

Understand Kosli

Getting started

User

Administration

Tutorials

Troubleshooting

FAQ

Integrations

Report Kubernetes environments to Kosli

Prerequisites

Report a snapshot

What gets reported

Running multiple reporters

What you’ve accomplished

​Prerequisites

​Report a snapshot

​What gets reported

​Running multiple reporters

​What you’ve accomplished

Prerequisites

Report a snapshot

What gets reported

Running multiple reporters

What you’ve accomplished