### Quickstart Terraform Commands

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/README.md

Quickstart guide for using the Control Plane Terraform provider. Includes logging in, initializing Terraform, applying a sample configuration, and destroying resources.

```bash
# 1. Log in via CLI
cpln login

# (For test environment)
cpln profile update default --login --endpoint https://api.test.cpln.io

# 2. Initialize Terraform
terraform init

# 3. Apply a sample configuration
terraform apply -var="org=<YOUR_ORG>"

# 4. When you’re done:
terraform destroy -var="org=<YOUR_ORG>"
```

--------------------------------

### Example Usage Snippet

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/CLAUDE.md

A basic example of how to declare a resource in Terraform configuration.

```terraform
resource "cpln_<kind>" "example" {
  name = "example"
  ...
}
```

--------------------------------

### Lambdalabs Provider Example Configuration

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/mk8s.md

Example configuration block for the lambdalabs provider, specifying resource limits and monitoring settings.

```hcl
log_splitter = {
    min_cpu         = "1m"
    max_cpu         = "1000m"
    min_memory      = "10Mi"
    max_memory      = "2000Mi"
    mem_buffer_size = "128M"
    per_pod_rate    = 10000
}

monitoring = {
    min_memory = "100Mi"
    max_memory = "20Gi"

    kube_state_metrics = {
        min_memory = "25Mi"
    }

    prometheus = {
        main = {
            storage = "10Gi"
        }
    }

    remote_write = [
        {
            url            = "https://prometheus.example.com/api/v1/write"
            remote_timeout = "30s"
            name           = "primary"
            headers = {
                "X-Scope-OrgID" = "byok-acceptance"
            }
            basic_auth = {
                username = "byok"
                password = "secret"
            }
            send_exemplars         = true
            send_native_histograms = false
            follow_redirects       = true
            enable_http2           = true
            queue_config = {
                capacity            = "10000"
                max_shards          = "200"
                min_shards          = "1"
                batch_send_deadline = "5s"
            }
            write_relabel_configs = [
                {
                    source_labels = "__name__"
                    regex         = "go_.*"
                    action        = "drop"
                },
            ]
        },
    ]

    external_labels = {
        cluster = "byok-acceptance"
    }
}

redis = {
    min_cpu    = "10m"
    max_cpu    = "2001m"
    min_memory = "100Mi"
    max_memory = "1000Mi"
    storage    = "8Gi"
}

redis_ha = {
    min_cpu    = "50m"
    max_cpu    = "2001m"
    min_memory = "100Mi"
    max_memory = "1000Mi"
    storage    = 0
}

redis_sentinel = {
    min_cpu    = "10m"
    max_cpu    = "500m"
    min_memory = "10Mi"
    max_memory = "400Mi"
    storage    = 0
}

tempo_agent = {
    min_cpu    = "0m"
    min_memory = "10Mi"
}

internal_dns = {
    min_cpu    = "0m"
    max_cpu    = "500m"
    min_memory = "10Mi"
    max_memory = "400Mi"
}
            }
        }
    }
}

```

--------------------------------

### Example Usage: Org Resources

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/policy.md

Terraform configuration example for creating a cpln_policy resource targeting organizational resources like service accounts.

```APIDOC
## Example Usage: Org Resources

```terraform
resource "cpln_service_account" "example" {

  name        = "service-account-example"
  description = "Example Service Account"

  tags = {
    terraform_generated = "true"
    example             = "true"
  }
}

resource "cpln_policy" "example" {

  name        = "policy-example"
  description = "Example Policy"

  tags = {
    terraform_generated = "true"
    example             = "true"
  }

  target_kind = "serviceaccount"

  # Policy can either target `all` or specific target links

  // target = "all"
  target_links = [cpln_service_account.example.name]

  target_query {

    spec {
      # match is either "all", "any", or "none"
      match = "all"

      terms {
        op    = "="
        tag   = "firebase/sign_in_provider"
        value = "microsoft.com"
      }
    }
  }

  binding {

    # Available permissions are based on the target kind
    permissions = ["manage", "edit"]

    # Principal links format: `group/GROUP_NAME`, `user/USER_EMAIL`, `cpln_identity.IDENTITY_RESOURCE_NAME.self_link`, `serviceaccount/SERVICE_ACCOUNT_NAME`
    principal_links = ["user/email@example.com", "group/viewers"]
  }
}
```
```

--------------------------------

### Example Usage: Lightstep Tracing

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/org_tracing.md

Configures the `cpln_org_tracing` resource to use Lightstep for tracing, including optional credentials and custom tags.

