diff --git a/docs.json b/docs.json index 4de7e53..9bb2dfd 100644 --- a/docs.json +++ b/docs.json @@ -473,7 +473,10 @@ "pages": [ "terraform-reference/resources/environment", "terraform-reference/resources/logical_environment", - "terraform-reference/resources/custom_attestation_type" + "terraform-reference/resources/custom_attestation_type", + "terraform-reference/resources/action", + "terraform-reference/resources/policy", + "terraform-reference/resources/policy_attachment" ] }, { @@ -481,7 +484,9 @@ "pages": [ "terraform-reference/data-sources/environment", "terraform-reference/data-sources/logical_environment", - "terraform-reference/data-sources/custom_attestation_type" + "terraform-reference/data-sources/custom_attestation_type", + "terraform-reference/data-sources/action", + "terraform-reference/data-sources/policy" ] } ] diff --git a/terraform-reference/data-sources/action.mdx b/terraform-reference/data-sources/action.mdx new file mode 100644 index 0000000..5c6651d --- /dev/null +++ b/terraform-reference/data-sources/action.mdx @@ -0,0 +1,50 @@ +--- +title: "kosli_action data source" +description: "Fetches details of an existing Kosli action." +icon: "database" +--- + +Fetches details of an existing Kosli action. + +Use this data source to reference existing actions and access metadata such as the environments being monitored and the trigger types configured. + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Query an existing action +data "kosli_action" "compliance_alerts" { + name = "compliance-alerts" +} + +output "action_number" { + description = "Server-assigned number of the action" + value = data.kosli_action.compliance_alerts.number +} + +output "action_environments" { + description = "Environments monitored by this action" + value = data.kosli_action.compliance_alerts.environments +} +``` + +## Schema + +### Required + +- `name` (String) The name of the action to query. + +### Read-only + +- `created_by` (String) User who created the action. +- `environments` (List of String) List of environment names this action monitors. +- `last_modified_at` (Number) Unix timestamp (with fractional seconds) of when the action was last modified. +- `number` (Number) Server-assigned numeric identifier for the action. +- `triggers` (List of String) List of trigger event types that activate this action. diff --git a/terraform-reference/data-sources/policy.mdx b/terraform-reference/data-sources/policy.mdx new file mode 100644 index 0000000..140da6f --- /dev/null +++ b/terraform-reference/data-sources/policy.mdx @@ -0,0 +1,49 @@ +--- +title: "kosli_policy data source" +description: "Fetches details of an existing Kosli policy." +icon: "database" +--- + +Fetches details of an existing Kosli policy. + +Use this data source to reference existing policies and access metadata such as the policy content, description, and latest version number. + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Query an existing policy +data "kosli_policy" "production" { + name = "prod-requirements" +} + +output "policy_latest_version" { + description = "Latest version number of the policy" + value = data.kosli_policy.production.latest_version +} + +output "policy_content" { + description = "YAML content of the latest policy version" + value = data.kosli_policy.production.content +} +``` + +## Schema + +### Required + +- `name` (String) The name of the policy to query. + +### Read-only + +- `content` (String) YAML content of the latest policy version. Null if the policy has no versions. +- `created_at` (Number) Unix timestamp of when the policy was first created. +- `description` (String) Description of the policy. +- `latest_version` (Number) The version number of the latest policy version. Null if the policy has no versions. diff --git a/terraform-reference/index.mdx b/terraform-reference/index.mdx index 53cc651..9302cac 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 environments, policies, actions, 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/docs). diff --git a/terraform-reference/resources/action.mdx b/terraform-reference/resources/action.mdx new file mode 100644 index 0000000..5eae4c1 --- /dev/null +++ b/terraform-reference/resources/action.mdx @@ -0,0 +1,65 @@ +--- +title: "kosli_action resource" +description: "Manages a Kosli action. Actions define webhook notifications triggered by environment compliance events." +icon: "cube" +--- + +Manages a Kosli action. Actions define webhook notifications triggered by environment compliance events. + + +Actions are identified internally by a server-assigned `number`. The `name` is used during import to look up the number. + + +Use this resource to configure automated notifications when environments change compliance state. Actions send webhooks to external services such as Slack or Microsoft Teams. + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Action that fires on non-compliant environment events +resource "kosli_action" "compliance_alerts" { + name = "compliance-alerts" + environments = ["production-k8s"] + triggers = ["ON_NON_COMPLIANT_ENV", "ON_COMPLIANT_ENV"] + webhook_url = "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX" +} + +# Action that fires on scaling events +resource "kosli_action" "scaling_alerts" { + name = "scaling-alerts" + environments = ["staging-ecs"] + triggers = ["ON_SCALED_ARTIFACT"] + webhook_url = "https://outlook.office.com/webhook/XXXX" +} +``` + +## Import + +Actions can be imported using their name: + +```shell +# Import an existing action by name +terraform import kosli_action.compliance_alerts compliance-alerts +``` + +## Schema + +### Required + +- `environments` (List of String) List of environment names this action monitors. +- `name` (String) Name of the action. Must be unique within the organization. Changing this will force recreation of the resource. +- `triggers` (List of String) List of trigger event types that activate this action (e.g. `ON_NON_COMPLIANT_ENV`, `ON_COMPLIANT_ENV`). +- `webhook_url` (String, Sensitive) Webhook URL to send notifications to. + +### Read-only + +- `created_by` (String) User who created the action. +- `last_modified_at` (Number) Unix timestamp of when the action was last modified. +- `number` (Number) Server-assigned numeric identifier for the action. diff --git a/terraform-reference/resources/environment.mdx b/terraform-reference/resources/environment.mdx index 0d22817..74e69e3 100644 --- a/terraform-reference/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](/terraform-reference/data-sources/environment). +This resource manages the environment configuration only. Environment tags are managed through a separate Kosli API. 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). Kosli environments track deployments and provide visibility into what's running in your infrastructure. Physical environments represent actual runtime locations such as: @@ -27,9 +27,9 @@ For aggregating multiple physical environments into logical groups, use the [`ko 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`). - + +To attach compliance policies to environments, use the [`kosli_policy_attachment` resource](/terraform-reference/resources/policy_attachment). + ## Example usage diff --git a/terraform-reference/resources/policy.mdx b/terraform-reference/resources/policy.mdx new file mode 100644 index 0000000..b4c1c56 --- /dev/null +++ b/terraform-reference/resources/policy.mdx @@ -0,0 +1,80 @@ +--- +title: "kosli_policy resource" +description: "Manages a Kosli policy. Policies define artifact compliance requirements that can be attached to environments." +icon: "cube" +--- + +Manages a Kosli policy. Policies define artifact compliance requirements (provenance, trail-compliance, attestations) that can be attached to environments. + +Policies are versioned and immutable: updating `content` or `description` creates a new version rather than modifying the existing one. + + +Deleting this resource removes it from Terraform state only. Kosli has no API endpoint to delete policies, so the policy will remain in Kosli after `terraform destroy`. To attach policies to environments, use the [`kosli_policy_attachment` resource](/terraform-reference/resources/policy_attachment). + + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Minimal policy requiring provenance for all artifacts +resource "kosli_policy" "minimal" { + name = "basic-requirements" + content = <<-YAML + _schema: https://kosli.com/schemas/policy/environment/v1 + artifacts: + provenance: + required: true + YAML +} + +# Production policy with full compliance requirements +resource "kosli_policy" "production" { + name = "prod-requirements" + description = "Compliance requirements for production environments" + content = <<-YAML + _schema: https://kosli.com/schemas/policy/environment/v1 + artifacts: + provenance: + required: true + trail-compliance: + required: true + attestations: + - name: unit-test + type: junit + - name: dependency-scan + type: "*" + YAML +} +``` + +## Import + +Policies can be imported using their name: + +```shell +# Import a policy by name. The content attribute is populated from the API response. +terraform import kosli_policy.example prod-requirements +``` + +## Schema + +### Required + +- `content` (String) YAML content of the policy, conforming to the Kosli policy schema (`_schema: https://kosli.com/schemas/policy/environment/v1`). Supports heredoc syntax for multi-line YAML. Updating this value creates a new policy version. +- `name` (String) Name of the policy. Must be unique within the organization. Changing this will force recreation of the resource. + +### Optional + +- `description` (String) Description of the policy. + +### Read-only + +- `created_at` (Number) Unix timestamp of when the policy was first created. +- `latest_version` (Number) The version number of the latest policy version. Null if the policy has no versions. diff --git a/terraform-reference/resources/policy_attachment.mdx b/terraform-reference/resources/policy_attachment.mdx new file mode 100644 index 0000000..89fda2f --- /dev/null +++ b/terraform-reference/resources/policy_attachment.mdx @@ -0,0 +1,48 @@ +--- +title: "kosli_policy_attachment resource" +description: "Attaches a Kosli policy to an environment. When this resource is destroyed, the policy is detached from the environment." +icon: "cube" +--- + +Attaches a Kosli policy to an environment (physical or logical). When this resource is destroyed, the policy is detached from the environment. + +Both `environment_name` and `policy_name` are immutable: changing either attribute will destroy the existing attachment and create a new one. + + +Both the policy and environment must exist before creating an attachment. Use the [`kosli_policy` resource](/terraform-reference/resources/policy) and [`kosli_environment` resource](/terraform-reference/resources/environment) to manage them. + + +## Example usage + +```terraform +terraform { + required_providers { + kosli = { + source = "kosli-dev/kosli" + } + } +} + +# Attach a policy to an environment. +# Both the policy and environment must exist before creating the attachment. +resource "kosli_policy_attachment" "example" { + environment_name = "my-environment" + policy_name = "my-policy" +} +``` + +## Import + +Policy attachments can be imported using the composite ID `environment_name/policy_name`: + +```shell +# Import a policy attachment using the composite ID: environment_name/policy_name +terraform import kosli_policy_attachment.example my-environment/my-policy +``` + +## Schema + +### Required + +- `environment_name` (String) Name of the environment to attach the policy to. Changing this will force recreation of the resource. +- `policy_name` (String) Name of the policy to attach. Changing this will force recreation of the resource.