From b0605293de7e9a87e335b440d49ad1aeb9042313 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Mon, 16 Mar 2026 22:28:06 +0100 Subject: [PATCH 1/9] feat: add Terraform provider reference docs under Administration Adds 7 Mintlify pages converted from the terraform-provider-kosli source: provider index, 3 resources, and 3 data sources. Updates docs.json navigation with a new "Terraform Provider" group under Administration, and updates managing_environments/overview.md to link internally instead of to the Terraform Registry. --- .../managing_environments/overview.md | 8 +- .../data-sources/custom_attestation_type.mdx | 81 +++++++ .../terraform/data-sources/environment.mdx | 102 +++++++++ .../data-sources/logical_environment.mdx | 186 ++++++++++++++++ administration/terraform/index.mdx | 68 ++++++ .../resources/custom_attestation_type.mdx | 163 ++++++++++++++ .../terraform/resources/environment.mdx | 135 ++++++++++++ .../resources/logical_environment.mdx | 201 ++++++++++++++++++ docs.json | 22 ++ 9 files changed, 962 insertions(+), 4 deletions(-) create mode 100644 administration/terraform/data-sources/custom_attestation_type.mdx create mode 100644 administration/terraform/data-sources/environment.mdx create mode 100644 administration/terraform/data-sources/logical_environment.mdx create mode 100644 administration/terraform/index.mdx create mode 100644 administration/terraform/resources/custom_attestation_type.mdx create mode 100644 administration/terraform/resources/environment.mdx create mode 100644 administration/terraform/resources/logical_environment.mdx diff --git a/administration/managing_environments/overview.md b/administration/managing_environments/overview.md index e1311624..60e72310 100644 --- a/administration/managing_environments/overview.md +++ b/administration/managing_environments/overview.md @@ -107,7 +107,7 @@ terraform import kosli_logical_environment.production_all production-all ## Reference -- [`kosli_environment` resource](https://registry.terraform.io/providers/kosli-dev/kosli/latest/docs/resources/environment) -- [`kosli_environment` data source](https://registry.terraform.io/providers/kosli-dev/kosli/latest/docs/data-sources/environment) -- [`kosli_logical_environment` resource](https://registry.terraform.io/providers/kosli-dev/kosli/latest/docs/resources/logical_environment) -- [`kosli_logical_environment` data source](https://registry.terraform.io/providers/kosli-dev/kosli/latest/docs/data-sources/logical_environment) +- [`kosli_environment` resource](/administration/terraform/resources/environment) +- [`kosli_environment` data source](/administration/terraform/data-sources/environment) +- [`kosli_logical_environment` resource](/administration/terraform/resources/logical_environment) +- [`kosli_logical_environment` data source](/administration/terraform/data-sources/logical_environment) diff --git a/administration/terraform/data-sources/custom_attestation_type.mdx b/administration/terraform/data-sources/custom_attestation_type.mdx new file mode 100644 index 00000000..c0a810b8 --- /dev/null +++ b/administration/terraform/data-sources/custom_attestation_type.mdx @@ -0,0 +1,81 @@ +--- +title: "kosli_custom_attestation_type data source" +description: "Fetches details of an existing custom attestation type from Kosli. Custom attestation types define how Kosli validates and evaluates evidence from proprietary tools, custom metrics, or specialized compliance requirements." +icon: "database" +--- + +Fetches details of an existing custom attestation type from Kosli. Custom attestation types define how Kosli validates and evaluates evidence from proprietary tools, custom metrics, or specialized compliance requirements. + +Use this data source to retrieve information about an existing custom attestation type. This is useful for: + +- Referencing existing attestation types in other configurations +- Creating variants of existing types with modified rules +- Querying attestation type metadata and schemas + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Query an existing custom attestation type +data "kosli_custom_attestation_type" "security" { + name = "security-scan" +} + +# Use the queried schema in a new attestation type +resource "kosli_custom_attestation_type" "security_strict" { + name = "security-scan-strict" + description = "Stricter security requirements" + + # Reuse the schema from the existing type + schema = data.kosli_custom_attestation_type.security.schema + + # Apply stricter validation rules + jq_rules = [ + ".critical_vulnerabilities == 0", + ".high_vulnerabilities == 0", + ".medium_vulnerabilities < 3" + ] +} + +# Reference attestation type metadata +output "security_scan_description" { + description = "Description of the security scan attestation type" + value = data.kosli_custom_attestation_type.security.description +} + +output "security_scan_rules" { + description = "JQ rules for the security scan attestation type" + value = data.kosli_custom_attestation_type.security.jq_rules +} + +output "security_scan_archived" { + description = "Whether the security scan attestation type is archived" + value = data.kosli_custom_attestation_type.security.archived +} +``` + +## Querying archived types + +By default, the data source retrieves active (non-archived) attestation types. Archived types can be queried but are read-only and typically represent historical configurations. + +The `archived` attribute indicates whether an attestation type has been deleted/archived in Kosli. Archived types cannot be modified through Terraform. + +## Schema + +### Required + +- `name` (String) The name of the custom attestation type. Must start with a letter or number and contain only letters, numbers, periods, hyphens, underscores, and tildes. + +### Read-only + +- `archived` (Boolean) Whether this attestation type has been archived. +- `description` (String) A description of what this attestation type validates. +- `jq_rules` (List of String) List of jq expressions that define evaluation rules. All rules must evaluate to `true` for compliance. +- `schema` (String) JSON Schema that defines the structure of attestation data. diff --git a/administration/terraform/data-sources/environment.mdx b/administration/terraform/data-sources/environment.mdx new file mode 100644 index 00000000..3d24e151 --- /dev/null +++ b/administration/terraform/data-sources/environment.mdx @@ -0,0 +1,102 @@ +--- +title: "kosli_environment data source" +description: "Fetches details of an existing Kosli environment. Use this data source to reference environments and access metadata like last modified and last reported timestamps." +icon: "database" +--- + +Fetches details of an existing Kosli environment. Use this data source to reference environments and access metadata like last modified and last reported timestamps. + +Environments represent runtime locations where artifacts are deployed and tracked for compliance monitoring. Use this data source to: + +- Reference existing environment configurations in other resources +- Monitor environment activity (last modified, last reported timestamps) +- Create conditional logic based on environment state +- Build alerts and notifications based on environment metadata + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Query an existing environment +data "kosli_environment" "production" { + name = "production-k8s" +} + +# Use the data source to create a similar environment +resource "kosli_environment" "staging" { + name = "staging-k8s" + type = data.kosli_environment.production.type + description = "Staging environment similar to ${data.kosli_environment.production.name}" +} + +# Reference environment metadata for monitoring +output "production_last_modified" { + description = "Timestamp of when production environment was last modified" + value = data.kosli_environment.production.last_modified_at +} + +output "production_last_reported" { + description = "Timestamp of when production environment last reported a snapshot" + value = data.kosli_environment.production.last_reported_at +} + +output "production_type" { + description = "Type of the production environment" + value = data.kosli_environment.production.type +} + +output "production_includes_scaling" { + description = "Whether production environment includes scaling events" + value = data.kosli_environment.production.include_scaling +} + +# Conditional logic based on environment metadata +locals { + # Check if environment has never reported a snapshot + needs_attention = data.kosli_environment.production.last_reported_at == null +} + +output "production_needs_attention" { + description = "Whether production environment needs attention (never reported)" + value = local.needs_attention +} +``` + +## Monitoring with data sources + +The data source exposes timestamp fields that are useful for monitoring: + +- `last_modified_at`: Unix timestamp of when the environment configuration was last changed +- `last_reported_at`: Unix timestamp of when the environment last reported a snapshot (can be null if never reported) + +These timestamps enable you to: + +- Create alerts for environments that haven't reported in a certain time period +- Track configuration changes across your infrastructure +- Build dashboards showing environment activity +- Implement conditional deployment logic based on environment state + +## Read-only access + +Data sources provide read-only access to environment metadata. To modify environment configurations, use the [`kosli_environment` resource](/administration/terraform/resources/environment). + +## Schema + +### Required + +- `name` (String) The name of the environment to query. + +### Read-only + +- `description` (String) The description of the environment. +- `include_scaling` (Boolean) Whether the environment includes scaling events in snapshots. +- `last_modified_at` (Number) Unix timestamp (with fractional seconds) of when the environment was last modified. +- `last_reported_at` (Number) Unix timestamp (with fractional seconds) of when the environment was last reported. May be null if never reported. +- `type` (String) The environment type (e.g., K8S, ECS, S3, docker, server, lambda). diff --git a/administration/terraform/data-sources/logical_environment.mdx b/administration/terraform/data-sources/logical_environment.mdx new file mode 100644 index 00000000..9358655d --- /dev/null +++ b/administration/terraform/data-sources/logical_environment.mdx @@ -0,0 +1,186 @@ +--- +title: "kosli_logical_environment data source" +description: "Fetches details of an existing Kosli logical environment. Use this data source to reference logical environments and access their aggregated physical environments." +icon: "database" +--- + +Fetches details of an existing Kosli logical environment. Use this data source to reference logical environments and access their aggregated physical environments. + +Use this data source to query existing logical environments in Kosli. This is useful for: + +- **Referencing metadata**: Access `last_modified_at` timestamps and other computed attributes +- **Cross-stack references**: Reference logical environments created outside Terraform +- **Dynamic configuration**: Use existing logical environment configurations to create variants +- **Validation**: Verify logical environments exist before referencing them +- **Monitoring**: Create conditional logic based on logical environment state + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Query an existing logical environment +data "kosli_logical_environment" "production" { + name = "production-aggregate" +} + +# Use the data source to create a similar logical environment +resource "kosli_logical_environment" "staging" { + name = "staging-aggregate" + description = "Staging version of ${data.kosli_logical_environment.production.name}" + included_environments = data.kosli_logical_environment.production.included_environments +} + +# Reference logical environment metadata +output "production_name" { + description = "Name of the production logical environment" + value = data.kosli_logical_environment.production.name +} + +output "production_type" { + description = "Type of the environment (should be 'logical')" + value = data.kosli_logical_environment.production.type +} + +output "production_description" { + description = "Description of the production logical environment" + value = data.kosli_logical_environment.production.description +} + +output "production_environments" { + description = "List of physical environments included in production aggregate" + value = data.kosli_logical_environment.production.included_environments +} + +output "production_last_modified" { + description = "Timestamp of when production logical environment was last modified" + value = data.kosli_logical_environment.production.last_modified_at +} + +# Count how many environments are aggregated +output "production_environment_count" { + description = "Number of environments aggregated in production" + value = length(data.kosli_logical_environment.production.included_environments) +} + +# Conditional logic based on aggregation +locals { + # Check if logical environment is empty (no included environments) + is_empty = length(data.kosli_logical_environment.production.included_environments) == 0 + + # Check if it includes a specific environment + includes_k8s = contains( + data.kosli_logical_environment.production.included_environments, + "production-k8s" + ) +} + +output "production_is_empty" { + description = "Whether production logical environment has no included environments" + value = local.is_empty +} + +output "production_includes_k8s" { + description = "Whether production aggregates a K8S environment" + value = local.includes_k8s +} +``` + +## Type validation + + +This data source validates that the queried environment is of type `logical`. Attempting to query a physical environment will result in an error. Use the [`kosli_environment` data source](/administration/terraform/data-sources/environment) for physical environments instead. + + +## Use cases + +### Reference metadata + +Query logical environment metadata for monitoring or conditional logic: + +```terraform +data "kosli_logical_environment" "production" { + name = "production-all" +} + +output "production_last_modified" { + value = data.kosli_logical_environment.production.last_modified_at +} + +output "production_environment_count" { + value = length(data.kosli_logical_environment.production.included_environments) +} +``` + +### Create variants + +Use an existing logical environment as a template for creating similar ones: + +```terraform +data "kosli_logical_environment" "production" { + name = "production-all" +} + +resource "kosli_logical_environment" "staging" { + name = "staging-all" + description = "Staging version of ${data.kosli_logical_environment.production.name}" + + # Reuse the same environment structure + included_environments = data.kosli_logical_environment.production.included_environments +} +``` + +### Cross-stack references + +Reference logical environments created in other Terraform workspaces or outside Terraform: + +```terraform +data "kosli_logical_environment" "shared_production" { + name = "production-all" # Created in infrastructure workspace +} + +# Use in application deployment workspace +locals { + production_environments = data.kosli_logical_environment.shared_production.included_environments +} +``` + +### Conditional logic + +Create conditional logic based on logical environment configuration: + +```terraform +data "kosli_logical_environment" "production" { + name = "production-all" +} + +locals { + # Check if environment is empty + is_empty = length(data.kosli_logical_environment.production.included_environments) == 0 + + # Check if it includes a specific environment + includes_k8s = contains( + data.kosli_logical_environment.production.included_environments, + "production-k8s" + ) +} +``` + +## Schema + +### Required + +- `name` (String) The name of the logical environment to query. + +### Read-only + +- `description` (String) The description of the logical environment. +- `included_environments` (List of String) List of physical environment names aggregated by this logical environment. +- `last_modified_at` (Number) Unix timestamp (with fractional seconds) of when the logical environment was last modified. +- `type` (String) The environment type (always `logical` for logical environments). diff --git a/administration/terraform/index.mdx b/administration/terraform/index.mdx new file mode 100644 index 00000000..adb02cb8 --- /dev/null +++ b/administration/terraform/index.mdx @@ -0,0 +1,68 @@ +--- +title: "Kosli Terraform Provider" +description: "Manage Kosli resources as Infrastructure-as-Code using Terraform." +icon: "layer-group" +--- + +The Kosli provider allows you to manage Kosli resources as Infrastructure-as-Code using Terraform. Use it to define and manage custom attestation types and integrate Kosli into your compliance workflows. + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Configure the Kosli Provider +# Authentication via environment variables (recommended) +provider "kosli" { + # API token - set via KOSLI_API_TOKEN environment variable + # Organization name - set via KOSLI_ORG environment variable + + # Optional: API endpoint URL (defaults to https://app.kosli.com) + # api_url = "https://app.us.kosli.com" # Use US region + + # Optional: HTTP client timeout in seconds (defaults to 30) + # timeout = 60 +} +``` + +## Authentication + +The provider requires a Kosli API token and organization name for authentication. These can be configured in two ways (in order of precedence): + +1. **Provider configuration** - Set directly in your Terraform configuration +2. **Environment variables** - Use `KOSLI_API_TOKEN` and `KOSLI_ORG` + +### Creating an API token + +To create an API token: + +1. Log in to [Kosli](https://app.kosli.com) +2. Navigate to **Settings** → **API Tokens** +3. Click **Create Token** +4. Copy the token and store it securely + + +API tokens grant full access to your Kosli organization. Store them securely and never commit them to version control. + + +## Regional endpoints + +Kosli operates in multiple regions. Configure the `api_url` to match your organization's region: + +- **EU (Default)**: `https://app.kosli.com` +- **US**: `https://app.us.kosli.com` + +## Schema + +### Optional + +- `api_token` (String, Sensitive) Kosli API token for authentication. Can also be set via KOSLI_API_TOKEN environment variable. +- `api_url` (String) Kosli API endpoint URL. Defaults to https://app.kosli.com (EU region). Use https://app.us.kosli.com for US region. Can also be set via KOSLI_API_URL environment variable. +- `org` (String) Kosli organization name. Can also be set via KOSLI_ORG environment variable. +- `timeout` (Number) HTTP client timeout in seconds. Defaults to 30 seconds. diff --git a/administration/terraform/resources/custom_attestation_type.mdx b/administration/terraform/resources/custom_attestation_type.mdx new file mode 100644 index 00000000..0465cd4d --- /dev/null +++ b/administration/terraform/resources/custom_attestation_type.mdx @@ -0,0 +1,163 @@ +--- +title: "kosli_custom_attestation_type resource" +description: "Manages a custom attestation type in Kosli. Custom attestation types define how Kosli validates and evaluates evidence from proprietary tools, custom metrics, or specialized compliance requirements." +icon: "cube" +--- + +Manages a custom attestation type in Kosli. Custom attestation types define how Kosli validates and evaluates evidence from proprietary tools, custom metrics, or specialized compliance requirements. + +Custom attestation types define the structure and validation rules for attestations in Kosli. They can include: + +- A JSON Schema (optional) that defines the expected structure of attestation data +- JQ rules (optional) that evaluate the attestation data for compliance + +**Note**: While both `schema` and `jq_rules` are optional attributes in Terraform, the Kosli API requires at least one of them to be provided when creating or updating a custom attestation type. + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Security scan attestation type +resource "kosli_custom_attestation_type" "security_scan" { + name = "security-scan" + description = "Validates security scan results" + + schema = jsonencode({ + type = "object" + properties = { + critical_vulnerabilities = { type = "integer" } + high_vulnerabilities = { type = "integer" } + medium_vulnerabilities = { type = "integer" } + scan_date = { type = "string" } + scanner_version = { type = "string" } + } + required = ["critical_vulnerabilities", "high_vulnerabilities", "scan_date"] + }) + + jq_rules = [ + ".critical_vulnerabilities == 0", + ".high_vulnerabilities < 5" + ] +} + +# Code coverage attestation type +resource "kosli_custom_attestation_type" "code_coverage" { + name = "code-coverage" + description = "Validates code coverage metrics" + + schema = jsonencode({ + type = "object" + properties = { + line_coverage = { + type = "number" + minimum = 0 + maximum = 100 + } + branch_coverage = { + type = "number" + minimum = 0 + maximum = 100 + } + total_lines = { type = "integer" } + covered_lines = { type = "integer" } + } + required = ["line_coverage", "total_lines", "covered_lines"] + }) + + jq_rules = [ + ".line_coverage >= 80", + ".branch_coverage >= 70" + ] +} + +# Age verification attestation type with only jq rules (no schema) +resource "kosli_custom_attestation_type" "age_verification" { + name = "age-verification" + description = "Verifies age is over 21 using only jq rules without schema validation" + + jq_rules = [".age > 21"] +} + +# Schema-only attestation type (no jq rules) +resource "kosli_custom_attestation_type" "schema_validation" { + name = "data-structure-validation" + description = "Validates data structure using schema without evaluation rules" + + schema = jsonencode({ + type = "object" + properties = { + timestamp = { type = "string" } + metadata = { type = "object" } + status = { + type = "string" + enum = ["pass", "fail", "skip"] + } + } + required = ["timestamp", "status"] + }) +} +``` + +## Schema validation + +The `schema` attribute is optional and can contain a valid JSON Schema (draft-07) that defines the structure of attestation data. When provided, attestation data will be validated against this schema. Common schema types: + +- **Security scans**: Define vulnerability counts and scan metadata +- **Code coverage**: Define coverage percentages and test metrics +- **Performance tests**: Define response times and error rates + +### Schema example + +```json +{ + "type": "object", + "properties": { + "critical_vulnerabilities": { "type": "integer" }, + "high_vulnerabilities": { "type": "integer" }, + "scan_date": { "type": "string" } + }, + "required": ["critical_vulnerabilities", "high_vulnerabilities", "scan_date"] +} +``` + +## JQ rules + +The `jq_rules` attribute is optional and contains an array of JQ expressions that must ALL evaluate to `true` for an attestation to be considered compliant. When provided, each rule is evaluated against the attestation data. If omitted, no evaluation is performed. + +### JQ rules examples + +```hcl +jq_rules = [ + ".critical_vulnerabilities == 0", # No critical vulnerabilities allowed + ".high_vulnerabilities < 5", # Less than 5 high vulnerabilities + ".scan_date != null" # Scan date must be present +] +``` + +## Import + +Custom attestation types can be imported using their name: + +```shell +# Import an existing custom attestation type by name +terraform import kosli_custom_attestation_type.security_scan security-scan +``` + +## Schema + +### Required + +- `name` (String) Name of the custom attestation type. Must start with a letter or number and can only contain letters, numbers, periods, hyphens, underscores, and tildes. Changing this will force recreation of the resource. + +### Optional + +- `description` (String) Description of the custom attestation type. Explains what this attestation type validates. +- `jq_rules` (List of String) List of jq evaluation rules. Each rule is a jq expression that must evaluate to true for the attestation to be considered compliant. Example: `[".coverage >= 80"]`. If omitted, no evaluation is performed. +- `schema` (String) JSON Schema definition that defines the structure of attestation data. Can be provided inline using heredoc syntax or loaded from a file using `file()`. If omitted, no schema validation is performed. Semantic equality is used for comparison, so formatting differences are ignored. diff --git a/administration/terraform/resources/environment.mdx b/administration/terraform/resources/environment.mdx new file mode 100644 index 00000000..3058e23d --- /dev/null +++ b/administration/terraform/resources/environment.mdx @@ -0,0 +1,135 @@ +--- +title: "kosli_environment resource" +description: "Manages a Kosli environment. Environments represent deployment targets where artifacts are deployed. Supports physical environment types: K8S, ECS, S3, docker, server, and lambda." +icon: "cube" +--- + +Manages a Kosli environment. Environments represent deployment targets where artifacts are deployed. Supports physical environment types: K8S, ECS, S3, docker, server, and lambda. + + +This resource manages the environment configuration only. Environment tags are managed through a separate Kosli API. Environment policies will be available in a future release. For querying environment metadata such as `last_modified_at`, `last_reported_at`, and `archived` status, use the [`kosli_environment` data source](/administration/terraform/data-sources/environment). + + +Kosli environments track deployments and provide visibility into what's running in your infrastructure. Physical environments represent actual runtime locations such as: + +- **K8S**: Kubernetes clusters +- **ECS**: Amazon Elastic Container Service clusters +- **S3**: Amazon S3 buckets +- **docker**: Docker containers +- **server**: Bare-metal or VM servers +- **lambda**: AWS Lambda functions + + +For aggregating multiple physical environments into logical groups, use the [`kosli_logical_environment` resource](/administration/terraform/resources/logical_environment). + + + +Environment tags are managed through a separate Kosli API and are not included in this Terraform resource. + + + +Environment policies will be available in a future release as a separate resource (`kosli_environment_policy`). + + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Basic K8S environment +resource "kosli_environment" "production_k8s" { + name = "production-k8s" + type = "K8S" + description = "Production Kubernetes cluster" +} + +# ECS environment with scaling +resource "kosli_environment" "staging_ecs" { + name = "staging-ecs" + type = "ECS" + description = "Staging ECS cluster" + include_scaling = true +} + +# S3 environment +resource "kosli_environment" "data_lake" { + name = "data-lake-s3" + type = "S3" + description = "Data lake S3 bucket environment" +} + +# Docker environment +resource "kosli_environment" "local_docker" { + name = "local-docker" + type = "docker" +} + +# Server environment +resource "kosli_environment" "production_servers" { + name = "production-servers" + type = "server" + description = "Production bare-metal servers" + include_scaling = false +} + +# Lambda environment +resource "kosli_environment" "serverless_functions" { + name = "serverless-lambda" + type = "lambda" + description = "AWS Lambda functions" +} +``` + +## Environment types + +The `type` attribute must be one of the following physical environment types: + +- `K8S` - Kubernetes clusters +- `ECS` - Amazon Elastic Container Service +- `S3` - Amazon S3 buckets +- `docker` - Docker containers +- `server` - Bare-metal or VM servers +- `lambda` - AWS Lambda functions + +## Configuration options + +### Include scaling + +The `include_scaling` attribute (default: `false`) determines whether scaling events in the environment should be tracked. This is useful for environments with auto-scaling where you want to monitor scale-up and scale-down events. + +## Import + +Environments can be imported using their name: + +```shell +#!/bin/bash + +# Import an existing environment by name +terraform import kosli_environment.production_k8s production-k8s + +# Import multiple environments +terraform import kosli_environment.staging_ecs staging-ecs +terraform import kosli_environment.data_lake data-lake-s3 +``` + +## Monitoring environments + +For querying environment metadata such as `last_modified_at` and `last_reported_at` timestamps, use the [`kosli_environment` data source](/administration/terraform/data-sources/environment). This is useful for monitoring and creating conditional logic based on environment state. + +## Schema + +### Required + +- `name` (String) Name of the environment. Must be unique within the organization. Changing this will force recreation of the resource. +- `type` (String) Type of the environment. Valid values: `K8S`, `ECS`, `S3`, `docker`, `server`, `lambda`. Changing this will force recreation of the resource. + +### Optional + +- `description` (String) Description of the environment. Explains the purpose and characteristics of this deployment target. +- `include_scaling` (Boolean) Whether to include scaling information when reporting environment snapshots. Defaults to `false`. diff --git a/administration/terraform/resources/logical_environment.mdx b/administration/terraform/resources/logical_environment.mdx new file mode 100644 index 00000000..95674ceb --- /dev/null +++ b/administration/terraform/resources/logical_environment.mdx @@ -0,0 +1,201 @@ +--- +title: "kosli_logical_environment resource" +description: "Manages a Kosli logical environment. Logical environments aggregate multiple physical environments for organizational purposes." +icon: "cube" +--- + +Manages a Kosli logical environment. Logical environments aggregate multiple physical environments for organizational purposes. + + +Logical environments can ONLY contain physical environments (K8S, ECS, S3, docker, server, lambda), not other logical environments. Attempting to include a logical environment will result in an error from the Kosli API. + + + +This resource manages logical environment configuration only. For querying environment metadata such as `last_modified_at` and `archived` status, use the [`kosli_logical_environment` data source](/administration/terraform/data-sources/logical_environment). + + +Logical environments in Kosli aggregate multiple physical environments for organizational purposes, providing: + +- **Unified visibility**: View compliance status across multiple environments at once +- **Flexible grouping**: Organize environments by region, service type, tier, or team +- **Simplified reporting**: Generate compliance reports for logical groupings +- **Team organization**: Allow different teams to focus on specific environment groups + +## Physical environments only + + +Logical environments can ONLY contain physical environments (K8S, ECS, S3, docker, server, lambda), not other logical environments. Attempting to include a logical environment will result in an API error. + + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# First, create physical environments that will be aggregated +resource "kosli_environment" "production_k8s" { + name = "production-k8s" + type = "K8S" + description = "Production Kubernetes cluster" +} + +resource "kosli_environment" "production_ecs" { + name = "production-ecs" + type = "ECS" + description = "Production ECS cluster" +} + +resource "kosli_environment" "production_lambda" { + name = "production-lambda" + type = "lambda" + description = "Production Lambda functions" +} + +# Basic logical environment aggregating production environments +resource "kosli_logical_environment" "production_all" { + name = "production-aggregate" + description = "Aggregates all production environments for unified visibility" + + included_environments = [ + kosli_environment.production_k8s.name, + kosli_environment.production_ecs.name, + kosli_environment.production_lambda.name, + ] +} + +# Logical environment with just two environments +resource "kosli_logical_environment" "cloud_services" { + name = "cloud-services" + description = "All cloud-based services" + + included_environments = [ + kosli_environment.production_ecs.name, + kosli_environment.production_lambda.name, + ] +} + +# Minimal logical environment with empty list (can be populated later) +resource "kosli_logical_environment" "future_environments" { + name = "future-environments" + included_environments = [] +} + +# Logical environment without description (optional) +resource "kosli_logical_environment" "simple" { + name = "simple-aggregate" + + included_environments = [ + kosli_environment.production_k8s.name, + ] +} +``` + +## Complete example + +For a comprehensive example showing logical environments aggregating physical environments by region, service type, and tier, see the [complete logical environments example](https://github.com/kosli-dev/terraform-provider-kosli/tree/main/examples/complete/logical-environments). + +## Common use cases + +### By environment tier + +Aggregate all production or staging environments for unified compliance reporting: + +```terraform +resource "kosli_logical_environment" "production_all" { + name = "production-all" + description = "All production environments" + + included_environments = [ + kosli_environment.prod_k8s.name, + kosli_environment.prod_ecs.name, + kosli_environment.prod_lambda.name, + ] +} +``` + +### By geographic region + +Group environments by region for regional compliance or disaster recovery: + +```terraform +resource "kosli_logical_environment" "production_us_east" { + name = "production-us-east" + description = "All production environments in US East" + + included_environments = [ + kosli_environment.prod_k8s_us_east.name, + kosli_environment.prod_ecs_us_east.name, + ] +} +``` + +### By service type + +Organize environments by technology stack or service type: + +```terraform +resource "kosli_logical_environment" "all_kubernetes" { + name = "all-kubernetes-clusters" + description = "All Kubernetes clusters across regions" + + included_environments = [ + kosli_environment.k8s_us_east.name, + kosli_environment.k8s_eu_west.name, + kosli_environment.k8s_ap_south.name, + ] +} +``` + +## Empty logical environments + +Logical environments can be created with empty `included_environments` lists and populated later: + +```terraform +resource "kosli_logical_environment" "future_environments" { + name = "planned-expansion" + description = "Placeholder for future environments" + included_environments = [] +} +``` + +## Import + +Logical environments can be imported using their name: + +```shell +#!/bin/bash + +# Import an existing logical environment by name +terraform import kosli_logical_environment.production_all production-aggregate + +# Import multiple logical environments +terraform import kosli_logical_environment.cloud_services cloud-services +terraform import kosli_logical_environment.future_environments future-environments +``` + +## Querying metadata + + +This resource manages logical environment configuration only. For querying environment metadata such as `last_modified_at` and `archived` status, use the [`kosli_logical_environment` data source](/administration/terraform/data-sources/logical_environment). + + +## Schema + +### Required + +- `included_environments` (List of String) List of physical environment names to aggregate. Only physical environments are allowed (K8S, ECS, S3, docker, server, lambda). Can be empty. +- `name` (String) Name of the logical environment. Must be unique within the organization. Changing this will force recreation of the resource. + +### Optional + +- `description` (String) Description of the logical environment. Explains the purpose and aggregation strategy. + +### Read-only + +- `type` (String) Type of the environment. Always set to `logical` (computed by provider, not user-configurable). diff --git a/docs.json b/docs.json index 7cb9d4fa..011381f7 100644 --- a/docs.json +++ b/docs.json @@ -84,6 +84,28 @@ "pages": [ "administration/managing_environments/overview" ] + }, + { + "group": "Terraform Provider", + "pages": [ + "administration/terraform/index", + { + "group": "Resources", + "pages": [ + "administration/terraform/resources/environment", + "administration/terraform/resources/logical_environment", + "administration/terraform/resources/custom_attestation_type" + ] + }, + { + "group": "Data Sources", + "pages": [ + "administration/terraform/data-sources/environment", + "administration/terraform/data-sources/logical_environment", + "administration/terraform/data-sources/custom_attestation_type" + ] + } + ] } ] }, From e376ff31562c9b9d3a0a5a7dddec97d2e5805fbd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Mon, 16 Mar 2026 22:31:24 +0100 Subject: [PATCH 2/9] fix: move Terraform Provider to Reference tab --- docs.json | 50 ++++++++++++++++++++++++++++---------------------- 1 file changed, 28 insertions(+), 22 deletions(-) diff --git a/docs.json b/docs.json index 011381f7..06d12fa8 100644 --- a/docs.json +++ b/docs.json @@ -84,28 +84,6 @@ "pages": [ "administration/managing_environments/overview" ] - }, - { - "group": "Terraform Provider", - "pages": [ - "administration/terraform/index", - { - "group": "Resources", - "pages": [ - "administration/terraform/resources/environment", - "administration/terraform/resources/logical_environment", - "administration/terraform/resources/custom_attestation_type" - ] - }, - { - "group": "Data Sources", - "pages": [ - "administration/terraform/data-sources/environment", - "administration/terraform/data-sources/logical_environment", - "administration/terraform/data-sources/custom_attestation_type" - ] - } - ] } ] }, @@ -419,6 +397,34 @@ } ] }, + { + "item": "Terraform Reference", + "icon": "layer-group", + "groups": [ + { + "group": "Provider", + "pages": [ + "administration/terraform/index" + ] + }, + { + "group": "Resources", + "pages": [ + "administration/terraform/resources/environment", + "administration/terraform/resources/logical_environment", + "administration/terraform/resources/custom_attestation_type" + ] + }, + { + "group": "Data Sources", + "pages": [ + "administration/terraform/data-sources/environment", + "administration/terraform/data-sources/logical_environment", + "administration/terraform/data-sources/custom_attestation_type" + ] + } + ] + }, { "item": "Helm Reference", "icon": "layer-group", From 6ad5eeb9eaf51c27950ddce5b8eea9727c8bb34f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Mon, 16 Mar 2026 22:33:04 +0100 Subject: [PATCH 3/9] fix: place Terraform Reference after Helm Reference in nav --- docs.json | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs.json b/docs.json index 06d12fa8..1270d000 100644 --- a/docs.json +++ b/docs.json @@ -397,6 +397,18 @@ } ] }, + { + "item": "Helm Reference", + "icon": "layer-group", + "groups": [ + { + "group": "Helm Charts", + "pages": [ + "helm/k8s_reporter" + ] + } + ] + }, { "item": "Terraform Reference", "icon": "layer-group", @@ -424,18 +436,6 @@ ] } ] - }, - { - "item": "Helm Reference", - "icon": "layer-group", - "groups": [ - { - "group": "Helm Charts", - "pages": [ - "helm/k8s_reporter" - ] - } - ] } ] }, From dde7101dcb72e470fec3689d94b7ee57963f70a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Mon, 16 Mar 2026 22:39:12 +0100 Subject: [PATCH 4/9] fix: move terraform docs from administration/ to terraform-reference/ --- .../managing_environments/overview.md | 8 +- docs.json | 14 +- faq/faq.md | 249 ++++++++++++++++++ .../data-sources/custom_attestation_type.mdx | 0 .../data-sources/environment.mdx | 2 +- .../data-sources/logical_environment.mdx | 2 +- .../index.mdx | 0 .../resources/custom_attestation_type.mdx | 0 .../resources/environment.mdx | 6 +- .../resources/logical_environment.mdx | 4 +- 10 files changed, 267 insertions(+), 18 deletions(-) create mode 100644 faq/faq.md rename {administration/terraform => terraform-reference}/data-sources/custom_attestation_type.mdx (100%) rename {administration/terraform => terraform-reference}/data-sources/environment.mdx (98%) rename {administration/terraform => terraform-reference}/data-sources/logical_environment.mdx (97%) rename {administration/terraform => terraform-reference}/index.mdx (100%) rename {administration/terraform => terraform-reference}/resources/custom_attestation_type.mdx (100%) rename {administration/terraform => terraform-reference}/resources/environment.mdx (93%) rename {administration/terraform => terraform-reference}/resources/logical_environment.mdx (98%) diff --git a/administration/managing_environments/overview.md b/administration/managing_environments/overview.md index 60e72310..5727f0b6 100644 --- a/administration/managing_environments/overview.md +++ b/administration/managing_environments/overview.md @@ -107,7 +107,7 @@ terraform import kosli_logical_environment.production_all production-all ## Reference -- [`kosli_environment` resource](/administration/terraform/resources/environment) -- [`kosli_environment` data source](/administration/terraform/data-sources/environment) -- [`kosli_logical_environment` resource](/administration/terraform/resources/logical_environment) -- [`kosli_logical_environment` data source](/administration/terraform/data-sources/logical_environment) +- [`kosli_environment` resource](/terraform-reference/resources/environment) +- [`kosli_environment` data source](/terraform-reference/data-sources/environment) +- [`kosli_logical_environment` resource](/terraform-reference/resources/logical_environment) +- [`kosli_logical_environment` data source](/terraform-reference/data-sources/logical_environment) diff --git a/docs.json b/docs.json index 1270d000..f90d9327 100644 --- a/docs.json +++ b/docs.json @@ -416,23 +416,23 @@ { "group": "Provider", "pages": [ - "administration/terraform/index" + "terraform-reference/index" ] }, { "group": "Resources", "pages": [ - "administration/terraform/resources/environment", - "administration/terraform/resources/logical_environment", - "administration/terraform/resources/custom_attestation_type" + "terraform-reference/resources/environment", + "terraform-reference/resources/logical_environment", + "terraform-reference/resources/custom_attestation_type" ] }, { "group": "Data Sources", "pages": [ - "administration/terraform/data-sources/environment", - "administration/terraform/data-sources/logical_environment", - "administration/terraform/data-sources/custom_attestation_type" + "terraform-reference/data-sources/environment", + "terraform-reference/data-sources/logical_environment", + "terraform-reference/data-sources/custom_attestation_type" ] } ] diff --git a/faq/faq.md b/faq/faq.md new file mode 100644 index 00000000..5c2dac83 --- /dev/null +++ b/faq/faq.md @@ -0,0 +1,249 @@ +--- +title: FAQ +description: "Frequently asked questions" +--- + +If you can't find the answer you're looking for please: + +* email us at [support@kosli.com](mailto:support@kosli.com) +* join our slack community [here](https://join.slack.com/t/koslicommunity/shared_invite/zt-1dlchm3s7-DEP6TKjP3Mr58OZVB3hCBw) + +## What do I do if Kosli is down? + +There is a [tutorial](/tutorials/what_do_i_do_if_kosli_is_down) dedicated to this. + +## Why am I getting "Error response from daemon: client version 1.47 is too new. Maximum supported API version is 1.45" error in my GitHub Action Workflow? + +The latest Kosli CLI defaults to using version 1.47 of the Docker API and +on Github Action Workflows, the maximum supported Docker API version is currently 1.45 + +You can tell the Kosli CLI to use version 1.45 by setting the +`DOCKER_API_VERSION` environment-variable. For example: + +```yaml +env: + DOCKER_API_VERSION: "1.45" +``` + + +## Why am I getting "unknown flag" error? + +If you see an error like below (or similar, with a different flag): +``` +Error: unknown flag: --artifact-type +``` +It most likely means you misspelled a flag. + +## "unknown command" errors +E.g. +``` +kosli expect deploymenct abc.exe --artifact-type file +Error: unknown command: deploymenct +available subcommands are: deployment +``` + +Note that there is a typo in deploymen**c**t. +This error will pop up if you're trying to use a command that is not present in the version of the kosli CLI you are using. + +## zsh: no such user or named directory + +When running commands with an argument starting with `~` you can encounter following problem: + +```shell +kosli list snapshots prod ~3..NOW +``` +```plaintext +zsh: no such user or named directory: 3..NOW +``` + +To help ZShell interpret the argument correctly, wrap it in quotation marks (single or double): +```shell +kosli list snapshots prod '~3..NOW' +``` +or +```shell +kosli list snapshots prod "~3..NOW" +``` + +## Github can't see KOSLI_API_TOKEN secret + +Secrets in Github actions are not automatically exported as environment variables. You need to add required secrets to your GITHUB environment explicitly. E.g. to make kosli_api_token secret available for all cli commands as an environment variable use the following: + +```yaml +env: + KOSLI_API_TOKEN: ${{ secrets.kosli_api_token }} +``` + +## I'm running the Kosli CLI in a subshell and the captured output includes stderr! + +The Kosli CLI writes debug information to `stderr`, and all other output to `stdout`. +Normally, in a bash $(subshell), only `stdout` is captured. +In the following example, the `DIGEST` variable captures _only_ the 64 character digest of the docker image; +the extra debug information is printed to the terminal. + +```shell +# In a local terminal +KOSLI_DEBUG=true +DIGEST="$(kosli fingerprint "${IMAGE_NAME}" --artifact-type=docker)" + +[debug] calculated fingerprint: 2c6079df58292ed10e8074adcb74be549b7f841a1bd8266f06bb5c518643193e for artifact: 244531986313.dkr.ecr.eu-central-1.amazonaws.com/exercises-start-points:86f9052 + +echo "DIGEST=${DIGEST}" +DIGEST=2c6079df58292ed10e8074adcb74be549b7f841a1bd8266f06bb5c518643193e +``` + +However, in many CI workflows (including Github and Gitlab), `stdout` and `stderr` are multiplexed together. +This means `DIGEST` will contain _both_ the 64 character digest _and_ the debug information. +For example: + +```shell +# In a CI workflow +KOSLI_DEBUG=true +DIGEST="$(kosli fingerprint "${IMAGE_NAME}" --artifact-type=docker)" + +echo "DIGEST=${DIGEST}" +DIGEST=[debug] calculated fingerprint: 2c6079df58292ed10e8074adcb74be549b7f841a1bd8266f06bb5c518643193e for artifact: 244531986313.dkr.ecr.eu-central-1.amazonaws.com/exercises-start-points:86f9052 +2c6079df58292ed10e8074adcb74be549b7f841a1bd8266f06bb5c518643193e +``` + +When running the Kosli CLI in a subshell, in a CI workflow, we recommend explicitly setting the `--debug` flag to false. + +```shell +# In a CI workflow +KOSLI_DEBUG=true +DIGEST="$(kosli fingerprint "${IMAGE_NAME}" --artifact-type=docker --debug=false)" + +echo "DIGEST=${DIGEST}" +DIGEST=2c6079df58292ed10e8074adcb74be549b7f841a1bd8266f06bb5c518643193e +``` + + +## Where can I find API documentation? + +Kosli API documentation is available for logged in Kosli users here: https://app.kosli.com/api/v2/doc/ +You can find the link at [app.kosli.com](https://app.kosli.com) after clicking at your avatar (top-right corner of the page) + +## Do I have to provide all the flags all the time? + +A number of flags won't change their values often (or at all) between commands, like `--org` or `--api-token`. Some will differ between e.g. workflows, like `--flow`. You can define them as environment variable to avoid unnecessary redundancy. Check [Environment variables](/getting_started/install#assigning-flags-via-environment-variables) section to learn more. + +## What is dry run and how to use it? + +You can use dry run to disable writing to app.kosli.com - e.g. if you're just trying things out, or troubleshooting (dry run will print the payload the CLI would send in a non dry run mode). + +Here are three possible ways of enabling a dry run: +1. use the `--dry-run` flag (no value needed) to enable it per command +2. set the `KOSLI_DRY_RUN` environment variable to `true` to enable it globally (e.g. in your terminal or CI) +3. set the `KOSLI_API_TOKEN` environment variable to `DRY_RUN` to enable it globally (e.g. in your terminal or CI) + +## What is the `--config-file` flag? + +A config file is an alternative for using Kosli flags or Environment variables. Usually you'd use a config file for the values that rarely change - like api token or org, but you can represent all Kosli flags with config file. The key for each value is the same as the flag name, capitalized, so `--api-token` would become `API-TOKEN`, and `--org` would become `ORG`, etc. + +You can use JSON, YAML or TOML format for your config file. + +If you want to keep certain Kosli configuration in a file use `--config-file` flag when running Kosli commands to let the CLI know where to look for the file. The path given to `--config-file` flag should be a path relative to the location you're running kosli from. The file needs a valid format and extension, e.g.: + +**kosli-conf.json:** +``` +{ + "ORG": "my-org", + "API-TOKEN": "123456abcdef" +} +``` + +**kosli-conf.yaml:** +``` +ORG: "my-org" +API-TOKEN: "123456abcdef" +``` + +**kosli-conf.toml:** +``` +ORG = "my-org" +API-TOKEN = "123456abcdef" +``` + +When calling Kosli command you can skip the file extension. For example, to list environments with `org` and `api-token` in the configuration file you would run: + +```shell +kosli list environments --config-file kosli-conf +``` + +`--config-file` defaults to `kosli`, so if you name your file `kosli.` and the file is in the same location as where you run Kosli commands from, you can skip the `--config-file` altogether. + + +## Reporting the same artifact and evidence multiple times +If an artifact or evidence is reported multiple times there are a few corner cases. +The issues are described here: + +### Template +When an artifact is reported, the template for the flow is stored together with the artifact. +If the template has changed between the times the same artifact is reported, it is the last +template that is considered the template for that artifact. + +### Evidence +If a given named evidence is reported multiple times it is the compliance status of the last +reported version of the evidence that is considered the compliance state of that evidence. + +If an artifact is reported multiple times with different git-commit, we can have the same named +commit-evidence being attached to the artifact through multiple git-commits. It is the last +reported version of the named commit-evidence that is considered the compliance state of that evidence. + +### Evidence outside the template +If an artifact has evidence, either commit evidence or artifact evidence, that is not +part of the template, the state of the extra evidence will affect the overall compliance of the artifact. + +## How to set compliant status of generic evidence + +The `--compliant` flag is a [boolean flag](#boolean-flags). +To report generic evidence as non-compliant use `--compliant=false`, as in this example: +```shell +kosli report evidence artifact generic server:1.0 \ + --artifact-type docker \ + --name test \ + --description "generic test evidence" \ + --compliant=false \ + --flow server +``` + +Keep in mind a number of flags, usually represented with environment variables, are omitted in this example. +`--compliance` flag is set to `true` by default, so if you want to report generic evidence as compliant, simply skip providing the flag altogether. + +## Boolean flags + +Flags with values can usually be specified with an `=` or with a **space** as a separator. +For example, `--artifact-type=file` or `--artifact-type file`. +However, an explicitly specified boolean flag value **must** use an `=`. +For example, if you try this: +``` +kosli attest generic Dockerfile --artifact-type file --compliant true ... +``` +You will get an error stating: +``` +Error: accepts at most 1 arg(s), received 2 +``` +Here, `--artifact-type file` is parsed as if it was `--artifact-type=file`, leaving: +``` +kosli attest generic Dockerfile --compliant true ... +``` +Then `--compliant` is parsed as if *implicitly* defaulting to `--compliant=true`, leaving: +``` +kosli attest generic Dockerfile true ... +``` +The parser then sees `Dockerfile` and `true` as the two +arguments to `kosli attest generic`. + +## Path/Image name is a single whitespace character! + +In order to calculate the fingerprint for an artifact, Kosli requires the path to the relevant file or directory, or the relevant image name. The command typically takes the form: +``` +kosli attest generic [IMAGE-NAME | FILE-PATH | DIR-PATH] [flags] +``` + +When using multi-line commands in the shell or a script, if the image name or path has not been provided as above and whitespace has unintentionally been added after the line-continuation backslash on one of the lines, this whitespace character is interpreted as the name or path. + +If you're using multi-line commands and receive an error message similar to this, check your command for extraneous whitespace: +``` +Error: failed to calculate artifact fingerprint: stat : no such file or directory. The directory path is ' '. +``` diff --git a/administration/terraform/data-sources/custom_attestation_type.mdx b/terraform-reference/data-sources/custom_attestation_type.mdx similarity index 100% rename from administration/terraform/data-sources/custom_attestation_type.mdx rename to terraform-reference/data-sources/custom_attestation_type.mdx diff --git a/administration/terraform/data-sources/environment.mdx b/terraform-reference/data-sources/environment.mdx similarity index 98% rename from administration/terraform/data-sources/environment.mdx rename to terraform-reference/data-sources/environment.mdx index 3d24e151..8b0eb410 100644 --- a/administration/terraform/data-sources/environment.mdx +++ b/terraform-reference/data-sources/environment.mdx @@ -85,7 +85,7 @@ These timestamps enable you to: ## Read-only access -Data sources provide read-only access to environment metadata. To modify environment configurations, use the [`kosli_environment` resource](/administration/terraform/resources/environment). +Data sources provide read-only access to environment metadata. To modify environment configurations, use the [`kosli_environment` resource](/terraform-reference/resources/environment). ## Schema diff --git a/administration/terraform/data-sources/logical_environment.mdx b/terraform-reference/data-sources/logical_environment.mdx similarity index 97% rename from administration/terraform/data-sources/logical_environment.mdx rename to terraform-reference/data-sources/logical_environment.mdx index 9358655d..6eb01bab 100644 --- a/administration/terraform/data-sources/logical_environment.mdx +++ b/terraform-reference/data-sources/logical_environment.mdx @@ -95,7 +95,7 @@ output "production_includes_k8s" { ## Type validation -This data source validates that the queried environment is of type `logical`. Attempting to query a physical environment will result in an error. Use the [`kosli_environment` data source](/administration/terraform/data-sources/environment) for physical environments instead. +This data source validates that the queried environment is of type `logical`. Attempting to query a physical environment will result in an error. Use the [`kosli_environment` data source](/terraform-reference/data-sources/environment) for physical environments instead. ## Use cases diff --git a/administration/terraform/index.mdx b/terraform-reference/index.mdx similarity index 100% rename from administration/terraform/index.mdx rename to terraform-reference/index.mdx diff --git a/administration/terraform/resources/custom_attestation_type.mdx b/terraform-reference/resources/custom_attestation_type.mdx similarity index 100% rename from administration/terraform/resources/custom_attestation_type.mdx rename to terraform-reference/resources/custom_attestation_type.mdx diff --git a/administration/terraform/resources/environment.mdx b/terraform-reference/resources/environment.mdx similarity index 93% rename from administration/terraform/resources/environment.mdx rename to terraform-reference/resources/environment.mdx index 3058e23d..0d228176 100644 --- a/administration/terraform/resources/environment.mdx +++ b/terraform-reference/resources/environment.mdx @@ -7,7 +7,7 @@ icon: "cube" Manages a Kosli environment. Environments represent deployment targets where artifacts are deployed. Supports physical environment types: K8S, ECS, S3, docker, server, and lambda. -This resource manages the environment configuration only. Environment tags are managed through a separate Kosli API. Environment policies will be available in a future release. For querying environment metadata such as `last_modified_at`, `last_reported_at`, and `archived` status, use the [`kosli_environment` data source](/administration/terraform/data-sources/environment). +This resource manages the environment configuration only. Environment tags are managed through a separate Kosli API. Environment policies will be available in a future release. For querying environment metadata such as `last_modified_at`, `last_reported_at`, and `archived` status, use the [`kosli_environment` data source](/terraform-reference/data-sources/environment). Kosli environments track deployments and provide visibility into what's running in your infrastructure. Physical environments represent actual runtime locations such as: @@ -20,7 +20,7 @@ Kosli environments track deployments and provide visibility into what's running - **lambda**: AWS Lambda functions -For aggregating multiple physical environments into logical groups, use the [`kosli_logical_environment` resource](/administration/terraform/resources/logical_environment). +For aggregating multiple physical environments into logical groups, use the [`kosli_logical_environment` resource](/terraform-reference/resources/logical_environment). @@ -120,7 +120,7 @@ terraform import kosli_environment.data_lake data-lake-s3 ## Monitoring environments -For querying environment metadata such as `last_modified_at` and `last_reported_at` timestamps, use the [`kosli_environment` data source](/administration/terraform/data-sources/environment). This is useful for monitoring and creating conditional logic based on environment state. +For querying environment metadata such as `last_modified_at` and `last_reported_at` timestamps, use the [`kosli_environment` data source](/terraform-reference/data-sources/environment). This is useful for monitoring and creating conditional logic based on environment state. ## Schema diff --git a/administration/terraform/resources/logical_environment.mdx b/terraform-reference/resources/logical_environment.mdx similarity index 98% rename from administration/terraform/resources/logical_environment.mdx rename to terraform-reference/resources/logical_environment.mdx index 95674ceb..8d0987c5 100644 --- a/administration/terraform/resources/logical_environment.mdx +++ b/terraform-reference/resources/logical_environment.mdx @@ -11,7 +11,7 @@ Logical environments can ONLY contain physical environments (K8S, ECS, S3, docke -This resource manages logical environment configuration only. For querying environment metadata such as `last_modified_at` and `archived` status, use the [`kosli_logical_environment` data source](/administration/terraform/data-sources/logical_environment). +This resource manages logical environment configuration only. For querying environment metadata such as `last_modified_at` and `archived` status, use the [`kosli_logical_environment` data source](/terraform-reference/data-sources/logical_environment). Logical environments in Kosli aggregate multiple physical environments for organizational purposes, providing: @@ -182,7 +182,7 @@ terraform import kosli_logical_environment.future_environments future-environmen ## Querying metadata -This resource manages logical environment configuration only. For querying environment metadata such as `last_modified_at` and `archived` status, use the [`kosli_logical_environment` data source](/administration/terraform/data-sources/logical_environment). +This resource manages logical environment configuration only. For querying environment metadata such as `last_modified_at` and `archived` status, use the [`kosli_logical_environment` data source](/terraform-reference/data-sources/logical_environment). ## Schema From 8c0f833ef11408708f863763b58905b45deff7e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Mon, 16 Mar 2026 22:40:11 +0100 Subject: [PATCH 5/9] chore: remove accidentally committed faq file --- faq/faq.md | 249 ----------------------------------------------------- 1 file changed, 249 deletions(-) delete mode 100644 faq/faq.md diff --git a/faq/faq.md b/faq/faq.md deleted file mode 100644 index 5c2dac83..00000000 --- a/faq/faq.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -title: FAQ -description: "Frequently asked questions" ---- - -If you can't find the answer you're looking for please: - -* email us at [support@kosli.com](mailto:support@kosli.com) -* join our slack community [here](https://join.slack.com/t/koslicommunity/shared_invite/zt-1dlchm3s7-DEP6TKjP3Mr58OZVB3hCBw) - -## What do I do if Kosli is down? - -There is a [tutorial](/tutorials/what_do_i_do_if_kosli_is_down) dedicated to this. - -## Why am I getting "Error response from daemon: client version 1.47 is too new. Maximum supported API version is 1.45" error in my GitHub Action Workflow? - -The latest Kosli CLI defaults to using version 1.47 of the Docker API and -on Github Action Workflows, the maximum supported Docker API version is currently 1.45 - -You can tell the Kosli CLI to use version 1.45 by setting the -`DOCKER_API_VERSION` environment-variable. For example: - -```yaml -env: - DOCKER_API_VERSION: "1.45" -``` - - -## Why am I getting "unknown flag" error? - -If you see an error like below (or similar, with a different flag): -``` -Error: unknown flag: --artifact-type -``` -It most likely means you misspelled a flag. - -## "unknown command" errors -E.g. -``` -kosli expect deploymenct abc.exe --artifact-type file -Error: unknown command: deploymenct -available subcommands are: deployment -``` - -Note that there is a typo in deploymen**c**t. -This error will pop up if you're trying to use a command that is not present in the version of the kosli CLI you are using. - -## zsh: no such user or named directory - -When running commands with an argument starting with `~` you can encounter following problem: - -```shell -kosli list snapshots prod ~3..NOW -``` -```plaintext -zsh: no such user or named directory: 3..NOW -``` - -To help ZShell interpret the argument correctly, wrap it in quotation marks (single or double): -```shell -kosli list snapshots prod '~3..NOW' -``` -or -```shell -kosli list snapshots prod "~3..NOW" -``` - -## Github can't see KOSLI_API_TOKEN secret - -Secrets in Github actions are not automatically exported as environment variables. You need to add required secrets to your GITHUB environment explicitly. E.g. to make kosli_api_token secret available for all cli commands as an environment variable use the following: - -```yaml -env: - KOSLI_API_TOKEN: ${{ secrets.kosli_api_token }} -``` - -## I'm running the Kosli CLI in a subshell and the captured output includes stderr! - -The Kosli CLI writes debug information to `stderr`, and all other output to `stdout`. -Normally, in a bash $(subshell), only `stdout` is captured. -In the following example, the `DIGEST` variable captures _only_ the 64 character digest of the docker image; -the extra debug information is printed to the terminal. - -```shell -# In a local terminal -KOSLI_DEBUG=true -DIGEST="$(kosli fingerprint "${IMAGE_NAME}" --artifact-type=docker)" - -[debug] calculated fingerprint: 2c6079df58292ed10e8074adcb74be549b7f841a1bd8266f06bb5c518643193e for artifact: 244531986313.dkr.ecr.eu-central-1.amazonaws.com/exercises-start-points:86f9052 - -echo "DIGEST=${DIGEST}" -DIGEST=2c6079df58292ed10e8074adcb74be549b7f841a1bd8266f06bb5c518643193e -``` - -However, in many CI workflows (including Github and Gitlab), `stdout` and `stderr` are multiplexed together. -This means `DIGEST` will contain _both_ the 64 character digest _and_ the debug information. -For example: - -```shell -# In a CI workflow -KOSLI_DEBUG=true -DIGEST="$(kosli fingerprint "${IMAGE_NAME}" --artifact-type=docker)" - -echo "DIGEST=${DIGEST}" -DIGEST=[debug] calculated fingerprint: 2c6079df58292ed10e8074adcb74be549b7f841a1bd8266f06bb5c518643193e for artifact: 244531986313.dkr.ecr.eu-central-1.amazonaws.com/exercises-start-points:86f9052 -2c6079df58292ed10e8074adcb74be549b7f841a1bd8266f06bb5c518643193e -``` - -When running the Kosli CLI in a subshell, in a CI workflow, we recommend explicitly setting the `--debug` flag to false. - -```shell -# In a CI workflow -KOSLI_DEBUG=true -DIGEST="$(kosli fingerprint "${IMAGE_NAME}" --artifact-type=docker --debug=false)" - -echo "DIGEST=${DIGEST}" -DIGEST=2c6079df58292ed10e8074adcb74be549b7f841a1bd8266f06bb5c518643193e -``` - - -## Where can I find API documentation? - -Kosli API documentation is available for logged in Kosli users here: https://app.kosli.com/api/v2/doc/ -You can find the link at [app.kosli.com](https://app.kosli.com) after clicking at your avatar (top-right corner of the page) - -## Do I have to provide all the flags all the time? - -A number of flags won't change their values often (or at all) between commands, like `--org` or `--api-token`. Some will differ between e.g. workflows, like `--flow`. You can define them as environment variable to avoid unnecessary redundancy. Check [Environment variables](/getting_started/install#assigning-flags-via-environment-variables) section to learn more. - -## What is dry run and how to use it? - -You can use dry run to disable writing to app.kosli.com - e.g. if you're just trying things out, or troubleshooting (dry run will print the payload the CLI would send in a non dry run mode). - -Here are three possible ways of enabling a dry run: -1. use the `--dry-run` flag (no value needed) to enable it per command -2. set the `KOSLI_DRY_RUN` environment variable to `true` to enable it globally (e.g. in your terminal or CI) -3. set the `KOSLI_API_TOKEN` environment variable to `DRY_RUN` to enable it globally (e.g. in your terminal or CI) - -## What is the `--config-file` flag? - -A config file is an alternative for using Kosli flags or Environment variables. Usually you'd use a config file for the values that rarely change - like api token or org, but you can represent all Kosli flags with config file. The key for each value is the same as the flag name, capitalized, so `--api-token` would become `API-TOKEN`, and `--org` would become `ORG`, etc. - -You can use JSON, YAML or TOML format for your config file. - -If you want to keep certain Kosli configuration in a file use `--config-file` flag when running Kosli commands to let the CLI know where to look for the file. The path given to `--config-file` flag should be a path relative to the location you're running kosli from. The file needs a valid format and extension, e.g.: - -**kosli-conf.json:** -``` -{ - "ORG": "my-org", - "API-TOKEN": "123456abcdef" -} -``` - -**kosli-conf.yaml:** -``` -ORG: "my-org" -API-TOKEN: "123456abcdef" -``` - -**kosli-conf.toml:** -``` -ORG = "my-org" -API-TOKEN = "123456abcdef" -``` - -When calling Kosli command you can skip the file extension. For example, to list environments with `org` and `api-token` in the configuration file you would run: - -```shell -kosli list environments --config-file kosli-conf -``` - -`--config-file` defaults to `kosli`, so if you name your file `kosli.` and the file is in the same location as where you run Kosli commands from, you can skip the `--config-file` altogether. - - -## Reporting the same artifact and evidence multiple times -If an artifact or evidence is reported multiple times there are a few corner cases. -The issues are described here: - -### Template -When an artifact is reported, the template for the flow is stored together with the artifact. -If the template has changed between the times the same artifact is reported, it is the last -template that is considered the template for that artifact. - -### Evidence -If a given named evidence is reported multiple times it is the compliance status of the last -reported version of the evidence that is considered the compliance state of that evidence. - -If an artifact is reported multiple times with different git-commit, we can have the same named -commit-evidence being attached to the artifact through multiple git-commits. It is the last -reported version of the named commit-evidence that is considered the compliance state of that evidence. - -### Evidence outside the template -If an artifact has evidence, either commit evidence or artifact evidence, that is not -part of the template, the state of the extra evidence will affect the overall compliance of the artifact. - -## How to set compliant status of generic evidence - -The `--compliant` flag is a [boolean flag](#boolean-flags). -To report generic evidence as non-compliant use `--compliant=false`, as in this example: -```shell -kosli report evidence artifact generic server:1.0 \ - --artifact-type docker \ - --name test \ - --description "generic test evidence" \ - --compliant=false \ - --flow server -``` - -Keep in mind a number of flags, usually represented with environment variables, are omitted in this example. -`--compliance` flag is set to `true` by default, so if you want to report generic evidence as compliant, simply skip providing the flag altogether. - -## Boolean flags - -Flags with values can usually be specified with an `=` or with a **space** as a separator. -For example, `--artifact-type=file` or `--artifact-type file`. -However, an explicitly specified boolean flag value **must** use an `=`. -For example, if you try this: -``` -kosli attest generic Dockerfile --artifact-type file --compliant true ... -``` -You will get an error stating: -``` -Error: accepts at most 1 arg(s), received 2 -``` -Here, `--artifact-type file` is parsed as if it was `--artifact-type=file`, leaving: -``` -kosli attest generic Dockerfile --compliant true ... -``` -Then `--compliant` is parsed as if *implicitly* defaulting to `--compliant=true`, leaving: -``` -kosli attest generic Dockerfile true ... -``` -The parser then sees `Dockerfile` and `true` as the two -arguments to `kosli attest generic`. - -## Path/Image name is a single whitespace character! - -In order to calculate the fingerprint for an artifact, Kosli requires the path to the relevant file or directory, or the relevant image name. The command typically takes the form: -``` -kosli attest generic [IMAGE-NAME | FILE-PATH | DIR-PATH] [flags] -``` - -When using multi-line commands in the shell or a script, if the image name or path has not been provided as above and whitespace has unintentionally been added after the line-continuation backslash on one of the lines, this whitespace character is interpreted as the name or path. - -If you're using multi-line commands and receive an error message similar to this, check your command for extraneous whitespace: -``` -Error: failed to calculate artifact fingerprint: stat : no such file or directory. The directory path is ' '. -``` From 34b49e2401e1c80f371032d1ee529d6d39c9bb94 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Mon, 16 Mar 2026 22:46:22 +0100 Subject: [PATCH 6/9] feat: add Managing Custom Attestation Types page under Administration --- .../overview.md | 98 +++++++++++++++++++ docs.json | 6 ++ 2 files changed, 104 insertions(+) create mode 100644 administration/managing_custom_attestation_types/overview.md diff --git a/administration/managing_custom_attestation_types/overview.md b/administration/managing_custom_attestation_types/overview.md new file mode 100644 index 00000000..19f0f12f --- /dev/null +++ b/administration/managing_custom_attestation_types/overview.md @@ -0,0 +1,98 @@ +--- +title: Managing Custom Attestation Types +description: Learn how to manage Kosli custom attestation types via Terraform, including creating and importing types with JSON Schema and jq evaluation rules. +--- + +The preferred way to manage custom attestation types is via the Kosli Terraform provider, so your Kosli configuration is version-controlled alongside your infrastructure. You can also manage custom attestation types through the Kosli CLI. + + +This page covers managing custom attestation types via Terraform. For an introduction to custom attestation types and creating them via the CLI, see [Getting started: Attestations](/getting_started/attestations). + + +Custom attestation types define how Kosli validates evidence from tools that don't have a built-in Kosli attestation command. Each type can include: + +- A **JSON Schema** (optional) that defines the expected structure of attestation data +- **jq rules** (optional) that evaluate the data to determine compliance + +At least one of the two must be provided. + +## Create a custom attestation type + +### With schema and jq rules + +```hcl +resource "kosli_custom_attestation_type" "security_scan" { + name = "security-scan" + description = "Validates security scan results" + + schema = jsonencode({ + type = "object" + properties = { + critical_vulnerabilities = { type = "integer" } + high_vulnerabilities = { type = "integer" } + scan_date = { type = "string" } + } + required = ["critical_vulnerabilities", "high_vulnerabilities", "scan_date"] + }) + + jq_rules = [ + ".critical_vulnerabilities == 0", + ".high_vulnerabilities < 5" + ] +} +``` + +### With jq rules only + +```hcl +resource "kosli_custom_attestation_type" "code_coverage" { + name = "code-coverage" + description = "Requires at least 80% line coverage" + + jq_rules = [".line_coverage >= 80"] +} +``` + +### With schema only + +```hcl +resource "kosli_custom_attestation_type" "deployment_record" { + name = "deployment-record" + description = "Validates deployment record structure" + + schema = jsonencode({ + type = "object" + properties = { + deployed_by = { type = "string" } + deployed_at = { type = "string" } + environment = { type = "string" } + } + required = ["deployed_by", "deployed_at", "environment"] + }) +} +``` + +## Import an existing custom attestation type + +If you have custom attestation types created via the CLI, you can bring them under Terraform management by importing them into your Terraform state. + +1. Find the attestation type name in the Kosli UI or run: + +```shell +kosli list attestation-types +``` + +2. Add a matching `kosli_custom_attestation_type` resource block to your configuration. + +3. Run the import: + +```shell +terraform import kosli_custom_attestation_type.security_scan security-scan +``` + +4. Verify with `terraform plan` — no changes should be planned if the import succeeded. + +## Reference + +- [`kosli_custom_attestation_type` resource](/terraform-reference/resources/custom_attestation_type) +- [`kosli_custom_attestation_type` data source](/terraform-reference/data-sources/custom_attestation_type) diff --git a/docs.json b/docs.json index f90d9327..9c37275f 100644 --- a/docs.json +++ b/docs.json @@ -84,6 +84,12 @@ "pages": [ "administration/managing_environments/overview" ] + }, + { + "group": "Managing Custom Attestation Types", + "pages": [ + "administration/managing_custom_attestation_types/overview" + ] } ] }, From 84cdf02e78648be5970f2e61f8b0a5c16ef2767a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Mon, 16 Mar 2026 22:53:52 +0100 Subject: [PATCH 7/9] docs: add Terraform Registry links to provider index and custom attestation types pages --- administration/managing_custom_attestation_types/overview.md | 1 + terraform-reference/index.mdx | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/administration/managing_custom_attestation_types/overview.md b/administration/managing_custom_attestation_types/overview.md index 19f0f12f..08c7c089 100644 --- a/administration/managing_custom_attestation_types/overview.md +++ b/administration/managing_custom_attestation_types/overview.md @@ -96,3 +96,4 @@ terraform import kosli_custom_attestation_type.security_scan security-scan - [`kosli_custom_attestation_type` resource](/terraform-reference/resources/custom_attestation_type) - [`kosli_custom_attestation_type` data source](/terraform-reference/data-sources/custom_attestation_type) +- [Kosli Terraform provider on the Terraform Registry](https://registry.terraform.io/providers/kosli-dev/kosli/latest) diff --git a/terraform-reference/index.mdx b/terraform-reference/index.mdx index adb02cb8..b8ae264e 100644 --- a/terraform-reference/index.mdx +++ b/terraform-reference/index.mdx @@ -4,7 +4,7 @@ description: "Manage Kosli resources as Infrastructure-as-Code using Terraform." icon: "layer-group" --- -The Kosli provider allows you to manage Kosli resources as Infrastructure-as-Code using Terraform. Use it to define and manage custom attestation types and integrate Kosli into your compliance workflows. +The Kosli provider allows you to manage Kosli resources as Infrastructure-as-Code using Terraform. Use it to define and manage custom attestation types and integrate Kosli into your compliance workflows. The provider is officially registered at the [Terraform Registry](https://registry.terraform.io/providers/kosli-dev/kosli/latest). ## Example usage From 024b6d4258f66143d7496655bc7145c710cdb381 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Mon, 16 Mar 2026 22:55:20 +0100 Subject: [PATCH 8/9] docs: add Terraform version requirement to provider index --- terraform-reference/index.mdx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/terraform-reference/index.mdx b/terraform-reference/index.mdx index b8ae264e..3afe84c5 100644 --- a/terraform-reference/index.mdx +++ b/terraform-reference/index.mdx @@ -6,6 +6,11 @@ icon: "layer-group" The Kosli provider allows you to manage Kosli resources as Infrastructure-as-Code using Terraform. Use it to define and manage custom attestation types and integrate Kosli into your compliance workflows. The provider is officially registered at the [Terraform Registry](https://registry.terraform.io/providers/kosli-dev/kosli/latest). +## Requirements + +- Terraform >= 1.8 +- A Kosli account with API credentials + ## Example usage ```terraform From 1904d063cee832e81af732873619a35aefc2e117 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Mon, 16 Mar 2026 22:59:34 +0100 Subject: [PATCH 9/9] style: use cubes icon for Terraform Reference nav item --- docs.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 9c37275f..d0254bbb 100644 --- a/docs.json +++ b/docs.json @@ -417,7 +417,7 @@ }, { "item": "Terraform Reference", - "icon": "layer-group", + "icon": "cubes", "groups": [ { "group": "Provider",