Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kosli.com/llms.txt

Use this file to discover all available pages before exploring further.

By the end of this tutorial, you will have reported a snapshot of your Cloud Run environment to Kosli, making its running services and jobs visible and trackable. kosli snapshot cloud-run covers a specific set of GCP deploy methods. See the kosli snapshot cloud-run reference for the current list of what’s supported. There are two ways to do this:
  • Kosli CLI — quick to run, suitable for testing only
  • — runs the reporter inside GCP on a schedule for continuous, production-grade reporting
Follow the section that matches your needs.

​
Prerequisites

​
Report using Kosli CLI

This approach is suitable for testing only. Install Kosli CLI if you have not done so, then authenticate to GCP with Application Default Credentials: 
gcloud auth application-default login
Run the snapshot command: 
kosli snapshot cloud-run cloud-run-tutorial \
    --project <your-gcp-project> \
    --region <your-gcp-region> \
    --resolve-names \
    --api-token <your-api-token-here> \
    --org <your-kosli-org-name>
--resolve-names makes Cloud Run services display their image tags (for example the commit SHA) instead of bare digests by reverse-resolving the deployed digest against Artifact Registry. The forward digest lookup for tag-pinned Jobs runs automatically whether you pass the flag or not. See kosli snapshot cloud-run for the full flag reference.

​
Report using a scheduled Cloud Run Job

For production, run the reporter inside GCP as a Cloud Run Job triggered by Cloud Scheduler.
1

Create a service account for the reporter

gcloud iam service-accounts create kosli-reporter \
    --display-name="Kosli reporter" \
    --project=<your-gcp-project>
2

Grant the reporter project-level access to Cloud Run

roles/run.viewer is the minimum needed to list services and jobs in the project.
gcloud projects add-iam-policy-binding <your-gcp-project> \
    --member="serviceAccount:kosli-reporter@<your-gcp-project>.iam.gserviceaccount.com" \
    --role="roles/run.viewer"
3

Store the Kosli API token in Secret Manager

Create a secret and add your token as the first version:
gcloud secrets create kosli-api-token \
    --replication-policy=automatic \
    --project=<your-gcp-project>

printf "<your-api-token-here>" | gcloud secrets versions add kosli-api-token \
    --data-file=- \
    --project=<your-gcp-project>
Grant the reporter service account read access to that specific secret:
gcloud secrets add-iam-policy-binding kosli-api-token \
    --member="serviceAccount:kosli-reporter@<your-gcp-project>.iam.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor" \
    --project=<your-gcp-project>
4

Grant Artifact Registry read access

Grant roles/artifactregistry.reader to the reporter on each Artifact Registry repository that holds your application images. This is what lets the reporter resolve digests and tags so artifact names are useful on Kosli.
gcloud artifacts repositories add-iam-policy-binding <your-repo> \
    --location=<your-gcp-region> \
    --member="serviceAccount:kosli-reporter@<your-gcp-project>.iam.gserviceaccount.com" \
    --role="roles/artifactregistry.reader" \
    --project=<your-gcp-project>
Repeat the command for every Artifact Registry repository that holds images deployed to Cloud Run in this project.
If you deploy any Cloud Functions 2nd-gen functions in this project, also grant the same role on the Google-managed gcf-artifacts repository in the same region. 2nd-gen functions store their backing images there, and the reporter needs read access to resolve them.
5

Deploy the reporter as a Cloud Run Job

gcloud run jobs deploy kosli-reporter \
    --image=ghcr.io/kosli-dev/cli:latest \
    --region=<your-gcp-region> \
    --project=<your-gcp-project> \
    --service-account=kosli-reporter@<your-gcp-project>.iam.gserviceaccount.com \
    --set-env-vars=KOSLI_ORG=<your-kosli-org-name>,KOSLI_HOST=https://app.kosli.com \
    --set-secrets=KOSLI_API_TOKEN=kosli-api-token:latest \
    --args=snapshot,cloud-run,cloud-run-tutorial,--project,<your-gcp-project>,--region,<your-gcp-region>,--resolve-names
Pin the CLI image to a specific version (for example ghcr.io/kosli-dev/cli:v2.18.0) so the reporter behaviour does not change unexpectedly when a new release is published.
Cloud Run Jobs are created with deletionProtection=true by default. You will need to disable it (gcloud run jobs update kosli-reporter --no-deletion-protection --region=<your-gcp-region>) before you can delete or replace the Job later.
6

Schedule the reporter with Cloud Scheduler

Create a Cloud Scheduler job that triggers the Cloud Run Job every five minutes, and grant its service account permission to invoke the Job:
gcloud scheduler jobs create http kosli-reporter-schedule \
    --location=<your-gcp-region> \
    --schedule="*/5 * * * *" \
    --uri="https://run.googleapis.com/v2/projects/<your-gcp-project>/locations/<your-gcp-region>/jobs/kosli-reporter:run" \
    --http-method=POST \
    --oauth-service-account-email=kosli-reporter@<your-gcp-project>.iam.gserviceaccount.com \
    --project=<your-gcp-project>

gcloud run jobs add-iam-policy-binding kosli-reporter \
    --region=<your-gcp-region> \
    --member="serviceAccount:kosli-reporter@<your-gcp-project>.iam.gserviceaccount.com" \
    --role="roles/run.invoker" \
    --project=<your-gcp-project>
7

Verify the reporter

In the GCP console, open Cloud Run -> Jobs -> kosli-reporter and check the execution logs for a recent successful run. Then confirm that a fresh snapshot has appeared for the cloud-run-tutorial environment in the Kosli UI.

​
What you’ve accomplished

You have reported a snapshot of your Cloud Run environment to Kosli. Kosli now tracks the running services and jobs in that environment and will record changes as they happen. From here you can:
Last modified on May 12, 2026