From 30296c574982c8740afe11661a594679c82ffd5a Mon Sep 17 00:00:00 2001 From: Alex Kantor Date: Fri, 12 Jun 2026 09:59:46 +0100 Subject: [PATCH] fix: switch cyber-dojo tutorials to kosli search The "tracing a production incident" and "from commit to production" tutorials used 'kosli get artifact @' examples that no longer work: the cyber-dojo flows they reference (creator, runner) were renamed when archived, and the get-artifact endpoint rejects short fingerprints. 'kosli search' resolves short fingerprints and commit SHAs org-wide, including archived flows, so the walkthroughs work again. Refresh the documented command output to match what the CLI (v2.26.0) prints against prod today, and fix the artifact deep link that 404'd since the flow rename. Addresses kosli-dev/server#4937. Co-Authored-By: Claude Fable 5 --- ...ng_a_git_commit_to_runtime_environments.md | 92 ++++++++++--------- ...production_incident_back_to_git_commits.md | 44 +++++---- 2 files changed, 75 insertions(+), 61 deletions(-) diff --git a/tutorials/following_a_git_commit_to_runtime_environments.md b/tutorials/following_a_git_commit_to_runtime_environments.md index 6e604d7..1d94e65 100644 --- a/tutorials/following_a_git_commit_to_runtime_environments.md +++ b/tutorials/following_a_git_commit_to_runtime_environments.md @@ -4,7 +4,7 @@ description: "In this 5 minute tutorial you'll learn how Kosli tracks \"life aft --- We will follow an actual git commit from a CI pipeline all the way into production runtime environments. -By the end, you will have queried Kosli to see an artifact's full history — from creation through deployment to scaling and shutdown — without any access to the production environment. +By the end, you will have queried Kosli to see an artifact's history — from creation in CI through running in production to eventual shutdown — without any access to the production environment. We will use **cyber-dojo**, an open-source microservice platform whose Kosli data is public. The commit we follow fixed a misconfiguration: `runner` should run with three replicas but was accidentally running with one after a migration from GKE to ECS. @@ -38,56 +38,61 @@ kosli list flows You will see: ```plaintext -NAME DESCRIPTION VISIBILITY -creator UX for Group/Kata creation public -custom-start-points Custom exercises choices public -dashboard UX for a group practice dashboard public -differ Diff files from two traffic-lights public -exercises-start-points Exercises choices public -languages-start-points Language+TestFramework choices public -nginx Reverse proxy public -repler REPL for Python images public -runner Test runner public -saver Group/Kata model+persistence public -version-reporter UX for git+image version-reporter public -web UX for practicing TDD public +NAME DESCRIPTION VISIBILITY TAGS +creator-ci UX for Group/Kata creation private [ci=github], [repo_url=https://github.com/cyber-dojo/creator], [kind=build], [env=aws-beta] +custom-start-points-ci Custom exercises choices private [env=aws-beta], [ci=github], [repo_url=https://github.com/cyber-dojo/custom-start-points], [kind=build] +dashboard-ci UX for a group practice dashboard private [ci=github], [repo_url=https://github.com/cyber-dojo/dashboard], [kind=build], [env=aws-beta] +differ-ci Diff files from two traffic-lights private [env=aws-beta], [ci=github], [repo_url=https://github.com/cyber-dojo/differ], [kind=build] +differ-ci-tf Terraform human-readable plan and state file fingerprint private +docker-base-ci Build cyber-dojo/docker-base image private +exercises-start-points-ci Exercises choices private [ci=github], [repo_url=https://github.com/cyber-dojo/exercises-start-points], [kind=build], [env=aws-beta] +languages-start-points-ci Language+TestFramework choices private [ci=github], [repo_url=https://github.com/cyber-dojo/languages-start-points], [kind=build], [env=aws-beta] +nginx-ci Reverse proxy private [kind=build], [env=aws-beta], [ci=github], [repo_url=https://github.com/cyber-dojo/nginx] +production-promotion Promotes sets of Artifacts from aws-beta to aws-prod private [ci=github], [repo_url=https://github.com/cyber-dojo/aws-prod-co-promotion], [kind=release], [env=aws-prod] +production-server-access Flow to track production server access private +runner-ci Test runner private [ci=github], [repo_url=https://github.com/cyber-dojo/runner], [kind=build], [env=aws-beta] + +...some output elided... ``` ## Follow the artifact -The commit that fixed the replica count was [16d9990](https://github.com/cyber-dojo/runner/commit/16d9990ad23a40eecaf087abac2a58a2d2a4b3f4) in the `runner` repository. Fetch its full history from Kosli: +The commit that fixed the replica count was [16d9990](https://github.com/cyber-dojo/runner/commit/16d9990ad23a40eecaf087abac2a58a2d2a4b3f4) in the `runner` repository. Fetch its history from Kosli with `kosli search`, which accepts a git commit (full or short-form) or an artifact fingerprint: ```shell -kosli get artifact runner:16d9990 +kosli search 16d9990 ``` You will see: ```plaintext -Name: cyberdojo/runner:16d9990 -Flow: runner -Fingerprint: 9af401c4350b21e3f1df17d6ad808da43d9646e75b6da902cc7c492bcfb9c625 -Created on: Mon, 22 Aug 2022 11:35:00 CEST • 15 days ago -Git commit: 16d9990ad23a40eecaf087abac2a58a2d2a4b3f4 -Commit URL: https://github.com/cyber-dojo/runner/commit/16d9990ad23a40eecaf087abac2a58a2d2a4b3f4 -Build URL: https://github.com/cyber-dojo/runner/actions/runs/2902808452 -State: COMPLIANT +Search result resolved to commit 16d9990ad23a40eecaf087abac2a58a2d2a4b3f4 +Name: cyberdojo/runner:16d9990 +Fingerprint: 9af401c4350b21e3f1df17d6ad808da43d9646e75b6da902cc7c492bcfb9c625 +Has provenance: true +Flow: runner-archived-at-1709658802 +Git commit: 16d9990ad23a40eecaf087abac2a58a2d2a4b3f4 +Commit URL: https://github.com/cyber-dojo/runner/commit/16d9990ad23a40eecaf087abac2a58a2d2a4b3f4 +Build URL: https://github.com/cyber-dojo/runner/actions/runs/2902808452 +Artifact URL: https://app.kosli.com/cyber-dojo/flows/runner-archived-at-1709658802/artifacts/9af401c4350b21e3f1df17d6ad808da43d9646e75b6da902cc7c492bcfb9c625 +Compliance state: COMPLIANT +Running in: [ ] +Exited from: [ aws-beta, aws-prod ] History: - Artifact created Mon, 22 Aug 2022 11:35:00 CEST - branch-coverage evidence received Mon, 22 Aug 2022 11:36:02 CEST - Deployment #18 to aws-beta environment Mon, 22 Aug 2022 11:37:17 CEST - Deployment #19 to aws-prod environment Mon, 22 Aug 2022 11:38:21 CEST - Started running in aws-beta#84 environment Mon, 22 Aug 2022 11:38:28 CEST - Started running in aws-prod#65 environment Mon, 22 Aug 2022 11:39:22 CEST - Scaled down from 3 to 2 in aws-beta#117 environment Wed, 24 Aug 2022 18:03:42 CEST - No longer running in aws-beta#119 environment Wed, 24 Aug 2022 18:05:42 CEST - Scaled down from 3 to 1 in aws-prod#94 environment Wed, 24 Aug 2022 18:10:28 CEST - No longer running in aws-prod#96 environment Wed, 24 Aug 2022 18:12:28 CEST + Artifact created Mon, 22 Aug 2022 11:35:00 CEST + Started running in aws-beta#84 environment Mon, 22 Aug 2022 11:38:28 CEST + Started running in aws-prod#65 environment Mon, 22 Aug 2022 11:39:22 CEST + No longer running in aws-beta#119 environment Wed, 24 Aug 2022 18:05:42 CEST + No longer running in aws-prod#96 environment Wed, 24 Aug 2022 18:12:28 CEST ``` -The **History** shows the artifact's complete lifecycle: created by CI, evidence attested, deployed to both environments, running with the correct 3 replicas, then eventually scaled down and replaced by a newer version. The state `COMPLIANT` means all required evidence was provided before deployment. + +When this commit was made, the runner repository reported to a flow simply named `runner`. cyber-dojo's flows have since been reorganized (today the repository reports to `runner-ci`, as the flow list above shows) and the original flows archived. Archiving a flow currently renames it by appending `-archived-at-`, which is why the historical evidence displays the longer name. + + +The **History** shows the artifact's lifecycle: created by CI, running in both environments, and eventually replaced by a newer version. `Has provenance: true` means the artifact was reported to Kosli by a CI pipeline, so its build history is known. The compliance state `COMPLIANT` means all required evidence was provided before deployment. -The same information is available in the [Kosli web interface](https://app.kosli.com/cyber-dojo/flows/runner/artifacts/9af401c4350b21e3f1df17d6ad808da43d9646e75b6da902cc7c492bcfb9c625). +The same information is available in the [Kosli web interface](https://app.kosli.com/cyber-dojo/flows/runner-archived-at-1709658802/artifacts/9af401c4350b21e3f1df17d6ad808da43d9646e75b6da902cc7c492bcfb9c625). ## Inspect the environment snapshot @@ -100,19 +105,19 @@ kosli get snapshot aws-prod#65 The output will be: ```plaintext -COMMIT ARTIFACT FLOW RUNNING_SINCE REPLICAS -16d9990 Name: 274425519734.dkr.ecr.eu-central-1.amazonaws.com/runner:16d9990 runner 11 days ago 3 +COMMIT ARTIFACT FLOW COMPLIANCE RUNNING_SINCE REPLICAS +16d9990 Name: 274425519734.dkr.ecr.eu-central-1.amazonaws.com/runner:16d9990 runner-archived-at-1709658802 COMPLIANT 2022-08-22 3 Fingerprint: 9af401c4350b21e3f1df17d6ad808da43d9646e75b6da902cc7c492bcfb9c625 -7c45272 Name: 274425519734.dkr.ecr.eu-central-1.amazonaws.com/shas:7c45272 shas 11 days ago 1 +7c45272 Name: 274425519734.dkr.ecr.eu-central-1.amazonaws.com/shas:7c45272 shas-archived-at-1705491385 COMPLIANT 2022-08-22 1 Fingerprint: 76c442c04283c4ca1af22d882750eb960cf53c0aa041bbdb2db9df2f2c1282be ...some output elided... -85d83c6 Name: 274425519734.dkr.ecr.eu-central-1.amazonaws.com/runner:85d83c6 runner 13 days ago 1 +85d83c6 Name: 274425519734.dkr.ecr.eu-central-1.amazonaws.com/runner:85d83c6 runner-archived-at-1709658802 COMPLIANT 2022-08-20 1 Fingerprint: eeb0cfc9ee7f69fbd9531d5b8c1e8d22a8de119e2a422344a714a868e9a8bfec -1a2b170 Name: 274425519734.dkr.ecr.eu-central-1.amazonaws.com/differ:1a2b170 differ 13 days ago 1 +1a2b170 Name: 274425519734.dkr.ecr.eu-central-1.amazonaws.com/differ:1a2b170 differ-archived-at-1707630536 COMPLIANT 2022-08-20 1 Fingerprint: d8440b94f7f9174c180324ceafd4148360d9d7c916be2b910f132c58b8a943ae ``` @@ -133,9 +138,10 @@ Only present in aws-prod#65 Name: 274425519734.dkr.ecr.eu-central-1.amazonaws.com/runner:16d9990 Fingerprint: 9af401c4350b21e3f1df17d6ad808da43d9646e75b6da902cc7c492bcfb9c625 - Flow: runner + Flow: runner-archived-at-1709658802 Commit URL: https://github.com/cyber-dojo/runner/commit/16d9990ad23a40eecaf087abac2a58a2d2a4b3f4 - Started: Mon, 22 Aug 2022 11:39:17 CEST • 15 days ago + Started: Mon, 22 Aug 2022 11:39:17 CEST • 2022-08-22 + Instances: 3 ``` This confirms that `runner:16d9990` is the only new artifact in snapshot 65 — exactly the commit that fixed the replica count. diff --git a/tutorials/tracing_a_production_incident_back_to_git_commits.md b/tutorials/tracing_a_production_incident_back_to_git_commits.md index 672967d..aee9ae0 100644 --- a/tutorials/tracing_a_production_incident_back_to_git_commits.md +++ b/tutorials/tracing_a_production_incident_back_to_git_commits.md @@ -40,48 +40,56 @@ kosli log env aws-prod --interval 176..177 You should see: ```plaintext -SNAPSHOT EVENT FLOW DEPLOYMENTS -#177 Artifact: 274425519734.dkr.ecr.eu-central-1.amazonaws.com/creator:31dee35 creator #87 +SNAPSHOT EVENT FLOW +#177 Artifact: 274425519734.dkr.ecr.eu-central-1.amazonaws.com/creator:31dee35 creator-archived-at-1707630496 Fingerprint: 5d1c926530213dadd5c9fcbf59c8822da56e32a04b0f9c774d7cdde3cf6ba66d - Description: 1 instance stopped running (from 1 to 0). + Description: 1 instance stopped running (from 1 to 0) Reported at: Tue, 06 Sep 2022 16:53:28 CEST -#176 Artifact: 274425519734.dkr.ecr.eu-central-1.amazonaws.com/creator:b7a5908 creator #89 +#176 Artifact: 274425519734.dkr.ecr.eu-central-1.amazonaws.com/creator:b7a5908 creator-archived-at-1707630496 Fingerprint: 860ad172ace5aee03e6a1e3492a88b3315ecac2a899d4f159f43ca7314290d5a - Description: 1 instance started running (from 0 to 1). + Description: 1 instance started running (from 0 to 1) Reported at: Tue, 06 Sep 2022 16:52:28 CEST ``` + +When this incident happened the flow was simply named `creator`. The flow has since been archived, and archiving a flow currently renames it by appending `-archived-at-`. The historical evidence is unchanged; only the displayed name is longer. + + These two snapshots are part of the same blue-green deployment: `creator:b7a5908` started in snapshot #176, and `creator:31dee35` stopped in snapshot #177. The new artifact arrived just before the 500 error — that is the one to investigate. ## Dig into the artifact -Get the full history of `creator:b7a5908`, using the fingerprint prefix from snapshot #176: +Get the full history of `creator:b7a5908` with `kosli search`, using the fingerprint prefix from snapshot #176: ```shell -kosli get artifact creator@860ad17 +kosli search 860ad17 ``` You should see: ```plaintext -Name: cyberdojo/creator:b7a5908 -Flow: creator -Fingerprint: 860ad172ace5aee03e6a1e3492a88b3315ecac2a899d4f159f43ca7314290d5a -Created on: Tue, 06 Sep 2022 16:48:07 CEST • 21 hours ago -Git commit: b7a590836cf140e17da3f01eadd5eca17d9efc65 -Commit URL: https://github.com/cyber-dojo/creator/commit/b7a590836cf140e17da3f01eadd5eca17d9efc65 -Build URL: https://github.com/cyber-dojo/creator/actions/runs/3001102984 -State: COMPLIANT +Search result resolved to artifact with fingerprint 860ad172ace5aee03e6a1e3492a88b3315ecac2a899d4f159f43ca7314290d5a +Name: cyberdojo/creator:b7a5908 +Fingerprint: 860ad172ace5aee03e6a1e3492a88b3315ecac2a899d4f159f43ca7314290d5a +Has provenance: true +Flow: creator-archived-at-1707630496 +Git commit: b7a590836cf140e17da3f01eadd5eca17d9efc65 +Commit URL: https://github.com/cyber-dojo/creator/commit/b7a590836cf140e17da3f01eadd5eca17d9efc65 +Build URL: https://github.com/cyber-dojo/creator/actions/runs/3001102984 +Artifact URL: https://app.kosli.com/cyber-dojo/flows/creator-archived-at-1707630496/artifacts/860ad172ace5aee03e6a1e3492a88b3315ecac2a899d4f159f43ca7314290d5a +Compliance state: COMPLIANT +Running in: [ ] +Exited from: [ aws-beta, aws-prod ] History: Artifact created Tue, 06 Sep 2022 16:48:07 CEST - Deployment #88 to aws-beta environment Tue, 06 Sep 2022 16:49:59 CEST - Deployment #89 to aws-prod environment Tue, 06 Sep 2022 16:51:12 CEST Started running in aws-beta#196 environment Tue, 06 Sep 2022 16:51:42 CEST Started running in aws-prod#176 environment Tue, 06 Sep 2022 16:52:28 CEST + No longer running in aws-beta#199 environment Tue, 06 Sep 2022 21:28:42 CEST + No longer running in aws-prod#179 environment Tue, 06 Sep 2022 21:30:28 CEST ``` -The artifact was deployed to `aws-prod` at 16:51 — right when the incident began. The output includes a direct link to the git commit. +The artifact started running in `aws-prod` at 16:52 — right when the incident began. The output includes a direct link to the git commit. (You can also see the artifact exiting both environments later that evening, once the incident was fixed by a newer commit.) ## Follow to the commit