From f7d54baa80bdc1057a6e7eba8ce0e200d528ad3f Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 10 Jul 2026 09:41:23 +0000 Subject: [PATCH] docs: add Terraform reference pages for service accounts and controls --- config/navigation.json | 9 +- terraform-reference/data-sources/control.mdx | 84 +++++++++++++++++ .../data-sources/service_account.mdx | 67 +++++++++++++ terraform-reference/resources/control.mdx | 82 ++++++++++++++++ .../resources/service_account.mdx | 80 ++++++++++++++++ .../resources/service_account_api_key.mdx | 94 +++++++++++++++++++ 6 files changed, 414 insertions(+), 2 deletions(-) create mode 100644 terraform-reference/data-sources/control.mdx create mode 100644 terraform-reference/data-sources/service_account.mdx create mode 100644 terraform-reference/resources/control.mdx create mode 100644 terraform-reference/resources/service_account.mdx create mode 100644 terraform-reference/resources/service_account_api_key.mdx diff --git a/config/navigation.json b/config/navigation.json index 25b00a7..c45cf0c 100644 --- a/config/navigation.json +++ b/config/navigation.json @@ -499,7 +499,10 @@ "terraform-reference/resources/custom_attestation_type", "terraform-reference/resources/action", "terraform-reference/resources/policy", - "terraform-reference/resources/policy_attachment" + "terraform-reference/resources/policy_attachment", + "terraform-reference/resources/service_account", + "terraform-reference/resources/service_account_api_key", + "terraform-reference/resources/control" ] }, { @@ -510,7 +513,9 @@ "terraform-reference/data-sources/flow", "terraform-reference/data-sources/custom_attestation_type", "terraform-reference/data-sources/action", - "terraform-reference/data-sources/policy" + "terraform-reference/data-sources/policy", + "terraform-reference/data-sources/service_account", + "terraform-reference/data-sources/control" ] } ] diff --git a/terraform-reference/data-sources/control.mdx b/terraform-reference/data-sources/control.mdx new file mode 100644 index 0000000..6467052 --- /dev/null +++ b/terraform-reference/data-sources/control.mdx @@ -0,0 +1,84 @@ +--- +title: "kosli_control data source" +description: "Fetches details of an existing Kosli control. Use this data source to reference controls and access metadata such as the version, tags, and referencing policies." +icon: "database" +--- + +Fetches details of an existing Kosli control. Use this data source to reference controls and access metadata such as the version, tags, and referencing policies. + + +Controls is a **beta** feature and must be enabled for your organization; API requests return `403 Forbidden` otherwise. + + +Use this data source to: + +- Reference an existing control managed outside Terraform +- Read control metadata such as `version`, `tags`, and `policies_referencing` +- Read a specific historical version of a control's `name`, `description`, and `links` +- Read a previously-archived control by opting in with `archived = true` + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Create a control +resource "kosli_control" "binary_provenance" { + identifier = "SDLC-001" + name = "Binary provenance" + description = "All production artifacts must have build provenance attestations" +} + +# Look up the control via data source +data "kosli_control" "binary_provenance" { + identifier = kosli_control.binary_provenance.identifier +} + +# Reference control metadata +output "control_version" { + description = "Current version of the control" + value = data.kosli_control.binary_provenance.version +} + +output "control_policies" { + description = "Environment policies referencing the control" + value = data.kosli_control.binary_provenance.policies_referencing +} + +output "control_tags" { + description = "Tags on the control" + value = data.kosli_control.binary_provenance.tags +} +``` + +## Read-only access + +Data sources provide read-only access to control metadata. To create or modify controls, use the [`kosli_control` resource](/terraform-reference/resources/control). + +## Schema + +### Required + +- `identifier` (String) The unique identifier of the control to query (e.g. `SDLC-001`). + +### Optional + +- `archived` (Boolean) Whether the control is archived. Deleting a `kosli_control` resource archives the control rather than hard-deleting it, and by default reading an archived control fails as if it did not exist. Set to `true` to read an archived control. Defaults to `false`. +- `version` (Number) Version of the control to read. Every update to a control creates a new version; set this to read the `name`, `description`, and `links` of a specific version. Defaults to the latest version. + +### Read-only + +- `created_at` (String) RFC3339 UTC timestamp of when the control was created. When `version` is set, this is when that version was created. +- `created_by` (String) Identifier of the user who created the control. When `version` is set, this is who created that version. +- `description` (String) The description of the control. +- `links` (Map of String) Named links related to the control, as a map of link name to URL. +- `name` (String) Human-readable display name of the control. +- `policies_referencing` (List of String) Names of the environment policies that reference this control. +- `status` (String) Status of the requested version (e.g. `created`). Only populated when `version` is set; the latest-control endpoint does not report a status. +- `tags` (Map of String) Tags on the control, as a map of tag key to value. diff --git a/terraform-reference/data-sources/service_account.mdx b/terraform-reference/data-sources/service_account.mdx new file mode 100644 index 0000000..769ded7 --- /dev/null +++ b/terraform-reference/data-sources/service_account.mdx @@ -0,0 +1,67 @@ +--- +title: "kosli_service_account data source" +description: "Fetches details of an existing Kosli service account. Use this data source to reference service accounts and access metadata such as the privilege, creator, and creation timestamp." +icon: "database" +--- + +Fetches details of an existing Kosli service account. Use this data source to reference service accounts and access metadata such as the privilege, creator, and creation timestamp. + +Use this data source to: + +- Reference an existing service account managed outside Terraform +- Read the granted privilege, creating user, and creation timestamp +- Build conditional logic based on service account metadata + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Create a service account +resource "kosli_service_account" "ci" { + name = "ci-pipeline" + description = "CI/CD pipeline service account" + privilege = "member" +} + +# Look up the service account via data source +data "kosli_service_account" "ci" { + name = kosli_service_account.ci.name +} + +# Reference service account metadata +output "ci_privilege" { + description = "Privilege (role) of the CI service account" + value = data.kosli_service_account.ci.privilege +} + +output "ci_created_at" { + description = "RFC3339 UTC timestamp of when the service account was created" + value = data.kosli_service_account.ci.created_at +} +``` + +## Read-only access + +Data sources provide read-only access to service account metadata. To create or modify service accounts, use the [`kosli_service_account` resource](/terraform-reference/resources/service_account). To manage API keys, use the [`kosli_service_account_api_key` resource](/terraform-reference/resources/service_account_api_key). + +## Schema + +### Required + +- `name` (String) The name of the service account to query. + +### Read-only + +- `created_at` (String) RFC3339 UTC timestamp of when the service account was created. +- `creating_user_id` (String) Identifier of the user who created the service account. +- `description` (String) The description of the service account. +- `display_name` (String) The display name of the service account. +- `for_webhook` (Boolean) Whether the service account was created for webhook usage. +- `privilege` (String) The privilege (role) of the service account within the organization (`admin`, `member`, `snapshotter`, or `reader`). diff --git a/terraform-reference/resources/control.mdx b/terraform-reference/resources/control.mdx new file mode 100644 index 0000000..588ccc3 --- /dev/null +++ b/terraform-reference/resources/control.mdx @@ -0,0 +1,82 @@ +--- +title: "kosli_control resource" +description: "Manages a Kosli control. Controls are org-level definitions of SDLC requirements whose compliance is evaluated from attestations and enforced through environment policies." +icon: "cube" +--- + +Manages a Kosli control. Controls are org-level definitions of SDLC requirements (for example `SDLC-001` "Binary provenance") whose compliance is evaluated from attestations and enforced through environment policies. + + +Controls is a **beta** feature and must be enabled for your organization; API requests return `403 Forbidden` otherwise. + + + +Deleting this resource **archives** the control in Kosli rather than hard-deleting it. Creating a new control with the identifier of an archived control fails with a conflict; unarchive the control in Kosli and import it instead. + + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Control requiring binary provenance for production artifacts +resource "kosli_control" "binary_provenance" { + identifier = "SDLC-001" + name = "Binary provenance" + description = "All production artifacts must have build provenance attestations" + + links = { + docs = "https://example.com/sdlc/binary-provenance" + } + + tags = { + framework = "finos-sdlc" + team = "platform" + } +} + +# Minimal control with only the required attributes +resource "kosli_control" "peer_review" { + identifier = "SDLC-002" + name = "Peer review" +} +``` + +## Import + +Controls can be imported using their identifier: + +```shell +# Import an existing control by identifier +terraform import kosli_control.binary_provenance SDLC-001 +``` + +## Querying controls + +To reference an existing control and access metadata such as the current version, tags, and referencing policies, use the [`kosli_control` data source](/terraform-reference/data-sources/control). + +## Schema + +### Required + +- `identifier` (String) Unique identifier of the control within the organization (e.g. `SDLC-001`). Must start with a letter or number and contain only letters, numbers, periods (`.`), hyphens (`-`), underscores (`_`), and tildes (`~`). Changing this will force recreation of the resource. +- `name` (String) Human-readable display name of the control (e.g. `Binary provenance`). Can be changed without recreating the control. + +### Optional + +- `description` (String) Free-form description of the control. +- `links` (Map of String) Named links related to the control (e.g. documentation or runbook URLs), as a map of link name to URL. +- `tags` (Map of String) Key-value pairs to tag the control. + +### Read-only + +- `created_at` (String) RFC3339 UTC timestamp of when the control was created. +- `created_by` (String) Identifier of the user who created the control. +- `policies_referencing` (List of String) Names of the environment policies that reference this control. +- `version` (Number) Version number of the control, assigned by the server and incremented on every update. diff --git a/terraform-reference/resources/service_account.mdx b/terraform-reference/resources/service_account.mdx new file mode 100644 index 0000000..984d70b --- /dev/null +++ b/terraform-reference/resources/service_account.mdx @@ -0,0 +1,80 @@ +--- +title: "kosli_service_account resource" +description: "Manages a Kosli service account. Service accounts are non-human identities used to authenticate automation (such as CI/CD pipelines) against the Kosli API." +icon: "cube" +--- + +Manages a Kosli service account. Service accounts are non-human identities used to authenticate automation (such as CI/CD pipelines) against the Kosli API. API keys for a service account are managed separately via the [`kosli_service_account_api_key` resource](/terraform-reference/resources/service_account_api_key). + + +Service accounts cannot be created in personal organizations. Only organization admins or the user who created the service account can manage it. + + +Use this resource to manage the lifecycle of a service account. To mint API keys, use the [`kosli_service_account_api_key` resource](/terraform-reference/resources/service_account_api_key). To look up an existing service account's metadata, use the [`kosli_service_account` data source](/terraform-reference/data-sources/service_account). + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Service account for a CI/CD pipeline +resource "kosli_service_account" "ci" { + name = "ci-pipeline" + description = "CI/CD pipeline service account" + privilege = "member" +} + +# Read-only service account (e.g. for dashboards) +resource "kosli_service_account" "dashboard" { + name = "dashboard-readonly" + privilege = "reader" +} +``` + +## Privileges + +The `privilege` attribute must be one of the following: + +- `admin` — Full administrative access +- `member` — Standard read/write access +- `snapshotter` — May report environment snapshots +- `reader` — Read-only access + +You can only create a service account with a privilege equal to or lower than your own. + +## Import + +Service accounts can be imported using their name: + +```shell +# Import an existing service account by name +terraform import kosli_service_account.ci ci-pipeline +``` + +## Managing API keys + +To mint API keys for a service account, use the [`kosli_service_account_api_key` resource](/terraform-reference/resources/service_account_api_key). To look up an existing service account's metadata, use the [`kosli_service_account` data source](/terraform-reference/data-sources/service_account). + +## Schema + +### Required + +- `name` (String) Name of the service account. Must be unique within the organization, contain only alphanumeric characters and hyphens (`^[a-zA-Z0-9\-]+$`), and be at most 64 characters. Changing this will force recreation of the resource. +- `privilege` (String) Privilege (role) granted to the service account within the organization. Valid values: `admin`, `member`, `snapshotter`, `reader`. You can only create a service account with a privilege equal to or lower than your own. + +### Optional + +- `description` (String) Free-form description of the service account. + +### Read-only + +- `created_at` (String) RFC3339 UTC timestamp of when the service account was created. +- `creating_user_id` (String) Identifier of the user who created the service account. +- `display_name` (String) Display name of the service account, assigned by the server. +- `for_webhook` (Boolean) Whether the service account was created for webhook usage. diff --git a/terraform-reference/resources/service_account_api_key.mdx b/terraform-reference/resources/service_account_api_key.mdx new file mode 100644 index 0000000..7058966 --- /dev/null +++ b/terraform-reference/resources/service_account_api_key.mdx @@ -0,0 +1,94 @@ +--- +title: "kosli_service_account_api_key resource" +description: "Manages an API key for a Kosli service account. The raw key value is returned only once, at creation time, and is stored in Terraform state as a sensitive value." +icon: "key" +--- + +Manages an API key for a Kosli service account. API keys authenticate a service account against the Kosli API. Use this resource to mint and revoke keys for a service account managed with the [`kosli_service_account` resource](/terraform-reference/resources/service_account). + + +The raw `key` value is returned **only once**, at creation time, and is stored in Terraform state as a sensitive value. It is SHA-256 hashed server-side and can never be retrieved again — protect your Terraform state accordingly. + + + +API keys are immutable. Changing `description`, `expires_at`, or `service_account_name` revokes the existing key and creates a new one. On `terraform import`, the `key` attribute cannot be populated because the raw value is not retrievable. + + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Service account that the API key belongs to +resource "kosli_service_account" "ci" { + name = "ci-pipeline" + description = "CI/CD pipeline service account" + privilege = "member" +} + +# A non-expiring API key +resource "kosli_service_account_api_key" "ci_key" { + service_account_name = kosli_service_account.ci.name + description = "Production CI key" +} + +# An API key that expires (RFC3339 timestamp) +resource "kosli_service_account_api_key" "ci_key_expiring" { + service_account_name = kosli_service_account.ci.name + description = "Temporary CI key" + expires_at = "2100-01-01T00:00:00Z" +} + +# The raw key is only available on creation and is sensitive +output "ci_api_key" { + value = kosli_service_account_api_key.ci_key.key + sensitive = true +} +``` + +## Expiry + +The `expires_at` attribute is an RFC3339 timestamp, e.g. `2100-01-01T00:00:00Z` (offsets such as `+01:00` are accepted and normalized to UTC). Omit it for a key that never expires. The timestamp must not be in the past. + +To derive dates dynamically, use Terraform's built-in functions, e.g. `timeadd("2026-01-01T00:00:00Z", "8760h")`. + + +All timestamps (`expires_at`, `created_at`, `last_used_at`) are RFC3339 UTC strings. `last_used_at` is null for a key that has never been used; `expires_at` is null for a key that never expires. + + +## Import + +API keys can be imported using the `/` format: + +```shell +# Import an existing API key using the "/" format. +# Note: the raw key value cannot be recovered on import (it is only returned once +# at creation), so the "key" attribute will be empty after import. +terraform import kosli_service_account_api_key.ci_key ci-pipeline/01HXYZ0123456789ABCDEFGHIJ +``` + +Because the raw key value is only returned at creation time, the `key` attribute is empty after an import. + +## Schema + +### Required + +- `description` (String) Description of the API key (at least one character). Changing this forces creation of a new key. +- `service_account_name` (String) Name of the service account this API key belongs to. Changing this forces creation of a new key. + +### Optional + +- `expires_at` (String) RFC3339 timestamp at which the key expires, e.g. `2100-01-01T00:00:00Z` (offsets allowed; whole seconds only). Omit for a key that never expires. Must not be in the past (validated server-side at apply time). Changing this forces creation of a new key. Removing a previously set value from configuration leaves the existing expiry unchanged; to get a non-expiring key again, the key must be recreated (e.g. via `terraform taint` or by changing another argument). + +### Read-only + +- `created_at` (String) RFC3339 UTC timestamp of when the API key was created. +- `id` (String) Server-assigned identifier of the API key. +- `key` (String, Sensitive) The raw API key value. Only available at creation time and stored as a sensitive value. Empty when the resource is imported. +- `last_used_at` (String) RFC3339 UTC timestamp of when the API key was last used. Null if the key has never been used.