```APIDOC
### Lightstep

```terraform
resource "cpln_secret" "opaque" {

  name        = "opaque-random-tbd"
  description = "description opaque-random-tbd"

  tags = {
    terraform_generated = "true"
    acceptance_test     = "true"
    secret_type         = "opaque"
  }

  opaque {
    payload  = "opaque_secret_payload"
    encoding = "plain"
  }
}

resource "cpln_org_tracing" "new" {

  lightstep_tracing {

    sampling = 50
    endpoint = "test.cpln.local:8080"

    // Opaque Secret Only
    credentials = cpln_secret.opaque.self_link

    custom_tags = {
      key = "value"
    }
  }
}
```
```

--------------------------------

### Install Terraform Provider Locally

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/README.md

Install the Terraform provider locally using the make command. Specify OS_ARCH for different operating systems like macOS.

```bash
cd terraform-provider
make install
```

```bash
make install OS_ARCH=darwin_arm64
```

```bash
make install OS_ARCH=darwin_amd64
```

--------------------------------

### Example Usage: GVC Resources

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/policy.md

Terraform configuration example for creating a cpln_policy resource targeting GVC resources like identity, workload, and volumeset.

```APIDOC
## Example Usage: GVC Resources (i.e. identity, workload and volumeset)

```terraform
resource "cpln_gvc" "example" {

  name        = "gvc-example"
  description = "Example GVC"

  locations = ["aws-eu-central-1"]

  tags = {
    terraform_generated = "true"
  }
}

resource "cpln_identity" "example" {

  gvc = cpln_gvc.exmaple.name

  name        = "identity-example"
  description = "Example Identity"

  tags = {
    terraform_generated = "true"
  }
}

resource "cpln_policy" "example" {

  name = "policy-example"
  description = "Example Policy for GVC resources"

  tags = {
    terraform_generated = "true"
  }

  target_kind = "identity"

  # gvc required for 'identity', 'workload' and 'volumeset' target kinds
  gvc = cpln_gvc.terraform_gvc.name

  target_links = [cpln_identity.example.name]


  binding {
    permissions = ["manage", "edit"]
    principal_links = ["user/support@controlplane.com", "group/viewers", cpln_identity.terraform_identity.self_link]
  }
}
```
```

--------------------------------

### Terraform CPLN Workload Resource Example

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/workload.md

This example demonstrates the full configuration of a CPLN workload resource, including GVC and identity links, container details, options, firewall specifications, security settings, and load balancer configurations. Use this as a template for creating your own workloads.

```terraform
resource "cpln_gvc" "new" {
  name        = "gvc-example"
  description = "Example GVC"

  locations = ["aws-us-west-2", "gcp-us-east1"]

  tags = {
    terraform_generated = "true"
    acceptance_test     = "true"
  }
}

resource "cpln_identity" "new" {

  gvc = cpln_gvc.new.name

  name        = "identity-example"
  description = "Identity created using terraform"

  tags = {
    terraform_generated = "true"
    acceptance_test     = "true"
  }
}


resource "cpln_workload" "new" {

  gvc = cpln_gvc.new.name

  name        = "workload-example"
  description = "Example Workload"
  type        = "serverless"

  tags = {
    terraform_generated = "true"
    acceptance_test     = "true"
  }

  identity_link        = cpln_identity.new.self_link
  support_dynamic_tags = true

  container {
    name   = "container-01"
    image  = "gcr.io/knative-samples/helloworld-go"

    memory = "7Gi"
    cpu    = "2"

    ports {
		protocol = "http"
		number   = "8080"
	}

    gpu_custom {
      resource      = "amd.com/gpu"
      runtime_class = "amd"
      quantity      = 1
    }

    command           = "override-command"
    working_directory = "/usr"

    env = {
      env-name-01 = "env-value-01",
      env-name-02 = "env-value-02",
    }

    args = ["arg-01", "arg-02"]

    volume {
      uri             = "s3://bucket"
      path            = "/testpath01"
    }

    volume {
      uri             = "azureblob://storageAccount/container"
      path            = "/testpath02"
    }

    metrics {
      path         = "/metrics"
      port         = 8181
		drop_metrics = ["go_.*", "process_.*", ".*_bucket|.*_sum|.*_count"]
    }

    readiness_probe {

      tcp_socket {
        port = 8181
      }

      period_seconds        = 11
      timeout_seconds       = 2
      failure_threshold     = 4
      success_threshold     = 2
      initial_delay_seconds = 1
    }

    liveness_probe {

      http_get {
        path   = "/path"
        port   = 8282
        scheme = "HTTPS"
        http_headers = {
          header-name-01 = "header-value-01"
          header-name-02 = "header-value-02"
        }
      }

      period_seconds        = 10
      timeout_seconds       = 3
      failure_threshold     = 5
      success_threshold     = 1
      initial_delay_seconds = 2
    }

    lifecycle {

      post_start {
        exec {
          command = ["command_post", "arg_1", "arg_2"]
        }
      }

      pre_stop {
        exec {
          command = ["command_pre", "arg_1", "arg_2"]
        }
      }
    }
  }

  options {
    capacity_ai                = false
    capacity_ai_update_minutes = 2
    timeout_seconds            = 30
    suspend                    = false

    autoscaling {
      metric              = "concurrency"
      target              = 100
      max_scale           = 3
      min_scale           = 2
      max_concurrency     = 500
      scale_to_zero_delay = 400
    }
  }

  firewall_spec {
    external {
      inbound_allow_cidr      = ["0.0.0.0/0"]
      inbound_blocked_cidr    = ["192.0.2.123"]
      outbound_allow_cidr     = []
      outbound_allow_hostname = ["*.controlplane.com", "*.cpln.io"]
      outbound_blocked_cidr   = ["198.51.100.77", "192.0.2.45"]
    }

    internal {
      # Allowed Types: "none", "same-gvc", "same-org", "workload-list"
      inbound_allow_type     = "none"
      inbound_allow_workload = []
    }
  }

  security_options {
    file_system_group_id = 1
    run_as_user          = 1000
  }

  load_balancer {

    direct {
      enabled = true
      
      port {
        external_port  = 22
        protocol       = "TCP"
        scheme         = "http"
        container_port = 80
      }
    }

    geo_location {
      enabled = true
      headers {
        asn = "198.51.100.0/24"
        city = "Los Angeles"
        country = "USA"
        region = "North America"
      }
    }
  }
}

```

