Skip to content

Commit 30a9bce

Browse files
ToreMerkelyclaude
ToreMerkely
and
claude
authored
docs: add Cloud Run environment reporting tutorial (server/#4986) (#217)
- **docs: add Cloud Run environment reporting tutorial** - **docs: add scope pointer and deletion-protection note to Cloud Run tutorial** - **Updated text of what mind update does** --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 5bf8a23 commit 30a9bce

5 files changed

Lines changed: 275 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Other useful commands:
2020
```bash
2121
mint broken-links # Validate all internal links
2222
mint a11y # Check colour contrast and accessibility
23-
mint update # Update the CLI
23+
mint update # Update the mint CLI tool
2424
```
2525

2626
## Content

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