Turf — Use cases: GPU clouds, fleets, installers, agents, CI/CD

01 · Neocloud providers

GPU clouds, from metal to tokens.

A neocloud sells a managed cluster, not GPUs by the hour: qualified before handover, current on drivers and firmware, back in service soon after a fault. Turf brings the whole managed cluster up in one convergence loop, certification included, and services it on the provider’s runbook.

Every layer is code, brought up by one convergence loop. The decision layer, the provider’s agent, runbook and policy, approves each change plan and oversees remediation.

certification.tfcertification as a step of the run

resource "kubernetes_manifest" "certification" {
  manifest = {
    apiVersion = "nvcre.nvidia.com/v1alpha1"
    kind       = "Certification"
    spec       = local.spec
  }
  lifecycle {
    action_trigger {
      events  = [before_create]
      actions = [action.kubewait_condition.gpu_census]
    }
    action_trigger {
      events     = [after_create]
      actions    = [action.kubewait_condition.certification_complete]
      on_failure = taint
    }
  }
}

adapted from turf-examples/use-cases/datacenter/aicr-eks-certification · the census before, the wait after

Day 1 · bring-up

From pools of inventory to a certified cluster

The provider offers hardware as a pool; Turf starts where the pool hands over a machine. The host playbook runs as a Terraform action, the cluster comes up, the AI runtime installs as the rendered recipe, and the certification runs as a resource with the GPU census before it and the wait after. One change plan covers all of it, approved by policy or a person, round by round, until nothing is left to defer.

Day 2 · the runbook

One approved step at a time

The health checks find the fault. What happens next is the provider’s remediation runbook, and the agent follows it: cordon and drain, repair or replace, re-certify, uncordon and return, each step a change plan the engine carries out. A recipe upgrade re-fires the certification under the same approval, and a fleet is many stacks from a few golden recipes.

coming soon A preview of the Turf console: the AI runtime applying in round 2, paused at the certify step. Click to enlarge.

The reference architecture.

Metal to Tokens walks the cluster stack three times: one layer at a time, then the convergence loop, then day 2 across the data center. Seventeen pages, free, with the stacks on GitHub.

Proof Metal to Tokens → aicr-stack → node-maintenance → slinky-stack → the engine →

Read Metal to Tokens Get started

02 · SaaS and platform providers

Managed services on Kubernetes fleets.

A control plane, a golden recipe, and a fleet of Kubernetes® clusters that each deliver your service to a tenant. Turf runs in the cluster beside them: a tenant’s cluster is one module call, a change arrives as a pull request or an MCP call, and every cluster is its own stack under approval.

tenants/acme.tfa tenant's cluster: one call to the recipe

module "tenant_acme" {
  source  = "registry.example.com/platform/gpu-cluster/kubernetes"
  version = "2.4.0"

  tenant    = "acme"
  recipe    = "h100-inference"
  gpu_nodes = 16
}

output "acme" {
  value = module.tenant_acme.endpoints   # read back by the control plane
}

illustrative, after Metal to Tokens, chapter 12 · the golden recipe is a registry module with the variables the provider opens

A tenant order, in the data center. Each block is a tenant cluster, and the green ones have a run in flight.

Day 1 · a tenant order

A module call becomes a cluster

The control plane writes the tenant’s cluster as HCL and opens a pull request, or calls Turf’s MCP server directly: open, up, plan, apply, output. Either way the change is a plan, approved before it runs, and the outputs come back to the control plane when the run converges. Turf runs in Kubernetes, deployed as an agent, with its state in the cluster.

Day 2 · the fleet

Upgrades, cluster by cluster, under one approval policy

Bump the recipe version and every cluster plans its own change; routine changes are approved by policy, the rest by a person. Drift is found on every plan. Replacing a cluster plans the orderly teardown of what it hosted instead of letting it vanish with the machine, and a run that is interrupted picks up where it stopped.

Proof Turf in the cluster, via kagent → state in a Kubernetes secret → Metal to Tokens, chapter 12 → the engine →

Get started Start a pilot

03 · ISVs and AI-native products

Products that install themselves.

Your product ships a reference architecture; the customer gets a forty-page deployment guide and a solutions engineer. Make the installer part of the product instead: the architecture as Terraform modules, planned in the customer’s account before anything exists, with the installer’s own steps written in as turf actions.

The installer is code too. The product ships its architecture and its own steps; Turf plans in the customer's account with no credentials, the customer approves, and the loop creates identity, compute, network and storage until the app is up.

Day 1 · the install