--------------------------------

### Create Service Account and Key

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/service_account_key.md

Example of creating a service account and then a key associated with it. The key can only be created and deleted; updates will fail.

```terraform
resource "cpln_service_account" "example" {

  name        = "service-account-example"
  description = "Example Service Account"

  tags = {
    terraform_generated = "true"
    example             = "true"
  }
}

resource "cpln_service_account_key" "example" {

  service_account_name = cpln_service_account.example.name
  description          = "Service Account Key"
}
```

--------------------------------

### Get Specific Images of a Repository

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/data-sources/images.md

This example demonstrates how to fetch specific images belonging to a particular repository using the `query` and `terms` arguments.

```APIDOC
## Get Specific Images of a Repository

### Description
Fetches images that match specific criteria, such as belonging to a particular repository.

### Method
GET

### Endpoint
/api/images

### Parameters
#### Query Parameters
- **query** (Block List, Max: 1) - Optional - Allows for filtering and fetching specific images.
  - **fetch** (String) - Optional - Type of fetch. Specify either: `links` or `items`. Default: `items`.
  - **spec** (Block List, Max: 1) - Optional - Specifies the criteria for matching images.
    - **match** (String) - Optional - Type of match. Available values: `all`, `any`, `none`. Default: `all`.
    - **terms** (Block List) - Optional - A list of terms to use for matching images.
      - **op** (String) - Optional - Type of query operation. Available values: `=`, `>`, `>=`, `<`, `<=`, `!=`, `exists`, `!exists`. Default: `= `.
      - **property** (String) - Required - Property to use for query evaluation. Example: `repository`.
      - **value** (String) - Required - Testing value for query evaluation. Example: `REPOSITORY_NAME`.

### Request Example
```terraform
data "cpln_images" "images-query" {
  query {
    fetch = "items"
    spec {
      match = "all"
      terms {
        op       = "="
        property = "repository"
        value    = "REPOSITORY_NAME"
      }
    }
  }
}
```

### Response Example
```json
{
  "images": [
    {
      "cpln_id": "guid-5678-efgh",
      "name": "specific-image",
      "tags": {},
      "self_link": "https://api.controlplane.com/images/guid-5678-efgh",
      "tag": "v1.0",
      "repository": "REPOSITORY_NAME",
      "digest": "sha256:another-digest...",
      "manifest": []
    }
  ]
}
```
```

--------------------------------

### Oblivus Provider Configuration Example

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/mk8s.md

This snippet shows a comprehensive configuration for the Oblivus provider, detailing resource allocation and settings for different services like log splitting, monitoring, Redis, and DNS.

