diff --git a/terraform-reference/index.mdx b/terraform-reference/index.mdx index 9302cac..e12a852 100644 --- a/terraform-reference/index.mdx +++ b/terraform-reference/index.mdx @@ -60,6 +60,14 @@ To create an API token: API tokens grant full access to your Kosli organization. Store them securely and never commit them to version control. +### Required permissions + +Use a token that belongs to a user or service account with the **Admin** role. + +Some provider operations are restricted to admins. Destroying a `kosli_environment` or `kosli_logical_environment` archives the environment in Kosli, and archiving requires the Admin role. With a Member token, `terraform apply` can create and update environments. However, `terraform destroy` (or removing the resource from your configuration) fails with `403 Forbidden` and the resource stays in state. + +The recommended setup is a dedicated service account with the `admin` privilege and an API key minted for it. You can create both in the Kosli UI under **Settings** → **Service Accounts**, or with the [`kosli_service_account`](/terraform-reference/resources/service_account) and [`kosli_service_account_api_key`](/terraform-reference/resources/service_account_api_key) resources. The initial bootstrap with these resources must itself run with an Admin token, because a service account cannot be granted a higher privilege than the caller's. + ## Regional endpoints Kosli operates in multiple regions. Configure the `api_url` to match your organization's region: @@ -67,11 +75,23 @@ Kosli operates in multiple regions. Configure the `api_url` to match your organi - **EU (Default)**: `https://app.kosli.com` - **US**: `https://app.us.kosli.com` +The `api_url` must use `https`. Plain `http` is only accepted for localhost. + +## Telemetry + +Alongside the `User-Agent`, every request the provider sends to Kosli carries these headers, which Kosli uses to understand how the provider is used: + +- `X-Kosli-Client`: the provider name and version, for example `terraform/v0.11.0` +- `X-Kosli-Operation`: the resource, data source, or list resource type and the operation, for example `kosli_environment create` or `data.kosli_flow read` +- `X-Kosli-Invocation-Id`: a random ID generated each time Terraform starts the provider, which groups the requests from that run + +These headers contain only type names and operation names. The provider never sends configuration values, such as resource names, URLs, or IDs, in these headers. + ## 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. +- `api_url` (String) Kosli API endpoint URL. Defaults to https://app.kosli.com (EU region). Use https://app.us.kosli.com for US region. Must use https; plain http is only accepted for localhost. 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/terraform-reference/resources/environment.mdx b/terraform-reference/resources/environment.mdx index 6252b59..ddb6044 100644 --- a/terraform-reference/resources/environment.mdx +++ b/terraform-reference/resources/environment.mdx @@ -10,6 +10,10 @@ Manages a Kosli environment. Environments represent deployment targets where art This resource manages the environment configuration and tags. To attach compliance policies, use the [`kosli_policy_attachment` resource](/terraform-reference/resources/policy_attachment). 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). + +Destroying this resource archives the environment in Kosli. Archiving requires an API token with the **Admin** role. A Member token can create and update environments, but `terraform destroy` fails with `403 Forbidden`. + + 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 @@ -118,6 +122,14 @@ terraform import kosli_environment.staging_ecs staging-ecs terraform import kosli_environment.data_lake data-lake-s3 ``` +## Destroying environments + +Kosli never hard-deletes environments. When you run `terraform destroy` or remove a `kosli_environment` from your configuration, the provider archives the environment. The environment disappears from the environment list in Kosli, but Kosli keeps its snapshot history. + + +Archiving an environment requires a Kosli API token with the **Admin** role. A token with the Member role can create and update environments but cannot archive them. In that case, `terraform destroy` fails with `403 Forbidden` and the resource stays in state. If you cannot use an Admin token and only want Terraform to stop managing the environment, run `terraform state rm kosli_environment.` instead. The environment then remains active in Kosli. See [required permissions](/terraform-reference#required-permissions) for how to set up a service account with the right permissions. + + ## Monitoring environments 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. diff --git a/terraform-reference/resources/logical_environment.mdx b/terraform-reference/resources/logical_environment.mdx index 0ed87c9..cf1d0a4 100644 --- a/terraform-reference/resources/logical_environment.mdx +++ b/terraform-reference/resources/logical_environment.mdx @@ -14,6 +14,10 @@ Logical environments can ONLY contain physical environments (K8S, ECS, S3, docke This resource manages logical environment configuration and tags. 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). + +Destroying this resource archives the logical environment in Kosli. Archiving requires an API token with the **Admin** role. A Member token can create and update logical environments, but `terraform destroy` fails with `403 Forbidden`. + + Logical environments in Kosli aggregate multiple physical environments for organizational purposes, providing: - **Unified visibility**: View compliance status across multiple environments at once @@ -196,6 +200,14 @@ terraform import kosli_logical_environment.cloud_services cloud-services terraform import kosli_logical_environment.future_environments future-environments ``` +## Destroying logical environments + +Kosli never hard-deletes environments. When you run `terraform destroy` or remove a `kosli_logical_environment` from your configuration, the provider archives the logical environment. The physical environments it included are not affected. + + +Archiving an environment requires a Kosli API token with the **Admin** role. A token with the Member role can create and update logical environments but cannot archive them. In that case, `terraform destroy` fails with `403 Forbidden` and the resource stays in state. If you cannot use an Admin token and only want Terraform to stop managing the logical environment, run `terraform state rm kosli_logical_environment.` instead. The logical environment then remains active in Kosli. See [required permissions](/terraform-reference#required-permissions) for how to set up a service account with the right permissions. + + ## Querying metadata ## Schema