Planned before anything exists

The reference architecture is Terraform modules the product ships. In the customer’s account Turf plans it from empty, the customer approves, and the apply runs with the installer’s steps inside it: verify the storage is private, send the welcome when the app is usable. Any mix of HCL and natural language: the modules carry the architecture, the customer’s specifics arrive as variables or as a sentence.

Day 2 · the same plan, again

Upgrades and drift, under the same approval

A new version of the product is a new plan in the customer’s account. Drift is detected on every plan and healed by the same loop. Nothing that holds the customer’s data is removed without their word, because consent is bound before its destroy. The product drives Turf over MCP, the same interface Claude Code uses, and runs where the product runs: embedded, in a container, in the cluster, on a local model.

Proof data-lake-installer → drive Turf over MCP → the compatibility matrix →

Talk to us Get started

04 · Teams adopting agents

The ultimate infrastructure agent.

Turf is an MCP server at its core: the tools and the skills an agent needs to take a sentence to a running stack and to operate it afterwards, with the plan as the contract between them. Designed for efficient reasoning models such as Claude Sonnet 5.5: the skills carry the procedure, the results carry the summary, and the model carries the judgment.

The same agent, with a shell or with Turf. The engine carries it out; the agent oversees, and every step leaves a record.

a session, from a sentence

> deploy a data lake for tenant acme with Turf

provider search "aws" → hashicorp/aws

provider describe aws_s3_bucket → schema · identity

(the authoring skill writes versions.tf, lake.tf)

init ./lake → providers locked

open workspace acme

up → plan gate

plan → approval point · 7 to add

show → input.tfplan → policy: no denials

apply by its digest → converged · outputs

lake.tffrom the console: the agent writes the import block

import {
  to = aws_s3_bucket.raw
  id = "acme-raw-data"
}

resource "aws_s3_bucket" "raw" {
  bucket = "acme-raw-data"
}

plan: up · destroy · import · refresh, then planEvery change is a plan: converge the directory, tear it down, adopt what exists by id or identity, or read the world back into state. Each round waits at its plan gate; plan plans it, refresh and replace chosen there, and stops at its approval point with the plan's summary.

approve: apply, by digestapply with the plan's digest is the approval, of that plan and no other; apply with decline turns it down, and cancel ends the run. Nothing is approved in advance.

the plan, for integrationshow returns the plan as OpenTofu's own document: input.tfplan for OPA, conftest or Checkov, or your platform's policy groups, before a non-trivial plan is approved. A plan-only run keeps its plan as a planfile, for another server, with its own credentials, to apply.

apply, with interaction pointsThe engine carries the plan out and stops at every turf action it meets: a backup, a check, a question, a notification, answered by the agent and recorded with the run.

invoke: action-only plans, for day 2One declared action, or an ad-hoc one for this run alone, planned by itself with its own plan gate and approval point: reboot, backup, cordon, re-certify.

state: list · show · output · taintState, outputs and plans as OpenTofu's own documents, sensitive values redacted unless asked; taint marks a replacement for the next plan; workspaces listed and deleted.

provider search · describeAny provider on the registry, and the exact schema of a type: required, computed, write-only, identity. Provider-linked skills coming soon

resource queryBulk discovery with list and query, for import at scale.coming soon

Day 1 · from a sentence

To a running stack, in your directory

The agent finds the provider, reads the schema it will write against, and writes ordinary Terraform files you can read, commit and run anywhere. up starts the run, plan plans the whole directory and stops at the approval point with the plan’s summary; you approve from Claude Code, Cursor, Codex or any MCP client, on the subscription you already have, and the engine carries it out.

Day 2 · the same agent operates

Import, refresh, invoke, answer, check

What was clicked together comes in through import. Drift shows on every plan. A declared action runs on demand with its own approval point. The guardrails example scans every provider before it runs, pins the workload to a commit and checks every plan against policy before it is approved. Local models and private GPU clouds: intent never has to leave your network.

Proof connect your agent → guardrails → the guided journeys, /turf:guide → the compatibility matrix → the engine →

Connect your agent Get started

05 · Platform engineers

Pull request to production, with the plan reviewed every time.

The pipeline you have plans at pull_request, applies at push, and applies with -auto-approve: the plan the reviewer saw is not the plan that runs, and nobody reads the one that does. Put an agent in the pipeline, with Turf on the runner as its engine. It reads the plan, judges it by your policy in plain language, checks the providers against GitHub’s Advisory Database, applies the reviewed plan and no other, verifies from inside the apply, and promotes by GitHub Environment. Turf™ is an autonomous infrastructure-as-code tool for agentic workflows, built on OpenTofu™.