```terraform
log_splitter = {
    min_cpu         = "1m"
    max_cpu         = "1000m"
    min_memory      = "10Mi"
    max_memory      = "2000Mi"
    mem_buffer_size = "128M"
    per_pod_rate    = 10000
}

monitoring = {
    min_memory = "100Mi"
    max_memory = "20Gi"

    kube_state_metrics = {
        min_memory = "25Mi"
    }

    prometheus = {
        main = {
            storage = "10Gi"
        }
    }

    remote_write = [
        {
            url            = "https://prometheus.example.com/api/v1/write"
            remote_timeout = "30s"
            name           = "primary"
            headers = {
                "X-Scope-OrgID" = "byok-acceptance"
            }
            basic_auth = {
                username = "byok"
                password = "secret"
            }
            send_exemplars         = true
            send_native_histograms = false
            follow_redirects       = true
            enable_http2           = true
            queue_config = {
                capacity            = "10000"
                max_shards          = "200"
                min_shards          = "1"
                batch_send_deadline = "5s"
            }
            write_relabel_configs = [
                {
                    source_labels = "__name__"
                    regex         = "go_.*"
                    action        = "drop"
                },
            ]
        },
    ]

    external_labels = {
        cluster = "byok-acceptance"
    }
}

redis = {
    min_cpu    = "10m"
    max_cpu    = "2001m"
    min_memory = "100Mi"
    max_memory = "1000Mi"
    storage    = "8Gi"
}

redis_ha = {
    min_cpu    = "50m"
    max_cpu    = "2001m"
    min_memory = "100Mi"
    max_memory = "1000Mi"
    storage    = 0
}

redis_sentinel = {
    min_cpu    = "10m"
    max_cpu    = "500m"
    min_memory = "10Mi"
    max_memory = "400Mi"
    storage    = 0
}

tempo_agent = {
    min_cpu    = "0m"
    min_memory = "10Mi"
}

internal_dns = {
    min_cpu    = "0m"
    max_cpu    = "500m"
    min_memory = "10Mi"
    max_memory = "400Mi"
}
            }
        }

        sysbox = true
    }
}
```

--------------------------------

### Example Usage: OpenTelemetry (Otel) Tracing

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/org_tracing.md

Configures the `cpln_org_tracing` resource to use OpenTelemetry (Otel) for tracing, including optional custom tags.

```APIDOC
### Otel

```terraform

resource "cpln_org_tracing" "new" {

  otel_tracing {

    sampling = 50
    endpoint = "test.cpln.local:8080"

    custom_tags = {
      key = "value"
    }
  }
}
```
```

--------------------------------

### Create a TLS Secret

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/secret.md

This example demonstrates creating a TLS secret. It requires a name, description, private key, and certificate. The certificate chain is optional.

```terraform
resource "cpln_secret" "tls" {

  name        = "tls-${var.random}"
  description = "tls description ${var.random}"

  tags = {
    terraform_generated = "true"
    example             = "true"
    secret_type         = "tls"
  }

  tls {

    # Required
    key = var.testcertprivate

    # Required
    cert = var.testcert

    # Optional
    chain = var.testcert
  }
}
```

--------------------------------

### Example Usage: Control Plane Tracing

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/org_tracing.md

Configures the `cpln_org_tracing` resource to use Control Plane's native tracing, including optional custom tags.

```APIDOC
### Control Plane

```terraform

resource "cpln_org_tracing" "new" {

  controlplane_tracing {

    sampling = 50

    custom_tags = {
      key = "value"
    }
  }
}
```
```

--------------------------------

### Create a Service Account and Policy

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/scripts/terraform_reference.mdx

Example of creating a service account and then a policy that targets it. Demonstrates setting policy attributes like name, description, tags, target kind, target links, target query, and binding.

```terraform
resource "cpln_service_account" "example" {

  name        = "service-account-example"
  description = "Example Service Account"

  tags = {
    terraform_generated = "true"
    example             = "true"
  }
}

resource "cpln_policy" "example" {

  name        = "policy-example"
  description = "Example Policy"

  tags = {
    terraform_generated = "true"
    example             = "true"
  }

  target_kind = "serviceaccount"

  # Policy can either target `all` or specific target links

  # target = "all"
  target_links = [cpln_service_account.example.name]

  target_query {

    spec {
      # match is either "all", "any", or "none"
      match = "all"

      terms {
        op    = "="
        tag   = "firebase/sign_in_provider"
        value = "microsoft.com"
      }
    }
  }

  binding {

    # Available permissions are based on the target kind
    permissions = ["manage", "edit"]

    # Principal links format: `group/GROUP_NAME`, `user/USER_EMAIL`, `identity/IDENTITY_NAME`, `serviceaccount/SERVICE_ACCOUNT_NAME`
    principal_links = ["user/email@example.com", "group/viewers"]
  }

}
```

