Warning
This is an early-stage provider under active development. Features and APIs may change. We recommend not to use this provider in production environments yet, and to pin to specific versions when you do.
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.
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
}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
- Complete examples - End-to-end scenarios
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
truefor 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.
kosli_custom_attestation_type- Create and manage custom attestation typeskosli_environment- Create and manage physical environments (K8S, ECS, S3, docker, server, lambda)kosli_logical_environment- Create and manage logical environments that aggregate physical environmentskosli_action- Create and manage actions that define webhook notifications triggered by environment compliance eventskosli_policy- Create and manage policies, which define artifact compliance requirements (provenance, trail-compliance, attestations) that can be attached to environmentskosli_policy_attachment- Attach a policy to an environment (physical or logical)
kosli_custom_attestation_type- Reference existing attestation typeskosli_environment- Reference existing physical environmentskosli_logical_environment- Reference existing logical environmentskosli_action- Reference existing actionskosli_policy- Reference existing policies
The Kosli provider requires authentication via API token and organization name.
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 regionThen configure the provider without hardcoded credentials:
provider "kosli" {
# Credentials are read from environment variables:
# KOSLI_API_TOKEN, KOSLI_ORG, KOSLI_API_URL
}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
}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.
Recommended: Use Service Accounts
Service accounts provide secure, programmatic access to Kosli without tying credentials to individual users:
- Log in to your Kosli account
- Navigate to Settings → Service Accounts
- Click Add New Service Account
- Give it a descriptive name (e.g., "Terraform Automation")
- Assign Admin permissions to the service account (required for managing environments and attestation types)
- Click the "..." menu on the service account
- Select Add API Key
- 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
.envrcfile (with direnv) or similar - never commit credentials to version control
We welcome contributions! Whether you're fixing a bug, adding a feature, or improving documentation, your help is appreciated.
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Make your changes and add tests
- Run
make fmt && make vet && make test - Submit a pull request
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
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- Questions: GitHub Discussions
- Bug reports: GitHub Issues
- Community: Kosli Community
See GitHub Issues for detailed feature tracking.
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_ORGIncrease the timeout if you're experiencing timeout errors:
provider "kosli" {
api_token = var.kosli_api_token
timeout = 60 # seconds
}If Terraform state becomes out of sync with Kosli:
terraform refresh- Documentation: https://docs.kosli.com
- Issues: GitHub Issues
- Community: Kosli Slack Community
- Email: support@kosli.com
This provider is released under the MIT License.
Kosli is a software intelligence platform that helps teams maintain visibility and governance over their Software Delivery Lifecycle (SDLC). Learn more at kosli.com.