feat: add docs for Kosli Capture Managed Service

administration/kosli_capture/getting_started.md

@@ -0,0 +1,69 @@
+---
+title: "Getting started with Kosli Capture"
+sidebarTitle: "Getting started"
+description: "Learn how to configure Kosli Capture for your organization"
+tag: "BETA"
+---
+
+<Warning>
+Kosli Capture is still in active development. Its capabilities and configuration format may change, and onboarding is done together with Kosli's Customer Success team.
+</Warning>
+
+Kosli Capture is a managed service that runs on Kosli's infrastructure and connects to your cloud platform to observe the resources deployed there. To get set up with Kosli Capture you need to grant permissions to Kosli's cloud account and enable Kosli Capture within your Kosli org.
+
+## Overview
+
+Getting started with Kosli Capture involves two steps.
+
+<Steps>
+  <Step title="Prepare your environment">
+    Create an IAM role in your cloud accounts specifically for Kosli Capture.
+  </Step>
+  <Step title="Enable Kosli Capture">
+    Enable Kosli Capture for your Kosli org, and the regular snapshots will appear in Kosli.
+  </Step>
+</Steps>
+
+<Tabs>
+<Tab title="AWS">
+
+## Prepare your environment
+
+In order for Kosli Capture to reach into your AWS cloud, to discover your ECS clusters and Lambdas, you need to grant permission to Kosli to do so. This requires the creation of an IAM role that Kosli can assume; the role will exist within your AWS account.
+
+To simplify this process, Kosli has created a CloudFormation template that contains a role with the minimum set of permissions needed by Kosli Capture.  The role can be assumed by Kosli and is protected by an external Id; each organization within Kosli has its own external Id.  The CloudFormation template can be downloaded from the Settings page for your organization within the Kosli UI.
+
+If you would rather create the role yourself, see [Kosli Capture Security](/administration/kosli_capture/security) for the trust policy and the full set of permissions the role needs.
+
+The CloudFormation template can be deployed within an AWS account, or can be attached to an AWS Organizational Unit (OU) as a StackSet; this latter option ensures the correct IAM permissions are rolled out to all AWS accounts within the OU.
+
+When used, the CloudFormation template will send your AWS account id to Kosli, so that we are automatically notified that your account is ready to be included in Kosli Capture.  Similarly, if you delete the CloudFormation stack we will be notified and know that the account is no longer to be included.
+
+## Enable Kosli Capture
+
+When you have created the IAM role, using the CloudFormation template, you can activate Kosli Capture within the Kosli user-interface.  Kosli Capture runs on a five-minute schedule, and once you have enabled it, Kosli Capture will pick up your environment the next time it runs - you should see environments and snapshots appearing within a few minutes.
+
+## Excluding resources
+
+If there are resources you do not wish to include within a Kosli Capture Managed 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 Kosli Capture skips over that resource.
+</Tab>
+<Tab title="GCP">
+## Prepare your environment
+
+In order for Kosli Capture to reach into your GCP cloud, to discover your Kubernetes clusters, you need to grant permission to Kosli to do so.  This requires the creation of an IAM role that Kosli can assume; the role will exist within your Google Cloud account.
+
+To simplify this process, Kosli has created a Terraform configuration that contains a role with the minimum set of permissions needed by Kosli Capture.  The role can be used by Kosli and is protected by ensuring the `principalSet` supplied contains the specific Kosli Capture role that was created for your organization. The Terraform can be downloaded from the Settings page for your organization within the Kosli UI.
+
+If you would rather create the role yourself, see [Kosli Capture Security](/administration/kosli_capture/security) for the trust policy and the full set of permissions the role needs.
+When used, you need the CloudFormation template will send your AWS account id to Kosli, so that we are automatically notified that your account is ready to be included in Kosli Capture.  Similarly, if you delete the CloudFormation stack we will be notified and know that the account is no longer to be included.
+
+## Enable Kosli Capture
+
+When you have created the role and added the account details to Kosli, you can activate Kosli Capture within the Kosli user-interface.  Kosli Capture runs on a five-minute schedule, and once you have enabled it, Kosli Capture will pick up your environment the next time it runs - you should see environments and snapshots appearing within a few minutes.
+
+## Excluding resources
+
+If there are resources you do not wish to include within a Kosli Capture Managed snapshot, for example a specific 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 Kosli Capture skips over that resource.
+</Tab>
+</Tabs>
+

