kosli_logical_environment resource

Manages a Kosli logical environment. Logical environments aggregate multiple physical environments for organizational purposes.

Logical environments can ONLY contain physical environments (K8S, ECS, S3, docker, server, lambda), not other logical environments. Attempting to include a logical environment will result in an error from the Kosli API.

This resource manages logical environment configuration and tags. For querying environment metadata such as last_modified_at and archived status, use the kosli_logical_environment data source.

Destroying this resource archives the logical environment in Kosli. Archiving requires an API token with the Admin role. A Member token can create and update logical environments, but terraform destroy fails with 403 Forbidden.

Changing name renames the logical environment in place, the same as kosli rename environment. The logical environment keeps its identity and history. The old name keeps resolving to the renamed environment until another environment is created with, or renamed to, that name. See Renaming logical environments.

Logical environments in Kosli aggregate multiple physical environments for organizational purposes, providing:

Unified visibility: View compliance status across multiple environments at once
Flexible grouping: Organize environments by region, service type, tier, or team
Simplified reporting: Generate compliance reports for logical groupings
Team organization: Allow different teams to focus on specific environment groups

Physical environments only

Example usage

terraform {
  required_providers {
    kosli = {
      source = "kosli-dev/kosli"
    }
  }
}

# First, create physical environments that will be aggregated
resource "kosli_environment" "production_k8s" {
  name        = "production-k8s"
  type        = "K8S"
  description = "Production Kubernetes cluster"
}

resource "kosli_environment" "production_ecs" {
  name        = "production-ecs"
  type        = "ECS"
  description = "Production ECS cluster"
}

resource "kosli_environment" "production_lambda" {
  name        = "production-lambda"
  type        = "lambda"
  description = "Production Lambda functions"
}

# Basic logical environment aggregating production environments
resource "kosli_logical_environment" "production_all" {
  name        = "production-aggregate"
  description = "Aggregates all production environments for unified visibility"

  included_environments = [
    kosli_environment.production_k8s.name,
    kosli_environment.production_ecs.name,
    kosli_environment.production_lambda.name,
  ]
}

# Logical environment with just two environments
resource "kosli_logical_environment" "cloud_services" {
  name        = "cloud-services"
  description = "All cloud-based services"

  included_environments = [
    kosli_environment.production_ecs.name,
    kosli_environment.production_lambda.name,
  ]
}

# Minimal logical environment with empty list (can be populated later)
resource "kosli_logical_environment" "future_environments" {
  name                  = "future-environments"
  included_environments = []
}

# Logical environment with tags
resource "kosli_logical_environment" "tagged" {
  name        = "production-tagged"
  description = "Tagged production logical environment"

  included_environments = [
    kosli_environment.production_k8s.name,
    kosli_environment.production_ecs.name,
  ]

  tags = {
    managed-by  = "terraform"
    environment = "production"
    team        = "platform"
  }
}

# Logical environment without description (optional)
resource "kosli_logical_environment" "simple" {
  name = "simple-aggregate"

  included_environments = [
    kosli_environment.production_k8s.name,
  ]
}

Complete example

For a comprehensive example showing logical environments aggregating physical environments by region, service type, and tier, see the complete logical environments example.

Common use cases

By environment tier

Aggregate all production or staging environments for unified compliance reporting:

resource "kosli_logical_environment" "production_all" {
  name        = "production-all"
  description = "All production environments"

  included_environments = [
    kosli_environment.prod_k8s.name,
    kosli_environment.prod_ecs.name,
    kosli_environment.prod_lambda.name,
  ]
}

By geographic region

Group environments by region for regional compliance or disaster recovery:

resource "kosli_logical_environment" "production_us_east" {
  name        = "production-us-east"
  description = "All production environments in US East"

  included_environments = [
    kosli_environment.prod_k8s_us_east.name,
    kosli_environment.prod_ecs_us_east.name,
  ]
}

By service type

Organize environments by technology stack or service type:

resource "kosli_logical_environment" "all_kubernetes" {
  name        = "all-kubernetes-clusters"
  description = "All Kubernetes clusters across regions"

  included_environments = [
    kosli_environment.k8s_us_east.name,
    kosli_environment.k8s_eu_west.name,
    kosli_environment.k8s_ap_south.name,
  ]
}

Empty logical environments

Logical environments can be created with empty included_environments lists and populated later:

resource "kosli_logical_environment" "future_environments" {
  name                  = "planned-expansion"
  description           = "Placeholder for future environments"
  included_environments = []
}

Import

Logical environments can be imported using their name:

#!/bin/bash

# Import an existing logical environment by name
terraform import kosli_logical_environment.production_all production-aggregate

# Import multiple logical environments
terraform import kosli_logical_environment.cloud_services cloud-services
terraform import kosli_logical_environment.future_environments future-environments

Renaming logical environments

Changing name renames the logical environment in place, the same as kosli rename environment. The logical environment keeps its identity, snapshot history, included environments and tags, and the plan shows an update rather than a replacement. After a rename, the old name still resolves to the renamed logical environment for both reads and writes. The old name stops resolving once another environment is created with, or renamed to, that name. Terraform has no ordering between two resources that are both renamed in one plan. If one resource takes the name another is giving up, such as a to b together with b to c, or a swap, the rename that runs first can hit a name that still exists. Apply chained renames in separate steps.

Destroying logical environments

Kosli never hard-deletes environments. When you run terraform destroy or remove a kosli_logical_environment from your configuration, the provider archives the logical environment. The physical environments it included are not affected.

Archiving an environment requires a Kosli API token with the Admin role. A token with the Member role can create and update logical environments but cannot archive them. In that case, terraform destroy fails with 403 Forbidden and the resource stays in state. If you cannot use an Admin token and only want Terraform to stop managing the logical environment, run terraform state rm kosli_logical_environment.<name> instead. The logical environment then remains active in Kosli. See required permissions for how to set up a service account with the right permissions.

Querying metadata

Schema

Required

included_environments (List of String) List of physical environment names to aggregate. Only physical environments are allowed (K8S, ECS, S3, docker, server, lambda). Can be empty.
name (String) Name of the logical environment. Must be unique within the organization. Changing this renames the logical environment in place, keeping its snapshot history. The old name keeps resolving to the renamed environment until another environment is created with, or renamed to, that name.

Optional

description (String) Description of the logical environment. Explains the purpose and aggregation strategy.
tags (Map of String) Key-value pairs to tag the logical environment. Tags are applied via a diff — only changed tags are sent to the API. An empty map (tags = {}) removes all tags.

Read-only

type (String) Type of the environment. Always set to logical (computed by provider, not user-configurable).

Provider

Resources

Data sources

List resources

kosli_logical_environment resource

Physical environments only

Example usage

Complete example

Common use cases

By environment tier

By geographic region

By service type

Empty logical environments

Import

Renaming logical environments

Destroying logical environments

Querying metadata

Schema

Required

Optional

Read-only

​Physical environments only

​Example usage

​Complete example

​Common use cases

​By environment tier

​By geographic region

​By service type

​Empty logical environments

​Import

​Renaming logical environments

​Destroying logical environments

​Querying metadata

​Schema

​Required

​Optional

​Read-only

Physical environments only

Example usage

Complete example

Common use cases

By environment tier

By geographic region

By service type

Empty logical environments

Import

Renaming logical environments

Destroying logical environments

Querying metadata

Schema

Required

Optional

Read-only