Secret

Defined insecrets.hcl

The secret resource retrieves a team-managed secret and makes its value available to other resources in the sandbox configuration. Secrets are stored and managed at the team level, and referenced by name in your lab configuration.

Note

The reference field corresponds to the name of the secret as configured in your team’s settings. Make sure the secret exists in your team before referencing it in a lab.

Declared secrets are always resolved — disabled does not help

Every declared secret resource is resolved from the team’s secret store when the session starts, before the sandbox evaluates the configuration — and that step ignores disabled. If the team secret does not exist, the session fails to start with an error like Secret [projects/…/secrets/<team>-<reference>] not found or has no versions. Remove or comment out the secret resource until the team secret exists; disabled = true does not prevent the lookup.

Use Cases

As a lab author, you can use secret resources to:

• Secure Credential Injection: Provide API keys, tokens, and passwords to containers and scripts without hardcoding sensitive values in your configuration
• Third-Party Service Access: Supply credentials for external services like cloud APIs, registries, or SaaS tools needed during lab execution
• Centralized Secret Management: Reuse team-level secrets across multiple labs without duplicating or embedding sensitive values

Secret resources allow you to safely inject sensitive values into your lab environment by referencing secrets managed centrally by your team.

HCL Syntax

Basic Syntax

resource "secret" "name" {
  reference = "TEAM_SECRET_NAME"
}

Usage in Other Resources

resource "secret" "api_key" {
  reference = "MY_API_KEY"
}

resource "container" "app" {
  image {
    name = "myapp:latest"
  }

  environment = {
    API_KEY = resource.secret.api_key.value
  }
}

Fields

Field	Type	Required	Description
reference	string	✓	Reference key to look up in the secret manager Constraintssecret reference must not be empty; secret reference must only contain letters, digits, underscores, and hyphens

Computed Attributes

These attributes are set by the system and are read-only.

Attribute	Type	Description
value	string	Resolved secret value, populated after apply

Examples

Injecting a Secret into a Container

resource "secret" "db_password" {
  reference = "DATABASE_PASSWORD"
}

resource "container" "database" {
  image {
    name = "postgres:15"
  }

  environment = {
    POSTGRES_PASSWORD = resource.secret.db_password.value
    POSTGRES_DB       = "myapp"
  }
}

Using a Secret in an Exec Script

resource "secret" "api_token" {
  reference = "EXTERNAL_API_TOKEN"
}

resource "exec" "configure" {
  script = "scripts/exec/configure/script.sh"

  environment = {
    API_TOKEN = resource.secret.api_token.value
  }
}

scripts/exec/configure/script.sh (the script field must point at a file — inline scripts fail validation):

#!/bin/bash
curl -H "Authorization: Bearer $API_TOKEN" https://api.example.com/configure

Pulling from a Private Registry

resource "secret" "registry_password" {
  reference = "REGISTRY_PASSWORD"
}

resource "container" "app" {
  image {
    name     = "registry.example.com/myapp:latest"
    username = "registry_user"
    password = resource.secret.registry_password.value
  }
}

Multiple Secrets

resource "secret" "db_password" {
  reference = "PROD_DB_PASSWORD"
}

resource "secret" "api_key" {
  reference = "THIRD_PARTY_API_KEY"
}

resource "container" "app" {
  image {
    name = "myapp:latest"
  }

  environment = {
    DATABASE_PASSWORD = resource.secret.db_password.value
    API_KEY           = resource.secret.api_key.value
  }
}