Skip to content

Commit 615f26b

Browse files
ToreMerkelyclaude
ToreMerkely
and
claude
committed
docs: add Cloud Run environment reporting tutorial
Add tutorial for reporting Cloud Run services and jobs to Kosli via `kosli snapshot cloud-run`, covering both a CLI quick-test path and a production scheduled Cloud Run Job. Also adds the CLI reference page for the command and surfaces Cloud Run on the Environments overview. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent cf24d7a commit 615f26b

4 files changed

Lines changed: 268 additions & 1 deletion

File tree

‎client_reference/kosli_snapshot_cloud-run.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
title: "kosli snapshot cloud-run"
3+
beta: false
4+
deprecated: false
5+
description: "Report a snapshot of Cloud Run services and jobs in a Google Cloud project and region to Kosli. "
6+
---
7+
8+
## Synopsis
9+
10+
```shell
11+
kosli snapshot cloud-run ENVIRONMENT-NAME [flags]
12+
```
13+
14+
Report a snapshot of Cloud Run services and jobs in a Google Cloud project and region to Kosli.
15+
Each Cloud Run service contributes one artifact per revision in its traffic
16+
configuration. Each Cloud Run Job contributes one artifact, identified by the
17+
image bound to the Job (Jobs do not have a revision/traffic-split model).
18+
Idle Jobs (no currently-running Execution) are included.
19+
20+
GCP authentication uses Application Default Credentials. On a developer
21+
machine, run `gcloud auth application-default login`; in GCE/GKE/Cloud Run
22+
the metadata server / Workload Identity is used automatically. The caller
23+
needs at least `roles/run.viewer` on the target project.
24+
25+
Skip all filtering flags to report every service and every job in the given
26+
project + region. Use `--include` and/or `--include-regex` to snapshot only a
27+
subset, OR `--exclude` and/or `--exclude-regex` to omit a subset; include and
28+
exclude are mutually exclusive. Filters apply uniformly to both service and
29+
job names and are case-sensitive.
30+
31+
Currently a hidden, in-development command. Use --dry-run to inspect the payload without sending it to Kosli.
32+
33+
## Flags
34+
| Flag | Description |
35+
| :--- | :--- |
36+
| -D, --dry-run | [optional] Run in dry-run mode. When enabled, no data is sent to Kosli and the CLI exits with 0 exit code regardless of any errors. |
37+
| --exclude strings | [optional] The comma-separated list of Cloud Run service or job names to exclude. Can't be used together with --include or --include-regex. |
38+
| --exclude-regex strings | [optional] The comma-separated list of Cloud Run service or job name regex patterns to exclude. Can't be used together with --include or --include-regex. |
39+
| -h, --help | help for cloud-run |
40+
| --include strings | [optional] The comma-separated list of Cloud Run service or job names to snapshot. Can't be used together with --exclude or --exclude-regex. |
41+
| --include-regex strings | [optional] The comma-separated list of Cloud Run service or job name regex patterns to snapshot. Can't be used together with --exclude or --exclude-regex. |
42+
| --project string | [required] GCP project ID. |
43+
| --region string | [required] GCP region (e.g. europe-west1). |
44+
45+
46+
## Flags inherited from parent commands
47+
| Flag | Description |
48+
| :--- | :--- |
49+
| -a, --api-token string | The Kosli API token. |
50+
| -c, --config-file string | [optional] The Kosli config file path. (default "kosli") |
51+
| --debug | [optional] Print debug logs to stdout. A boolean flag [docs](/faq/#boolean-flags) (default false) |
52+
| -H, --host string | [defaulted] The Kosli endpoint. (default "https://app.kosli.com") |
53+
| --http-proxy http://proxy-server-ip:proxy-port | [optional] The HTTP proxy URL including protocol and port number. e.g. http://proxy-server-ip:proxy-port |
54+
| -r, --max-api-retries int | [defaulted] How many times should API calls be retried when the API host is not reachable. (default 3) |
55+
| --org string | The Kosli organization. |
56+
57+
58+
## Examples Use Cases
59+
60+
These examples all assume that the flags `--api-token`, `--org`, `--host`, (and `--flow`, `--trail` when required), are [set/provided](/getting_started/install/#assigning-flags-via-environment-variables).
61+
62+
<AccordionGroup>
63+
<Accordion title="report every Cloud Run service and job in a project + region">
64+
```shell
65+
kosli snapshot cloud-run yourEnvironmentName
66+
--project yourGCPProject
67+
--region yourGCPRegion
68+
69+
```
70+
</Accordion>
71+
<Accordion title="report only the named services and jobs">
72+
```shell
73+
kosli snapshot cloud-run yourEnvironmentName
74+
--project yourGCPProject
75+
--region yourGCPRegion
76+
--include hello-world,sandman-job
77+
78+
```
79+
</Accordion>
80+
<Accordion title="report everything except the kosli-reporter job (the Job that runs this command)">
81+
```shell
82+
kosli snapshot cloud-run yourEnvironmentName
83+
--project yourGCPProject
84+
--region yourGCPRegion
85+
--exclude kosli-reporter
86+
```
87+
</Accordion>
88+
</AccordionGroup>
89+

‎config/navigation.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,8 @@
8080
"group": "Reporting environments",
8181
"pages": [
8282
"tutorials/report_aws_envs",
83-
"tutorials/report_k8s_envs"
83+
"tutorials/report_k8s_envs",
84+
"tutorials/report_cloud_run_envs"
8485
]
8586
},
8687
{
@@ -370,6 +371,7 @@
370371
"group": "kosli snapshot",
371372
"pages": [
372373
"client_reference/kosli_snapshot_azure",
374+
"client_reference/kosli_snapshot_cloud-run",
373375
"client_reference/kosli_snapshot_docker",
374376
"client_reference/kosli_snapshot_ecs",
375377
"client_reference/kosli_snapshot_k8s",

‎getting_started/environments.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,12 +53,14 @@ Currently, the following environment types are supported:
5353
- AWS Lambda
5454
- AWS Elastic Container Service (ECS)
5555
- Azure Web Apps and Function Apps
56+
- Google Cloud Run (services and jobs)
5657

5758
You can report environment snapshots manually using the `kosli snapshot [...]` commands for testing. For production use, however, you would configure the reporting to happen automatically on regular intervals, e.g. via a cron job or scheduled CI job, or on certain events.
5859

5960
You can follow one of the tutorials below to setup automatic snapshot reporting for your environment:
6061
- [Kubernetes environment reporting](/tutorials/report_k8s_envs)
6162
- [AWS ECS/S3/Lambda environment reporting](/tutorials/report_aws_envs)
63+
- [Cloud Run environment reporting](/tutorials/report_cloud_run_envs)
6264

6365
### Snapshotting scopes
6466

@@ -72,6 +74,7 @@ Depending on the type of your environment, you can scope what to snapshot from t
7274
| docker (containers) | √ | | | | |
7375
| k8s (namespaces) | √ | √ | √ | √ | √ |
7476
| azure (functions and apps) | √ | | | | |
77+
| cloud-run (services and jobs) | √ | √ | √ | √ | √ |
7578

7679

7780
## Environment Compliance

‎tutorials/report_cloud_run_envs.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
title: "Report Cloud Run environments to Kosli"
3+
description: "Learn how to report running artifacts from a Google Cloud Run project and region to Kosli — using the CLI for a quick test or a scheduled Cloud Run Job for production."
4+
---
5+
6+
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.
7+
8+
There are two ways to do this:
9+
10+
- **Kosli CLI** — quick to run, suitable for testing only
11+
- **<Tooltip tip="A Cloud Run Job that runs the Kosli CLI image on a Cloud Scheduler cron, reporting the project's Cloud Run services and jobs to Kosli automatically.">Scheduled Cloud Run Job</Tooltip>** — runs the reporter inside GCP on a schedule for continuous, production-grade reporting
12+
13+
Follow the section that matches your needs.
14+
15+
## Prerequisites
16+
17+
* Have access to a Google Cloud project and region with Cloud Run resources.
18+
* [Create a Cloud Run Kosli environment](/getting_started/environments#create-an-environment) named `cloud-run-tutorial`.
19+
* [Get a Kosli API token](/getting_started/service-accounts).
20+
21+
## Report using Kosli CLI
22+
23+
This approach is suitable for testing only.
24+
25+
[Install Kosli CLI](/getting_started/install) if you have not done so, then authenticate to GCP with Application Default Credentials:
26+
27+
```shell
28+
gcloud auth application-default login
29+
```
30+
31+
Run the snapshot command:
32+
33+
```shell
34+
kosli snapshot cloud-run cloud-run-tutorial \
35+
--project <your-gcp-project> \
36+
--region <your-gcp-region> \
37+
--resolve-names \
38+
--api-token <your-api-token-here> \
39+
--org <your-kosli-org-name>
40+
```
41+
42+
`--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.
43+
44+
See [`kosli snapshot cloud-run`](/client_reference/kosli_snapshot_cloud-run) for the full flag reference.
45+
46+
## Report using a scheduled Cloud Run Job
47+
48+
For production, run the reporter inside GCP as a Cloud Run Job triggered by Cloud Scheduler.
49+
50+
<Steps>
51+
<Step title="Create a service account for the reporter">
52+
53+
```shell
54+
gcloud iam service-accounts create kosli-reporter \
55+
--display-name="Kosli reporter" \
56+
--project=<your-gcp-project>
57+
```
58+
59+
</Step>
60+
61+
<Step title="Grant the reporter project-level access to Cloud Run">
62+
63+
`roles/run.viewer` is the minimum needed to list services and jobs in the project.
64+
65+
```shell
66+
gcloud projects add-iam-policy-binding <your-gcp-project> \
67+
--member="serviceAccount:kosli-reporter@<your-gcp-project>.iam.gserviceaccount.com" \
68+
--role="roles/run.viewer"
69+
```
70+
71+
</Step>
72+
73+
<Step title="Store the Kosli API token in Secret Manager">
74+
75+
Create a secret and add your token as the first version:
76+
77+
```shell
78+
gcloud secrets create kosli-api-token \
79+
--replication-policy=automatic \
80+
--project=<your-gcp-project>
81+
82+
printf "<your-api-token-here>" | gcloud secrets versions add kosli-api-token \
83+
--data-file=- \
84+
--project=<your-gcp-project>
85+
```
86+
87+
Grant the reporter service account read access to that specific secret:
88+
89+
```shell
90+
gcloud secrets add-iam-policy-binding kosli-api-token \
91+
--member="serviceAccount:kosli-reporter@<your-gcp-project>.iam.gserviceaccount.com" \
92+
--role="roles/secretmanager.secretAccessor" \
93+
--project=<your-gcp-project>
94+
```
95+
96+
</Step>
97+
98+
<Step title="Grant Artifact Registry read access">
99+
100+
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.
101+
102+
```shell
103+
gcloud artifacts repositories add-iam-policy-binding <your-repo> \
104+
--location=<your-gcp-region> \
105+
--member="serviceAccount:kosli-reporter@<your-gcp-project>.iam.gserviceaccount.com" \
106+
--role="roles/artifactregistry.reader" \
107+
--project=<your-gcp-project>
108+
```
109+
110+
Repeat the command for every Artifact Registry repository that holds images deployed to Cloud Run in this project.
111+
112+
<Note>
113+
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.
114+
</Note>
115+
116+
</Step>
117+
118+
<Step title="Deploy the reporter as a Cloud Run Job">
119+
120+
```shell
121+
gcloud run jobs deploy kosli-reporter \
122+
--image=ghcr.io/kosli-dev/cli:latest \
123+
--region=<your-gcp-region> \
124+
--project=<your-gcp-project> \
125+
--service-account=kosli-reporter@<your-gcp-project>.iam.gserviceaccount.com \
126+
--set-env-vars=KOSLI_ORG=<your-kosli-org-name>,KOSLI_HOST=https://app.kosli.com \
127+
--set-secrets=KOSLI_API_TOKEN=kosli-api-token:latest \
128+
--args=snapshot,cloud-run,cloud-run-tutorial,--project,<your-gcp-project>,--region,<your-gcp-region>,--resolve-names
129+
```
130+
131+
<Tip>
132+
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.
133+
</Tip>
134+
135+
</Step>
136+
137+
<Step title="Schedule the reporter with Cloud Scheduler">
138+
139+
Create a Cloud Scheduler job that triggers the Cloud Run Job every five minutes, and grant its service account permission to invoke the Job:
140+
141+
```shell
142+
gcloud scheduler jobs create http kosli-reporter-schedule \
143+
--location=<your-gcp-region> \
144+
--schedule="*/5 * * * *" \
145+
--uri="https://run.googleapis.com/v2/projects/<your-gcp-project>/locations/<your-gcp-region>/jobs/kosli-reporter:run" \
146+
--http-method=POST \
147+
--oauth-service-account-email=kosli-reporter@<your-gcp-project>.iam.gserviceaccount.com \
148+
--project=<your-gcp-project>
149+
150+
gcloud run jobs add-iam-policy-binding kosli-reporter \
151+
--region=<your-gcp-region> \
152+
--member="serviceAccount:kosli-reporter@<your-gcp-project>.iam.gserviceaccount.com" \
153+
--role="roles/run.invoker" \
154+
--project=<your-gcp-project>
155+
```
156+
157+
</Step>
158+
159+
<Step title="Verify the reporter">
160+
161+
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.
162+
163+
</Step>
164+
</Steps>
165+
166+
## What you've accomplished
167+
168+
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.
169+
170+
From here you can:
171+
* Query your environment with [`kosli list snapshots`](/client_reference/kosli_list_snapshots) and [`kosli get snapshot`](/client_reference/kosli_get_snapshot)
172+
* [Compare snapshots to see what changed](/client_reference/kosli_diff_snapshots)
173+
* Trace a running artifact back to its git commit with the [From commit to production](/tutorials/following_a_git_commit_to_runtime_environments) tutorial

0 commit comments

Comments
 (0)