--------------------------------

### Readiness Probe HTTP GET Configuration

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/scripts/terraform_reference.mdx

Defines the configuration for performing an HTTP GET request as part of a readiness probe.

```APIDOC
## container.readiness_probe.http_get

### Description
Configuration for performing an HTTP GET request as part of a readiness probe.

### Parameters
#### Optional Parameters
- **http_headers** (Map of String) - Name-Value list of HTTP Headers to send to container.
- **path** (String) - Path. Default: "/".
- **port** (Number) - Port. Min: 80. Max: 65535.
- **scheme** (String) - HTTP Scheme. Valid values: "HTTP", "HTTPS". Default: "HTTP".
```

--------------------------------

### Resource Configuration Method

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/templates/resource_skeleton.txt

Configures the resource instance with necessary components, including base configuration and resource-specific operations.

```go
// Configure configures the resource before use.
func ({RESOURCE_INSTANCE_NAME} *{RESOURCE_NAME}Resource) Configure(ctx context.Context, req resource.ConfigureRequest, resp *resource.ConfigureResponse) {
	{RESOURCE_INSTANCE_NAME}.ResourceBaseConfigure(ctx, req, resp)
	{RESOURCE_INSTANCE_NAME}.Operations = NewResourceOperations(*{RESOURCE_INSTANCE_NAME}, &{RESOURCE_NAME}ResourceOperator{})
}
```

--------------------------------

### GVC Data Source Example

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/data-sources/gvc.md

Example of how to use the cpln_gvc data source to retrieve GVC information and output its ID and locations.

```terraform
data "cpln_gvc" "gvc" {
  name = "gvc-example"
}

output "gvc_id" {
  value = data.cpln_gvc.gvc.id
}

output "gvc_locations" {
  value = data.cpln_gvc.gvc.locations
}
```

--------------------------------

### Render Helm Chart from Repository

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/data-sources/helm_template.md

This example demonstrates rendering a Helm chart directly from a repository. Specify the `chart`, `repository`, and optionally `version`. You can also provide custom `values` files and `set` values.

```terraform
data "cpln_helm_template" "nginx" {
  name       = "my-nginx"
  gvc        = "my-gvc"
  chart      = "nginx"
  repository = "https://charts.bitnami.com/bitnami"
  version    = "15.0.0"

  values = [file("${path.module}/values.yaml")]

  set = {
    "image.tag" = "1.25.0"
  }
}
```

--------------------------------

### Configure Local Provider Installation

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/README.md

Configure local provider installation by creating a .terraform.rc file. This method allows for alternative local execution of the provider.

```hcl
provider_installation {
  filesystem_mirror {
    path    = "/Users/<username>/.terraform.d/plugins"
  }
  direct {
    exclude = ["controlplane.com/*/*"]
  }
}
```

--------------------------------

### Output Organization Summary

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/data-sources/org.md

This example demonstrates how to output a summary of the organization's details, including its name, Control Plane ID, associated account ID, session timeout, and observability configuration. This is helpful for verifying or using organization settings in subsequent resources.

```terraform
output "org_summary" {
  value = {
    name                = data.cpln_org.org.name
    cpln_id             = data.cpln_org.org.cpln_id
    account_id          = data.cpln_org.org.account_id
    session_timeout_sec = data.cpln_org.org.session_timeout_seconds
    observability       = data.cpln_org.org.observability
  }
}
```

--------------------------------

### Readiness Probe Exec Configuration

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/scripts/terraform_reference.mdx

Specifies how to execute a command as part of a readiness probe.

```APIDOC
## container.readiness_probe.exec

### Description
Configuration for executing a command as part of a readiness probe.

### Parameters
#### Required Parameters
- **command** (List of Strings) - List of commands to execute. Min: 1.
```

--------------------------------

### Workload Data Source Example

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/data-sources/workload.md

Use the `cpln_workload` data source to fetch details of a specific workload by its name and GVC. This example demonstrates how to retrieve the workload's ID.

```terraform
data "cpln_workload" "workload" {
  name = "workload-example"
  gvc  = "gvc-example"
}

output "workload_id" {
  value = data.cpln_workload.workload.id
}
```

--------------------------------

### Create a Service Account Policy

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/policy.md

This example demonstrates how to create a policy for a service account. It includes setting the target kind, specific target links, a target query with terms, and binding permissions for principals.

