> ## Documentation Index
> Fetch the complete documentation index at: https://www.datum.net/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Agent home for Datum, with what it is, pricing, and how to act: https://agents.datum.net
> If you can only fetch URLs: read https://www.datum.net/docs/llms.txt in full and open the most specific page for the task. Commands, limits, and field paths are on task, operations, and limits pages, not on section overviews. Pages described as "Documentation is coming soon" are placeholders.
> If you have a shell or can save files: download https://www.datum.net/docs/llms-full.txt (every page, about 740 KB) once and search it with grep, instead of fetching pages one at a time.
> datumctl describes itself: `datumctl api-resources` lists resource types and `datumctl explain <resource>` shows a schema. To act on live resources, use Datum MCP or datumctl. To search the docs, use the Docs MCP server at https://www.datum.net/docs/mcp.

# gVPC configuration

> Create a gVPC network, attach a Compute workload to it, and keep Instance addresses.

To learn how networks relate to projects, locations, and Instances, see [Networks overview](https://www.datum.net/docs/galactic-vpc/networks/overview). To view, change, or delete a network, see [Operations](https://www.datum.net/docs/galactic-vpc/operations.md).

> [!NOTE]
>
> [gVPC](https://www.datum.net/docs/galactic-vpc/overview.md) is in preview, and the `networking.datumapis.com/v1alpha` API can change.

## Before you begin

* Install `datumctl`, log in, and select a project. For more information, see [Install datumctl](https://www.datum.net/docs/datumctl/install.md).
* To create, change, or delete networks, you need the **Network Admin** role in the project. The same role lets you attach workloads to a network. For more information, see [Permissions](#permissions).

## Create a network

To create a network, follow these steps:

1. Save the following manifest as `network.yaml`:

   ```yaml theme={null}
   apiVersion: networking.datumapis.com/v1alpha
   kind: Network
   metadata:
     name: backend
   spec:
     ipam:
       mode: Auto
   ```

   `spec.ipam.mode: Auto` tells Datum to assign the network's address space. `ipam.mode` is the only field that you need to set.

2. To create the network, run the following command:

   ```bash theme={null}
   datumctl apply -f network.yaml
   ```

3. To check that the network is ready, run the following command:

   ```bash theme={null}
   datumctl get networks
   ```

   When the network is ready, the `IPV6PREFIX` column shows the private IPv6 prefix that Datum assigned, and the `READY` column shows `True`.

A network has two optional settings: `spec.ipFamilies` defaults to `[IPv6]`, and `spec.mtu` defaults to `1440`. Keep the defaults unless you have a reason to change them. Datum rejects a network that doesn't include IPv6, and a larger MTU can cause connections between locations to stall.

To create a network with the `network` plugin instead of a manifest, run the following command:

```bash theme={null}
datumctl network create backend --wait
```

The plugin creates the same IPv6-only network. To install the plugin, see [Operations](https://www.datum.net/docs/galactic-vpc/operations.md#install-the-plugin).

## Attach a workload to a network

A workload chooses its network when you create it. You can't move a workload to a different network later.

To attach a workload with `datumctl`, pass `--network` when you create it:

```bash theme={null}
datumctl compute deploy WORKLOAD_NAME \
  --image=IMAGE \
  --location=LOCATION \
  --network=NETWORK_NAME
```

Replace the following:

* `WORKLOAD_NAME`: a name for your workload.
* `IMAGE`: the full image reference, including the registry host.
* `LOCATION`: one or more locations, separated by commas.
* `NETWORK_NAME`: the name of the network, such as `backend`.

If you omit `--network`, the command attaches the workload to the `default` network. For more information, see [The default network](https://www.datum.net/docs/galactic-vpc/networks/overview#the-default-network).

To attach a workload in a manifest, set `network.name` in the workload's only entry under `spec.template.spec.networkInterfaces`. The following workload runs in Dallas and Ashburn on the `backend` network:

```yaml theme={null}
apiVersion: compute.datumapis.com/v1alpha
kind: Workload
metadata:
  name: api
spec:
  template:
    spec:
      runtime:
        class: general-purpose
        resources:
          instanceType: datumcloud/d1-standard-2
        sandbox:
          containers:
            - name: api
              image: ghcr.io/example/api:1.4.2
              ports:
                - name: http
                  port: 8080
      networkInterfaces:
        - network:
            name: backend
  placements:
    - name: dallas
      locations:
        - name: us-central-1
      scaleSettings:
        minReplicas: 1
    - name: ashburn
      locations:
        - name: us-east-1
      scaleSettings:
        minReplicas: 1
```

If the network doesn't exist, the workload reports `NetworkNotFound` and no Instances start. If you don't have permission to use the network, Datum rejects the workload with `permission to use the network was denied`.

## Keep addresses after scale-down

By default, an Instance keeps its address when Datum replaces it during a rollout or restart, but Datum releases the address when it removes the Instance, such as when you scale down or delete the workload.

To keep addresses reserved even after scale-down, set `reclaimPolicy: Retain` on the network interface when you create the workload:

```yaml theme={null}
networkInterfaces:
  - network:
      name: backend
    reclaimPolicy: Retain
```

Retained addresses stay reserved even when you scale down. You can't change `reclaimPolicy` after you create the workload.

To see and release the interfaces that hold retained addresses after their Instance is gone, see [Manage network interfaces](https://www.datum.net/docs/galactic-vpc/operations.md#manage-network-interfaces).

## Permissions

Networks use the following roles and permissions:

| Task | What you need |
| - | - |
| View networks | The **Network Viewer** role or the **Network Admin** role. |
| Create, change, or delete a network | The **Network Admin** role. |
| Attach a workload to a network | The `networking.datumapis.com/networks.use` permission on the network, in addition to permission to create the workload. The **Network Admin** role includes `networks.use`. Datum checks the permission when you create the workload. |
| Attach an ALB to a workload | The **Network Admin** role. For more information, see [Publish a workload](https://www.datum.net/docs/compute/compute-and-alb.md). |

## What's next

* To view, change, and delete networks, see [Operations](https://www.datum.net/docs/galactic-vpc/operations.md).
* To give a workload a stable name for a load balancer, see [Network services](https://www.datum.net/docs/galactic-vpc/networks/network-services.md).
* To learn how Instances get addresses, see [Addressing](https://www.datum.net/docs/galactic-vpc/networks/addressing.md).
* To review what networks can't do, see [Limitations and roadmap](https://www.datum.net/docs/galactic-vpc/limitations-and-roadmap.md).
* To serve a workload publicly through Datum's ALB, see [Compute and ALB](https://www.datum.net/docs/compute/compute-and-alb.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.