Digitalocean Terraform

DigitalOcean Terraform provider

Everything here is derived from the official digitalocean/digitalocean provider docs at v2.99.1, bundled verbatim under references/provider-docs/. Those files are authoritative on argument names, types, defaults, and import syntax — prefer them over recollection, because this provider changes often and several of its resources have near-identical siblings that take different arguments.

Start here

Never write digitalocean_* HCL from memory. The failure mode is not a clear error — it is configuration that looks correct, passes review, and then either fails at apply or produces a plan that never converges. Confirm arguments first; it costs one command.

# What exists? (fuzzy, matches resources and data sources)
python3 scripts/dodocs.py list database

# Exact arguments and attributes for one resource
python3 scripts/dodocs.py args droplet

# Just the example, or just the import syntax
python3 scripts/dodocs.py example loadbalancer
python3 scripts/dodocs.py import database_db

# Which resources mention an argument at all?
python3 scripts/dodocs.py search vpc_uuid

# Data source rather than resource, when both names exist
python3 scripts/dodocs.py args kubernetes_cluster --kind data

Run from the skill directory. Names work with or without the digitalocean_ prefix, and a wrong guess suggests near matches instead of failing silently.

The files

Provider setup

terraform {
  required_providers {
    digitalocean = {
      source  = "digitalocean/digitalocean"
      version = "~> 2.99"
    }
  }
}

provider "digitalocean" {
  token = var.do_token # or the DIGITALOCEAN_TOKEN environment variable
}

The token grants full account access, so keep it in an environment variable or a secret manager — never committed, and never a default value on a variable.

Spaces is the exception that catches everyone. Spaces resources authenticate with S3-style keys, not the API token. Without spaces_access_id / spaces_secret_key (or SPACES_ACCESS_KEY_ID / SPACES_SECRET_ACCESS_KEY), Spaces resources fail while every other resource applies normally.

Other provider arguments worth knowing: requests_per_second (throttle to avoid rate limits on large applies), http_retry_max, api_endpoint, spaces_endpoint. Full list in references/provider-docs/index.md.

Where things live

The provider's own subcategories, with what each covers:

Full per-resource breakdown with purposes: references/resource-index.md.

The traps that actually bite

These cause the majority of broken DigitalOcean configurations. Details and fixes in references/gotchas.md.

1. Attach exactly one way. Volumes, reserved IPs, reserved IPv6s, and floating IPs can each be attached inline on the Droplet or through a separate *_attachment / *_assignment resource. Using both makes every plan show changes forever. Setting volume_ids also means Terraform claims the Droplet's entire volume set.
2. Floating IPs are now reserved IPs. digitalocean_floating_ip* is deprecated; use digitalocean_reserved_ip*.
3. ssh_keys cannot change after creation. It takes key IDs or fingerprints, not key material, and editing it destroys and recreates the Droplet.
4. Don't create a DOKS cluster and its Kubernetes resources in one module. Terraform evaluates provider blocks before resources exist. Split into two applies.
5. Database *_config resources don't unset remote settings on destroy. They only leave state. Reset values explicitly first.
6. Managed Redis was discontinued (30 June 2025). Use Valkey for anything new.
7. certificate_id can never converge — it is a drift bug, not a style nit. digitalocean_certificate.id is the certificate's name, not its UUID, so the field permanently disagrees with the API. Attach by certificate_name, and rotate with a new name plus create_before_destroy.
8. Set disable_lets_encrypt_dns_records = true when a load balancer has a Let's Encrypt cert and you also manage that hostname's DNS record in Terraform — otherwise DigitalOcean's auto-created record fights yours.
9. force_destroy on a Spaces bucket defaults to false, so destroy fails on a non-empty bucket.
10. Projects take URNs (.urn), not IDs.
11. Singular data sources error on zero or multiple matches. Use the plural forms (digitalocean_droplets, digitalocean_images, …) for lists.
12. Renaming a volume's filesystem_type to initial_filesystem_type destroys the volume and its data. The replacement is ForceNew and never read back, so on an existing volume it always diffs null → "ext4" and forces replacement. Delete the deprecated argument instead of renaming it (gotchas.md §12b).

Working approach

Writing new configuration

1. Find the resource — dodocs.py list <term> or references/resource-index.md.
2. Read its real arguments — dodocs.py args <name>. Note which are (Required) and which say "Changing this forces a new resource".
3. If more than one resource is involved, check references/patterns.md for the composed shape before assembling it yourself.
4. Scan references/gotchas.md for anything touching the resources you used.
5. Look up regions, sizes, and versions with data sources rather than hardcoding slugs — availability changes per account and region.
6. Verify: terraform fmt, then terraform validate, then terraform plan.

Reviewing or debugging existing configuration

• Plan never converges / always shows changes → check three things, in this order: the attach-once rule (gotchas.md §1), certificate_id on a load balancer or CDN (§8 — the field is structurally incapable of converging), and *_config resources (§5). A config can have more than one cause at once, so keep looking after the first hit.
• Cleaning up deprecated arguments on a live resource → check gotchas.md §12b first. The obvious fix for a volume's filesystem_type destroys the volume. Read the plan for must be replaced before applying, and stop on a -/+ against anything holding data.
• Unexpected destroy/recreate → look for ssh_keys edits, or an argument the docs mark as forcing a new resource. dodocs.py args <name> shows these.
• Auth failures on only some resources → missing Spaces credentials.
• Copied from a blog post → check the deprecated-argument table in gotchas.md §9; private_networking, algorithm, certificate_id, and app routes/cors are the usual survivors.

Verification honesty: terraform validate checks syntax and types but does not contact the API, so it cannot confirm that a region supports a size or that a slug exists. Only terraform plan (with credentials) does. Say which one you actually ran rather than implying more coverage than you have.

Version note

Bundled docs are v2.99.1 (published 2026-08-06). If the user pins a different major or a much newer minor version, arguments may differ — check the upstream repo at github.com/digitalocean/terraform-provider-digitalocean under docs/, or the registry, and say so rather than assuming these docs still apply.