terraform-provider-kosli

README

Terraform Provider for Kosli

[!WARNING] This is a provider under active development. Features and APIs might still change. Be careful using this provider in production environments, and it's recommended to pin it to specific versions to avoid breaking changes.

Manage Kosli resources using Terraform. This provider allows you to define and manage Kosli custom attestation types as Infrastructure-as-Code, enabling you to integrate proprietary tools, custom metrics, or specialized compliance requirements into your Kosli workflows.

The Terraform provider enables you to automate the management of Kosli resources alongside your infrastructure.

Requirements

• Terraform >= 1.10 (>= 1.14 for terraform query list resources)
• Go 1.26 or later (for development)
• Kosli account and API credentials

Quick Start

Installation

The provider is available on the Terraform Registry. Add it to your Terraform configuration:

terraform {
  required_providers {
    kosli = {
      source  = "kosli-dev/kosli"
      version = "~> 0.3"
    }
  }
}

provider "kosli" {
  api_token = var.kosli_api_token
  org       = var.kosli_org_name
  api_url   = "https://app.kosli.com"  # Optional, defaults to EU region
}

Basic Configuration

For complete examples with variables and multiple use cases, see the examples directory:

• Resource examples - Creating and managing resources
• Data source examples - Referencing existing resources
• List resource examples - Discovering existing resources with terraform query
• Complete examples - End-to-end scenarios

Documentation

Attestation Types

Attestation types are custom data structures that define how Kosli validates and evaluates evidence. They act as templates specifying:

• JSON Schema: Defines the structure and data types for attestation data
• Evaluation Rules: jq-formatted rules that must evaluate to true for compliance
• Naming Convention: Names must start with a letter/number and contain only letters, numbers, periods, hyphens, underscores, and tildes

Common use cases include:

• Security scan validation (e.g., no critical vulnerabilities)
• Test coverage requirements (e.g., minimum 80% coverage)
• Code quality checks (e.g., no failing tests)
• Custom compliance criteria specific to your organization

Full documentation is available on the Terraform Registry and in the docs/ directory.

For more details on attestation types, see the Kosli documentation.

Supported Resources

Resources

• kosli_custom_attestation_type - Create and manage custom attestation types
• kosli_environment - Create and manage physical environments (K8S, ECS, S3, docker, server, lambda)
• kosli_flow - Create and manage flows that represents a business or software process that requires change tracking. It allows you to monitor changes across all steps within a process or focus specifically on a subset of critical steps
• kosli_logical_environment - Create and manage logical environments that aggregate physical environments
• kosli_action - Create and manage actions that define webhook notifications triggered by environment compliance events
• kosli_policy - Create and manage policies, which define artifact compliance requirements (provenance, trail-compliance, attestations) that can be attached to environments
• kosli_policy_attachment - Attach a policy to an environment (physical or logical)
• kosli_service_account - Create and manage service accounts used to authenticate automation against the Kosli API
• kosli_service_account_api_key - Mint and revoke API keys for a service account
• kosli_control - Create and manage controls, org-level definitions of SDLC requirements evaluated from attestations and enforced through environment policies (beta feature)

Data Sources

• kosli_custom_attestation_type - Reference existing attestation types
• kosli_environment - Reference existing physical environments
• kosli_flow - Reference existing flows
• kosli_logical_environment - Reference existing logical environments
• kosli_action - Reference existing actions
• kosli_policy - Reference existing policies
• kosli_service_account - Reference existing service accounts
• kosli_service_account_api_keys - List the API keys (metadata only) for a service account
• kosli_control - Reference existing controls

List Resources (terraform query, Terraform >= 1.14)

• kosli_control - Discover existing (unmanaged) controls and generate import/config blocks for them (beta feature)

Place list blocks in a .tfquery.hcl file and run terraform query:

list "kosli_control" "all" {
  provider = kosli
}

list "kosli_control" "sdlc" {
  provider         = kosli
  include_resource = true

  config {
    search = "SDLC"
  }
}

