Skip to content
Merged
3 changes: 1 addition & 2 deletions compute/limitations-and-roadmap.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@

- One instance type is available, and you can't set CPU or memory for each container.
- Persistent disks aren't available. The workload API includes a `disk` volume type, but no runtime class serves it, so Datum rejects a workload that declares one. Files written at runtime are lost when Datum replaces an Instance. For details, see [Disk volumes](/compute/configuration#disk-volumes).
- Raw devices, GPUs, and custom virtual machine images aren't available.

Check warning on line 21 in compute/limitations-and-roadmap.mdx

View check run for this annotation

Mintlify / Mintlify Validation (datum-4926dda5) - vale-spellcheck

compute/limitations-and-roadmap.mdx#L21

Did you really mean 'GPUs'?
- Instances with more than one container aren't supported. Run one container per workload.
- Health probes, such as readiness and liveness checks, aren't available. An Instance is ready when its containers are running.

Check warning on line 23 in compute/limitations-and-roadmap.mdx

View check run for this annotation

Mintlify / Mintlify Validation (datum-4926dda5) - vale-spellcheck

compute/limitations-and-roadmap.mdx#L23

Did you really mean 'liveness'?
- You can't suspend, resume, or snapshot Instances. You can open a shell or run a command in a running `general-purpose` Instance; see [Instance shell sessions](/compute/instance-shell).
- A workload's runtime class and network can't change after you create it.

Expand All @@ -28,14 +28,13 @@

- Compute runs in `us-central-1` (Dallas), `us-east-1` (Ashburn), and `us-west-1` (San Jose).
- Workloads don't scale automatically, and they can't scale to zero. Don't set `scaleSettings.maxReplicas` or `scaleSettings.metrics`.
- Rollouts replace Instances one at a time in each location, with no option to add extra Instances during the rollout.

Check warning on line 31 in compute/limitations-and-roadmap.mdx

View check run for this annotation

Mintlify / Mintlify Validation (datum-4926dda5) - vale-spellcheck

compute/limitations-and-roadmap.mdx#L31

Did you really mean 'Rollouts'?

### Networking