```terraform
resource "cpln_service_account" "example" {

  name        = "service-account-example"
  description = "Example Service Account"

  tags = {
    terraform_generated = "true"
    example             = "true"
  }
}

resource "cpln_policy" "example" {

  name        = "policy-example"
  description = "Example Policy"

  tags = {
    terraform_generated = "true"
    example             = "true"
  }

  target_kind = "serviceaccount"

  # Policy can either target `all` or specific target links

  // target = "all"
  target_links = [cpln_service_account.example.name]

  target_query {

    spec {
      # match is either "all", "any", or "none"
      match = "all"

      terms {
        op    = "="
        tag   = "firebase/sign_in_provider"
        value = "microsoft.com"
      }
    }
  }

  binding {

    # Available permissions are based on the target kind
    permissions = ["manage", "edit"]

    # Principal links format: `group/GROUP_NAME`, `user/USER_EMAIL`, `cpln_identity.IDENTITY_RESOURCE_NAME.self_link`, `serviceaccount/SERVICE_ACCOUNT_NAME`
    principal_links = ["user/email@example.com", "group/viewers"]
  }
}
```

--------------------------------

### GET /controlplane/api/{API_OBJECT_NAME}/{name}

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/templates/resource_skeleton.txt

Retrieves a specific resource by its name.

```APIDOC
## GET /controlplane/api/{API_OBJECT_NAME}/{name}

### Description
Retrieves a specific resource by its name.

### Method
GET

### Endpoint
/controlplane/api/{API_OBJECT_NAME}/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the resource to retrieve.

### Response
#### Success Response (200)
- **{API_OBJECT_NAME}** (object) - The retrieved resource object.
- **statusCode** (int) - The HTTP status code of the response.

#### Response Example
```json
{
  "example": "{\"name\": \"example-resource\", \"id\": \"123e4567-e89b-12d3-a456-426614174000\"}"
}
```
```

--------------------------------

### container.lifecycle

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/data-sources/workload.md

Configures lifecycle hooks for a container, allowing execution of commands before stopping or after starting.

```APIDOC
## container.lifecycle

### Description
Configures lifecycle hooks for a container, allowing execution of commands before stopping or after starting.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **post_start** (Block List, Max: 1) - Optional - Configuration for the post-start hook.
- **pre_stop** (Block List, Max: 1) - Optional - Configuration for the pre-stop hook.

### Request Example
```json
{
  "post_start": {
    "exec": {
      "command": ["echo", "Container started"]
    }
  },
  "pre_stop": {
    "exec": {
      "command": ["echo", "Container stopping"]
    }
  }
}
```

### Response
#### Success Response (200)
This configuration is used internally and does not have a direct response.

#### Response Example
None
```

--------------------------------

### Compress Provider Artifacts for Windows

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/README.md

Use this command to create a compressed archive for the Windows build of the provider.

```bash
tar -cvzf terraform-provider-cpln_1.0.0_windows_amd64.zip terraform-provider-cpln_1.0.0_windows_amd64.exe
```

--------------------------------

### Output Service Account Key Value

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/service_account_key.md

Example of outputting the generated key value for a service account key.

```terraform
output "key_01" {
  value = cpln_service_account_key.example.key
}

output "key_02" {
  value = cpln_service_account_key.example_02.key
}
```

--------------------------------

### Invoke Read API Call

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/templates/resource_skeleton.txt

Invokes the Get API method of the client to retrieve an existing resource by its name.

```go
// InvokeRead invokes the Get API to retrieve an existing resource by name.

```

--------------------------------

### GCP Cloud Account Configuration and Output

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/cloud_account.md

Set up a GCP cloud account by specifying the project ID. The example also shows how to output the generated GCP service account name and roles.

```terraform
resource "cpln_cloud_account" "gcp" {
  name        = "cloud-account-gcp"
  description = "GCP cloud account"

  tags = {
    terraform_generated = "true"
    example             = "true"
  }

  gcp {
    project_id = "cpln_gcp_project_1234"
  }
}

output "cloud_account_gcp_service_account_name" {
  value = cpln_cloud_account.gcp.gcp_service_account_name
}

output "cloud_account_gcp_roles" {
  value = cpln_cloud_account.gcp.gcp_roles
}
```

--------------------------------

### Clone Terraform Provider Repository

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/README.md

Clone the Control Plane Terraform provider repository from GitHub to install it from source.

```bash
git clone https://github.com/controlplane-com/terraform-provider-cpln.git
```

--------------------------------

### Interactive Resource Generation

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/scripts/GENERATE_RESOURCE_USAGE.md

If any required keys are omitted, the script will prompt for their values interactively. This example shows prompts for missing parameters.