administration/kosli_capture/overview.md

@@ -0,0 +1,59 @@
+---
+title: "Kosli Capture Managed Service"
+sidebarTitle: "Kosli Capture"
+description: "Learn how the Kosli Capture Managed Service snapshots your cloud environments from Kosli's infrastructure, with no software to install."
+tag: "BETA"
+---
+
+<Warning>
+Kosli Capture is still in active development. Its capabilities and configuration format may change, and onboarding is done together with Kosli's Customer Success team.
+</Warning>
+
+Kosli 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 Kosli 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.
+
+Kosli also supports reporting from your own cloud accounts by running the Kosli CLI on a schedule. Kosli Capture inverts this, with Kosli running the regular [snapshots](/getting_started/environments) so there is no software for you to install.
+
+To set it up for your organization, see [Getting started with Kosli Capture](/administration/kosli_capture/getting_started).
+
+## Overview
+
+Kosli Capture connects to your cloud accounts using permissions that you manage.  You configure Kosli Capture by activating it for different services, and Kosli Capture uses the permissions to regularly reach into your estate and record snapshots, sending the data into your Kosli organization.  Kosli Capture uses details about your infrastructure, such as the name of an ECS cluster, to build environments within Kosli.
+
+<Frame>
+<img src="/images/administration/kosli-capture-overview.png" alt="Diagram showing Kosli Capture, inside Kosli, sending queries to and receiving snapshots from three customer cloud accounts, then passing the data to the Kosli API and database" />
+</Frame>
+
+## Security
+
+The security of your cloud infrastructure is the primary driver behind the internal architecture of
+Kosli Capture. You grant a read-only IAM role in your account, protected by an external ID that acts
+as a shared secret between Kosli and you. On Kosli's side, each Kosli Capture job runs under a role
+scoped to your organization alone, so a worker running for another customer cannot reach your cloud
+account. Kosli Capture holds no customer data; snapshots go straight to Kosli through the same ingest
+path as your existing pipelines. See [Kosli Capture Security](/administration/kosli_capture/security)
+for the isolation model and the full list of permissions.
+
+## Hands-off operation
+
+Kosli Capture has been designed to operate with no on-going support from you.  Once the initial security permissions have been created, Kosli Capture will continue to operate in a headless mode. As your cloud infrastructure changes over time, Kosli Capture will continue to find resources without you needing to do anything; your application teams do not need to take any action in order to onboard their products and services into Kosli.
+
+## Finding resources
+
+Kosli Capture finds all supported resources within your AWS accounts, and determines which Kosli environment should hold the snapshots. Kosli Capture will create physical environments for you inside Kosli.
+
+Kosli Capture can [filter out resources based on AWS tags](/administration/kosli_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, Kosli Capture automatically detects the changes. Because Kosli 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.
+
+## Multiple AWS accounts
+
+Kosli Capture can operate across multiple AWS regions and accounts, allowing you to snapshot development, QA, pre-production, and production workloads with the same process.
+
+## Operation
+
+When Kosli Capture runs against one of your cloud accounts, it starts by gaining temporary credentials for the role you have created. It then uses these credentials to find resources to snapshot, such as finding all of your AWS ECS clusters.  For each resource it identifies, Kosli Capture generates a snapshot within Kosli.
+
+<Frame>
+<img src="/images/administration/kosli-capture-4-steps.png" alt="Diagram of the four steps Kosli Capture follows in a customer AWS account: assume the IAM role using the external ID, receive temporary STS credentials, find the ECS clusters, then snapshot the clusters" />
+</Frame>
+