diff --git a/README.md b/README.md index 9cc9a44..619f14a 100644 --- a/README.md +++ b/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 diff --git a/client_reference/kosli_snapshot_cloud-run.md b/client_reference/kosli_snapshot_cloud-run.md new file mode 100644 index 0000000..36a6617 --- /dev/null +++ b/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). + + + +```shell +kosli snapshot cloud-run yourEnvironmentName + --project yourGCPProject + --region yourGCPRegion + +``` + + +```shell +kosli snapshot cloud-run yourEnvironmentName + --project yourGCPProject + --region yourGCPRegion + --include hello-world,sandman-job + +``` + + +```shell +kosli snapshot cloud-run yourEnvironmentName + --project yourGCPProject + --region yourGCPRegion + --exclude kosli-reporter +``` + + + diff --git a/config/navigation.json b/config/navigation.json index 343227a..bc105ac 100644 --- a/config/navigation.json +++ b/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", diff --git a/getting_started/environments.md b/getting_started/environments.md index dc4a5b3..ed8723f 100644 --- a/getting_started/environments.md +++ b/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 diff --git a/tutorials/report_cloud_run_envs.md b/tutorials/report_cloud_run_envs.md new file mode 100644 index 0000000..331e9eb --- /dev/null +++ b/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 +- **Scheduled Cloud Run Job** — 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 \ + --region \ + --resolve-names \ + --api-token \ + --org +``` + +`--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. + + + + +```shell +gcloud iam service-accounts create kosli-reporter \ + --display-name="Kosli reporter" \ + --project= +``` + + + + + +`roles/run.viewer` is the minimum needed to list services and jobs in the project. + +```shell +gcloud projects add-iam-policy-binding \ + --member="serviceAccount:kosli-reporter@.iam.gserviceaccount.com" \ + --role="roles/run.viewer" +``` + + + + + +Create a secret and add your token as the first version: + +```shell +gcloud secrets create kosli-api-token \ + --replication-policy=automatic \ + --project= + +printf "" | gcloud secrets versions add kosli-api-token \ + --data-file=- \ + --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@.iam.gserviceaccount.com" \ + --role="roles/secretmanager.secretAccessor" \ + --project= +``` + + + + + +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 \ + --location= \ + --member="serviceAccount:kosli-reporter@.iam.gserviceaccount.com" \ + --role="roles/artifactregistry.reader" \ + --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. + + + + + + +```shell +gcloud run jobs deploy kosli-reporter \ + --image=ghcr.io/kosli-dev/cli:latest \ + --region= \ + --project= \ + --service-account=kosli-reporter@.iam.gserviceaccount.com \ + --set-env-vars=KOSLI_ORG=,KOSLI_HOST=https://app.kosli.com \ + --set-secrets=KOSLI_API_TOKEN=kosli-api-token:latest \ + --args=snapshot,cloud-run,cloud-run-tutorial,--project,,--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=`) before you can delete or replace the Job later. + + + + + + +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= \ + --schedule="*/5 * * * *" \ + --uri="https://run.googleapis.com/v2/projects//locations//jobs/kosli-reporter:run" \ + --http-method=POST \ + --oauth-service-account-email=kosli-reporter@.iam.gserviceaccount.com \ + --project= + +gcloud run jobs add-iam-policy-binding kosli-reporter \ + --region= \ + --member="serviceAccount:kosli-reporter@.iam.gserviceaccount.com" \ + --role="roles/run.invoker" \ + --project= +``` + + + + + +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: +* 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