datum-cloud · scotwells · Jul 2, 2026
diff --git a/api/billing/billingaccount.mdx b/api/billing/billingaccount.mdx
@@ -0,0 +1,99 @@
+---
+title: "BillingAccount"
+sidebarTitle: "BillingAccount"
+description: "BillingAccount is the Schema for the billingaccounts API. It represents a billing entity within an organization that is responsible for paying for service consumption."
+---
+
+<Note>
+  API resource reference for **BillingAccount**, part of the [Billing service](/api/billing/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+</Note>
+
+<Warning>
+  This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+</Warning>
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `billing.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `BillingAccount` |
+| Scope | Project |
+
+## Overview
+
+A `BillingAccount` represents the paying entity within an organization that is charged for service consumption. Use it to record who is billed, the currency invoices are issued in, the postal contact and address printed on invoices, the default payment method used to process charges, the invoicing schedule, and any tax registrations that apply to the account.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.currencyCode` | string | Yes | ISO 4217 currency code for this billing account. Immutable once the account transitions past the Provisioning phase. |
+| `spec.contactInfo` | Object | No | Billing contact and the postal address invoices are issued to. |
+| `spec.contactInfo.email` | string | Yes* | Primary billing contact email. Receives billing notifications and, when `invoiceEmails` is unset, also receives invoices and receipts. (*Required when `contactInfo` is set.) |
+| `spec.contactInfo.name` | string | No | Display name of the individual billing contact. Appears as the "ATTN:" line on invoices when `businessName` is also set. |
+| `spec.contactInfo.businessName` | string | No | Legal entity that pays. Populate for B2B accounts so invoices print the company name; maps onto the provider `Customer.name`. |
+| `spec.contactInfo.invoiceEmails` | []string | No | Recipients for invoices and receipts. First entry is primary, the rest are CC'd. Duplicates rejected; maximum 10 entries. |
+| `spec.contactInfo.address` | Object | No | Postal billing address. Appears on invoices and is surfaced to the provider controller for tax determination and address verification. |
+| `spec.contactInfo.address.country` | string | Yes* | ISO 3166-1 alpha-2 country code (e.g. `GB`, `US`). (*Required when `address` is set — tax and currency restrictions depend on it.) |
+| `spec.contactInfo.address.line1` | string | No | First line of the street address (typically number + street). |
+| `spec.contactInfo.address.line2` | string | No | Second line of the street address (apartment / suite / building). |
+| `spec.contactInfo.address.city` | string | No | Locality. |
+| `spec.contactInfo.address.region` | string | No | State, province, or county (free-form). |
+| `spec.contactInfo.address.postalCode` | string | No | Post / zip code. |
+| `spec.defaultPaymentMethodRef` | Object | No | References the `PaymentMethod` used by default for charge processing. Must reside in the same Project and be in the Active phase. |
+| `spec.defaultPaymentMethodRef.name` | string | Yes* | Name of the referenced `PaymentMethod`. (*Required when the reference is set.) |
+| `spec.paymentTerms` | Object | No | Invoicing schedule for this billing account. |
+| `spec.paymentTerms.invoiceFrequency` | string | No | How often invoices are generated. One of `Monthly`, `Quarterly`, `Annual`. |
+| `spec.paymentTerms.invoiceDayOfMonth` | integer | No | Day of the month invoices are generated. |
+| `spec.paymentTerms.netDays` | integer | No | Number of days after the invoice date that payment is due. |
+| `spec.taxIds` | []Object | No | Tax registrations attached to this account. An account can carry multiple entries. |
+| `spec.taxIds[].type` | string | Yes* | Tax registration scheme, following a `<jurisdiction>_<scheme>` convention (e.g. `gb_vat`, `eu_vat`, `us_ein`). (*Required per entry.) |
+| `spec.taxIds[].value` | string | Yes* | Registration number / identifier (e.g. `GB123456789`). (*Required per entry.) |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.phase` | string | Current lifecycle phase. One of `Provisioning`, `Ready`, `Suspended`, `Archived`. |
+| `status.linkedProjectsCount` | integer | Number of projects currently bound to this billing account. |
+| `status.conditions` | []Object | Latest available observations of the billing account's state. |
+| `status.observedGeneration` | integer | Most recent generation observed by the controller. |
+
+## Usage
+
+```yaml
+apiVersion: billing.miloapis.com/v1alpha1
+kind: BillingAccount
+metadata:
+  name: acme-billing
+spec:
+  currencyCode: GBP
+  contactInfo:
+    email: billing@acme.example
+    name: Jane Doe
+    businessName: Acme Ltd
+    address:
+      country: GB
+      line1: 1 High Street
+      city: London
+      postalCode: SW1A 1AA
+  paymentTerms:
+    invoiceFrequency: Monthly
+    invoiceDayOfMonth: 1
+    netDays: 30
+  taxIds:
+    - type: gb_vat
+      value: GB123456789
+```
+
+```bash
+datumctl apply -f billingaccount.yaml --project my-project
+datumctl get billingaccounts --project my-project
+datumctl describe billingaccount acme-billing --project my-project
+```
+
+<Tip>
+  Run `datumctl explain billingaccounts --recursive` to see the full, live field tree for this resource.
+</Tip>
diff --git a/api/billing/billingaccountbinding.mdx b/api/billing/billingaccountbinding.mdx
@@ -0,0 +1,72 @@
+---
+title: "BillingAccountBinding"
+sidebarTitle: "BillingAccountBinding"
+description: "BillingAccountBinding links a project to a billing account, establishing billing responsibility for the project's resource consumption."
+---
+
+<Note>
+  API resource reference for **BillingAccountBinding**, part of the [Billing service](/api/billing/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+</Note>
+
+<Warning>
+  This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+</Warning>
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `billing.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `BillingAccountBinding` |
+| Scope | Project |
+
+## Overview
+
+A `BillingAccountBinding` connects a Project to a billing account so that the Project's resource consumption is charged to that account. Creating a binding establishes billing responsibility for the Project; the platform tracks which account is currently responsible and when that responsibility took effect.
+
+All fields in the spec are immutable once the binding is created. To move a Project to a different billing account, create a new binding — the previous one moves to the `Superseded` phase.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.billingAccountRef` | Object | Yes | References the billing account to bind. |
+| `spec.billingAccountRef.name` | string | Yes | Name of the BillingAccount. |
+| `spec.projectRef` | Object | Yes | References the project to bind to the billing account. |
+| `spec.projectRef.name` | string | Yes | Name of the project. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.phase` | string | Current lifecycle phase of the binding. One of `Active` or `Superseded`. |
+| `status.billingResponsibility` | Object | Tracks when billing responsibility was established for this binding. |
+| `status.billingResponsibility.currentAccount` | string | Name of the currently responsible billing account. |
+| `status.billingResponsibility.establishedAt` | string | Time when billing responsibility was established. |
+| `status.conditions` | []Object | Latest available observations of the binding's state. |
+| `status.observedGeneration` | integer | Most recent generation observed by the controller. |
+
+## Usage
+
+```yaml
+apiVersion: billing.miloapis.com/v1alpha1
+kind: BillingAccountBinding
+metadata:
+  name: my-project-billing
+spec:
+  billingAccountRef:
+    name: acme-billing-account
+  projectRef:
+    name: my-project
+```
+
+```bash
+datumctl apply -f billingaccountbinding.yaml --project my-project
+datumctl get billingaccountbindings --project my-project
+datumctl describe billingaccountbindings my-project-billing --project my-project
+```
+
+<Tip>
+  Run `datumctl explain billingaccountbindings --recursive` to see the full, live field tree for this resource.
+</Tip>
diff --git a/api/billing/overview.mdx b/api/billing/overview.mdx
@@ -0,0 +1,34 @@
+---
+title: "Billing"
+sidebarTitle: "Overview"
+description: "Billing on Datum Cloud — billing accounts, the projects bound to them, and the payment methods that fund service consumption."
+---
+
+Datum Cloud manages billing through the `billing.miloapis.com` API. A **billing account** is the entity within an organization responsible for paying for service consumption; you bind projects to it so their usage rolls up to a single payer, and you attach payment methods that fund the account. Billing accounts and payment methods are created with `datumctl apply -f` and inspected with `datumctl get` and `datumctl describe`.
+
+<Warning>
+  The Billing API is **alpha** (`v1alpha1`). Fields and behavior may change in backward-incompatible ways between releases.
+</Warning>
+
+## Resources
+
+<CardGroup cols={2}>
+  <Card title="BillingAccount" icon="file-invoice-dollar" href="/api/billing/billingaccount">
+    A billing entity within an organization that is responsible for paying for service consumption.
+  </Card>
+  <Card title="BillingAccountBinding" icon="link" href="/api/billing/billingaccountbinding">
+    Links a project to a billing account, establishing billing responsibility for the project's resource consumption.
+  </Card>
+  <Card title="PaymentMethod" icon="credit-card" href="/api/billing/paymentmethod">
+    Associates a payment instrument with a billing account to fund it.
+  </Card>
+</CardGroup>
+
+<Tip>
+  Inspect the exact fields for any resource with `datumctl explain`, for example `datumctl explain billingaccounts.spec` or `datumctl explain paymentmethods.spec`.
+</Tip>
+
+## Learn more
+
+- [API resources overview](/api/overview) — the resource reference landing page across all Datum Cloud services.
+- [Changing resources](/datumctl/resources/changing) — how to apply, edit, and safely preview changes to these resources.
diff --git a/api/billing/paymentmethod.mdx b/api/billing/paymentmethod.mdx
@@ -0,0 +1,75 @@
+---
+title: "PaymentMethod"
+sidebarTitle: "PaymentMethod"
+description: "PaymentMethod is the Schema for the paymentmethods API."
+---
+
+<Note>
+  API resource reference for **PaymentMethod**, part of the [Billing service](/api/billing/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+</Note>
+
+<Warning>
+  This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
+</Warning>
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `billing.miloapis.com` |
+| Version | `v1alpha1` |
+| Kind | `PaymentMethod` |
+| Scope | Project |
+
+## Overview
+
+A `PaymentMethod` associates a payment instrument — such as a credit card or US bank account — with a `BillingAccount`. You create one carrying only a reference to the billing account and a human-readable display name. The billing service then injects the `PaymentMethodClass` that selects the provider, and the provider controller drives the setup flow and reports the confirmed instrument back on `status` once it is active.
+
+Use it when you need to register a new way to pay for a billing account within a Project.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.billingAccountRef` | Object | Yes | References the `BillingAccount` this payment method belongs to. The BillingAccount must reside in the same Project. |
+| `spec.billingAccountRef.name` | string | Yes | The name of the `BillingAccount`. |
+| `spec.displayName` | string | Yes | A human-readable label shown in the portal and on invoices (e.g., `Corporate Visa`). |
+| `spec.paymentMethodClassRef` | Object | No | Selects the `PaymentMethodClass` — and through it the provider controller — that owns the setup flow. Left unset by consumers and injected by the defaulting webhook. Immutable once set. |
+| `spec.paymentMethodClassRef.name` | string | No | The name of the `PaymentMethodClass`. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.phase` | string | Current lifecycle phase: `Pending`, `AwaitingConfirmation`, `Active`, or `Failed`. |
+| `status.details` | Object | Normalized, provider-agnostic description of the confirmed instrument. Populated once the phase reaches `Active`. |
+| `status.details.type` | string | The instrument category: `card` or `usBankAccount`. |
+| `status.details.card` | Object | Card details, populated when `type` is `card`. |
+| `status.details.usBankAccount` | Object | US bank account details, populated when `type` is `usBankAccount`. |
+| `status.failureReason` | string | Short, machine-parseable failure code (e.g., `card_declined`). Set when phase is `Failed`. |
+| `status.failureMessage` | string | Human-readable description of the failure. |
+| `status.conditions` | []Object | Latest available observations of the payment method's state. |
+| `status.observedGeneration` | integer | Most recent generation observed by the reconciling controller. |
+
+## Usage
+
+```yaml
+apiVersion: billing.miloapis.com/v1alpha1
+kind: PaymentMethod
+metadata:
+  name: corporate-visa
+spec:
+  billingAccountRef:
+    name: acme-billing
+  displayName: Corporate Visa
+```
+
+```bash
+datumctl apply -f paymentmethod.yaml --project my-project
+datumctl get paymentmethods --project my-project
+datumctl describe paymentmethod corporate-visa --project my-project
+```
+
+<Tip>
+  Run `datumctl explain paymentmethods --recursive` to see the full, live field tree for this resource.
+</Tip>
diff --git a/api/compute/instance.mdx b/api/compute/instance.mdx
@@ -0,0 +1,91 @@
+---
+title: "Instance"
+sidebarTitle: "Instance"
+description: "Instance is the Schema for the instances API."
+---
+
+<Note>
+  API resource reference for **Instance**, part of the [Compute service](/api/compute/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
+</Note>
+
+<Warning>
+  This resource is part of the `v1alpha` API and is subject to change. Fields and behavior may change in future releases.
+</Warning>
+
+## Identity
+
+| | |
+| --- | --- |
+| Group | `compute.datumapis.com` |
+| Version | `v1alpha` |
+| Kind | `Instance` |
+| Scope | Project |
+
+## Overview
+
+An `Instance` represents a single compute workload running in a Datum Cloud Project. Each instance runs one of two runtime types: a **sandbox** (a managed, isolated environment for running one or more containers) or a **virtual machine** (a classical VM booting a full OS from a user-provided image). Every instance attaches to one or more networks through its network interfaces and may mount volumes backed by disks, config maps, or secrets.
+
+Use an `Instance` when you need to run application code — as containers or as a full VM — with a defined instance type, network connectivity, and optional persistent storage inside a Project.
+
+## Spec fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `spec.runtime` | Object | Yes | The runtime type of the instance, such as a container sandbox or a VM. |
+| `spec.runtime.resources` | Object | Yes | Resources each instance must be allocated across its containers or VM. |
+| `spec.runtime.resources.instanceType` | string | Yes | Full or partial URL of the instance type resource to use (for example, `datumcloud/d1-standard-2`). |
+| `spec.runtime.resources.requests` | map[string]Object | No | Adjustments to the resources defined by the instance type (for customizable instance families). |
+| `spec.runtime.sandbox` | Object | No | A managed isolated environment capable of running containers. |
+| `spec.runtime.sandbox.containers` | []Object | Yes (if sandbox) | The containers to run within the sandbox; each requires a `name` and `image`. |
+| `spec.runtime.sandbox.imagePullSecrets` | []Object | No | Secrets in the same Project used for pulling images. |
+| `spec.runtime.virtualMachine` | Object | No | A classical VM environment booting a full OS from a user-provided image. |
+| `spec.runtime.virtualMachine.volumeAttachments` | []Object | Yes (if VM) | Volumes to attach to the VM. |
+| `spec.runtime.virtualMachine.ports` | []Object | No | Named ports for the virtual machine. |
+| `spec.networkInterfaces` | []Object | Yes | Network interface configuration for the instance. |
+| `spec.networkInterfaces[].network` | Object | Yes | The network to attach the interface to; `network.name` is required. |
+| `spec.networkInterfaces[].networkPolicy` | Object | No | An interface-specific, platform-managed network policy targeting this interface. |
+| `spec.volumes` | []Object | No | Volumes available to attach to the instance's containers or VM. |
+| `spec.volumes[].name` | string | Yes (per volume) | Name used to reference the volume in container/VM volume attachments. |
+| `spec.volumes[].disk` | Object | No | A persistent disk backed volume. |
+| `spec.volumes[].configMap` | Object | No | A config map that populates this volume. |
+| `spec.volumes[].secret` | Object | No | A secret that populates this volume. |
+| `spec.location` | Object | No | The location the instance has been scheduled to (`name` and `namespace`). |
+| `spec.controller` | Object | No | Settings driven by the controller managing the instance, including `templateHash` and `schedulingGates`. |
+
+## Status fields (read-only)
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status.conditions` | []Object | Observations of the instance's current state; known types are `Available` and `Progressing`. |
+| `status.controller` | Object | Controller status, including the `observedTemplateHash` last applied to this instance. |
+| `status.networkInterfaces` | []Object | Network interface information, including address assignments. |
+
+## Usage
+
+```yaml
+apiVersion: compute.datumapis.com/v1alpha
+kind: Instance
+metadata:
+  name: web-server
+spec:
+  runtime:
+    resources:
+      instanceType: datumcloud/d1-standard-2
+    sandbox:
+      containers:
+        - name: web
+          image: nginx:1.27
+  networkInterfaces:
+    - network:
+        name: default
+```
+
+```bash
+datumctl apply -f instance.yaml --project my-project
+datumctl get instances --project my-project
+datumctl describe instance web-server --project my-project
+```
+
+<Tip>
+  Run `datumctl explain instances --recursive` to see the full, live field tree for this resource.
+</Tip>