> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kosli.com/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.kosli.com/feedback

```json
{
  "path": "/terraform-reference/resources/logical_environment",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# kosli_logical_environment resource

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

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

<Warning>
  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.
</Warning>

<Warning>
  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](/terraform-reference/data-sources/logical_environment).
</Warning>

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

<Warning>
  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 API error.
</Warning>

## Example usage

```terraform theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
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](https://github.com/kosli-dev/terraform-provider-kosli/tree/main/examples/complete/logical-environments).

## Common use cases

### By environment tier

Aggregate all production or staging environments for unified compliance reporting:

```terraform theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
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:

```terraform theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
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:

```terraform theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
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:

```terraform theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
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:

```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
#!/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
```

## 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 will force recreation of the resource.

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