Terraform Yandex Cloud

Quick Start

Choose Structure

Modular (environments/ + modules/): Multiple environments (dev/stage/prod), reusable components

Flat (functional files): Single environment, small-medium projects

Essential Patterns

# Resource naming with prefix
locals {
  resource_prefix = "${var.project_name}-${var.environment}"
}

# YDB tables require wait for database readiness
resource "time_sleep" "wait_for_database" {
  depends_on      = [yandex_ydb_database_serverless.this]
  create_duration = "30s"
}

# TTL on temporary data
ttl {
  column_name     = "expires_at"
  expire_interval = "PT0S"  # immediate
}

# Secondary index with concurrency guard
resource "yandex_ydb_table_index" "index2" {
  # ...
  depends_on = [yandex_ydb_table_index.index1]
}

Common Tasks

• Setup from scratch: See GETTING_STARTED.md for installation, authentication, provider setup
• Add YDB table: See YDB.md for table patterns, TTL, indexes
• Add S3 bucket: See S3.md for public/private buckets, lifecycle, CORS
• Add Cloud Function: See FUNCTIONS.md for build+deploy patterns
• Add Message Queue: See QUEUE.md for DLQ and retry patterns
• Add Serverless Container: See CONTAINERS.md for Docker registry, triggers, sizing
• IAM roles: See IAM.md for common role combinations
• Store API keys / secrets: See LOCKBOX.md for Lockbox secret management, injecting secrets into functions and containers

Authentication — Mandatory Clarification

Always ask the user how they authenticate with Yandex Cloud before writing provider configuration.

The preferred and most secure method is service account (service_account_key_file). Always recommend it over other options.

Method	Security	Use Case
service_account_key_file	Preferred	CI/CD, production, any automated workflow
Environment variables	Preferred	CI/CD, production — keeps credentials out of .tf files
token (IAM token)	Acceptable	Short-lived scripts, local dev with impersonation
Yandex/federated account token	Not recommended	Personal dev only, less secure

Environment variables (YC_TOKEN or YC_SERVICE_ACCOUNT_KEY_FILE, plus YC_CLOUD_ID, YC_FOLDER_ID) are read automatically by the provider even when not set in the provider {} block. This is the cleanest approach for CI/CD as no credentials appear in .tf files:

export YC_SERVICE_ACCOUNT_KEY_FILE=/path/to/key.json
export YC_CLOUD_ID=$(yc config get cloud-id)
export YC_FOLDER_ID=$(yc config get folder-id)

If the user has not mentioned authentication, ask: "How do you authenticate with Yandex Cloud — via a service account key file, environment variables, IAM token, or another method?" Then use the appropriate provider block.

Key Pitfalls

1. YDB tables fail without depends_on = [time_sleep.wait_for_database]
2. Multiple indexes need sequential depends_on to avoid concurrent schema modifications
3. TTL format: P5D = 5 days, PT0S = immediate
4. Service accounts need explicit IAM role bindings
5. Functions need user_hash for redeployment triggers
6. Docker images MUST be built with --platform=linux/amd64 (ARM images fail with "Internal error")
7. Never put API keys or passwords in environment variables directly — use Lockbox secrets instead; see LOCKBOX.md
8. Lockbox: always use yandex_lockbox_secret_version_hashed (not _version) to keep plain-text values out of Terraform state
9. Lockbox: the function/container service account needs lockbox.payloadViewer on each secret, not just on the folder