Skip to main content
This reference architecture helps platform engineers and infrastructure teams deploy a production-ready CoreWeave environment with Terraform. It uses a modular repository that provisions a VPC, CoreWeave Kubernetes Service (CKS) cluster, node pools, and Distributed File Storage (DFS) in two phases. Phase 1 creates the networking and cluster. Phase 2 adds node pools and DFS volumes after the cluster runs and you have kubeconfig. CoreWeave AI Object Storage is an optional add-on you can include at any point. Use this page to understand what the architecture deploys, the prerequisites you must meet, and how the repository is organized before you begin Phase 1.

​
What this deploys

The reference architecture uses a single Terraform root with separate modules for each resource. The two-phase apply exists because node pools and DFS volumes are Kubernetes manifests, which need a running cluster and kubeconfig before Terraform can create them.

​
Phase 1: Networking and cluster

ResourceDescription
VPCCoreWeave VPC with host prefixes and named CIDR prefixes for CKS (pod, service, internal LB).
CKS clusterCKS cluster in the VPC. Supports OIDC configuration for external IdPs.

​
Phase 2: Node pools and storage

ResourceDescription
NodePoolsOne or more CKS node pools (Kubernetes manifest). Requires kubeconfig from Phase 1.
DFS PVCsOne or more Distributed File Storage PVCs (shared-vast, ReadWriteMany). Requires kubeconfig from Phase 1.

​
Optional: Object Storage add-on

Object Storage is independent of the two-phase apply, and you can add it at any point.
ResourceDescription
Object Storage org access policyOrganization-wide access policy for Object Storage. At least one must exist before creating buckets.
Object Storage bucketObject Storage (S3-compatible) bucket.
Object Storage bucket policyPer-bucket S3-compatible access policy for fine-grained control.

Phase 1: Deploy core infrastructure

Create a VPC and CKS cluster, then download kubeconfig.Deploy core infrastructure

Phase 2: Add node pools and storage

Add node pools, DFS volumes, and optionally Object Storage.Add node pools and storage

​
Prerequisites

Before you begin, ensure you have the required tools and Identity and Access Management (IAM) roles described in the following sections.

​
Tools

​
IAM roles

Your CoreWeave user or API token must have the appropriate IAM roles for each phase. The following table lists the minimum required roles.
PhaseRequired IAM role
Phase 1 (VPC and CKS cluster)CKS Admin to create, update, and delete clusters and VPC resources.
Phase 2 (NodePool and DFS)CKS Admin and kubeconfig for the cluster.
Object Storage add-on (optional)Object Storage Admin to create or delete buckets and manage organization access policies.
OIDC WIF setup (optional)IAM Admin to configure identity integrations, including Workload Identity Federation.
If you’re using legacy group role assignments, users in the admin or write groups already have the CKS Admin and Object Storage Admin roles.

​
Repository structure

Review the repository layout before you start to locate the files you edit during each phase. The reference architecture repository organizes all resources as modules. The root main.tf wires them together. 
.
├── README.md
├── .gitignore
├── .terraform.lock.hcl       # Committed for reproducible provider versions
├── terraform.tfvars.example  # Copy to terraform.tfvars and fill in your values
├── providers.tf              # CoreWeave + Kubernetes providers, token variable
├── main.tf                   # Calls all modules (network, cks, object_storage, nodepool, dfs)
├── variables.tf              # Root variables (passed into modules)
├── outputs.tf                # Outputs from each module
└── modules/
    ├── network/              # VPC (coreweave_networking_vpc)
    │   ├── main.tf
    │   ├── variables.tf
    │   ├── outputs.tf
    │   └── versions.tf
    ├── cks/                  # CKS cluster (coreweave_cks_cluster)
    │   ├── main.tf
    │   ├── variables.tf
    │   ├── outputs.tf
    │   └── versions.tf
    ├── object_storage/       # Optional AI Object Storage bucket + policies
    │   ├── main.tf           # Bucket, org access policy, bucket policy
    │   ├── variables.tf
    │   ├── outputs.tf
    │   └── versions.tf
    ├── nodepool/             # CKS NodePool (kubernetes_manifest, Phase 2)
    │   ├── main.tf
    │   ├── variables.tf
    │   ├── outputs.tf
    │   └── versions.tf
    └── dfs/                  # DFS PVC (shared-vast, kubernetes_manifest, Phase 2)
        ├── main.tf
        ├── variables.tf
        ├── outputs.tf
        └── versions.tf
  • Don’t commit terraform.tfvars. Create it from terraform.tfvars.example.
  • Don’t commit state files (*.tfstate). Use a remote backend for production environments.

​
Outputs

After apply, Terraform outputs include:
OutputSourceDescription
vpc_idmodule.networkCreated VPC ID.
cks_cluster_idmodule.cksCKS cluster ID.
cks_cluster_namemodule.cksCKS cluster name.
cks_api_server_endpointmodule.cksKubernetes API server endpoint.
cks_statusmodule.cksCurrent cluster status.
cks_service_account_oidc_issuer_urlmodule.cksOIDC issuer URL for CKS service account tokens (use for WIF).
nodepoolsmodule.nodepoolMap of created NodePool names.
dfs_pvcsmodule.dfsMap of created DFS PVCs.
If you include the Object Storage add-on, the following outputs are also available.
OutputSourceDescription
object_storage_bucket_namemodule.object_storageBucket name, if created.
object_storage_org_access_policy_namesmodule.object_storageMap of created org access policy names.
object_storage_bucket_policy_jsonmodule.object_storageBucket policy JSON, if applied.
Last modified on June 4, 2026