```bash
scripts/generate_resource.py
Missing parameters: API_OBJECT_NAME, RESOURCE_VAR_NAME
(1/7) Enter value for API_OBJECT_NAME: Identity
(2/7) Enter value for RESOURCE_VAR_NAME: identity
```

--------------------------------

### Create a Standard Workload with Multi-Metric Autoscaling

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/workload.md

This snippet demonstrates the creation of a standard workload with detailed container configuration, multi-metric autoscaling (CPU and memory), and comprehensive firewall specifications. It includes settings for readiness probes, lifecycle hooks, and load balancing.

```terraform
resource "cpln_gvc" "example" {
  name        = "gvc-example"
  description = "Example GVC"

  locations = ["aws-eu-central-1", "aws-us-west-2"]

  tags = {
    terraform_generated = "true"
    example             = "true"
  }
}

resource "cpln_identity" "example" {

  gvc = cpln_gvc.example.name

  name        = "identity-example"
  description = "Example Identity"

  tags = {
    terraform_generated = "true"
    example             = "true"
  }
}

resource "cpln_workload" "new" {

  gvc = cpln_gvc.example.name

  type = "standard"

  name        = "workload-example"
  description = "Example Workload"

  support_dynamic_tags = false

  tags = {
    terraform_generated = "true"
    example             = "true"
  }

  identity_link = cpln_identity.example.self_link

  container {
    name   = "container-01"
    image  = "gcr.io/knative-samples/helloworld-go"
    memory = "128Mi"
    cpu    = "50m"
		ports {
		  protocol = "http"
			number   = "80"
		}

		ports {
			protocol = "http2"
			number   = "8080"
	  }

    env = {
      env-name-01 = "env-value-01",
      env-name-02 = "env-value-02",
    }

    lifecycle {

      post_start {
        exec {
          command = ["command_post", "arg_1", "arg_2"]
        }
      }

      pre_stop {
        exec {
          command = ["command_pre", "arg_1", "arg_2"]
        }
      }
    }

    readiness_probe {

			grpc {
			  port = 3000
			}

			period_seconds        = 11
			timeout_seconds       = 2
			failure_threshold     = 4
			success_threshold     = 2
			initial_delay_seconds = 1
    }
  }

  options {
    capacity_ai                = false
    capacity_ai_update_minutes = 3
    timeout_seconds            = 30
    suspend                    = false

    autoscaling {
      metric_percentile = "p50" 
      max_scale         = 3
      min_scale         = 2
      max_concurrency   = 500
      
      multi {
        metric = "cpu"
        target = 95
      }

      multi {
        metric = "memory"
        target = 95
      }
    }
  }

  firewall_spec {
    external {
      inbound_allow_cidr      = ["0.0.0.0/0"]
      inbound_blocked_cidr    = ["192.0.2.123"]
      outbound_allow_cidr     = []
      outbound_allow_hostname = ["*.controlplane.com", "*.cpln.io"]
      outbound_blocked_cidr   = ["198.51.100.77", "192.0.2.45"]

      outbound_allow_port {
			protocol = "http"
			number   = 80
			}

			outbound_allow_port {
				protocol = "https"
				number   = 443
			}
    }
    internal {
      # Allowed Types: "none", "same-gvc", "same-org", "workload-list" 
      inbound_allow_type     = "none"
      inbound_allow_workload = []
    }
  }

  rollout_options {
    min_ready_seconds = 2
    max_unavailable_replicas = "10"
    max_surge_replicas = "20"
    scaling_policy = "Parallel"
  }

  security_options {
    file_system_group_id = 1
    run_as_user          = 1000
  }

  load_balancer {

    direct {
      enabled = true
      
      port {
        external_port  = 22
        protocol       = "TCP"
        scheme         = "http"
        container_port = 80
      }
    }

    geo_location {
      enabled = true
      headers {
        asn = "198.51.100.0/24"
        city = "Los Angeles"
        country = "USA"
        region = "North America"
      }
    }
  }
}

```

--------------------------------

### Import Syntax

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/service_account.md

Instructions on how to import an existing service account into Terraform management.

```APIDOC
## Import Syntax

The `terraform import` command is used to bring existing infrastructure resources, created outside of Terraform, into the Terraform state file, enabling their management through Terraform going forward.

To update a statefile with an existing service resource, execute the following import command:

```terraform
terraform import cpln_service_account.RESOURCE_NAME SERVICE_ACCOUNT_NAME
```

-> 1. Substitute RESOURCE_NAME with the same string that is defined in the HCL file.<br/>2. Substitute SERVICE_ACCOUNT_NAME with the corresponding service account defined in the resource.
```

--------------------------------

