docs: add Cloud Run environment reporting tutorial (server/#4986)

README.md

@@ -20,7 +20,7 @@ Other useful commands:
 ```bash
 mint broken-links   # Validate all internal links
 mint a11y           # Check colour contrast and accessibility
-mint update         # Update the CLI
+mint update         # Update the mint CLI tool
 ```
 
 ## Content

client_reference/kosli_snapshot_cloud-run.md

@@ -0,0 +1,89 @@
+---
+title: "kosli snapshot cloud-run"
+beta: false
+deprecated: false
+description: "Report a snapshot of Cloud Run services and jobs in a Google Cloud project and region to Kosli.  "
+---
+
+## Synopsis
+
+```shell
+kosli snapshot cloud-run ENVIRONMENT-NAME [flags]
+```
+
+Report a snapshot of Cloud Run services and jobs in a Google Cloud project and region to Kosli.  
+Each Cloud Run service contributes one artifact per revision in its traffic
+configuration. Each Cloud Run Job contributes one artifact, identified by the
+image bound to the Job (Jobs do not have a revision/traffic-split model).
+Idle Jobs (no currently-running Execution) are included.
+
+GCP authentication uses Application Default Credentials. On a developer
+machine, run `gcloud auth application-default login`; in GCE/GKE/Cloud Run
+the metadata server / Workload Identity is used automatically. The caller
+needs at least `roles/run.viewer` on the target project.
+
+Skip all filtering flags to report every service and every job in the given
+project + region. Use `--include` and/or `--include-regex` to snapshot only a
+subset, OR `--exclude` and/or `--exclude-regex` to omit a subset; include and
+exclude are mutually exclusive. Filters apply uniformly to both service and
+job names and are case-sensitive.
+
+Currently a hidden, in-development command. Use --dry-run to inspect the payload without sending it to Kosli.
+
+## Flags
+| Flag | Description |
+| :--- | :--- |
+|    -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.  |
+|        --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.  |
+|        --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.  |
+|    -h, --help  |  help for cloud-run  |
+|        --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.  |
+|        --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.  |
+|        --project string  |  [required] GCP project ID.  |
+|        --region string  |  [required] GCP region (e.g. europe-west1).  |
+
+
+## Flags inherited from parent commands
+| Flag | Description |
+| :--- | :--- |
+|    -a, --api-token string  |  The Kosli API token.  |
+|    -c, --config-file string  |  [optional] The Kosli config file path. (default "kosli")  |
+|        --debug  |  [optional] Print debug logs to stdout. A boolean flag [docs](/faq/#boolean-flags) (default false)  |
+|    -H, --host string  |  [defaulted] The Kosli endpoint. (default "https://app.kosli.com")  |
+|        --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  |
+|    -r, --max-api-retries int  |  [defaulted] How many times should API calls be retried when the API host is not reachable. (default 3)  |
+|        --org string  |  The Kosli organization.  |
+
+
+## Examples Use Cases
+
+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). 
+
+<AccordionGroup>
+<Accordion title="report every Cloud Run service and job in a project + region">
+```shell
+kosli snapshot cloud-run yourEnvironmentName 
+	--project yourGCPProject 
+	--region yourGCPRegion 
+
+```
+</Accordion>
+<Accordion title="report only the named services and jobs">
+```shell
+kosli snapshot cloud-run yourEnvironmentName 
+	--project yourGCPProject 
+	--region yourGCPRegion 
+	--include hello-world,sandman-job 
+
+```
+</Accordion>
+<Accordion title="report everything except the kosli-reporter job (the Job that runs this command)">
+```shell
+kosli snapshot cloud-run yourEnvironmentName 
+	--project yourGCPProject 
+	--region yourGCPRegion 
+	--exclude kosli-reporter 
+```
+</Accordion>
+</AccordionGroup>
+

config/navigation.json

@@ -80,7 +80,8 @@
               "group": "Reporting environments",
               "pages": [
                 "tutorials/report_aws_envs",
-                "tutorials/report_k8s_envs"
+                "tutorials/report_k8s_envs",
+                "tutorials/report_cloud_run_envs"
               ]
             },
             {
@@ -370,6 +371,7 @@
               "group": "kosli snapshot",
               "pages": [
                 "client_reference/kosli_snapshot_azure",
+                "client_reference/kosli_snapshot_cloud-run",
                 "client_reference/kosli_snapshot_docker",
                 "client_reference/kosli_snapshot_ecs",
                 "client_reference/kosli_snapshot_k8s",

getting_started/environments.md

@@ -53,12 +53,14 @@ Currently, the following environment types are supported:
 - AWS Lambda
 - AWS Elastic Container Service (ECS)
 - Azure Web Apps and Function Apps
+- Google Cloud Run (services and jobs)
 
 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.
 
 You can follow one of the tutorials below to setup automatic snapshot reporting for your environment:
 - [Kubernetes environment reporting](/tutorials/report_k8s_envs)
 - [AWS ECS/S3/Lambda environment reporting](/tutorials/report_aws_envs)
+- [Cloud Run environment reporting](/tutorials/report_cloud_run_envs)
 
 ### Snapshotting scopes
 
@@ -72,6 +74,7 @@ Depending on the type of your environment, you can scope what to snapshot from t
 | docker (containers)        |       √       |                    |                    |                  |                  |
 | k8s (namespaces)           |       √       |          √         |          √         |         √        |         √        |
 | azure (functions and apps) |       √       |                    |                    |                  |                  |
+| cloud-run (services and jobs) |    √       |          √         |          √         |         √        |         √        |
 
 
 ## Environment Compliance

tutorials/report_cloud_run_envs.md

@@ -0,0 +1,179 @@
+---
+title: "Report Cloud Run environments to Kosli"
+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."
+---
+
+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`](/client_reference/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
+- **<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
+
+Follow the section that matches your needs.
+
+## Prerequisites
+
+* Have access to a Google Cloud project and region with Cloud Run resources.
+* [Create a Cloud Run Kosli environment](/getting_started/environments#create-an-environment) named `cloud-run-tutorial`.
+* [Get a Kosli API token](/getting_started/service-accounts).
+
+## Report using Kosli CLI
+
+This approach is suitable for testing only.
+
+[Install Kosli CLI](/getting_started/install) if you have not done so, then authenticate to GCP with Application Default Credentials:
+
+```shell
+gcloud auth application-default login
+```
+
+Run the snapshot command:
+
+```shell
+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`](/client_reference/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.
+
+<Steps>
+<Step title="Create a service account for the reporter">
+
+```shell
+gcloud iam service-accounts create kosli-reporter \
+    --display-name="Kosli reporter" \
+    --project=<your-gcp-project>
+```
+
+</Step>
+
+<Step title="Grant the reporter project-level access to Cloud Run">
+
+`roles/run.viewer` is the minimum needed to list services and jobs in the project.
+
+```shell
+gcloud projects add-iam-policy-binding <your-gcp-project> \
+    --member="serviceAccount:kosli-reporter@<your-gcp-project>.iam.gserviceaccount.com" \
+    --role="roles/run.viewer"
+```
+
+</Step>
+
+<Step title="Store the Kosli API token in Secret Manager">
+
+Create a secret and add your token as the first version:
+
+```shell
+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:
+
+```shell
+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>
+```
+
+</Step>
+
+<Step title="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.
+
+```shell
+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.
+
+<Note>
+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.
+</Note>
+
+</Step>
+
+<Step title="Deploy the reporter as a Cloud Run Job">
+
+```shell
+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
+```
+
+<Tip>
+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.
+</Tip>
+
+<Note>
+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.
+</Note>
+
+</Step>
+
+<Step title="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:
+
+```shell
+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>
+```
+
+</Step>
+
+<Step title="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.
+
+</Step>
+</Steps>
+
+## 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:
+* Query your environment with [`kosli list snapshots`](/client_reference/kosli_list_snapshots) and [`kosli get snapshot`](/client_reference/kosli_get_snapshot)
+* [Compare snapshots to see what changed](/client_reference/kosli_diff_snapshots)
+* Trace a running artifact back to its git commit with the [From commit to production](/tutorials/following_a_git_commit_to_runtime_environments) tutorial