yba-terraform

name: yba-terraform description: Use when writing, generating, or troubleshooting Terraform that drives YugabyteDB Anywhere (YBA) via the yugabyte/yba provider — installing YBA on a VM, registering the first customer, and creating cloud (AWS/GCP/Azure) or on-prem providers, storage configs, universes, backups, schedules, and restores. Also covers the upstream cloud Terraform (IAM user / service account / service principal) that grants YBA its node-deployment permissions, and the CLI commands to discover the VPC/subnet/security-group network info those manifests need. Triggers on yba_installer, yba_customer_resource, yba_aws_provider/yba_gcp_provider/yba_azure_provider, yba_universe, yba_backup, source = "yugabyte/yba", or any mention of the YBA Terraform provider. Does NOT cover the YBA REST API directly (use the yba-api skill) or YugabyteDB Aeon.

YugabyteDB Anywhere (YBA) Terraform Provider

This skill generates correct Terraform for the yugabyte/yba provider — the official provider that installs and drives a self-managed YugabyteDB Anywhere control plane.

• Registry: https://registry.terraform.io/providers/yugabyte/yba/latest/docs
• Source: https://github.com/yugabyte/terraform-provider-yba (branch main)
• Current version: 1.0.0 (Early Access). Requires YBA stable >= 2024.2.0.0 or preview >= 2.23.1.0. Kubernetes universes are not supported by this provider — for those use the yb-k8s-operator skill.

It is not about:

• The YBA REST API directly — use the yba-api skill (this provider calls that API for you).
• YugabyteDB Aeon (managed DBaaS) or YSQL/YCQL database access.

Reference files (read before generating non-trivial manifests)

• references/prereqs-and-network.md — YBA host VM requirements (CPU/RAM/disk/OS/Python/ports), DB-node requirements, and the aws/gcloud/az CLI commands to discover VPC IDs, subnets-per-zone, security groups, and regions. Read this first when sizing a VM or filling in network IDs.
• references/cloud-iam-setup.md — Terraform (using the aws/google/azurerm providers, not the yba provider) that creates the IAM user / service account / service principal YBA uses to deploy nodes, with the exact delegated permissions from the Yugabyte docs. Read this when the user needs to grant YBA cloud access.
• references/install-bootstrap.md — the yba_installer and yba_customer_resource resources and the two-provider (unauthenticated → authenticated) pattern. Read this when installing YBA or wiring up the API token.
• references/providers-universe.md — full HCL for yba_aws_provider / yba_gcp_provider / yba_azure_provider / yba_onprem_provider, the four storage-config resources, yba_universe, and yba_backup / yba_backup_schedule / yba_restore. Read this when generating any provider, universe, or backup resource.

The end-to-end workflow

A complete "from nothing to a running universe with backups" deployment is two Terraform stages because the API token does not exist until YBA is installed and the customer is registered.

┌─ Stage 0 (optional, upstream cloud TF) ── references/cloud-iam-setup.md
│   aws_iam_user / google_service_account / azuread_application
│   → the credentials YBA will use to deploy nodes
│
├─ Stage 1 (unauthenticated yba provider) ── references/install-bootstrap.md
│   yba_installer          → install YBA on an existing VM over SSH
│   yba_customer_resource  → register first customer; OUTPUTS api_token + cuuid
│
└─ Stage 2 (authenticated yba provider, api_token from stage 1) ── references/providers-universe.md
    yba_aws_provider / yba_gcp_provider / yba_azure_provider   (network info from references/prereqs-and-network.md)
    yba_s3_storage_config / yba_gcs_storage_config / ...
    yba_universe
    yba_backup_schedule / yba_backup / yba_restore

Run Stage 1 and Stage 2 as separate applys (or separate root modules / -target), because the api_token produced by yba_customer_resource must be known before the authenticated provider can be configured. Passing a provider api_token that is computed in the same apply is fragile — split the state.

Provider configuration (the two-provider pattern)

terraform {
  required_providers {
    yba = {
      source  = "yugabyte/yba"
      version = "~> 1.0"
    }
  }
}

# Stage 1: install + customer registration need NO token.
provider "yba" {
  alias = "unauthenticated"
  host  = var.yba_host   # IP or DNS, optionally :port
}

# Stage 2: everything else needs the customer API token.
provider "yba" {
  host      = var.yba_host
  api_token = var.yba_api_token   # from yba_customer_resource.<name>.api_token
}

The provider block accepts exactly three arguments — all optional, all env-var backed:

There is no api_key provider argument — YBA_API_KEY is only an env-var alias for api_token. With env vars set, the authenticated block can be empty (provider "yba" {}).

Resource cheat-sheet (use the per-cloud resources, not the deprecated generics)

Useful data sources: yba_provider_key, yba_release_version, yba_universe_schema (keyspace/table discovery for backups), yba_storage_configs, yba_provider_regions, yba_backup_info.

Getting the network info a cloud provider needs

yba_aws_provider / yba_azure_provider need VPC/vnet IDs, subnet IDs per zone, and a security group; yba_gcp_provider needs the network and a regional subnet (GCP zones auto-discover). Before generating a provider manifest:

1. Check memory / the conversation for already-known VPC, subnet, region, and project/subscription IDs.
2. If unknown, run the discovery CLI commands in references/prereqs-and-network.md (aws ec2 describe-subnets …, gcloud compute networks subnets list …, az network vnet subnet list …) and read the IDs from the output.
3. If the user has no cloud CLI configured and the info isn't in memory, ask the user for the region(s), VPC/vnet ID, subnet ID per availability zone, and security-group ID — list exactly what's missing rather than inventing placeholder IDs that will fail at apply.

Never invent real-looking IDs (vpc-0123…, subnet-…). Use clearly-templated placeholders (<aws-vpc-id>) only when explicitly producing a template the user will fill in.

Prerequisites (always state these when planning an install)

The YBA host VM (official minimums, from the Yugabyte docs):

• 4 vCPU, 8 GB RAM, x86_64 only (ARM is not supported for the YBA host).
• Disk: 215 GB minimum. Provision a 250 GB root volume (or a dedicated filesystem mounted at YBA's data dir, default /opt/yugabyte/data) to leave headroom — a too-small root volume is the most common install failure.
• A supported Linux OS (AlmaLinux 8/9, RHEL 8/9, Rocky 8/9, Oracle Linux 8, Ubuntu 20/22, Amazon Linux 2023, SLES 15 SP5). AlmaLinux 8 / RHEL 8 recommended for production.
• Python 3.10–3.12, with both python and python3 resolving to Python 3.
• A YBA license file from Yugabyte, and sudo access for the SSH user (YBA Installer also supports non-root mode).

Full host + DB-node requirements and the port list are in references/prereqs-and-network.md.

Anti-patterns