### Create Additional Service Account Key with Dependency

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/service_account_key.md

Demonstrates creating a second service account key. It's recommended to use `depends_on` to ensure keys are added synchronously.

```terraform
resource "cpln_service_account_key" "example_02" {

  // When adding another key, use `depends_on` to add the keys synchronously
  depends_on = [cpln_service_account_key.example]

  service_account_name = cpln_service_account.example.name
  description          = "Service Account Key #2"
}
```

--------------------------------

### Configure Prometheus with Remote Write

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/mk8s.md

Example of configuring Prometheus with remote write capabilities, including storage, URL, authentication, and queue configuration.

```terraform
prometheus = {
    main = {
        storage = "10Gi"
    }
}

remote_write = [
    {
        url            = "https://prometheus.example.com/api/v1/write"
        remote_timeout = "30s"
        name           = "primary"
        headers = {
            "X-Scope-OrgID" = "byok-acceptance"
        }
        basic_auth = {
            username = "byok"
            password = "secret"
        }
        send_exemplars         = true
        send_native_histograms = false
        follow_redirects       = true
        enable_http2           = true
        queue_config = {
            capacity            = "10000"
            max_shards          = "200"
            min_shards          = "1"
            batch_send_deadline = "5s"
        }
        write_relabel_configs = [
            {
                source_labels = "__name__"
                regex         = "go_.*"
                action        = "drop"
            },
        ]
    },
]

external_labels = {
    cluster = "byok-acceptance"
}

```

--------------------------------

### Import Syntax

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/org_tracing.md

Instructions on how to import an existing `cpln_org_tracing` resource into Terraform state.

```APIDOC
## Import Syntax

The `terraform import` command is used to bring existing infrastructure resources, created outside of Terraform, into the Terraform state file, enabling their management through Terraform going forward.

To update a statefile with an existing org tracing resource, execute the following import command:

```terraform
terraform import cpln_org_tracing.RESOURCE_NAME ORG_NAME
```

-> 1. Substitute RESOURCE_NAME with the same string that is defined in the HCL file.<br/>2. Substitute ORG_NAME with the target org.
```

--------------------------------

### Terraform Cron Workload Example

Source: https://github.com/controlplane-com/terraform-provider-cpln/blob/main/docs/resources/workload.md

Defines a cron workload with specified container, volumes, metrics, firewall rules, security options, and job scheduling.

```terraform
resource "cpln_gvc" "example" {

  name        = "gvc-example"
  description = "Example GVC"
  locations   = ["aws-us-west-2"]

  tags = {
    terraform_generated = "true"
    example             = "true"
  }
}

resource "cpln_identity" "example" {

  gvc         = cpln_gvc.example.name
  name        = "identity-example"
  description = "Example Identity"

  tags = {
    terraform_generated = "true"
    example             = "true"
  }
}

resource "cpln_workload" "new" {

  gvc = cpln_gvc.example.name

  type = "cron"

  name        = "workload-example"
  description = "Example Workload"

  support_dynamic_tags = false

  tags = {
    terraform_generated = "true"
    example             = "true"
  }

  identity_link = cpln_identity.example.self_link

  container {
    name              = "container-01"
    image             = "gcr.io/knative-samples/helloworld-go"
    memory            = "128Mi"
    cpu               = "50m"
    command           = "override-command"
    working_directory = "/usr"

    env = {
      env-name-01 = "env-value-01",
      env-name-02 = "env-value-02",
    }

    args = ["arg-01", "arg-02"]

    volume {
      uri  = "s3://bucket"
      path = "/testpath01"
    }

    volume {
      uri  = "azureblob://storageAccount/container"
      path = "/testpath02"
    }

    metrics {
      path         = "/metrics"
      port         = 8181
		drop_metrics = ["go_.*", "process_.*", ".*_bucket|.*_sum|.*_count"]
    }
  }

  options {
    suspend = false
  }

  firewall_spec {
    external {
      inbound_allow_cidr      = ["0.0.0.0/0"]
      outbound_allow_hostname = ["*.controlplane.com", "*.cpln.io"]
      outbound_blocked_cidr   = ["198.51.100.77", "192.0.2.45"]

      outbound_allow_port {
        protocol = "http"
        number   = 80
      }

      outbound_allow_port {
        protocol = "https"
        number   = 443
      }
    }
  }

  security_options {
    file_system_group_id = 1
    run_as_user          = 1000
  }

  job {
    schedule                = "* * * * *"
    concurrency_policy      = "Forbid"
    history_limit           = 5
    restart_policy          = "Never"
    active_deadline_seconds = 1200
  }
}

```