From 7476fa349ecff735f0689d6ccc18277720f4e7d1 Mon Sep 17 00:00:00 2001 From: Sami Alajrami Date: Fri, 16 Oct 2026 11:31:50 +0200 Subject: [PATCH 1/4] docs: explain how to exclude resources from Cloud Capture by tag The getting-started page said to tag a resource `kosli.capture=false`, which was the plan before cloud-capture#18 settled that customers choose their own tags in the Cloud Capture settings. The section now says where the tags are set, how they are matched (key and value, exactly), which resource they are read on (an ECS cluster with everything in it, a Lambda function on its own), when a change takes effect, and that the published IAM role already grants the permissions to read them; and it shows the settings API body for anyone scripting it. The overview's pointer to the section is reworded to match. Closes kosli-dev/cloud-capture#20 Co-Authored-By: Claude Fable 5.1 --- .../cloud_capture/getting_started.md | 40 ++++++++++++++++++- administration/cloud_capture/overview.md | 2 +- 2 files changed, 39 insertions(+), 3 deletions(-) diff --git a/administration/cloud_capture/getting_started.md b/administration/cloud_capture/getting_started.md index c4dccecd..bd87e4d7 100644 --- a/administration/cloud_capture/getting_started.md +++ b/administration/cloud_capture/getting_started.md @@ -45,7 +45,43 @@ When you have created the IAM role, using the CloudFormation template, you can a ### Excluding resources -If there are resources you do not wish to include within a Cloud Capture snapshot, for example an ECS cluster that you consider to be out of scope, you can add a tag to it indicating that the item should be skipped. Adding a tag with the name `kosli.capture` and the value `false` will ensure that Cloud Capture skips over that resource. +If there are resources you do not want Cloud Capture to snapshot, such as a test cluster or a service a vendor runs in your account, exclude them by tag. You choose the tags: in your organization's **Settings**, under **Cloud Capture**, the **Skip tags** panel takes any number of key and value pairs, and Cloud Capture skips every resource that carries one of them. + +1. Tag the resource in AWS, with any key and value you like. For example, to tag an ECS cluster and a Lambda function with `kosli-capture=false`: + + ```bash + aws ecs tag-resource \ + --resource-arn arn:aws:ecs:eu-west-1:123456789012:cluster/sandbox \ + --tags key=kosli-capture,value=false + + aws lambda tag-resource \ + --resource arn:aws:lambda:eu-west-1:123456789012:function:scratch \ + --tags kosli-capture=false + ``` + +2. In the **Skip tags** panel, enter the key `kosli-capture` and the value `false`, select **Add**, then **Save**. + +How the tags are matched: + +- A resource is skipped when any one of its tags equals any one of the skip tags, key and value both, exactly as AWS stores them. Tags are case-sensitive, so `Env=test` does not match `env=test`. A key on its own does not match: to skip both `env=test` and `env=staging`, add both. +- The tag is read on the resource Cloud Capture snapshots. An ECS cluster is skipped with everything in it, its services and tasks included; tags on a service or a task definition are not read. A Lambda function is skipped on its own, and the region's Lambda environment in Kosli is made up of the functions that remain. +- The change takes effect on the next scheduled run. A Kosli environment that was already being captured keeps its last snapshot and receives no new ones; nothing is deleted. Remove the tag, or the skip tag, and the next run picks the resource up again. +- Skip tags, like the other Cloud Capture settings, can only be changed while Cloud Capture is enabled. +- The IAM role created by the CloudFormation template already grants the permissions needed to read tags, `ecs:DescribeClusters` and `lambda:ListTags`, so no change to the role is needed. + +Skip tags can also be set through the API, as part of the organization's Cloud Capture settings. The settings are replaced whole on each write, so send them all: + +```bash +curl -X PUT "https://app.kosli.com/api/v2/cloud-capture//settings" \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "enabled": true, + "default_regions": {"aws": ["eu-west-1"]}, + "scan_interval_minutes": 5, + "skip_tags": {"aws": [{"key": "kosli-capture", "value": "false"}]} + }' +``` @@ -69,7 +105,7 @@ When you have created the role and added the account details to Kosli, you can a ### Excluding resources -Support for excluding resources is coming soon. +Excluding resources by label is coming with GCP support. diff --git a/administration/cloud_capture/overview.md b/administration/cloud_capture/overview.md index 06b4c211..29d4ace2 100644 --- a/administration/cloud_capture/overview.md +++ b/administration/cloud_capture/overview.md @@ -41,7 +41,7 @@ Cloud Capture has been designed to operate with no on-going support from you. O Cloud Capture finds all supported resources within your AWS accounts, and determines which Kosli environment should hold the snapshots. Cloud Capture will create physical environments for you inside Kosli. -Cloud Capture can [filter out resources based on AWS tags](/administration/cloud_capture/getting_started#excluding-resources). +You can keep a resource out of Cloud Capture by tagging it with any tag you have listed in your Cloud Capture settings; see [Excluding resources](/administration/cloud_capture/getting_started#excluding-resources). As your cloud environment evolves, such as the addition of new AWS ECS clusters or the retirement of existing Lambdas, Cloud Capture automatically detects the changes. Because Cloud Capture creates physical environments as needed, when your infrastructure changes, Kosli will keep up. No changes to the configuration created during the initial setup are required. From e3cbb8d196111fa49aedff107fbabb7005a13c98 Mon Sep 17 00:00:00 2001 From: Sami Alajrami Date: Fri, 16 Oct 2026 11:41:19 +0200 Subject: [PATCH 2/4] docs: document the scan frequency and start the API example from stored settings The settings PUT replaces every setting, so the skip-tags API example now tells the reader to read the current configuration and send the other settings back unchanged, as the doc review pointed out a copied example would otherwise reset their regions and interval. Both tabs said Cloud Capture "runs on a five-minute schedule". It does by default, and an admin can now pick another interval on the settings page, so a Scan frequency section explains where, which presets are offered, what the interval means for what Kosli sees, and the API field. Co-Authored-By: Claude Fable 5.1 --- .../cloud_capture/getting_started.md | 21 +++++++++++++++---- administration/cloud_capture/overview.md | 2 +- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/administration/cloud_capture/getting_started.md b/administration/cloud_capture/getting_started.md index bd87e4d7..25a86004 100644 --- a/administration/cloud_capture/getting_started.md +++ b/administration/cloud_capture/getting_started.md @@ -41,7 +41,7 @@ When used, the CloudFormation template will send your AWS account id to Kosli, s ### Enable Cloud Capture -When you have created the IAM role, using the CloudFormation template, you can activate Cloud Capture within the Kosli user-interface. Cloud Capture runs on a five-minute schedule, and once you have enabled it, Cloud Capture will pick up your environment the next time it runs - you should see environments and snapshots appearing within a few minutes. +When you have created the IAM role, using the CloudFormation template, you can activate Cloud Capture within the Kosli user-interface. Cloud Capture scans every five minutes unless you [choose another frequency](#scan-frequency), and once you have enabled it, Cloud Capture will pick up your environment the next time it runs - you should see environments and snapshots appearing within a few minutes. ### Excluding resources @@ -65,13 +65,16 @@ How the tags are matched: - A resource is skipped when any one of its tags equals any one of the skip tags, key and value both, exactly as AWS stores them. Tags are case-sensitive, so `Env=test` does not match `env=test`. A key on its own does not match: to skip both `env=test` and `env=staging`, add both. - The tag is read on the resource Cloud Capture snapshots. An ECS cluster is skipped with everything in it, its services and tasks included; tags on a service or a task definition are not read. A Lambda function is skipped on its own, and the region's Lambda environment in Kosli is made up of the functions that remain. -- The change takes effect on the next scheduled run. A Kosli environment that was already being captured keeps its last snapshot and receives no new ones; nothing is deleted. Remove the tag, or the skip tag, and the next run picks the resource up again. +- The change takes effect on the next scan. A Kosli environment that was already being captured keeps its last snapshot and receives no new ones; nothing is deleted. Remove the tag, or the skip tag, and the next run picks the resource up again. - Skip tags, like the other Cloud Capture settings, can only be changed while Cloud Capture is enabled. - The IAM role created by the CloudFormation template already grants the permissions needed to read tags, `ecs:DescribeClusters` and `lambda:ListTags`, so no change to the role is needed. -Skip tags can also be set through the API, as part of the organization's Cloud Capture settings. The settings are replaced whole on each write, so send them all: +Skip tags can also be set through the API, as part of the organization's Cloud Capture settings. The settings PUT replaces every setting, not only the one you are changing, so start from what is stored: read the current configuration, take the `enabled`, `default_regions`, `scan_interval_minutes` and `skip_tags` values from its `settings` object, add your tags to `skip_tags`, and send those four fields back. Sending the example below as it stands would also set your default regions and scan interval to the values shown. ```bash +curl "https://app.kosli.com/api/v2/cloud-capture/" \ + -H "Authorization: Bearer " + curl -X PUT "https://app.kosli.com/api/v2/cloud-capture//settings" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ @@ -101,7 +104,7 @@ GCP has no equivalent of the CloudFormation "phone-home" feature, so the Terrafo ### Enable Cloud Capture -When you have created the role and added the account details to Kosli, you can activate Cloud Capture within the Kosli user-interface. Cloud Capture runs on a five-minute schedule, and once you have enabled it, Cloud Capture will pick up your environment the next time it runs - you should see environments and snapshots appearing within a few minutes. +When you have created the role and added the account details to Kosli, you can activate Cloud Capture within the Kosli user-interface. Cloud Capture scans every five minutes unless you [choose another frequency](#scan-frequency), and once you have enabled it, Cloud Capture will pick up your environment the next time it runs - you should see environments and snapshots appearing within a few minutes. ### Excluding resources @@ -109,3 +112,13 @@ Excluding resources by label is coming with GCP support. +## Scan frequency + +Cloud Capture scans your registered accounts every five minutes unless you choose otherwise. The frequency is a setting of your Kosli organization, so it applies to every account and region Cloud Capture scans for you. + +To change it, open your organization's **Settings**, go to **Cloud Capture**, and under **Scan frequency** pick an interval from the list: every 5, 10, 15 or 30 minutes, or every 1, 2, 6, 12 or 24 hours. Select **Save**, and the next scan runs at the new interval; nothing restarts and no snapshots are lost. Like the other Cloud Capture settings, the frequency can only be changed while Cloud Capture is enabled. + +Each scan reports what is running in every environment Cloud Capture manages for you, and Kosli records a new snapshot when that differs from the last one. The interval is therefore how long a change can go unnoticed: a deployment that lands and is rolled back inside one interval may never be seen. Five minutes suits most teams; an estate that changes rarely can scan hourly. Scanning more often than every five minutes is available on request through Kosli's Customer Success team. + +Through the API, the frequency is `scan_interval_minutes` on the same settings resource as the skip tags above: a whole number of minutes from 5 to 1440 (a day), with 5 the value when it is left out. The PUT replaces every setting, so read the current configuration first and send the other settings back unchanged. + diff --git a/administration/cloud_capture/overview.md b/administration/cloud_capture/overview.md index 29d4ace2..13b98fa6 100644 --- a/administration/cloud_capture/overview.md +++ b/administration/cloud_capture/overview.md @@ -9,7 +9,7 @@ tag: "BETA" Cloud Capture is still in active development. Its capabilities and configuration format may change, and onboarding is done together with Kosli's Customer Success team. -Cloud Capture is a managed service that runs on Kosli's infrastructure and connects to your cloud platform to observe the resources deployed there. You grant Cloud Capture a set of permissions, and it uses them to run a `kosli snapshot` every few minutes against the infrastructure you have allowed it to scan. +Cloud Capture is a managed service that runs on Kosli's infrastructure and connects to your cloud platform to observe the resources deployed there. You grant Cloud Capture a set of permissions, and it uses them to run a `kosli snapshot` against the infrastructure you have allowed it to scan, every five minutes unless you [choose another frequency](/administration/cloud_capture/getting_started#scan-frequency). Kosli also supports reporting from your own cloud accounts by running the Kosli CLI on a schedule. Cloud Capture inverts this, with Kosli running the regular [snapshots](/getting_started/environments) so there is no software for you to install. From 73b9f41c3ea380abc715f7e583ff86603f93facc Mon Sep 17 00:00:00 2001 From: Sami Alajrami Date: Fri, 16 Oct 2026 11:43:43 +0200 Subject: [PATCH 3/4] docs: drop the offer of sub-five-minute scans on request Whether to offer a shorter interval, and to whom, is not a commitment the docs should make. Co-Authored-By: Claude Fable 5.1 --- administration/cloud_capture/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/administration/cloud_capture/getting_started.md b/administration/cloud_capture/getting_started.md index 25a86004..bfeec283 100644 --- a/administration/cloud_capture/getting_started.md +++ b/administration/cloud_capture/getting_started.md @@ -118,7 +118,7 @@ Cloud Capture scans your registered accounts every five minutes unless you choos To change it, open your organization's **Settings**, go to **Cloud Capture**, and under **Scan frequency** pick an interval from the list: every 5, 10, 15 or 30 minutes, or every 1, 2, 6, 12 or 24 hours. Select **Save**, and the next scan runs at the new interval; nothing restarts and no snapshots are lost. Like the other Cloud Capture settings, the frequency can only be changed while Cloud Capture is enabled. -Each scan reports what is running in every environment Cloud Capture manages for you, and Kosli records a new snapshot when that differs from the last one. The interval is therefore how long a change can go unnoticed: a deployment that lands and is rolled back inside one interval may never be seen. Five minutes suits most teams; an estate that changes rarely can scan hourly. Scanning more often than every five minutes is available on request through Kosli's Customer Success team. +Each scan reports what is running in every environment Cloud Capture manages for you, and Kosli records a new snapshot when that differs from the last one. The interval is therefore how long a change can go unnoticed: a deployment that lands and is rolled back inside one interval may never be seen. Five minutes suits most teams; an estate that changes rarely can scan hourly. Through the API, the frequency is `scan_interval_minutes` on the same settings resource as the skip tags above: a whole number of minutes from 5 to 1440 (a day), with 5 the value when it is left out. The PUT replaces every setting, so read the current configuration first and send the other settings back unchanged. From 5dc106509a383d8e36a1ba31f74c9bf56a572caa Mon Sep 17 00:00:00 2001 From: Sami Alajrami Date: Fri, 16 Oct 2026 11:45:32 +0200 Subject: [PATCH 4/4] docs: say the API takes any interval, not only the page's presets The page offers a short list of intervals; the API takes any whole number of minutes, and the page shows a non-preset value as its own option. The doc review read the two sentences as contradicting each other, so the API one now says which is the wider. Co-Authored-By: Claude Fable 5.1 --- administration/cloud_capture/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/administration/cloud_capture/getting_started.md b/administration/cloud_capture/getting_started.md index bfeec283..59b21ac8 100644 --- a/administration/cloud_capture/getting_started.md +++ b/administration/cloud_capture/getting_started.md @@ -120,5 +120,5 @@ To change it, open your organization's **Settings**, go to **Cloud Capture**, an Each scan reports what is running in every environment Cloud Capture manages for you, and Kosli records a new snapshot when that differs from the last one. The interval is therefore how long a change can go unnoticed: a deployment that lands and is rolled back inside one interval may never be seen. Five minutes suits most teams; an estate that changes rarely can scan hourly. -Through the API, the frequency is `scan_interval_minutes` on the same settings resource as the skip tags above: a whole number of minutes from 5 to 1440 (a day), with 5 the value when it is left out. The PUT replaces every setting, so read the current configuration first and send the other settings back unchanged. +Through the API, the frequency is `scan_interval_minutes` on the same settings resource as the skip tags above: any whole number of minutes from 5 to 1440 (a day), not only the presets the settings page offers, with 5 the value when it is left out. An interval set this way that is not one of the presets is shown on the settings page as its own option, so saving another setting there keeps it. The PUT replaces every setting, so read the current configuration first and send the other settings back unchanged.