docs: update Terraform reference - service accounts and controls (v0.7.0, v0.8.0)

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"
               ]
             }
           ]

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.
+
+<Warning>
+Controls is a **beta** feature and must be enabled for your organization; API requests return `403 Forbidden` otherwise.
+</Warning>
+
+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.

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`).

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.
+
+<Warning>
+Controls is a **beta** feature and must be enabled for your organization; API requests return `403 Forbidden` otherwise.
+</Warning>
+
+<Note>
+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.
+</Note>
+
+## 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.

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).
+
+<Note>
+Service accounts cannot be created in personal organizations. Only organization admins or the user who created the service account can manage it.
+</Note>
+
+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.