Use terraform query -generate-config-out=generated.tf to bring the discovered controls under Terraform management.

Configuration

The Kosli provider requires authentication via API token and organization name.

Using Environment Variables (Recommended)

The recommended approach is to use environment variables, especially for sensitive credentials:

export KOSLI_API_TOKEN="your-api-token"
export KOSLI_ORG="your-org-name"
export KOSLI_API_URL="https://app.kosli.com"  # Optional, defaults to EU region

Then configure the provider without hardcoded credentials:

provider "kosli" {
  # Credentials are read from environment variables:
  # KOSLI_API_TOKEN, KOSLI_ORG, KOSLI_API_URL
}

Using Terraform Variables

Alternatively, use Terraform variables (ensure you manage secrets securely):

provider "kosli" {
  api_token = var.kosli_api_token  # Use secure variable management
  org       = var.kosli_org_name
  api_url   = "https://app.kosli.com"  # Optional, defaults to EU region
  timeout   = 30                        # Optional, defaults to 30s
}

Regional Endpoints

Kosli operates in two regions:

• EU Region (default): https://app.kosli.com
• US Region: https://app.us.kosli.com

Configure the appropriate endpoint based on where your Kosli organization is hosted.

Getting API Credentials

Recommended: Use Service Accounts

Service accounts provide secure, programmatic access to Kosli without tying credentials to individual users:

1. Log in to your Kosli account
2. Navigate to Settings → Service Accounts
3. Click Add New Service Account
4. Give it a descriptive name (e.g., "Terraform Automation")
5. Assign Admin permissions to the service account (required for managing environments and attestation types)
6. Click the "..." menu on the service account
7. Select Add API Key
8. Copy the API key and store it securely

[!IMPORTANT] The Terraform provider requires a Service Account with Admin permissions to manage Kosli resources.

Store credentials securely:

• Use environment variables (see Configuration above)
• For CI/CD: Use your platform's secrets management (GitHub Secrets, GitLab CI/CD variables, etc.)
• For local development: Use a .envrc file (with direnv) or similar - never commit credentials to version control

Contributing

We welcome contributions! Whether you're fixing a bug, adding a feature, or improving documentation, your help is appreciated.

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Make your changes and add tests
4. Run make fmt && make vet && make test
5. Submit a pull request

Development Guide

For comprehensive development information, see CONTRIBUTING.md:

• Development environment setup - Prerequisites and dependencies
• Building and testing - Make commands and workflows
• Code quality standards - Formatting, linting, and best practices
• Pull request process - Detailed submission guidelines and review timeline
• Project structure - Directory organization and architecture
• Release process - How releases are created and published

Common Development Commands

make help         # View all available commands
make build        # Build the provider
make test         # Run unit tests with coverage
make testacc      # Run acceptance tests
make install      # Install locally for testing

Getting Help

• Questions: GitHub Discussions
• Bug reports: GitHub Issues
• Community: Kosli Community

Roadmap

See GitHub Issues for detailed feature tracking.

Troubleshooting

Authentication Errors

Verify your API token and organization are valid:

# For EU region (default)
curl -H "Authorization: Bearer $KOSLI_API_TOKEN" https://app.kosli.com/api/v2/environments/$KOSLI_ORG

# For US region
curl -H "Authorization: Bearer $KOSLI_API_TOKEN" https://app.us.kosli.com/api/v2/environments/$KOSLI_ORG

API Timeouts

Increase the timeout if you're experiencing timeout errors:

provider "kosli" {
  api_token = var.kosli_api_token
  timeout   = 60  # seconds
}

Resource State Issues

If Terraform state becomes out of sync with Kosli:

terraform refresh

Support

• Documentation: https://docs.kosli.com
• Issues: GitHub Issues
• Community: Kosli Slack Community
• Email: support@kosli.com

License

This provider is released under the MIT License.

About Kosli

Kosli is a software intelligence platform that helps teams maintain visibility and governance over their Software Delivery Lifecycle (SDLC).