feat(vpc): add info on DNS (scaleway#4159)

* feat(dns): first draft

* feat(vps): dns more info

* fix(vpc): juggle info

* fix(vpc): add info

* Apply suggestions from code review

Co-authored-by: Benedikt Rollik <[email protected]>

* Apply suggestions from code review

Co-authored-by: Jessica <[email protected]>

* fix(vpc): add info to dns doc

---------

Co-authored-by: Benedikt Rollik <[email protected]>
Co-authored-by: Jessica <[email protected]>

Author: 3 people

menu/navigation.json

@@ -2923,17 +2923,21 @@
               },
               {
                 "items": [
-                  {
-                    "label": "Understanding VPC GA and migration",
-                    "slug": "vpc-migration"
-                  },
                   {
                     "label": "Understanding routing",
                     "slug": "understanding-routing"
                   },
+                  {
+                    "label": "Understanding DNS",
+                    "slug": "dns"
+                  },
                   {
                     "label": "Getting the most from Private Networks",
                     "slug": "getting-most-private-networks"
+                  },
+                  {
+                    "label": "Understanding VPC GA and migration",
+                    "slug": "vpc-migration"
                   }
                 ],
                 "label": "Additional Content",

network/vpc/concepts.mdx

@@ -42,11 +42,9 @@ While DHCP is built into all new Private Networks, it may not be automatically a
 
 ## DNS
 
-The **D**omain **N**ame **S**ystem (DNS) is a naming system for devices connected to the internet or Private Networks. Most prominently, DNS servers translate text-based domain names (e.g. www.scaleway.com) to numerical IP addresses (e.g. 51.158.66.220).
+The **D**omain **N**ame **S**ystem (DNS) is a naming system for devices connected to the internet or Private Networks. Most prominently, DNS servers translate text-based domain names (e.g. www.scaleway.com) to numerical IP addresses (e.g. `51.158.66.220`).
 
-Private Networks benefit from managed DNS, which resolves the hostnames of attached resources into their IP addresses. The hostname for a given device is generally the name defined when creating the resource (and which in the case of an Instance, for example, displays in the shell when connected to that resource by SSH). See [full information](/network/vpc/how-to/attach-resources-to-pn/#how-to-access-a-resource-on-a-private-network-via-its-hostname-dns) on reaching a resource via its hostname.
-
- When a Private Network is attached to a [legacy Public Gateway](/network/public-gateways/concepts/#ipam) however, the gateway's DNS takes priority over that of the Private Network, to allow hostname resolution across the different Private Networks it may be attached to.
+Private Networks benefit from managed DNS, which resolves the hostnames of attached resources into their IP addresses. The hostname for a given device is generally the name defined when creating the resource (and which in the case of an Instance, for example, displays in the shell when connected to that resource by SSH). See [full information](/network/vpc/reference-content/dns/) on Scaleway DNS and how to reach a resource via its hostname.
 
 ## IPAM
 

network/vpc/how-to/attach-resources-to-pn.mdx

@@ -118,14 +118,7 @@ In addition to using its IP address, you can also access a resource on a Private
 
 A resource's hostname is equivalent to the name you gave the resource when creating it. For example, if you have an Instance with the name `instance123` attached to a Private Network named `prodpn`, its address on that network is `instance123.prodpn.internal`.
 
-<Message type="tip">
-- If you update the resource's name after creating it, and thus its hostname changes, it will not be automatically updated on our DNS records unless you detach and reattach the resource to the Private Network. <br/><br/>
-- If you created the resource via the API, and it has dots in its name, these dots should be replaced by dashes for the purposes of DNS resolution (`my.instance` --> `my-instance`)<br/><br/>
-- You can also reach a resource via its resource ID, e.g. `e49902a6-ed4c-431f-bd62-0fc41063eec0.prodpn.internal`
-
-</Message>
-
-If you are still having problems reaching a resource attached to a Private Network via its hostname, see our [troubleshooting guide](/network/vpc/troubleshooting/pn-name/).
+For full information on Scaleway internal DNS and hostname formats, including troubleshooting advice, see our [dedicated documentation](/network/vpc/reference-content/dns/).
 
 ## How to detach a resource from a Private Network
 

network/vpc/reference-content/dns.mdx

@@ -0,0 +1,85 @@
+---
+meta:
+  title: Understanding Scaleway DNS for VPC and Private Networks
+  description: Learn more about how internal DNS works within the Scaleway ecosystem, and how to ensure your infrastructure is using DNS efficiently.
+content:
+  h1: Understanding Scaleway DNS for VPC and Private Networks
+  paragraph: Learn more about how internal DNS works within the Scaleway ecosystem, and how to ensure your infrastructure is using DNS efficiently.
+tags: vpc private-network dns dns-server dns-resolution hostname
+dates:
+  validation: 2024-12-31
+  posted: 2024-12-31
+categories:
+  - network
+---
+
+Scaleway VPC and Private Networks integrate managed DNS, for the effective resolution of hostnames to IP addresses. Read on to find out more.
+
+## What is DNS?
+
+The **D**omain **N**ame **S**ystem (DNS) is a naming system for devices connected to the internet or any network. Most prominently, DNS servers translate text-based domain names (e.g. www.scaleway.com) to numerical IP addresses (e.g. 51.158.66.220). This allows traffic to find its destination by resolving a human-readable text-based name, to the numerical IP addresses used by networks and servers.
+
+## Scaleway DNS overview
+
+Scaleway Private Networks benefit from managed internal DNS. This allows the resolution of resources' **hostnames** on the Private Network, into their private IP addresses. This managed DNS service is automatically exposed in each Private Network and no user configuration is required.
+
+<Message type="note">
+When a Private Network is attached to a [legacy Public Gateway](/network/public-gateways/concepts/#ipam), the gateway’s DNS takes priority over that of the Private Network.
+</Message>
+
+## Hostname format
+
+A resource's hostname is equivalent to the name you gave the resource when creating it. The full format for internal addressing is `<hostname>.<private-network-name>.internal`. For example, if you have an Instance with the name `instance123` attached to a Private Network named `prodpn`, its address on that network is `instance123.prodpn.internal`.
+
+<Message type="tip">
+- If you update the resource's name after creating it, and thus its hostname changes, it will not be automatically updated on our DNS records unless you detach and reattach the resource to the Private Network. <br/><br/>
+- If you created the resource via the API, and it has dots in its name, these dots should be replaced by dashes for the purposes of DNS resolution (`my.instance` --> `my-instance`). We generally recommend avoiding using dots in your resource names to avoid issues.<br/><br/>
+</Message>
+
+## DNS resolution details
+
+The managed DNS resolver service is exposed on each Private Network through the following IP addresses:
+
+- IPv4: `169.254.169.254`
+- IPv6: `fe80::200:22ff:fe05:ca1e`
+
+The service resolves both regular public records, as well as internal VPC records.
+
+<Message type="tip">
+The `.internal` at the end of internal addresses is important in enabling the resolver to distinguish between internal and external/public DNS. For this reason, you should always add `.internal` when addressing resources within your VPC.
+</Message>
+
+The DNS service resolves the following formats:
+
+```
+<resource_name>.<private-network_name>.internal
+<resource_name>.<private-network_uuid>.internal
+<resource_uuid>.<private-network_uuid>.internal
+```
+
+<Message type="tip">
+The `resource_uuid` does not generally correspond to the ID of the principal resource (e.g. Instance, Elastic Metal server, Public Gateway), but rather to the ID of the sub-resource that facilitates the attachment to the Private Network. For example:
+- Instances: `resource_uuid` corresponds to the [Private NIC](https://www.scaleway.com/en/developers/api/instance/#path-private-nics-list-all-private-nics) ID
+- Elastic Metal: `resource_uuid` corresponds to the ID of the [Server-to-Private Network mapping](https://www.scaleway.com/en/developers/api/elastic-metal/private-network-api/#path-private-networks-add-a-server-to-a-private-network)
+- Public Gateways: `resource_uuid` corresponds to the [GatewayNetwork](https://www.scaleway.com/en/developers/api/public-gateway/#path-gateway-networks-list-public-gateway-connections-to-private-networks) ID.
+</Message>
+
+DNS cannot resolve or forward queries between different VPCs. It can only resolve hostnames for resources within the same VPC, though they may be on different Private Networks within that VPC.
+
+## Rate limiting
+
+Currently, DNS requests are rate-limited to 50 requests per second per resource. Watch this space as we work to be able to increase this limit to accommodate higher traffic volumes.
+
+## Troubleshooting
+
+If you experience problems with DNS, try the following steps:
+
+1. **Detach and reattach the affected resources from/to the Private Network.** This is effective in solving many issues for older resources, or resources whose name you have changed.
+
+2. **Check resource hostname**. Issues can arise if your resource has a dot in its name. Rename it if necessary to eliminate the dot, and detach/reattach it from the Private Network.
+
+3. **Check Private Network name**. Issues can arise with Private Networks who share a name with a TLD. See our [dedicated document](/network/vpc/troubleshooting/pn-name/) for more help.
+
+4. **Check whether you are using Network Manager**: DNS does not work out of the box for Linux distributions using Network Managed, such as **RockyLinux**. Find out how to resolve this problem [on our troubleshooting page](/network/vpc/troubleshooting/private-dns-dhcp-not-working/#distributions-running-network-manager)
+
+If you are still having problems reaching a resource attached to a Private Network via its hostname, [open a support ticket](https://console.scaleway.com/support).

network/vpc/reference-content/getting-most-private-networks.mdx

@@ -69,6 +69,10 @@ Further, when you attach a resource to a Private Network and specify a reserved
 
 Using reserved IP addresses is ideal to ensure that certain IP addresses are never released into the general pool and kept for certain critical resources with fixed IP requirements, even when that resource is detached from the Private Network, or when migrating between resources. Reserved IP addresses may also be useful where your Private Network is extending or integrating with external networks, or to assign addresses to virtual machines hosted on Elastic Metal servers via Proxmox.
 
+### DNS and hostnames
+
+Scaleway Private Networks benefit from managed internal DNS. This allows the resolution of resources' **hostnames** on the Private Network, into their private IP addresses. See our documentation on [Understanding Scaleway DNS](/network/vpc/reference-content/dns/) for full details of how to effectively use hostname addressing and the capabilities of Private Networks' DNS resolver service.
+
 ## Removing public IPs from resources
 
 We strongly recommend that you disable public connectivity on all of your Scaleway resources, unless it is absolutely required. It is preferable to attach resources to Private Networks wherever possible, and direct all traffic to the resource's private IP address on that network. This ensures optimal security, reduced cost and enhanced latency. Find out more in our documentation about [public connectivity best practices](/network/ipam/reference-content/public-connectivity-best-practices).