---
description: "Define Verda serverless containers in Terraform: the images, GPU type, scaling limits, and environment variables, so that deployments stay fully reproducible."
revision_date: 04.08.2026
---

# Containers – Containers

Use Terraform to provision and manage container workloads on Verda. Containers let you run services, batch workloads, and inference applications without managing virtual machines directly.

In Verda, containers are defined as standalone resources and fully managed by the platform. Terraform allows you to describe container configuration declaratively, enabling repeatable deployments, safe updates, and easy teardown.

***

#### What this page covers

* Creating containers deployments with Terraform
* Selecting GPU compute for a deployment
* Configuring auto-scaling, including scale-to-zero
* Defining containers, images, and exposed ports
* Managing environment variables and secrets
* Adding a health check
* Understanding container lifecycle and updates
* Importing existing containers into Terraform state

***

#### Basic example

```hcl
terraform {
  required_providers {
    verda = {
      source  = "verda-cloud/verda"
      version = "~> 1.0"
    }
  }
}

provider "verda" {}

resource "verda_container" "example" {
  name = "terraform-container"
  compute = {
    name = "H100"
    size = 1
  }

  scaling = {
    min_replica_count               = 1
    max_replica_count               = 2
    queue_message_ttl_seconds       = 300
    concurrent_requests_per_replica = 10

    scale_down_policy = {
      delay_seconds = 300
    }

    scale_up_policy = {
      delay_seconds = 10
    }

    queue_load = {
      threshold = 1
    }
  }

  containers = [
    {
      image        = "nginx:1.30.3"
      exposed_port = 80

      env = [
        {
          type                         = "plain"
          name                         = "LOG_LEVEL"
          value_or_reference_to_secret = "info"
        }
      ]
    }
  ]
}
```

***

#### Key concepts

**Container identity**

* The `name` field is a human-readable identifier Private registries.
* Deployments are imported and referenced by `name`, so keep it stable once a deployment is live.
***
 
**Compute**
 
The `compute` block selects the GPU resources allocated to each replica.
 
* `name` — the GPU type (for example `H100` or `A100`).
* `size` — the number of GPUs per replica.
Choose the smallest GPU configuration that comfortably fits your workload. Over-provisioning increases cost, while under-provisioning can cause slow inference or out-of-memory failures.
 
***

**Scaling**
 
`scaling` is **required** every deployment must define it. Verda scales based on a request queue rather than raw CPU usage, and the `scale_up_policy`, `scale_down_policy`, and `queue_load` sub-blocks are all required as well.
 
* `min_replica_count` — minimum number of replicas. Set to `0` to enable **scale-to-zero**.
* `max_replica_count` — maximum number of replicas.
* `concurrent_requests_per_replica` — how many requests a single replica handles at once.
* `queue_message_ttl_seconds` — how long a queued request stays valid before it expires.
* `queue_load.threshold` — the queue load value (>=1.0) that triggers scaling.
* `scale_up_policy.delay_seconds` — how long to wait before adding replicas.
* `scale_down_policy.delay_seconds` — how long to wait before removing replicas.

For a simple deployment that always keeps one replica running, set `min_replica_count` and `max_replica_count` to `1`.
 
**Scale-to-zero:** with `min_replica_count = 0`, the deployment scales down to no replicas when idle. This saves cost but adds cold-start latency to the first request after an idle period. For latency-sensitive services, keep at least one replica warm.
 
***

**Containers**
 
The `containers` list defines one or more containers that make up the deployment. Each container is created from an OCI-compatible image (a Docker image).
 
Each container requires:
 
* `image` — the container image (for example `nginx:1.30.3`).
* `exposed_port` — the port the container listens on.

**Best practices:**

* Use immutable image tags (for example `1.30.3` instead of `latest`)
* Store images in a trusted container registry
* Version images alongside your Terraform configuration

If your registry requires authentication, configure registry credentials separately (see **Serverless Containers – Container registrys**).


***

**Environment variables**
 
Environment variables are defined per container as a list of typed entries, letting you configure application behavior at runtime without rebuilding images. Each entry has:
 
* `type` — `plain` for literal values, or `secret` to reference a stored secret.
* `name` — the environment variable name.
* `value_or_reference_to_secret` — the literal value (for `plain`) or the secret name (for `secret`).
```hcl
env = [
  {
    type                         = "plain"
    name                         = "MODE"
    value_or_reference_to_secret = "production"
  },
  {
    type                         = "secret"
    name                         = "API_KEY"
    value_or_reference_to_secret = "api-key-secret"
  }
]
```
 
For sensitive values, use `type = "secret"` rather than hardcoding them as plain values.
 
***

**Health check**
 
Add an optional `healthcheck` block to a container so the platform can verify it is ready to serve traffic.
 
```hcl
healthcheck = {
  enabled = "true"
  port    = "8080"
  path    = "/health"
}
```
***

**Spot instances**
 
Set `is_spot = true` to run the deployment on spot capacity at reduced cost. Spot capacity can be reclaimed, so use it for workloads that tolerate interruption. It defaults to `false`.

***

#### Updating containers safely

Most configuration changes, such as updating the image, compute, scaling, or environment variables, require **recreating the container**.

To reduce risk:

* Test changes in non-production environments first
* Use pinned image versions
* Always review `terraform plan` before applying changes

***

#### Importing an existing container

If a deployment already exists in Verda, you can import it into Terraform state using its **name**:

```bash
terraform import verda_container.example <deployment-name>
```

After importing, run:

```bash
terraform plan
```

Update your Terraform configuration until the plan shows no changes.

***

#### Troubleshooting

**Container fails to start**.   
Verify that the image exists and is accessible, that `exposed_port` matches the port your application listens on, and that the selected `compute` is sufficient for the workload.

**Unexpected deployment recreation**.  
Changes to image tags, compute, scaling, or environment variables typically force replacement.

**Cold starts on the first request**.  
 Expected when `min_replica_count = 0`. Keep at least one replica warm for latency-sensitive services.

**Image pull errors**  
Ensure registry credentials are configured correctly and accessible to Verda. If the image is in a private registry, registry credentials must be configured.