This is the multi-page printable view of this section. Click here to print.
Datum Cloud provides a declarative API platform to create the infrastructure necessary to deploy and manage services with advanced networking capabilities. Many of our APIs are exposed through a Kubernetes API as Custom Resources enabling you to use much of the tooling available within the Kubernetes ecosystem to interact with our API.
Continue reading the guides below to understand how to connect and interact with the Datum Cloud API.
The Datum Cloud platform supports users authenticating with the API with
short-lived Bearer tokens. Bearer tokens can be created by creating a Personal
Access Token in the Datum Cloud Portal and using the
https://api.datum.net/datum-os/oauth/token/exchange API endpoint to exchange
the Personal Access Token for a short-lived bearer token.
▶ curl https://api.datum.net/datum-os/oauth/token/exchange \
-H "Authorization: Bearer $PAT" -sS | jq
{
"access_token": "[[redacted]]",
"token_type": "Bearer"
}
Use the returned API token to authenticate with the Datum Cloud control planes. The token should be refreshed every hour.
datumctl auth get-token command to quickly grab a short-lived
access token that can be used to authenticate with the Datum Cloud API.Invalid authentication tokens or unauthorized requests will result in the same 403 Forbidden error.
{
"kind": "Status",
"apiVersion": "v1",
"metadata": {},
"status": "Failure",
"message": "forbidden: User \"system:anonymous\" cannot get path \"/openapi/v3\"",
"reason": "Forbidden",
"details": {},
"code": 403
}
The Datum Cloud platform is comprised of multiple control planes that users can interact with to manage their organization’s resources.
A control plane is the central component responsible for managing and reconciling resources within the system. It continuously monitors the declared state of customer-defined configurations and ensures that the actual system state aligns with those definitions.
The Datum Cloud control plane acts as the authoritative source of truth, processing API requests, validating configurations, and coordinating underlying infrastructure changes. It maintains resource consistency by detecting deviations and automatically applying corrective actions.
There are two primary control planes that users will interact with to manage the resources deployed within their organization.
Most users will interact with a project control plane to manage resources.
The following base URL can be used to access an organization’s control plane:
https://api.datum.net/apis/resourcemanager.datumapis.com/v1alpha/organizations/{organization_id}/control-plane
Projects created in an organization’s control plane will have their own control plane created to manage resources. Use the following base URL to access a project’s control plane:
https://api.datum.net/apis/resourcemanager.datumapis.com/v1alpha/projects/{project_id}/control-plane
Every control plane exports the APIs available in the control plane by exporting
an OpenAPI for each service at the /openapi/v3 URL. For example, here’s an
example that demonstrates some services available in an organization’s control
plane.
$ curl -sS 'https://api.datum.net/apis/resourcemanager.datumapis.com/v1alpha/organizations/{organization_id}/control-plane/openapi/v3' \
-H "Authorization: Bearer $(datumctl auth get-token)"
{
"paths": {
"apis/resourcemanager.datumapis.com/v1alpha": {
"serverRelativeURL": "/openapi/v3/apis/resourcemanager.datumapis.com/v1alpha?hash=D0A1DF465E973D5C8FC30D065B864272955A66C14609154E7EAECC0426C71E99F3982ECBA4D5C6C92EC3DF497E159F2129D0F8A20CDC8E5746583D1BFEA80A52"
},
]
}
The URL provided in the response can be used to retrieve the OpenAPI v3 spec for the service.
There are many resources available in the Datum Cloud API that can be used to manage your infrastructure. This document provides an overview of the available resources and how to use them.
Detailed Export Policies API Reference
apiVersion: v1
items:
- apiVersion: telemetry.datumapis.com/v1alpha1
kind: ExportPolicy
metadata:
name: exportpolicy
spec:
sinks:
- name: grafana-cloud-metrics
sources:
- telemetry-metrics
- gateway-metrics
target:
prometheusRemoteWrite:
authentication:
basicAuth:
secretRef:
name: grafana-cloud-credentials
batch:
maxSize: 500
timeout: 5s
endpoint: https://prometheus-prod-56-prod-us-east-2.grafana.net/api/prom/push
retry:
backoffDuration: 2s
maxAttempts: 3
sources:
- metrics:
metricsql: |
{service_name="telemetry.datumapis.com"}
name: telemetry-metrics
- metrics:
metricsql: |
{service_name="gateway.networking.k8s.io"}
name: gateway-metrics
kind: List
metadata: {}
apiVersion: telemetry.datumapis.com/v1alpha1
kind: ExportPolicy
metadata:
name: exportpolicy-sample
spec:
# Defines the telemetry sources that should be exported. An export policy can
# define multiple telemetry sources. Telemetry data will **not** be de-duped if
# its selected from multiple sources
sources:
- name: "telemetry-metrics" # Descriptive name for the source
# Source metrics from the Datum Cloud platform
metrics:
# The options in this section are expected to be mutually exclusive. Users
# can either leverage metricsql or resource selectors.
#
# This option allows user to supply a metricsql query if they're already
# familiar with using metricsql queries to select metric data from
# Victoria Metrics.
metricsql: |
{service_name="telemetry.datumapis.com"}
sinks:
- name: grafana-cloud-metrics
sources:
- telemetry-metrics
target:
prometheusRemoteWrite:
endpoint: "https://prometheus-prod-56-prod-us-east-2.grafana.net/api/prom/push"
authentication:
basicAuth:
secretRef:
name: "grafana-cloud-credentials"
batch:
timeout: 5s # Batch timeout before sending telemetry
maxSize: 500 # Maximum number of telemetry entries per batch
retry:
maxAttempts: 3 # Maximum retry attempts
backoffDuration: 2s # Delay between retry attempts
Detailed Instances API Reference
Instances are what a workload creates.
Let’s say you create a workload to run a container and set the location to a GCP region. Datum’s workload operator will create a GCP virtual machine in that region and run the container on it. The GCP virtual machine is the instance.
Detailed Locations API Reference
apiVersion: networking.datumapis.com/v1alpha
kind: Location
metadata:
name: gcp-us-west1-a
spec:
locationClassName: datum-managed
topology:
topology.datum.net/city-code: DLS
provider:
gcp:
projectId: datum-cloud-poc-1
region: us-west1
zone: us-west1-a
Detailed Networks API Reference
apiVersion: networking.datumapis.com/v1alpha
kind: Network
metadata:
name: default
spec:
ipam:
mode: Auto
apiVersion: networking.datumapis.com/v1alpha
kind: Network
metadata:
name: default
spec:
ipam:
mode: Auto
ipv4Ranges:
- 172.17.0.0/16
ipv6Ranges:
- fd20:1234:5678::/48
Detailed Network Bindings API Reference
Detailed Network Contexts API Reference
Detailed Network Policies API Reference
Detailed Projects API Reference
kind: Project
metadata:
generateName: sample-project-
spec:
Detailed Subnet Claims API Reference
Detailed Subnets API Reference
Detailed Workload API Reference
apiVersion: compute.datumapis.com/v1alpha
kind: Workload
metadata:
labels:
tier: app
name: workload-sandbox-sample
spec:
template:
metadata:
labels:
tier: app
spec:
runtime:
resources:
instanceType: datumcloud/d1-standard-2
sandbox:
containers:
- name: netdata
image: docker.io/netdata/netdata:latest
volumeAttachments:
- name: secret
mountPath: /secret
- name: configmap
mountPath: /configmap
networkInterfaces:
- network:
name: default
networkPolicy:
ingress:
- ports:
- port: 19999
- port: 22
from:
- ipBlock:
cidr: 0.0.0.0/0
volumes:
- name: secret
secret:
secretName: workload-sandbox-sample-secret
- name: configmap
configMap:
name: workload-sandbox-sample-configmap
placements:
- name: us
cityCodes:
- DFW
scaleSettings:
minReplicas: 1
apiVersion: compute.datumapis.com/v1alpha
kind: Workload
metadata:
labels:
tier: app
name: workload-sample
spec:
template:
metadata:
labels:
tier: app
spec:
runtime:
resources:
instanceType: datumcloud/d1-standard-2
sandbox:
containers:
- name: netdata
image: docker.io/netdata/netdata:latest
networkInterfaces:
- network:
name: default
networkPolicy:
ingress:
- ports:
- port: 19999
from:
- ipBlock:
cidr: 0.0.0.0/0
placements:
- name: us-south
cityCodes:
- DFW
scaleSettings:
minReplicas: 1
- name: us-south2
cityCodes:
- DFW
scaleSettings:
minReplicas: 1
apiVersion: compute.datumapis.com/v1alpha
kind: Workload
metadata:
labels:
tier: app
name: workload-vm-sample
spec:
template:
metadata:
annotations:
compute.datumapis.com/ssh-keys: |
myuser:ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAqyjfr0gTk1lxqA/eEac0djYWuw+ZLFphPHmfWwxbO5 joshlreese@gmail.com
labels:
tier: app
spec:
runtime:
resources:
instanceType: datumcloud/d1-standard-2
virtualMachine:
volumeAttachments:
- name: boot
- name: secret
mountPath: /secret
- name: configmap
mountPath: /configmap
networkInterfaces:
- network:
name: default
networkPolicy:
ingress:
- ports:
- port: 22
from:
- ipBlock:
cidr: 0.0.0.0/0
volumes:
- name: boot
disk:
template:
spec:
type: pd-standard
populator:
image:
name: datumcloud/ubuntu-2204-lts
- name: secret
secret:
secretName: workload-vm-sample-secret
- name: configmap
configMap:
name: workload-vm-sample-configmap
placements:
- name: us-south
cityCodes:
- DFW
scaleSettings:
minReplicas: 1
This is an example of a location that specifies a GCP region (us-central1) and a city code (DFW for Dallas Fort Worth):
apiVersion: compute.datumapis.com/v1alpha
kind: Location
metadata:
name: my-gcp-us-south1-a
spec:
locationClassName: datum-managed
topology:
topology.datum.net/city-code: DFW
provider:
gcp:
projectId: my-gcp-project
region: us-south1
zone: us-south1-a
Let’s walk through the sample spec and review each of the key components.
name: my-gcp-us-south1-a
locationClassName field specifies the class of the location. In this
case, it’s set to datum-managed, indicating that this location is managed by
Datum. Alternately, it can be set to self-managed for users who have deployed
their own self-managed Datum control-plane.locationClassName: datum-managed
The topology field is used to specify which Datum mangaed network to connect
to. Currently Datum offers the following City locations:
DFW (Dallas Fort Worth, Texas, USA)LHR (Heathrow, London, England)DLS (Dalles, Oregon, USA)topology:
topology.datum.net/city-code: DFW
provider section is where you tell it which cloud provider to use to
deploy your workload. For the GCP cloud provider, you specify the project ID,
region, and zone.provider:
gcp:
projectId: my-gcp-project
region: us-south1
zone: us-south1-a
For a complete API specification of the Location resource, refer to the Detailed Reference.
When deploying workloads in Datum, networks are used to define the IP Address Management of the workloads.
Most workloads can use the default network configuration shown below. This configuration leverages Datum’s built-in IP Address Management (IPAM) to automatically handle IP address assignment.
apiVersion: networking.datumapis.com/v1alpha
kind: Network
metadata:
name: default
spec:
ipam:
mode: Auto
Datum’s automatic IPAM mode simplifies network management by eliminating the need to manually configure IP addresses for each workload.
Default Auto Configuration:
spec:
ipam:
mode: Auto
In Auto mode, Datum uses the following default IP address ranges:
10.128.0.0/9fd20::/20You can override the default IP ranges by specifying custom ranges in your network manifest.
spec:
ipam:
mode: Auto
ipv4Ranges:
- 172.17.0.0/16
ipv6Ranges:
- fd20:1234:5678::/48
For a complete API specification of the Location resource, refer to the Detailed Reference.
Datum lets you deploy and manage workloads. Today, these workloads can be either virtual machines or containers. They’re defined like any other Kubernetes custom resource, usually in YAML.
This is an example of a workload that runs an nginx container and places it first location you have defined in your Datum project that is associated with DFW (Dallas Fort Worth).
apiVersion: compute.datumapis.com/v1alpha
kind: Workload
metadata:
name: nginx-workload
spec:
template:
spec:
runtime:
resources:
instanceType: datumcloud/d1-standard-2
sandbox:
containers:
- name: nginx
image: nginx:latest
ports:
- name: http
port: 8080
networkInterfaces:
- network:
name: default
networkPolicy:
ingress:
- ports:
- port: 8080
from:
- ipBlock:
cidr: 0.0.0.0/0
placements:
- name: us
cityCodes: ['DFW']
scaleSettings:
minReplicas: 1
Let’s walk through the sample spec and review each of the key components.
The name of the workload.
name: nginx-workload
The runtime environment for the workload. Datum currently supports Virtual Machines or containers as runtime environments, our sample uses a container runtime.
runtime:
sandbox:
containers:
- name: nginx
image: nginx/nginx
ports:
- name: http
port: 8080
The type of instance to use for the workload, currently datumcloud/d1-standard-2 is the only supported type.
instanceType: datumcloud/d1-standard-2
The network to connect the workload to, which ports should to expose, and what IPs to allow access from.
networkInterfaces:
- network:
name: default
networkPolicy:
ingress:
- ports:
- port: 8080
from:
- ipBlock:
cidr: 0.0.0.0/0
The placement of the workload, which defines where the workload should run. In this case, it will run in the first location in your project associated with DFW (Dallas Fort Worth).
placements:
- name: us
cityCodes: ['DFW']
scaleSettings:
minReplicas: 1
For a complete API specification of the Location resource, refer to the Detailed Reference.