Every stop attended. GitHub Agentic Workflows run the agent as an Actions job; Turf’s server and engine run on the same runner, with the cloud credentials in their process and never in the agent’s. The Environment supplies the variables, the role and the policy.

policy/approval.mdone paragraph per Environment

## staging

Approve any plan, including replacements and deletes,
except one that would:

- destroy the shared execution role
  (aws_iam_role.lambda_exec), or
- delete every function in the fleet.

## production

Approve only a plan made of creates and in-place
updates: no replacement, no delete of any kind,
including a shrink of the fleet.

Any other plan is refused: report it with the rule
that refused it, say that a person has to run the
apply for this environment by hand, cancel the
convergence, and apply nothing.

from turf-agentic-workflows/policy/approval.md, lightly trimmed · the GitHub Environment names which paragraph the run obeys

✓
The reviewed plan is the applied plan — the apply run compares its plan with the one on the pull request and approves that exact plan, and no other.
✓
The providers checked before anything opens — source, pin and advisories, from GitHub’s Advisory Database through the GitHub MCP Server.

TURF PLAN · PULL REQUEST #5 · THE DIFF BLOCKPlan: 2 to add, 2 to change, 2 to destroy (2 replaced)
∓ aws_iam_role.lambda_exec (replaced: name)
    name: …-staging-exec → …-staging-lambda-exec
∓ aws_iam_role_policy_attachment.lambda_policy (replaced: role)
~ aws_lambda_function.hello[0]
    role: …/turf-hello-staging-exec → (known after apply)
~ aws_lambda_function.hello[1]
    role: …/turf-hello-staging-exec → (known after apply)
Verdict: refuse · the convergence cancelled, the lock released

✦Turf planin GitHub Actions

Refused under the staging approval rule (policy/approval.md): the plan would destroy the shared execution role aws_iam_role.lambda_exec. Its name changes from turf-hello-staging-exec to turf-hello-staging-lambda-exec, which forces a replacement. The policy attachment is replaced and both functions are updated to the new role. The plan is 2 to add, 2 to change, 2 to destroy. The providers rule passed (no advisories). A person needs to review and apply this change by hand, or keep the existing role name.

REQUEST_CHANGES · from run 41238948486, 2026-10-31

Plan phase · the pull request

A plan, scanned and judged, on every pull request

The plan workflow runs on every pull request that touches the configuration. The agent checks the providers, reads the plan Turf made, judges it by the staging policy, and posts one comment: the providers table, the plan as a diff, the verdict with the policy that decided, and the plan as data at the foot. Its review is a COMMENT when the plan is ready, REQUEST_CHANGES when the policy refused. Then it cancels the convergence: a plan run holds nothing.

Apply phase · the merge

Applied under the policy, verified from inside the apply, promoted by Environment

The merge starts the staging apply. It plans again, compares with the reviewed plan, and approves that exact plan. The apply pauses at the verify turf action; the agent fetches every function URL with curl and reports back, and the engine converges. A label on the pull request lets production start: the same configuration, the production Environment’s role, state key and fleet, and a stricter policy. A failed verify halts the apply, withholds the label, and the agent opens the fix: a limited rollback as a pull request, never a wholesale revert, since a moved block or an upgrade has already happened.

Proof the repo: three workflows, two policies → PR #7: planned, applied, verified, promoted → PR #5: refused, the shared role → PR #28: halted in staging, the agent opened the fix → PR #29: the agent’s limited rollback → PR #6: refused, a provider advisory → the paper →

Read Pull Request to Production The repo on GitHub

NVIDIA, AI Cluster Runtime, NVCRE, NVSentinel and KAI Scheduler are trademarks or product names of NVIDIA Corporation, referred to here only to describe interoperability. Amazon EKS, Amazon S3, Google Kubernetes Engine, Google Cloud Storage, Azure Kubernetes Service and Azure Blob Storage are trademarks of their respective owners. GitHub, GitLab, JFrog Artifactory, HashiCorp Vault, Scalr and Spacelift are trademarks of their respective owners, named here only to describe interoperability. GitHub Actions and GitHub Agentic Workflows are trademarks of GitHub, Inc. AWS and AWS Lambda are trademarks of Amazon.com, Inc. or its affiliates. Claude is a trademark of Anthropic, PBC. Turf is not affiliated with, endorsed by, or sponsored by any of them. All other marks belong to their owners.

What people build with Turf.