DO NOT MERGE: Kosli Capture drop-in AWS snapshotting tutorial#337
Draft
mintlify[bot] wants to merge 1 commit into
Draft
DO NOT MERGE: Kosli Capture drop-in AWS snapshotting tutorial#337mintlify[bot] wants to merge 1 commit into
mintlify[bot] wants to merge 1 commit into
Conversation
Contributor
|
Claude finished @mintlify[bot]'s task in 2m 55s —— View job PR Review: Kosli Capture AWS Snapshotting Tutorial
SummarySolid first draft of the Kosli Capture tutorial. The page is well-written, technically detailed, and covers the full lifecycle (deploy → configure → verify → caveats). Navigation entry is correct, all internal links resolve, no relative links, and writing style is consistent with the repo conventions. 4 inline comments posted on the tutorial file — see the Files changed tab for details. FindingsCriticalNone. Improvement
Suggestion
Checklist passed
Overall assessmentThe tutorial is well-structured and provides good coverage of Kosli Capture. The main structural suggestion — splitting the config reference from the tutorial flow — would strengthen both the tutorial (tighter focus) and the config docs (independently discoverable). All other findings are minor style suggestions. No blockers. |
Contributor
Author
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| --- | ||
| title: "Snapshotting AWS runtimes with Kosli Capture" | ||
| description: "Drop a single stack into an AWS account and have Kosli Capture discover ECS, EKS, Lambda, and tagged S3 buckets, auto-create Kosli environments, and snapshot them on a schedule." | ||
| --- |
Contributor
There was a problem hiding this comment.
Suggestion: The description is ~200 characters — longer than most pages in this repo. Consider trimming to one focused sentence, e.g.:
Suggested change
| --- | |
| description: "Deploy Kosli Capture into an AWS account to auto-discover and snapshot ECS, EKS, Lambda, and S3 resources into Kosli." |
Comment on lines
+92
to
+173
|
|
||
| `config.yaml` at the repo root defines the policy Kosli Capture applies. It has three parts: **naming**, **scope**, and **types**. | ||
|
|
||
| ### Naming | ||
|
|
||
| ```yaml | ||
| naming: | ||
| prefix: aws-prod # global default; omitted -> aws-{account_id} | ||
| template: "{prefix}-{type}-{name}" # placeholders: {prefix} {account_id} {region} {type} {name} | ||
| prefix_tag: "kosli:prefix" # per-resource {prefix} override | ||
| name_tag: "kosli:env-name" # per-resource full env-name override (escape hatch) | ||
| ``` | ||
|
|
||
| The env name for each resource is resolved through a single precedence chain, used for whole resources and namespace slices alike: | ||
|
|
||
| | Precedence | Where | Behavior | | ||
| |------------|----------------------------------------------------|-----------------------------------------------------------------------------| | ||
| | 1 | Explicit env name (config, EKS `namespaces` map) | Wins outright | | ||
| | 2 | `kosli:env-name` tag on the resource | Whole resource → that name; sliced cluster → `<value>-<ns>` | | ||
| | 3 | Template | `{prefix}-{type}-{name}`; slices append `-<ns>` to `{name}` | | ||
|
|
||
| Within the template, `{prefix}` itself resolves: `kosli:prefix` tag on the resource → `types.<type>.prefix` → `naming.prefix` → `aws-{account_id}`. Keep `{type}` in the template — env names are unique per Kosli org and a bucket can share a name with a cluster. | ||
|
|
||
| ### Scope and tag filters | ||
|
|
||
| Every type block accepts the same tag-filter fields, combined with the global `scope`: | ||
|
|
||
| - **include** = global ∪ per-type pairs; a resource must match **all** of them (empty = opt-out mode: everything unless excluded). | ||
| - **exclude** = global ∪ per-type pairs; matching **any** pair excludes the resource. | ||
|
|
||
| ```yaml | ||
| scope: | ||
| regions: [] # empty = the Lambda's own region only | ||
| include_tags: {} # empty = opt-out mode | ||
| exclude_tags: | ||
| kosli:ignore: "true" # anything tagged kosli:ignore=true is skipped | ||
| ``` | ||
|
|
||
| Multi-region deployments list every region in `scope.regions`. When you scan multiple regions, add `{region}` to `naming.template` so each region gets its own env — a Kosli env holds one full-state snapshot, so overwriting the same name from different regions would clobber it each run. | ||
|
|
||
| ### Per-type toggles | ||
|
|
||
| ```yaml | ||
| types: | ||
| ecs: | ||
| enabled: true | ||
|
|
||
| eks: | ||
| enabled: true | ||
| include_scaling: true # capture replica-count changes as new snapshots | ||
|
|
||
| lambda: | ||
| enabled: true | ||
| granularity: account # account = one env per resolved prefix; function = env per function | ||
|
|
||
| s3: | ||
| enabled: true | ||
| include_tags: | ||
| kosli:track: "true" # S3 is opt-in — see below | ||
| ``` | ||
|
|
||
| **S3 is intentionally opt-in.** A Kosli `s3` environment fingerprints bucket **content** (for deployment tracking), not a bucket inventory. Most accounts have many buckets that are not deployment artifacts — Terraform state buckets, CloudFormation staging buckets, log buckets. Snapshotting all of them would be noise. `types.s3.include_tags` must therefore be non-empty; otherwise Kosli Capture records a gap and skips S3 entirely. | ||
|
|
||
| ### Grouping Lambdas or ECS clusters by tag | ||
|
|
||
| Sometimes several Lambda functions or ECS clusters should be reported into the **same** Kosli environment — for example, all the Lambdas that make up one application. Use `grouping` to map an exact env name to a set of tag pairs: | ||
|
|
||
| ```yaml | ||
| types: | ||
| lambda: | ||
| grouping: | ||
| aws-prod-payments: { team: payments } | ||
| aws-prod-checkout: { team: checkout, tier: prod } # multiple pairs = AND | ||
|
|
||
| ecs: | ||
| grouping: | ||
| aws-prod-platform: { team: platform } | ||
| ``` | ||
|
|
||
| Resources matching **all** pairs of an entry are reported together in one snapshot call (`snapshot lambda --function-names a,b,c` / `snapshot ecs --clusters a,b,c`). Unmatched resources fall through to the default behavior — Lambda's `granularity`, ECS's per-cluster env — unchanged. The first matching entry wins, and an entry with no tags never matches, so a typo cannot sweep in everything. | ||
|
|
||
| Grouping is only offered where the snapshot command reports a set in one call. S3 (`--bucket` is a single bucket) and per-cluster EKS have no such flag, so grouping does not apply to them — pointing several of those at one env name would just overwrite it each run. |
Contributor
There was a problem hiding this comment.
Improvement (Diátaxis): This 80-line config block (naming, scope, per-type toggles, grouping, EKS namespaces) reads as reference material rather than tutorial steps. In the Diátaxis model, a tutorial walks the reader through one concrete scenario; detailed option docs belong in a reference page.
Consider either:
- Trim for the tutorial path: show a minimal
config.yamlwith one customization (e.g. setting a prefix + enabling ECS only), then link out to a separate config reference page for the full option set. - Split the page: keep the deploy + verify flow here as a tutorial; extract the config documentation into
understand_kosli/kosli_capture_configor similar, and cross-link.
This would keep the tutorial focused and make the config details independently findable. Not blocking — the current form is usable — but it would improve both pages.
|
|
||
| [Kosli Capture](https://github.com/kosli-dev/kosli-capture) is a single deployable that sits **inside your AWS account**, discovers the resources you already run, and reports them to Kosli as environment snapshots — with no per-cluster reporter to install, no environments to pre-create, and no inventory list to maintain in config. | ||
|
|
||
| It exists to shorten the runtime-side onboarding story. Getting build and release evidence into Kosli is usually straightforward — you own the pipeline. The runtime side is where most of the friction lives: reporters to deploy into every cluster, environments to create by hand, networking approvals for each workload. Kosli Capture flips that: one stack per account, tags decide what is in scope, and Kosli environments are created on first sight. |
Contributor
There was a problem hiding this comment.
Suggestion: "onboarding story" is a bit vague. Consider something more concrete:
Suggested change
| It exists to shorten the runtime-side onboarding story. Getting build and release evidence into Kosli is usually straightforward — you own the pipeline. The runtime side is where most of the friction lives: reporters to deploy into every cluster, environments to create by hand, networking approvals for each workload. Kosli Capture flips that: one stack per account, tags decide what is in scope, and Kosli environments are created on first sight. | |
| It exists to shorten runtime-side onboarding. Getting build and release evidence into Kosli is usually straightforward — you own the pipeline. The runtime side is where most of the friction lives: reporters to deploy into every cluster, environments to create by hand, networking approvals for each workload. Kosli Capture flips that: one stack per account, tags decide what is in scope, and Kosli environments are created on first sight. |
| The region is pinned end-to-end: the Terraform provider, state bucket, CloudFormation stack, and ECR registry all use the same `REGION` value. Override everything at once with `make deploy REGION=<other-region>`. An ambient `AWS_REGION` cannot silently steer the deploy into a different region. | ||
| </Tip> | ||
|
|
||
| Once the first run completes (every two minutes by default), you should see Kosli environments appear in the [Kosli app](https://app.kosli.com) under **Environments**, named according to the template in `config.yaml`. |
Contributor
There was a problem hiding this comment.
Suggestion: "you should see" is slightly passive for a tutorial. Consider imperative mood per the style guide:
Suggested change
| Once the first run completes (every two minutes by default), you should see Kosli environments appear in the [Kosli app](https://app.kosli.com) under **Environments**, named according to the template in `config.yaml`. | |
| Once the first run completes (every two minutes by default), check the [Kosli app](https://app.kosli.com) under **Environments** — you will see Kosli environments named according to the template in `config.yaml`. |
Contributor
Author
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a new tutorial page walking through how to use kosli-dev/kosli-capture as a drop-in to start snapshotting AWS runtime environments (ECS, EKS, Lambda, tagged S3) into Kosli quickly.
Structured after
tutorials/working_with_controls.mdx:Sourced from:
Added to nav under Reporting environments alongside the existing per-resource reporter tutorial.
Draft / do-not-merge as requested — this is for review with the team and a couple of customers first.
Generated by Mintlify Agent.
Requested by: marko@kosli.com via Slack
Mintlify session: slack_1778705097.340389_D0ALT8RK1CJ