- During the preview, Instances have private IPv6 addresses only. Private IPv4 addresses and public IP addresses are a preview limitation.
- Instances reach IPv4-only internet services by hostname only, through DNS64 and NAT64. A connection to an IPv4 address fails. See [Reach the internet](/galactic-vpc/networks/traffic#reach-the-internet).
- Every Instance can reach the internet, and you can't turn that off. Outbound traffic leaves from shared addresses that Datum doesn't publish, so you can't allowlist your Instances at a destination.

Check warning on line 37 in compute/limitations-and-roadmap.mdx

View check run for this annotation

Mintlify / Mintlify Validation (datum-4926dda5) - vale-spellcheck

compute/limitations-and-roadmap.mdx#L37

Did you really mean 'allowlist'?
- Private DNS names for Instances are on the [roadmap](/galactic-vpc/limitations-and-roadmap#planned-capabilities).
- Firewall rules to filter traffic between Instances on a network are on the [roadmap](/galactic-vpc/limitations-and-roadmap#planned-capabilities).
- Public access is HTTP and HTTPS only, served through Datum's [ALB](/alb/overview). Raw TCP and UDP exposure is a preview limitation.

Expand All @@ -48,7 +47,7 @@

## Roadmap

Networking capabilities for Compute Instances, such as private DNS and firewall rules, are tracked in [gVPC planned capabilities](/galactic-vpc/limitations-and-roadmap#planned-capabilities). For the overall Datum roadmap, see [Platform roadmap](/platform/roadmap).
Networking capabilities for Compute Instances, such as firewall rules, are tracked in [gVPC planned capabilities](/galactic-vpc/limitations-and-roadmap#planned-capabilities). For the overall Datum roadmap, see [Platform roadmap](/platform/roadmap).

<Note>
Plans can change. This list isn't a commitment to deliver any feature or to meet any timeline.
Expand Down
3 changes: 3 additions & 0 deletions docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,9 @@
"domain-dns/domains",
"domain-dns/dns",
"domain-dns/private-dns",
"domain-dns/private-dns-quickstart",
"domain-dns/private-dns-zones",
"domain-dns/private-dns-reference",
"domain-dns/operations",
"domain-dns/point-to-alb",
"domain-dns/observability",
Expand Down
1 change: 1 addition & 0 deletions domain-dns/limitations-and-roadmap.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ Domains and DNS are still being built. This page lists known limitations and whe
- **A zone's domain name can't change.** To use a different domain, create a new zone.
- **One zone for each domain.** A domain can belong to only one zone on Datum.
- **`ALIAS` isn't portable.** `ALIAS` isn't a standard record type, so a zone file exported from Datum can't carry it to another provider. See [ALIAS](/domain-dns/dns#alias-/-cname-flattening).
- **Private DNS has no `datumctl dns` zone creation, no association commands, and no Portal editing yet.** Create private zones and associations with `datumctl apply`. You can edit their records with `datumctl dns record --vpc`. See [Manage private zones and records](/domain-dns/private-dns-zones).
- **The DNS API is `v1alpha1`.** Field names in `DNSZone` and `DNSRecordSet` can change between releases. The `datumctl dns` plugin keeps up with those changes for you.

## Roadmap
Expand Down
178 changes: 178 additions & 0 deletions domain-dns/private-dns-quickstart.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,178 @@
---
title: "Private DNS quickstart"
sidebarTitle: "Private DNS quickstart"
description: "Deploy two workloads on a gVPC network and reach one from the other by its private name."
---

This quickstart deploys two small workloads on the same [gVPC](/galactic-vpc/overview) network. From the first, you look up the second by its [Private DNS](/domain-dns/private-dns) name and connect to it. Then you give it a name of your own. It takes about ten minutes.

## Before you begin

- Install `datumctl` and the `compute` plugin, and select a project. See [Compute commands](/datumctl/compute/overview).
- Your account needs the **Compute Admin**, **Network Admin**, and **DNS Admin** roles in the project.

## Reach an Instance by name

<Steps>
<Step title="Deploy a web server">
Deploy an `nginx` workload named `web` to Dallas:

```bash
datumctl compute deploy web \
--image=docker.io/library/nginx:1.27-alpine \
--runtime-class=general-purpose \
--location=us-central-1
```

If this is the first deploy in the project, the command asks whether to create a network named `default`. Enter `y`. Then enter `y` to apply the plan.
</Step>

<Step title="Deploy a client">
Deploy a second workload named `client` on the same network. It uses the same image, because the image includes `nslookup` and `wget`:

```bash
datumctl compute deploy client \
--image=docker.io/library/nginx:1.27-alpine \
--runtime-class=general-purpose \
--location=us-central-1
```
</Step>

<Step title="Find the web server's name">
Compute publishes each Instance at `<instance-name>.instances.datum.internal`. Read the exact name from the Instance:

```bash
datumctl compute instances --workload=web
datumctl get instance web-default-us-central-1-0 \
-o jsonpath='{.status.dns[0].hostnames[0]}'
```

The output is similar to the following:

```text
web-default-us-central-1-0.instances.datum.internal
```

If the output is empty, wait a few seconds and run the command again. The name appears once the Instance is ready.
</Step>

<Step title="Look up and connect by name">
Open a shell in the client and look up the web server:

```bash
datumctl compute exec client-default-us-central-1-0 -- \
nslookup -type=AAAA web-default-us-central-1-0.instances.datum.internal
```

The answer is the web server's private IPv6 address. Note it for later. Now connect to it by name:

```bash
datumctl compute exec client-default-us-central-1-0 -- \
wget -qO- http://web-default-us-central-1-0.instances.datum.internal/
```

The output is the `nginx` welcome page.
</Step>
</Steps>

## Give the web server your own name

To give the web server a name you choose, create a private zone of your own, attach it to the network, and add a record.

<Steps>
<Step title="Find the network's DNS context">
Each network has one DNS context. To list them with the network each one belongs to, run:

```bash
datumctl get dnsresolvercontexts \
-o custom-columns='CONTEXT:.metadata.name,NETWORK:.metadata.ownerReferences[0].name'
```

Note the `CONTEXT` for the `default` network, such as `dns-default-4f1c2a9e7b30`.
</Step>

<Step title="Create a zone, attach it, and add a record">
Save the following as `private-zone.yaml`. Replace `CONTEXT_NAME` with the context from the previous step, and `WEB_ADDRESS` with the web server's address from the lookup:

```yaml
apiVersion: dns.networking.miloapis.com/v1alpha1
kind: DNSZone
metadata:
name: corp-internal
spec:
domainName: corp.internal
visibility: Private
---
apiVersion: dns.networking.miloapis.com/v1alpha1
kind: DNSZoneAssociation
metadata:
name: corp-internal-default
spec:
dnsZoneRef:
name: corp-internal
resolverContextRef:
name: CONTEXT_NAME
---
apiVersion: dns.networking.miloapis.com/v1alpha1
kind: DNSRecordSet
metadata:
name: www
spec:
dnsZoneRef:
name: corp-internal
recordType: AAAA
records:
- name: www
ttl: 60
aaaa:
content: WEB_ADDRESS
```

Apply it:

```bash
datumctl apply -f private-zone.yaml
```
</Step>

<Step title="Wait for the zone">
Check that the association and record are accepted, and that the zone is programmed:

```bash
datumctl get dnszoneassociation corp-internal-default \
-o jsonpath='{.status.conditions[?(@.type=="Accepted")].status}'
datumctl get dnsrecordset www \
-o jsonpath='{.status.conditions[?(@.type=="Accepted")].status}'
datumctl get dnszone corp-internal
```

Continue when both commands print `True` and the zone's `PROGRAMMED` column shows `True`. This usually takes less than a minute. If something stays `False`, see [Troubleshooting](/domain-dns/troubleshooting#private-dns).
</Step>

<Step title="Connect by your name">
```bash
datumctl compute exec client-default-us-central-1-0 -- \
wget -qO- http://www.corp.internal/

Check warning on line 155 in domain-dns/private-dns-quickstart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (datum-4926dda5) - vale-spellcheck

domain-dns/private-dns-quickstart.mdx#L155

Did you really mean 'wget'?
```

The output is the same welcome page. The name resolves only from the `default` network.

This record holds an address, so update it if Compute replaces the web server's Instance. For names that follow an Instance, see [Find services by name](/domain-dns/private-dns-zones#find-services-by-name).
</Step>
</Steps>

## Clean up

```bash
datumctl delete -f private-zone.yaml
datumctl compute destroy client
datumctl compute destroy web
```

Deleting the workloads removes their Instance names.

## What's next

- [Manage private zones and records](/domain-dns/private-dns-zones)
- [Private DNS limits and behavior](/domain-dns/private-dns-reference)
- [Private DNS for Compute](/compute/private-dns)
71 changes: 71 additions & 0 deletions domain-dns/private-dns-reference.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
---
title: "Private DNS limits and behavior"
sidebarTitle: "Private DNS limits"
description: "Where Private DNS is available, naming rules, limits, and how long changes take."
---

This page lists the rules and limits for [Private DNS](/domain-dns/private-dns).

<Note>
Private DNS is in preview, and the `v1alpha1` API can change.
</Note>

## Locations and runtimes

Check warning on line 13 in domain-dns/private-dns-reference.mdx

View check run for this annotation

Mintlify / Mintlify Validation (datum-4926dda5) - vale-spellcheck

domain-dns/private-dns-reference.mdx#L13

Did you really mean 'runtimes'?

Private DNS works on every [gVPC](/galactic-vpc/overview) network, in these locations:

| Location | City |
| --- | --- |
| `us-central-1` | Dallas |
| `us-east-1` | Ashburn |
| `us-west-1` | San Jose |

A network that spans several locations has one set of names. An Instance in one location resolves the names of Instances in the other locations on the same network.

Both [runtime classes](/compute/runtimes/overview), `general-purpose` and `unikernel`, get Private DNS. Instances use the resolvers that Datum configures for them. In a `general-purpose` Instance, they're in `/etc/resolv.conf`. An app that uses its own resolver, such as a hard-coded public resolver or DNS over HTTPS, can't resolve private names.

## Names

- Every network's managed zone is `datum.internal`. Each network has its own copy.
- Compute publishes Instances at `<instance-name>.instances.datum.internal`. Long or unusual Instance names are shortened, so read the exact name from the Instance's `status.dns`. Compute owns every name at or below `instances.datum.internal`, so you can't add records there or create a zone that covers it.
- Use full names. Don't rely on short names such as `web-default-us-central-1-0`: they depend on search domains that can differ between Instances.
- Zone domains use lowercase letters, digits, and hyphens, with each label starting and ending with a letter or digit. They have at least two labels and are at most 253 characters long.
- Record names are relative to their zone, such as `api`, or fully qualified. `@` means the zone's own domain. Names aren't case-sensitive.
- A private zone hides the public records of the same domain from the networks it's associated with.

## Record rules

- `ALIAS` and `SOA` records aren't supported. Datum manages each private zone's `SOA` record.
- A zone's own domain (`@`) can't be a `CNAME`.
- A `CNAME` can't share a name with another record type.
- Point a `CNAME` at a name in the same zone. A `CNAME` that points into another zone, or at a public name, may return only the `CNAME`, which most apps can't follow.
- An `SRV` target must be a name with `A` or `AAAA` records in the same zone.
- If two record sets have the same name and type, the older one keeps it, and the newer one isn't accepted.
- A record set is accepted or rejected as a whole. One invalid record keeps every name in it from resolving.

## Limits

| Limit | Value |
| --- | --- |
| Private zones a network can resolve, including `datum.internal` | 256. An association past the limit is refused with the reason `ZoneLimitExceeded`. Zones already associated keep working. To make room, delete an association you don't need. |
| Zone domain length | 253 characters |
| Default TTL of a record you create | 300 seconds |
| TTL of an Instance name | 30 seconds |

## How long changes take

| Change | When it takes effect |
| --- | --- |
| New Instance | Its name usually resolves within about 30 seconds of the Instance becoming ready. |
| New record, zone, or association | Usually within a minute of being accepted, and longer when a project changes many names at once. The zone's `Programmed` condition says when. |
| Changed or removed record | New lookups get the new answer once the zone is programmed. Clients that cached the old answer keep it until its TTL expires. |

Check warning on line 61 in domain-dns/private-dns-reference.mdx

View check run for this annotation

Mintlify / Mintlify Validation (datum-4926dda5) - vale-spellcheck

domain-dns/private-dns-reference.mdx#L61

Did you really mean 'lookups'?
| Deleted or unready Instance | Its addresses are withdrawn. Clients can keep the old answer for up to 30 seconds. |

Publication is asynchronous. Wait for the status conditions described in [Check status](/domain-dns/private-dns-zones#check-status) rather than a fixed delay.

## Privacy

- A private name resolves only from networks that its zone is associated with. Private names aren't published to public DNS.
- A network resolves another network's zone only through an association that you create.
- Resolving a name doesn't grant network access. See [Traffic and connecting](/galactic-vpc/networks/traffic).
- Public names keep resolving through the same resolvers.
Loading
Loading