From 063524af6d5b1493946c344748286e3e251f1d9c Mon Sep 17 00:00:00 2001 From: ditahkk Date: Sun, 19 Jul 2026 08:15:09 -0400 Subject: [PATCH] Enhance DNS documentation and examples - Updated the "Domains" documentation to include additional resources for DNS management and troubleshooting. - Added a new "DNS Examples" document providing practical recipes for common DNS tasks using the `zcp` CLI. - Created a "DNS Overview" document explaining how zones, name servers, and records work together. - Removed the outdated "DNS Records" document and replaced it with individual pages for each record type (A, AAAA, CNAME, MX, TXT, CAA, NS) with detailed explanations and examples. - Introduced a "DNS Troubleshooting" document to assist users in resolving common DNS issues. - Added a tutorial for hosting a domain on ZCP DNS and managing records using the CLI, covering the entire process from domain creation to verification. --- astro.config.mjs | 23 +- src/content/docs/changelog/index.md | 42 ++ src/content/docs/fr/changelog/index.md | 48 ++ .../docs/fr/public-cloud/cli/reference.md | 18 +- src/content/docs/fr/public-cloud/dns/api.mdx | 460 ++++++++++++++++++ src/content/docs/fr/public-cloud/dns/cli.md | 217 +++++++++ .../docs/fr/public-cloud/dns/domains.md | 8 +- .../docs/fr/public-cloud/dns/examples.md | 121 +++++ .../docs/fr/public-cloud/dns/overview.md | 81 +++ .../docs/fr/public-cloud/dns/records.md | 56 --- .../fr/public-cloud/dns/records/a-aaaa.md | 62 +++ .../docs/fr/public-cloud/dns/records/caa.md | 61 +++ .../docs/fr/public-cloud/dns/records/cname.md | 62 +++ .../docs/fr/public-cloud/dns/records/index.md | 63 +++ .../docs/fr/public-cloud/dns/records/mx.md | 86 ++++ .../docs/fr/public-cloud/dns/records/ns.md | 69 +++ .../docs/fr/public-cloud/dns/records/txt.md | 66 +++ .../fr/public-cloud/dns/troubleshooting.md | 101 ++++ .../docs/fr/tutorials/host-dns-on-zcp-cli.md | 190 ++++++++ .../docs/public-cloud/cli/reference.md | 16 +- src/content/docs/public-cloud/dns/api.mdx | 452 +++++++++++++++++ src/content/docs/public-cloud/dns/cli.md | 208 ++++++++ src/content/docs/public-cloud/dns/domains.md | 8 +- src/content/docs/public-cloud/dns/examples.md | 117 +++++ src/content/docs/public-cloud/dns/overview.md | 76 +++ src/content/docs/public-cloud/dns/records.md | 55 --- .../docs/public-cloud/dns/records/a-aaaa.md | 58 +++ .../docs/public-cloud/dns/records/caa.md | 58 +++ .../docs/public-cloud/dns/records/cname.md | 58 +++ .../docs/public-cloud/dns/records/index.md | 58 +++ .../docs/public-cloud/dns/records/mx.md | 81 +++ .../docs/public-cloud/dns/records/ns.md | 64 +++ .../docs/public-cloud/dns/records/txt.md | 60 +++ .../docs/public-cloud/dns/troubleshooting.md | 93 ++++ .../docs/tutorials/host-dns-on-zcp-cli.md | 180 +++++++ 35 files changed, 3350 insertions(+), 126 deletions(-) create mode 100644 src/content/docs/fr/public-cloud/dns/api.mdx create mode 100644 src/content/docs/fr/public-cloud/dns/cli.md create mode 100644 src/content/docs/fr/public-cloud/dns/examples.md create mode 100644 src/content/docs/fr/public-cloud/dns/overview.md delete mode 100644 src/content/docs/fr/public-cloud/dns/records.md create mode 100644 src/content/docs/fr/public-cloud/dns/records/a-aaaa.md create mode 100644 src/content/docs/fr/public-cloud/dns/records/caa.md create mode 100644 src/content/docs/fr/public-cloud/dns/records/cname.md create mode 100644 src/content/docs/fr/public-cloud/dns/records/index.md create mode 100644 src/content/docs/fr/public-cloud/dns/records/mx.md create mode 100644 src/content/docs/fr/public-cloud/dns/records/ns.md create mode 100644 src/content/docs/fr/public-cloud/dns/records/txt.md create mode 100644 src/content/docs/fr/public-cloud/dns/troubleshooting.md create mode 100644 src/content/docs/fr/tutorials/host-dns-on-zcp-cli.md create mode 100644 src/content/docs/public-cloud/dns/api.mdx create mode 100644 src/content/docs/public-cloud/dns/cli.md create mode 100644 src/content/docs/public-cloud/dns/examples.md create mode 100644 src/content/docs/public-cloud/dns/overview.md delete mode 100644 src/content/docs/public-cloud/dns/records.md create mode 100644 src/content/docs/public-cloud/dns/records/a-aaaa.md create mode 100644 src/content/docs/public-cloud/dns/records/caa.md create mode 100644 src/content/docs/public-cloud/dns/records/cname.md create mode 100644 src/content/docs/public-cloud/dns/records/index.md create mode 100644 src/content/docs/public-cloud/dns/records/mx.md create mode 100644 src/content/docs/public-cloud/dns/records/ns.md create mode 100644 src/content/docs/public-cloud/dns/records/txt.md create mode 100644 src/content/docs/public-cloud/dns/troubleshooting.md create mode 100644 src/content/docs/tutorials/host-dns-on-zcp-cli.md diff --git a/astro.config.mjs b/astro.config.mjs index 16cd87c..acc4479 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -10,6 +10,7 @@ const frSidebarLabels = { Changelog: 'Journal des modifications', Tutorials: 'Tutoriels', 'Deploy a VPS with Dokploy (CLI)': 'Déployer un VPS avec Dokploy (CLI)', + 'Host DNS on ZCP (CLI)': 'Héberger le DNS sur ZCP (CLI)', Installation: 'Installation', Quickstart: 'Démarrage rapide', Configuration: 'Configuration', @@ -76,6 +77,8 @@ const frSidebarLabels = { DNS: 'DNS', Domains: 'Domaines', Records: 'Enregistrements', + 'A and AAAA': 'A et AAAA', + Examples: 'Exemples', Marketplace: 'Marketplace', Databases: 'Bases de données', 'Web Stacks': 'Piles Web', @@ -219,6 +222,7 @@ export default defineConfig({ label: 'Manage ZCP with Terraform / OpenTofu', slug: 'tutorials/manage-infrastructure-terraform', }, + { label: 'Host DNS on ZCP (CLI)', slug: 'tutorials/host-dns-on-zcp-cli' }, ], }, @@ -412,8 +416,25 @@ export default defineConfig({ label: 'DNS', collapsed: true, items: [ + { label: 'Overview', slug: 'public-cloud/dns/overview' }, { label: 'Domains', slug: 'public-cloud/dns/domains' }, - { label: 'Records', slug: 'public-cloud/dns/records' }, + { + label: 'Records', + collapsed: true, + items: [ + { label: 'Overview', slug: 'public-cloud/dns/records' }, + { label: 'A and AAAA', slug: 'public-cloud/dns/records/a-aaaa' }, + { label: 'CNAME', slug: 'public-cloud/dns/records/cname' }, + { label: 'MX', slug: 'public-cloud/dns/records/mx' }, + { label: 'TXT', slug: 'public-cloud/dns/records/txt' }, + { label: 'CAA', slug: 'public-cloud/dns/records/caa' }, + { label: 'NS', slug: 'public-cloud/dns/records/ns' }, + ], + }, + { label: 'CLI', slug: 'public-cloud/dns/cli' }, + { label: 'API', slug: 'public-cloud/dns/api' }, + { label: 'Examples', slug: 'public-cloud/dns/examples' }, + { label: 'Troubleshooting', slug: 'public-cloud/dns/troubleshooting' }, ], }, { diff --git a/src/content/docs/changelog/index.md b/src/content/docs/changelog/index.md index 5a2e718..4c4f799 100644 --- a/src/content/docs/changelog/index.md +++ b/src/content/docs/changelog/index.md @@ -38,6 +38,30 @@ One-click application images for compute instances. The official command-line tool for the platform. The entries below mirror the CLI's [`CHANGELOG.md`](https://github.com/zsoftly/zcp-cli/blob/main/CHANGELOG.md) on GitHub. +### v0.0.25: July 18, 2026 + +**`MX` records now work from the CLI.** `zcp dns record-create` never sent a record's priority, so +every `MX` create failed with an API error. It now takes a `--priority` flag (0-65535, required for +`MX`): put the mail server in `--content` and the preference number in `--priority`. The CLI sends a +`0` preference correctly and rejects `--priority` on every other type with a clear message. See +[Manage DNS with the CLI](/public-cloud/dns/cli). + +```bash +zcp dns record-create --domain examplecom --name @ --type MX --content mail.example.com. --priority 10 +``` + +### v0.0.24: July 16, 2026 + +**Deleting a VM now releases its auto-assigned public IP.** `instance delete` uses the same +service-cancellation workflow as the console, so the address is no longer left allocated and +billable. `loadbalancer delete` also uses service cancellation, but keeps its separate, reusable +public IP by default. Add `--release-ip` to release the address. + +- **`instance list` and `instance get` now show the public IP**, and `get` shows the billing cycle. +- **`ip list` and `loadbalancer list` return every result** instead of stopping at the first page. +- **The CLI and its SDK are now Apache 2.0 licensed**, allowing the Terraform / OpenTofu provider to + embed the SDK. + ### v0.0.23: July 8, 2026 **`--wait` now reports the real instance state.** The platform's cached state sometimes lags minutes @@ -278,6 +302,24 @@ Manage ZCP infrastructure as code with the official provider, published as `zsof [Terraform Registry](https://registry.terraform.io/providers/zsoftly/zcp). Source code lives at [github.com/zsoftly/terraform-provider-zcp](https://github.com/zsoftly/terraform-provider-zcp). +### v0.1.2: July 18, 2026 + +**`MX` records in `zcp_dns_record`.** A new `priority` argument (0-65535) sets the preference +number. Put the mail server in `content`. The provider requires priority for `MX` and rejects it for +every other type during planning, so invalid configurations fail before apply. Built on the `zcp` +CLI SDK v0.0.25 and verified against the live DNS API. + +- **Dropped `SRV` from the documented `type` values.** The DNS API rejects `SRV` and `LOC` records, + so advertising `SRV` was misleading. `type` stays a free-form string. + +### v0.1.1: July 18, 2026 + +**Destroy operations release auto-assigned public IPs.** `zcp_instance` and `zcp_load_balancer` +release auto-assigned public IPs through the service-cancellation workflow, preventing billable +addresses from remaining after destroy. Set `assign_public_ip = false` to create an instance without +one. This release also upgrades the `zcp` CLI SDK to v0.0.24, which pages through every result in +public IP and load balancer listings. + ### v0.1.0: July 8, 2026 **First public release, live on both registries.** 38 resources and 12 data sources cover everything diff --git a/src/content/docs/fr/changelog/index.md b/src/content/docs/fr/changelog/index.md index 929ba2a..79e7adf 100644 --- a/src/content/docs/fr/changelog/index.md +++ b/src/content/docs/fr/changelog/index.md @@ -40,6 +40,34 @@ Images d'applications en un clic pour les instances de calcul. L'outil en ligne de commande officiel de la plateforme. Les entrées ci-dessous reflètent le [`CHANGELOG.md`](https://github.com/zsoftly/zcp-cli/blob/main/CHANGELOG.md) du CLI sur GitHub. +### v0.0.25 : 18 juillet 2026 + +**Les enregistrements `MX` fonctionnent désormais depuis le CLI.** `zcp dns record-create` +n'envoyait jamais la priorité de l'enregistrement. Chaque création d'un `MX` échouait donc avec une +erreur d'API. La commande reçoit maintenant l'option `--priority` (de 0 à 65535, obligatoire pour +`MX`). Placez le serveur de courrier dans `--content` et le nombre de préférence dans `--priority`. +Une préférence de `0` est envoyée correctement. Le CLI refuse `--priority` pour les autres types et +affiche un message clair. Voir [Gérer le DNS avec le CLI](/fr/public-cloud/dns/cli). + +```bash +zcp dns record-create --domain examplecom --name @ --type MX --content mail.example.com. --priority 10 +``` + +### v0.0.24 : 16 juillet 2026 + +**La suppression d'une VM libère maintenant son IP publique.** `instance delete` passe par le même +flux d'annulation de service que la console. L'adresse attribuée automatiquement est donc libérée au +lieu de rester allouée et facturable. L'IP publique d'un répartiteur de charge constitue une +ressource distincte et réutilisable. Elle est conservée par défaut. Ajoutez `--release-ip` à +`loadbalancer delete` pour la libérer aussi. + +- **`instance list` et `instance get` affichent maintenant l'IP publique**, et `get` affiche le + cycle de facturation. +- **`ip list` et `loadbalancer list` renvoient tous les résultats** au lieu de s'arrêter à la + première page. +- **Le CLI et son SDK sont maintenant sous licence Apache 2.0**, ce qui permet au fournisseur + Terraform / OpenTofu d'intégrer le SDK. + ### v0.0.23 : 8 juillet 2026 **`--wait` rapporte désormais l'état réel de l'instance.** L'état en cache de la plateforme accuse @@ -310,6 +338,26 @@ le [registre OpenTofu](https://search.opentofu.org/provider/zsoftly/zcp) et le [registre Terraform](https://registry.terraform.io/providers/zsoftly/zcp). Le code source se trouve sur [github.com/zsoftly/terraform-provider-zcp](https://github.com/zsoftly/terraform-provider-zcp). +### v0.1.2 : 18 juillet 2026 + +**Les enregistrements `MX` dans `zcp_dns_record`.** Un nouvel argument `priority`, de 0 à 65535, +définit le nombre de préférence. Placez le serveur de courrier dans `content`. La priorité est +obligatoire pour `MX` et refusée pour tous les autres types. Ces deux règles sont vérifiées pendant +la planification afin qu'une erreur survienne avant l'application. Cette version repose sur le SDK +du CLI `zcp` v0.0.25 et a été vérifiée avec l'API DNS en production. + +- **La valeur `SRV` a été retirée des valeurs de `type` documentées.** L'API DNS refuse les + enregistrements `SRV` et `LOC`. La présentation de `SRV` induisait donc en erreur. `type` demeure + une chaîne libre. + +### v0.1.1 : 18 juillet 2026 + +**Les destructions libèrent les IP publiques attribuées automatiquement.** `zcp_instance` et +`zcp_load_balancer` libèrent ces adresses au moyen du flux d'annulation de service. Une destruction +ne laisse donc plus d'adresse facturable. Définissez `assign_public_ip = false` pour créer une +instance sans IP publique. Cette version passe aussi au SDK du CLI `zcp` v0.0.24, qui parcourt +toutes les pages des listes d'IP publiques et de répartiteurs de charge. + ### v0.1.0 : 8 juillet 2026 **Première version publique, disponible sur les deux registres.** 38 ressources et 12 sources de diff --git a/src/content/docs/fr/public-cloud/cli/reference.md b/src/content/docs/fr/public-cloud/cli/reference.md index 99e3cb2..1aa0ec3 100644 --- a/src/content/docs/fr/public-cloud/cli/reference.md +++ b/src/content/docs/fr/public-cloud/cli/reference.md @@ -121,11 +121,17 @@ les commandes IAM `sub-user`/`role`/`permission`) sont exemptées. Voir ### Réseau : DNS -| Commande | Description | -| ------------------------- | ----------------------- | -| `zcp dns list` | Lister les domaines DNS | -| `zcp dns create` | Ajouter un domaine | -| `zcp dns delete ` | Retirer un domaine | +De niveau compte. Aucun `--region`/`--project` requis, sauf pour `zcp dns create`, qui reçoit +`--project`. Voir [Gérer le DNS avec le CLI](/fr/public-cloud/dns/cli). + +| Commande | Description | +| ------------------------- | -------------------------------------------------- | +| `zcp dns list` | Lister les domaines DNS | +| `zcp dns create` | Ajouter un domaine | +| `zcp dns show ` | Afficher un domaine et ses enregistrements | +| `zcp dns record-create` | Ajouter un enregistrement par nom, type et contenu | +| `zcp dns record-delete` | Supprimer un ensemble par nom et type | +| `zcp dns delete ` | Retirer un domaine | ### Réseau : adresses IP @@ -146,7 +152,7 @@ les commandes IAM `sub-user`/`role`/`permission`) sont exemptées. Voir ### Identité et accès (IAM) -De niveau compte — aucun `--region`/`--project` requis. Voir +De niveau compte. Aucun `--region`/`--project` requis. Voir [Rôles et permissions](/fr/public-cloud/iam/roles) et [Utilisateurs](/fr/public-cloud/iam/users) pour le modèle et le catalogue complet des permissions. diff --git a/src/content/docs/fr/public-cloud/dns/api.mdx b/src/content/docs/fr/public-cloud/dns/api.mdx new file mode 100644 index 0000000..4744df4 --- /dev/null +++ b/src/content/docs/fr/public-cloud/dns/api.mdx @@ -0,0 +1,460 @@ +--- +title: Gérer le DNS avec l'API +description: + Listez les zones DNS, consultez les enregistrements et ajoutez-les ou supprimez-les avec l'API de + la plateforme infonuagique ZSoftly. +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +Gérez les enregistrements DNS avec l'API REST. Chaque requête emploie l'URL de base +`https://api.zcp.zsoftly.ca/api` et envoie un jeton Bearer dans l'en-tête `Authorization`. Consultez +[Authentification](/fr/public-cloud/api/authentication) pour créer un jeton. + +:::note + +Créez d'abord la zone dans le [portail](/fr/public-cloud/dns/domains) ou avec le CLI +(`zcp dns create`). Gérez ensuite ses enregistrements avec les appels ci-dessous. Chaque zone +possède un **slug** employé par tous les appels d'enregistrement. Obtenez-le avec `zcp dns list` ou +l'appel de liste ci-dessous. + +::: + +## Lister vos zones + + + + +```bash +curl -s "https://api.zcp.zsoftly.ca/api/dns/domains" \ + -H "Authorization: Bearer your-token" \ + -H "Accept: application/json" | jq '.data' +``` + + + + +```python +import requests + +BASE = "https://api.zcp.zsoftly.ca/api" +TOKEN = "your-token" + +resp = requests.get( + f"{BASE}/dns/domains", + headers={"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"}, +) +for zone in resp.json()["data"]: + print(zone["slug"], zone["name"], zone["status"]) +``` + + + + +```js +const BASE = 'https://api.zcp.zsoftly.ca/api'; +const TOKEN = 'your-token'; + +const res = await fetch(`${BASE}/dns/domains`, { + headers: { Authorization: `Bearer ${TOKEN}`, Accept: 'application/json' }, +}); +const { data } = await res.json(); +for (const zone of data) { + console.log(zone.slug, zone.name, zone.status); +} +``` + + + + +```go +package main + +import ( + "encoding/json" + "fmt" + "net/http" +) + +func main() { + const base = "https://api.zcp.zsoftly.ca/api" + const token = "your-token" + + req, _ := http.NewRequest("GET", base+"/dns/domains", nil) + req.Header.Set("Authorization", "Bearer "+token) + req.Header.Set("Accept", "application/json") + + resp, err := http.DefaultClient.Do(req) + if err != nil { + panic(err) + } + defer resp.Body.Close() + + var env struct { + Data []struct { + Slug string `json:"slug"` + Name string `json:"name"` + Status bool `json:"status"` + } `json:"data"` + } + json.NewDecoder(resp.Body).Decode(&env) + for _, zone := range env.Data { + fmt.Println(zone.Slug, zone.Name, zone.Status) + } +} +``` + + + + +Réponse : + +```json +{ + "status": "Success", + "message": "OK", + "total": 1, + "data": [{ "name": "example.com", "slug": "examplecom", "status": true }] +} +``` + +## Afficher une zone et ses enregistrements + +Passez le slug de la zone. La réponse énumère tous les enregistrements, y compris ceux de type `SOA` +et `NS` ajoutés par ZCP. + + + + +```bash +curl -s "https://api.zcp.zsoftly.ca/api/dns/domains/examplecom" \ + -H "Authorization: Bearer your-token" \ + -H "Accept: application/json" | jq '.data.records' +``` + + + + +```python +import requests + +BASE = "https://api.zcp.zsoftly.ca/api" +TOKEN = "your-token" + +resp = requests.get( + f"{BASE}/dns/domains/examplecom", + headers={"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"}, +) +for rec in resp.json()["data"]["records"]: + print(rec["name"], rec["type"], rec["contents"], rec["ttl"]) +``` + + + + +```js +const BASE = 'https://api.zcp.zsoftly.ca/api'; +const TOKEN = 'your-token'; + +const res = await fetch(`${BASE}/dns/domains/examplecom`, { + headers: { Authorization: `Bearer ${TOKEN}`, Accept: 'application/json' }, +}); +const { data } = await res.json(); +for (const rec of data.records) { + console.log(rec.name, rec.type, rec.contents, rec.ttl); +} +``` + + + + +```go +package main + +import ( + "encoding/json" + "fmt" + "net/http" +) + +func main() { + const base = "https://api.zcp.zsoftly.ca/api" + const token = "your-token" + + req, _ := http.NewRequest("GET", base+"/dns/domains/examplecom", nil) + req.Header.Set("Authorization", "Bearer "+token) + req.Header.Set("Accept", "application/json") + + resp, err := http.DefaultClient.Do(req) + if err != nil { + panic(err) + } + defer resp.Body.Close() + + var env struct { + Data struct { + Records []struct { + Name string `json:"name"` + Type string `json:"type"` + Contents []string `json:"contents"` + TTL int `json:"ttl"` + } `json:"records"` + } `json:"data"` + } + json.NewDecoder(resp.Body).Decode(&env) + for _, rec := range env.Data.Records { + fmt.Println(rec.Name, rec.Type, rec.Contents, rec.TTL) + } +} +``` + + + + +L'API regroupe les enregistrements par nom et par type. Un ensemble d'enregistrements contient une +ou plusieurs valeurs sous `contents` : + +```json +{ + "name": "www.example.com.", + "type": "A", + "ttl": 14400, + "contents": ["203.0.113.10"] +} +``` + +## Ajouter un enregistrement + +Envoyez une requête `POST` vers le chemin `records` de la zone. Le champ `name` est **relatif** à la +zone. Envoyez `www`, et non `www.example.com`. Utilisez `@` pour la racine de la zone. + +:::note + +Les types pris en charge sont `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `CAA` et `NS`. `SRV` et `LOC` ne +sont pas encore disponibles. + +::: + + + + +```bash +curl -s -X POST "https://api.zcp.zsoftly.ca/api/dns/domains/examplecom/records" \ + -H "Authorization: Bearer your-token" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -d '{ "name": "www", "type": "A", "content": "203.0.113.10", "ttl": 14400 }' +``` + + + + +```python +import requests + +BASE = "https://api.zcp.zsoftly.ca/api" +TOKEN = "your-token" + +record = {"name": "www", "type": "A", "content": "203.0.113.10", "ttl": 14400} + +resp = requests.post( + f"{BASE}/dns/domains/examplecom/records", + headers={"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"}, + json=record, +) +print(resp.json()["message"]) +``` + + + + +```js +const BASE = 'https://api.zcp.zsoftly.ca/api'; +const TOKEN = 'your-token'; + +const res = await fetch(`${BASE}/dns/domains/examplecom/records`, { + method: 'POST', + headers: { + Authorization: `Bearer ${TOKEN}`, + 'Content-Type': 'application/json', + Accept: 'application/json', + }, + body: JSON.stringify({ name: 'www', type: 'A', content: '203.0.113.10', ttl: 14400 }), +}); +console.log((await res.json()).message); +``` + + + + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "net/http" +) + +func main() { + const base = "https://api.zcp.zsoftly.ca/api" + const token = "your-token" + + body := []byte(`{"name":"www","type":"A","content":"203.0.113.10","ttl":14400}`) + + req, _ := http.NewRequest("POST", base+"/dns/domains/examplecom/records", bytes.NewReader(body)) + req.Header.Set("Authorization", "Bearer "+token) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Accept", "application/json") + + resp, err := http.DefaultClient.Do(req) + if err != nil { + panic(err) + } + defer resp.Body.Close() + + var env struct { + Message string `json:"message"` + } + json.NewDecoder(resp.Body).Decode(&env) + fmt.Println(env.Message) +} +``` + + + + +Réponse : + +```json +{ "status": "Success", "message": "Domain record created successfully." } +``` + +Il n'existe aucun point de terminaison de mise à jour. Pour modifier un enregistrement, +supprimez-le, puis recréez-le avec la nouvelle valeur. + +### Enregistrements MX + +Un enregistrement `MX` exige un champ **`priority`** en plus de `content`. Envoyez le serveur de +courrier dans `content` et le nombre de préférence dans `priority`. + +```bash +curl -s -X POST "https://api.zcp.zsoftly.ca/api/dns/domains/examplecom/records" \ + -H "Authorization: Bearer your-token" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -d '{ "name": "@", "type": "MX", "content": "mail.example.com.", "priority": 10, "ttl": 3600 }' +``` + +L'enregistrement se résout alors sous la forme `10 mail.example.com.`. Une requête `MX` sans +`priority` échoue. + +## Supprimer un enregistrement + +Envoyez une requête `DELETE` vers le chemin `records` de la zone avec les paramètres de requête +`name` et `type`. Ici, `name` est le nom **pleinement qualifié** de l'enregistrement, terminé par un +point. + + + + +```bash +curl -s -X DELETE \ + "https://api.zcp.zsoftly.ca/api/dns/domains/examplecom/records?name=www.example.com.&type=A" \ + -H "Authorization: Bearer your-token" \ + -H "Accept: application/json" +``` + + + + +```python +import requests + +BASE = "https://api.zcp.zsoftly.ca/api" +TOKEN = "your-token" + +resp = requests.delete( + f"{BASE}/dns/domains/examplecom/records", + headers={"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"}, + params={"name": "www.example.com.", "type": "A"}, +) +print(resp.json()["message"]) +``` + + + + +```js +const BASE = 'https://api.zcp.zsoftly.ca/api'; +const TOKEN = 'your-token'; + +const url = new URL(`${BASE}/dns/domains/examplecom/records`); +url.search = new URLSearchParams({ name: 'www.example.com.', type: 'A' }).toString(); + +const res = await fetch(url, { + method: 'DELETE', + headers: { Authorization: `Bearer ${TOKEN}`, Accept: 'application/json' }, +}); +console.log((await res.json()).message); +``` + + + + +```go +package main + +import ( + "encoding/json" + "fmt" + "net/http" + "net/url" +) + +func main() { + const base = "https://api.zcp.zsoftly.ca/api" + const token = "your-token" + + q := url.Values{"name": {"www.example.com."}, "type": {"A"}} + endpoint := base + "/dns/domains/examplecom/records?" + q.Encode() + + req, _ := http.NewRequest("DELETE", endpoint, nil) + req.Header.Set("Authorization", "Bearer "+token) + req.Header.Set("Accept", "application/json") + + resp, err := http.DefaultClient.Do(req) + if err != nil { + panic(err) + } + defer resp.Body.Close() + + var env struct { + Message string `json:"message"` + } + json.NewDecoder(resp.Body).Decode(&env) + fmt.Println(env.Message) +} +``` + + + + +Réponse : + +```json +{ "status": "Success", "message": "Domain record deleted successfully." } +``` + +## Référence complète de l'API + +L'interface Swagger fournit la référence interactive complète : +[Ouvrir l'API de la plateforme infonuagique](https://api.zcp.zsoftly.ca/api/docs/nimbo). + +Voir aussi : [Vue d'ensemble du DNS](/fr/public-cloud/dns/overview), +[Domaines](/fr/public-cloud/dns/domains), [Enregistrements DNS](/fr/public-cloud/dns/records), +[Exemples pratiques](/fr/public-cloud/dns/examples), +[Gérer le DNS avec le CLI](/fr/public-cloud/dns/cli), +[Dépannage](/fr/public-cloud/dns/troubleshooting), +[Démarrage rapide de l'API](/fr/public-cloud/api/quickstart) diff --git a/src/content/docs/fr/public-cloud/dns/cli.md b/src/content/docs/fr/public-cloud/dns/cli.md new file mode 100644 index 0000000..203fa8d --- /dev/null +++ b/src/content/docs/fr/public-cloud/dns/cli.md @@ -0,0 +1,217 @@ +--- +title: Gérer le DNS avec le CLI +description: + Créez des zones DNS, ajoutez ou supprimez des enregistrements et déléguez votre domaine à ZSoftly + depuis le terminal avec le CLI zcp. +--- + +Le CLI `zcp` gère vos zones et enregistrements DNS depuis le terminal. Cette page couvre chaque +étape : créer une zone, consulter les serveurs de noms auxquels la déléguer, ajouter ou supprimer +des enregistrements, puis vérifier le résultat. + +## Avant de commencer + +- Le CLI `zcp` doit être installé et authentifié. Consultez le + [guide d'installation du CLI](/fr/public-cloud/cli/installation) et le + [démarrage rapide du CLI](/fr/public-cloud/cli/quickstart). +- Vous devez contrôler un domaine chez son registraire. + +:::note + +Les commandes DNS s'exécutent au niveau du compte. Contrairement à la plupart des autres commandes +`zcp`, elles n'exigent ni `--region` ni `--project`. Seule la commande `zcp dns create` exige +`--project` afin de placer la nouvelle zone dans un projet. + +::: + +## Créer une zone + +Ajoutez votre domaine à ZCP. Cette commande crée la zone DNS servie par ZSoftly. + +```bash +zcp dns create --name example.com --project default-9 +``` + +Sortie : + +```text +FIELD VALUE +Slug examplecom +Name example.com +Status false +Created 2026-07-18T21:08:26.000000Z +``` + +ZCP génère un **slug** à partir du nom de domaine. Toutes les commandes suivantes désignent la zone +par ce slug, et non par son nom de domaine. Copiez-le depuis cette sortie ou depuis `zcp dns list`. +La valeur de `Status` devient active peu après la création. + +:::tip + +ZCP sert le DNS depuis une seule région pour l'ensemble du compte. `zcp dns create` ignore donc +`ZCP_REGION` et définit la région pour vous. Passez uniquement `--name` et `--project`. + +::: + +## Consulter vos serveurs de noms + +Lorsque vous créez une zone, ZCP ajoute ses enregistrements `SOA` et `NS`. L'ensemble +d'enregistrements `NS` contient les deux serveurs de noms vers lesquels faire pointer votre +registraire. + +```bash +zcp dns show examplecom +``` + +Sortie : + +```text +FIELD VALUE +Slug examplecom +Name example.com +Status true +Created 2026-07-18T21:08:26.000000Z +Updated 2026-07-18T21:08:26.000000Z + +Records (2): +NAME TYPE CONTENT TTL +example.com. SOA ns1.zsoftly.ca. hostmaster.zsoftly.ca. 2026071801 10800 3600 604800 3600 3600 +example.com. NS ns1.zsoftly.ca., ns2.zsoftly.ca. 3600 +``` + +Faites pointer votre registraire vers les deux serveurs de noms avant d'y envoyer le trafic en +production. Consultez [Domaines](/fr/public-cloud/dns/domains) pour les étapes propres à chaque +registraire et l'exception Cloudflare Registrar. + +## Ajouter des enregistrements + +Utilisez `zcp dns record-create` avec le slug de la zone, un nom relatif, un type et le contenu. + +```bash +# Apex A record (use @ for the zone root) +zcp dns record-create --domain examplecom --name @ --type A --content 203.0.113.10 + +# Subdomain A record +zcp dns record-create --domain examplecom --name www --type A --content 203.0.113.10 + +# IPv6 address +zcp dns record-create --domain examplecom --name ipv6 --type AAAA --content 2001:db8::10 + +# Alias one name to another +zcp dns record-create --domain examplecom --name blog --type CNAME --content www.example.com. + +# Text record for SPF or domain verification +zcp dns record-create --domain examplecom --name @ --type TXT --content '"v=spf1 -all"' + +# Mail server (MX needs a priority) +zcp dns record-create --domain examplecom --name @ --type MX --content mail.example.com. --priority 10 +``` + +:::caution + +La valeur de `--name` est **relative** à la zone. Passez `www`, et non `www.example.com`. ZCP ajoute +la zone. Un nom complet comme `www.example.com` crée `www.example.com.example.com`. Utilisez `@` +pour la racine de la zone. + +::: + +Règles relatives aux enregistrements : + +- Le TTL par défaut est de `14400` secondes, soit 4 heures. Modifiez-le avec `--ttl`, par exemple + `--ttl 3600`. +- Protégez le contenu `TXT` avec des guillemets, par exemple `'"v=spf1 -all"'`, afin que ceux-ci + parviennent à l'enregistrement. +- Terminez une cible `CNAME` par un point (`www.example.com.`) afin qu'elle reste pleinement + qualifiée. +- Un enregistrement `MX` exige `--priority`. Placez le serveur de courrier dans `--content` et le + nombre de préférence dans `--priority`, par exemple `--priority 10`. Le CLI renvoie une erreur si + cette option manque. +- Les types pris en charge sont `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `CAA` et `NS`. `SRV` et `LOC` ne + sont pas encore disponibles. + +:::note + +Vous pouvez aussi créer des enregistrements `MX` dans le [portail](/fr/public-cloud/dns/records) ou +avec l'[API](/fr/public-cloud/dns/api#enregistrements-mx). + +::: + +## Lister et afficher les enregistrements + +`zcp dns show` affiche la zone et tous ses enregistrements. + +```bash +zcp dns show examplecom +``` + +```text +Records (6): +NAME TYPE CONTENT TTL +www.example.com. A 203.0.113.10 14400 +ipv6.example.com. AAAA 2001:db8::10 14400 +blog.example.com. CNAME www.example.com. 14400 +example.com. TXT "v=spf1 -all" 14400 +example.com. SOA ns1.zsoftly.ca. hostmaster.zsoftly.ca. 2026071807 10800 3600 604800 3600 3600 +example.com. NS ns1.zsoftly.ca., ns2.zsoftly.ca. 3600 +``` + +Pour un script, ajoutez `--output json`, puis redirigez la sortie vers `jq`. + +```bash +zcp dns list --output json +zcp dns show examplecom --output json +``` + +## Mettre à jour un enregistrement + +Il n'existe aucune commande de mise à jour. Pour modifier un enregistrement, supprimez-le, puis +recréez-le avec la nouvelle valeur. + +```bash +zcp dns record-delete --domain examplecom --name www --type A --yes +zcp dns record-create --domain examplecom --name www --type A --content 203.0.113.20 +``` + +## Supprimer un enregistrement + +Désignez l'ensemble d'enregistrements par son nom et son type. + +```bash +zcp dns record-delete --domain examplecom --name www --type A +``` + +Ajoutez `--yes` pour ignorer la demande de confirmation dans un script. Sortie : + +```text +DNS record A "www.example.com." deleted from domain "examplecom". +``` + +## Supprimer une zone + +Cette commande supprime la zone et tous ses enregistrements. + +```bash +zcp dns delete examplecom +``` + +Ajoutez `--yes` pour ignorer la demande de confirmation. + +## Vérifier + +Interrogez directement les serveurs de noms ZSoftly afin de vérifier un enregistrement avant la fin +de la propagation mondiale. + +```bash +# Ask a ZSoftly name server for the record +dig A www.example.com @ns1.zsoftly.ca +short + +# After you delegate at your registrar, query any public resolver +dig A www.example.com @1.1.1.1 +short +``` + +Voir aussi : [Vue d'ensemble du DNS](/fr/public-cloud/dns/overview), +[Domaines](/fr/public-cloud/dns/domains), [Enregistrements DNS](/fr/public-cloud/dns/records), +[Exemples pratiques](/fr/public-cloud/dns/examples), +[Gérer le DNS avec l'API](/fr/public-cloud/dns/api), +[Dépannage](/fr/public-cloud/dns/troubleshooting), +[Référence du CLI](/fr/public-cloud/cli/reference) diff --git a/src/content/docs/fr/public-cloud/dns/domains.md b/src/content/docs/fr/public-cloud/dns/domains.md index ab6d744..d0e82ea 100644 --- a/src/content/docs/fr/public-cloud/dns/domains.md +++ b/src/content/docs/fr/public-cloud/dns/domains.md @@ -183,5 +183,11 @@ verrouillé ou expiré chez le registraire. ## Prochaines étapes +- [Vue d'ensemble du DNS](/fr/public-cloud/dns/overview) : comprenez le rôle des zones, des serveurs + de noms et des enregistrements. - [Gérer les enregistrements DNS](/fr/public-cloud/dns/records) : ajoutez et modifiez des - enregistrements A, CNAME, MX, TXT et autres une fois que ZSoftly est faisant autorité. + enregistrements A, AAAA, CNAME, MX, TXT, CAA et NS lorsque ZSoftly fait autorité. +- [Exemples pratiques](/fr/public-cloud/dns/examples) : hébergez un site Web, acheminez les + courriels, vérifiez la propriété, limitez l'émission de certificats ou déléguez un sous-domaine. +- [Dépannage](/fr/public-cloud/dns/troubleshooting) : vérifiez la propagation et corrigez les + problèmes courants. diff --git a/src/content/docs/fr/public-cloud/dns/examples.md b/src/content/docs/fr/public-cloud/dns/examples.md new file mode 100644 index 0000000..beaa349 --- /dev/null +++ b/src/content/docs/fr/public-cloud/dns/examples.md @@ -0,0 +1,121 @@ +--- +title: Exemples DNS +description: + Exemples DNS complets pour ZCP. Hébergez un site Web, acheminez les courriels, vérifiez la + propriété d'un domaine, limitez l'émission de certificats et déléguez un sous-domaine, avec une + vérification pour chaque cas. +--- + +Voici des exemples pratiques pour les tâches DNS courantes. Chacun utilise le CLI `zcp` avec une +zone dont le slug est `examplecom`, puis vérifie le résultat avec `dig`. Obtenez votre slug avec +`zcp dns list`. Les mêmes enregistrements fonctionnent depuis la +[console](/fr/public-cloud/dns/records) et l'[API](/fr/public-cloud/dns/api). + +:::note + +Ajoutez vos enregistrements **avant** de déléguer le domaine à ZSoftly, puis vérifiez-les. Consultez +[Domaines](/fr/public-cloud/dns/domains) pour la délégation et +[Dépannage](/fr/public-cloud/dns/troubleshooting) pour vérifier la propagation. + +::: + +## Héberger un site Web + +Faites pointer la racine et `www` vers votre serveur. + +```bash +zcp dns record-create --domain examplecom --name @ --type A --content 203.0.113.10 +zcp dns record-create --domain examplecom --name www --type A --content 203.0.113.10 +``` + +Vérifiez depuis un résolveur public : + +```bash +dig A example.com +short # 203.0.113.10 +dig A www.example.com +short # 203.0.113.10 +``` + +## Acheminer les courriels + +Ajoutez un serveur de courrier et une politique SPF. `MX` reçoit la priorité dans son propre champ. + +```bash +zcp dns record-create --domain examplecom --name @ --type MX --content mail.example.com. --priority 10 +zcp dns record-create --domain examplecom --name @ --type TXT --content '"v=spf1 mx -all"' +``` + +Vérifiez : + +```bash +dig MX example.com +short # 10 mail.example.com. +dig TXT example.com +short # "v=spf1 mx -all" +``` + +Voir [Enregistrements MX](/fr/public-cloud/dns/records/mx) et +[Enregistrements TXT](/fr/public-cloud/dns/records/txt). + +## Vérifier la propriété d'un domaine + +De nombreux services vous demandent de publier un enregistrement `TXT` pour prouver que le domaine +vous appartient. Collez la valeur fournie. + +```bash +zcp dns record-create --domain examplecom --name @ --type TXT --content '"provider-verification=abc123"' +``` + +```bash +dig TXT example.com +short +``` + +## Limiter l'émission de certificats + +Autorisez uniquement votre autorité de certification à émettre des certificats. + +```bash +zcp dns record-create --domain examplecom --name @ --type CAA --content '0 issue "letsencrypt.org"' +``` + +```bash +dig CAA example.com +short # 0 issue "letsencrypt.org" +``` + +## Déléguer un sous-domaine + +Confiez `subzone.example.com` à un autre fournisseur DNS. + +```bash +zcp dns record-create --domain examplecom --name subzone --type NS --content ns1.other-dns.com. +zcp dns record-create --domain examplecom --name subzone --type NS --content ns2.other-dns.com. +``` + +```bash +dig NS subzone.example.com +short +``` + +## Modifier un enregistrement + +Aucune action de mise à jour n'existe. Supprimez l'enregistrement, puis recréez-le avec la nouvelle +valeur. + +```bash +zcp dns record-delete --domain examplecom --name www --type A --yes +zcp dns record-create --domain examplecom --name www --type A --content 203.0.113.20 +``` + +Vérifiez la nouvelle valeur après l'expiration du TTL dans les caches des résolveurs : + +```bash +dig A www.example.com +short # 203.0.113.20 +``` + +## Supprimer un enregistrement + +```bash +zcp dns record-delete --domain examplecom --name subzone --type NS +``` + +Ajoutez `--yes` pour ignorer la demande de confirmation dans un script. + +Voir aussi : [Types d'enregistrements](/fr/public-cloud/dns/records), +[Gérer le DNS avec le CLI](/fr/public-cloud/dns/cli), +[Dépannage](/fr/public-cloud/dns/troubleshooting) diff --git a/src/content/docs/fr/public-cloud/dns/overview.md b/src/content/docs/fr/public-cloud/dns/overview.md new file mode 100644 index 0000000..7c66017 --- /dev/null +++ b/src/content/docs/fr/public-cloud/dns/overview.md @@ -0,0 +1,81 @@ +--- +title: Vue d'ensemble du DNS +description: + Hébergez le DNS faisant autorité de vos domaines sur la plateforme infonuagique ZSoftly. Voyez + comment les zones, les serveurs de noms et les enregistrements fonctionnent ensemble, puis + choisissez une méthode de gestion. +--- + +Hébergez le DNS faisant autorité de votre domaine sur ZCP. Ajoutez un domaine, faites pointer votre +registraire vers les serveurs de noms ZSoftly, puis gérez tous vos enregistrements depuis la +console, le CLI ou l'API. + +## Fonctionnement + +Un **domaine** (aussi appelé zone) contient vos enregistrements, par exemple `example.com`. Lorsque +vous ajoutez un domaine, ZCP crée la zone et ses enregistrements `SOA` et `NS`. Vous déléguez +ensuite le domaine à ZSoftly chez votre registraire. ZCP répond alors aux requêtes DNS pour ce +domaine. + +Suivez ce flux de travail : + +1. **Ajoutez votre domaine** à ZCP. Voir [Domaines](/fr/public-cloud/dns/domains). +2. **Ajoutez vos enregistrements** pendant que le domaine passe encore par son fournisseur actuel. +3. **Déléguez** le domaine aux serveurs de noms ZSoftly chez votre registraire. +4. **Vérifiez** la résolution mondiale des nouveaux enregistrements. Voir + [Dépannage](/fr/public-cloud/dns/troubleshooting). + +Cet ordre évite une période avec une zone vide pendant la transition. + +## Serveurs de noms + +ZCP sert chaque zone depuis deux serveurs de noms faisant autorité : + +| Serveur de noms | Valeur | +| --------------- | ---------------- | +| Principal | `ns1.zsoftly.ca` | +| Secondaire | `ns2.zsoftly.ca` | + +Faites pointer votre domaine vers les deux serveurs. Les valeurs exactes figurent aussi dans la +console et dans la sortie de `zcp dns show`. + +## Types d'enregistrements pris en charge + +| Type | Rôle | Détails | +| ------------ | ---------------------------------------------------- | ------------------------------------------------ | +| `A` / `AAAA` | Associer un nom à une adresse IPv4 ou IPv6 | [A et AAAA](/fr/public-cloud/dns/records/a-aaaa) | +| `CNAME` | Créer un alias d'un nom vers un autre | [CNAME](/fr/public-cloud/dns/records/cname) | +| `MX` | Acheminer les courriels vers un serveur de courrier | [MX](/fr/public-cloud/dns/records/mx) | +| `TXT` | Stocker du texte (SPF, DKIM, vérification) | [TXT](/fr/public-cloud/dns/records/txt) | +| `CAA` | Limiter l'émission de certificats aux AC choisies | [CAA](/fr/public-cloud/dns/records/caa) | +| `NS` | Déléguer un sous-domaine à d'autres serveurs de noms | [NS](/fr/public-cloud/dns/records/ns) | + +:::note + +Les enregistrements `SRV` et `LOC` ne sont pas encore disponibles. + +::: + +## Méthodes de gestion du DNS + +- **Console** : la section DNS du portail. Consultez [Enregistrements](/fr/public-cloud/dns/records) + pour la référence de chaque type. +- **CLI** : [Gérer le DNS avec le CLI](/fr/public-cloud/dns/cli). +- **API** : [Gérer le DNS avec l'API](/fr/public-cloud/dns/api). +- **Infrastructure en tant que code** : la ressource `zcp_dns_record` du + [fournisseur Terraform / OpenTofu](/tutorials/manage-infrastructure-terraform) (en anglais). + +Les commandes DNS s'exécutent au niveau du compte. Contrairement à la plupart des autres ressources, +elles n'exigent ni région ni projet. Seule la création d'un domaine exige un projet. + +## Prochaines étapes + +- [Ajouter et déléguer un domaine](/fr/public-cloud/dns/domains) +- [Référence des types d'enregistrements](/fr/public-cloud/dns/records) +- [Exemples pratiques](/fr/public-cloud/dns/examples) : hébergez un site Web, acheminez les + courriels, vérifiez la propriété d'un domaine, limitez l'émission de certificats et déléguez un + sous-domaine. + +Voir aussi : [Gérer le DNS avec le CLI](/fr/public-cloud/dns/cli), +[Gérer le DNS avec l'API](/fr/public-cloud/dns/api), +[Dépannage](/fr/public-cloud/dns/troubleshooting) diff --git a/src/content/docs/fr/public-cloud/dns/records.md b/src/content/docs/fr/public-cloud/dns/records.md deleted file mode 100644 index eb3ca9f..0000000 --- a/src/content/docs/fr/public-cloud/dns/records.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Enregistrements DNS -sidebar_position: 2 ---- - -Les enregistrements DNS relient votre domaine à des services précis. Pour créer un enregistrement, -cliquez sur **Créer un enregistrement** dans le tableau de bord de votre domaine. - -### Types d'enregistrements - -**Enregistrement A** : associe un domaine à une adresse IPv4. - -``` -@ A 192.0.2.1 14400 -``` - -**Enregistrement AAAA** : associe un domaine à une adresse IPv6. - -``` -@ AAAA 2001:0db8:85a3::8a2e:0370:7334 14400 -``` - -**Enregistrement CNAME** : crée un alias pointant vers un autre domaine. - -``` -blog CNAME example.com. 14400 -``` - -**Enregistrement MX** : dirige le courriel vers un serveur de messagerie. - -``` -@ MX 10 mail.example.com. 14400 -``` - -**Enregistrement TXT** : stocke des données texte (SPF, DKIM, vérification de domaine). - -``` -@ TXT "v=spf1 mx -all" 14400 -``` - -**Enregistrement NS** : désigne les serveurs de noms faisant autorité. - -``` -@ NS ns1.example.com. 14400 -``` - -**Enregistrement SRV** : localise un service précis. - -``` -_sip._tcp SRV 10 60 5060 sipserver.example.com. 14400 -``` - -Utilisez `@` pour le domaine racine ou entrez un nom d'hôte pour les sous-domaines (par exemple, -`www`, `blog`). - -Voir aussi : [Domaines](/fr/public-cloud/dns/domains) diff --git a/src/content/docs/fr/public-cloud/dns/records/a-aaaa.md b/src/content/docs/fr/public-cloud/dns/records/a-aaaa.md new file mode 100644 index 0000000..4507654 --- /dev/null +++ b/src/content/docs/fr/public-cloud/dns/records/a-aaaa.md @@ -0,0 +1,62 @@ +--- +title: Enregistrements A et AAAA +description: + Faites pointer un nom d'hôte vers une adresse IPv4 (A) ou IPv6 (AAAA) sur ZCP DNS, avec des + exemples pour la console, le CLI et l'API, ainsi que des commandes de vérification. +--- + +Un enregistrement `A` associe un nom à une adresse **IPv4**. Un enregistrement `AAAA` associe un nom +à une adresse **IPv6**. Utilisez ces enregistrements pour faire pointer un nom vers votre serveur. + +## Champs + +| Champ | Exemple | Remarques | +| ------- | -------------- | -------------------------------------------- | +| Nom | `@` ou `www` | Relatif à la zone. `@` représente le sommet. | +| Type | `A` / `AAAA` | | +| Contenu | `203.0.113.10` | Une adresse IPv4 (`A`) ou IPv6 (`AAAA`) | +| TTL | `14400` | En secondes. Valeur par défaut de 4 heures. | + +## Créer + +Console (affichage sous forme de fichier de zone) : + +```text +@ A 203.0.113.10 14400 +www A 203.0.113.10 14400 +ipv6 AAAA 2001:db8::10 14400 +``` + +CLI : + +```bash +zcp dns record-create --domain examplecom --name @ --type A --content 203.0.113.10 +zcp dns record-create --domain examplecom --name www --type A --content 203.0.113.10 +zcp dns record-create --domain examplecom --name ipv6 --type AAAA --content 2001:db8::10 +``` + +API : envoyez une requête `POST` avec +`{ "name": "www", "type": "A", "content": "203.0.113.10", "ttl": 14400 }`. Voir +[Gérer le DNS avec l'API](/fr/public-cloud/dns/api#ajouter-un-enregistrement). + +## Vérifier + +```bash +dig A www.example.com +short # 203.0.113.10 +dig AAAA ipv6.example.com +short # 2001:db8::10 +``` + +## Remarques + +- **Sommet et adresse IP.** Faites pointer le sommet (`@`) vers une adresse IP fixe avec un + enregistrement `A` ou `AAAA`. N'utilisez pas de `CNAME` au sommet. Voir + [CNAME](/fr/public-cloud/dns/records/cname). +- **Plusieurs adresses.** Ajoutez plusieurs enregistrements `A` portant le même nom, mais des + adresses IP différentes, pour renvoyer plusieurs adresses. Cette configuration fournit une + distribution DNS simple, sans vérification d'intégrité. +- **Double pile.** Publiez un enregistrement `A` et un enregistrement `AAAA` pour un même nom afin + de servir les clients IPv4 et IPv6. + +Voir aussi : [CNAME](/fr/public-cloud/dns/records/cname), +[Exemples pratiques](/fr/public-cloud/dns/examples), +[Types d'enregistrements](/fr/public-cloud/dns/records) diff --git a/src/content/docs/fr/public-cloud/dns/records/caa.md b/src/content/docs/fr/public-cloud/dns/records/caa.md new file mode 100644 index 0000000..4bb7e2e --- /dev/null +++ b/src/content/docs/fr/public-cloud/dns/records/caa.md @@ -0,0 +1,61 @@ +--- +title: Enregistrements CAA +description: + Limitez l'émission de certificats pour votre domaine aux autorités de certification choisies avec + un enregistrement CAA sur ZCP DNS. +--- + +Un enregistrement `CAA` énumère les autorités de certification autorisées à émettre des certificats +pour votre domaine. Les autorités de certification vérifient cette politique avant l'émission. + +## Champs + +| Champ | Exemple | Remarques | +| ------- | --------------------------- | --------------------------------------------------------------------- | +| Nom | `@` | Généralement le sommet. S'applique au domaine et à ses sous-domaines. | +| Type | `CAA` | | +| Contenu | `0 issue "letsencrypt.org"` | Indicateur, balise et valeur. | +| TTL | `14400` | En secondes. | + +La valeur comporte trois parties : un **indicateur** (généralement `0`), une **balise** (`issue`, +`issuewild` ou `iodef`) et une **valeur** entre guillemets (le domaine de l'autorité, ou une URL de +contact pour `iodef`). + +## Créer + +Console (affichage sous forme de fichier de zone) : + +```text +@ CAA 0 issue "letsencrypt.org" 14400 +@ CAA 0 iodef "mailto:security@example.com" 14400 +``` + +CLI (protégez la valeur afin que les guillemets parviennent à l'enregistrement) : + +```bash +zcp dns record-create --domain examplecom --name @ --type CAA --content '0 issue "letsencrypt.org"' +``` + +API : envoyez une requête `POST` avec +`{ "name": "@", "type": "CAA", "content": "0 issue \"letsencrypt.org\"", "ttl": 14400 }`. + +## Vérifier + +```bash +dig CAA example.com +short +# 0 issue "letsencrypt.org" +``` + +## Remarques + +- **`issue`** autorise une AC à émettre des certificats non génériques. **`issuewild`** couvre les + certificats génériques. **`iodef`** définit un contact pour les signalements de violation de + politique. +- **Autorisez chaque AC employée.** Si vos certificats proviennent de plusieurs autorités, ajoutez + un enregistrement `issue` pour chacune. Les autorités absentes doivent refuser l'émission. +- **Aucun enregistrement CAA signifie aucune restriction.** Sans enregistrement `CAA`, aucune + politique ne limite l'émission de certificats. + +Voir aussi : [Enregistrements TXT](/fr/public-cloud/dns/records/txt), +[Exemples pratiques](/fr/public-cloud/dns/examples), +[Types d'enregistrements](/fr/public-cloud/dns/records) diff --git a/src/content/docs/fr/public-cloud/dns/records/cname.md b/src/content/docs/fr/public-cloud/dns/records/cname.md new file mode 100644 index 0000000..f19a774 --- /dev/null +++ b/src/content/docs/fr/public-cloud/dns/records/cname.md @@ -0,0 +1,62 @@ +--- +title: Enregistrements CNAME +description: + Créez un alias d'un nom vers un autre avec un enregistrement CNAME sur ZCP DNS, en respectant les + règles du sommet et de coexistence. +--- + +Un enregistrement `CNAME` crée un alias d'un nom vers un autre. Une requête visant l'alias renvoie +les enregistrements de la cible. Utilisez-le pour faire pointer un sous-domaine vers un nom d'hôte +possédant déjà une adresse, comme un répartiteur de charge ou un point de terminaison de +plateforme-service. + +## Champs + +| Champ | Exemple | Remarques | +| ------- | ------------------ | ------------------------------------------- | +| Nom | `blog` | Relatif à la zone. | +| Type | `CNAME` | | +| Contenu | `www.example.com.` | Nom d'hôte cible. Terminez-le par un point. | +| TTL | `14400` | En secondes. Valeur par défaut de 4 heures. | + +## Créer + +Console (affichage sous forme de fichier de zone) : + +```text +blog CNAME www.example.com. 14400 +``` + +CLI : + +```bash +zcp dns record-create --domain examplecom --name blog --type CNAME --content www.example.com. +``` + +API : envoyez une requête `POST` avec +`{ "name": "blog", "type": "CNAME", "content": "www.example.com.", "ttl": 14400 }`. + +## Vérifier + +```bash +dig blog.example.com +short +# www.example.com. +# 203.0.113.10 +``` + +La réponse affiche l'alias, puis l'adresse de la cible. + +## Remarques + +- **Jamais au sommet.** Un `CNAME` ne peut pas se trouver à la racine de la zone (`@`). Le sommet + possède déjà des enregistrements `SOA` et `NS`, et un `CNAME` ne peut pas coexister avec d'autres + enregistrements portant le même nom. Utilisez un enregistrement + [`A` ou `AAAA`](/fr/public-cloud/dns/records/a-aaaa) pour le sommet. +- **Seul pour son nom.** Un nom associé à un `CNAME` ne peut pas aussi contenir un enregistrement + `A`, `MX`, `TXT` ou d'un autre type. Choisissez une seule option. +- **Point final.** Terminez la cible par un point (`www.example.com.`) afin que ZCP la traite comme + un nom absolu et n'y ajoute pas votre zone. + +Voir aussi : [A et AAAA](/fr/public-cloud/dns/records/a-aaaa), +[Exemples pratiques](/fr/public-cloud/dns/examples), +[Types d'enregistrements](/fr/public-cloud/dns/records) diff --git a/src/content/docs/fr/public-cloud/dns/records/index.md b/src/content/docs/fr/public-cloud/dns/records/index.md new file mode 100644 index 0000000..69ffec5 --- /dev/null +++ b/src/content/docs/fr/public-cloud/dns/records/index.md @@ -0,0 +1,63 @@ +--- +title: Enregistrements DNS +description: + Découvrez les types d'enregistrements DNS offerts par ZCP, les règles communes de nommage et de + TTL, ainsi que la référence de chaque type. +--- + +Les enregistrements DNS relient votre domaine à des services. Chaque enregistrement possède un +**nom**, un **type**, une **valeur** et un **TTL**. Cette page décrit les règles communes. La page +de chaque type présente ses champs, des exemples et ses contraintes. + +## Types d'enregistrements + +| Type | Rôle | Page | +| ------------ | ---------------------------------------------------- | ------------------------------------------------ | +| `A` / `AAAA` | Faire pointer un nom vers une adresse IPv4 ou IPv6 | [A et AAAA](/fr/public-cloud/dns/records/a-aaaa) | +| `CNAME` | Créer un alias d'un nom vers un autre | [CNAME](/fr/public-cloud/dns/records/cname) | +| `MX` | Acheminer les courriels vers un serveur de courrier | [MX](/fr/public-cloud/dns/records/mx) | +| `TXT` | Stocker du texte (SPF, DKIM, vérification) | [TXT](/fr/public-cloud/dns/records/txt) | +| `CAA` | Limiter l'émission de certificats aux AC choisies | [CAA](/fr/public-cloud/dns/records/caa) | +| `NS` | Déléguer un sous-domaine à d'autres serveurs de noms | [NS](/fr/public-cloud/dns/records/ns) | + +:::note + +Les enregistrements `SRV` et `LOC` ne sont pas encore disponibles. + +::: + +## Les noms sont relatifs + +Le **nom** de l'enregistrement est relatif à votre zone. Saisissez `www` pour `www.example.com`, et +non le nom complet. Utilisez `@` pour la racine de la zone, aussi appelée sommet. Dans le CLI et +l'API, ZCP ajoute la zone. Un nom complet comme `www.example.com` deviendrait donc +`www.example.com.example.com`. + +## Valeurs terminées par un point + +Les valeurs qui constituent des noms d'hôte, comme la cible d'un `CNAME`, le serveur de courrier +d'un `MX` ou le serveur de noms d'un `NS`, doivent se terminer par un point. Utilisez par exemple +`mail.example.com.`. Le point indique un nom pleinement qualifié afin que ZCP ne le traite pas comme +un nom relatif à votre zone. + +## TTL + +Le **TTL** (durée de vie) indique, en secondes, combien de temps les résolveurs conservent +l'enregistrement en cache. Sa valeur par défaut est `14400`, soit 4 heures. Réduisez-la à `300` un +ou deux jours avant une modification prévue afin de propager rapidement le changement. Augmentez-la +de nouveau lorsque l'enregistrement est stable. + +## Gérer les enregistrements + +Tous les types se gèrent de la même façon dans chaque interface : + +- **Console** : ouvrez la section DNS du portail, puis cliquez sur **Créer un enregistrement**. +- **CLI** : [Gérer le DNS avec le CLI](/fr/public-cloud/dns/cli). +- **API** : [Gérer le DNS avec l'API](/fr/public-cloud/dns/api). + +Aucune action de mise à jour n'existe. Pour modifier un enregistrement, supprimez-le, puis +recréez-le avec la nouvelle valeur. + +Voir aussi : [Vue d'ensemble du DNS](/fr/public-cloud/dns/overview), +[Exemples pratiques](/fr/public-cloud/dns/examples), +[Dépannage](/fr/public-cloud/dns/troubleshooting) diff --git a/src/content/docs/fr/public-cloud/dns/records/mx.md b/src/content/docs/fr/public-cloud/dns/records/mx.md new file mode 100644 index 0000000..6c42529 --- /dev/null +++ b/src/content/docs/fr/public-cloud/dns/records/mx.md @@ -0,0 +1,86 @@ +--- +title: Enregistrements MX +description: + Acheminez les courriels vers un serveur de courrier avec un enregistrement MX sur ZCP DNS. Le + champ distinct de priorité est obligatoire pour ce type. +--- + +Un enregistrement `MX` achemine les courriels de votre domaine vers un serveur de courrier. Chaque +enregistrement `MX` possède une **priorité**, soit un nombre de préférence, et le nom d'hôte d'un +**serveur de courrier**. La livraison tente d'abord le nombre de priorité le plus bas. + +## Champs + +| Champ | Exemple | Remarques | +| -------- | ------------------- | -------------------------------------------------------------------- | +| Nom | `@` | Généralement le sommet, pour les adresses `@votre-domaine`. | +| Type | `MX` | | +| Priorité | `10` | De 0 à 65535. ZCP préfère les valeurs basses. Obligatoire pour `MX`. | +| Contenu | `mail.example.com.` | Nom d'hôte du serveur de courrier. Terminez-le par un point. | +| TTL | `3600` | En secondes. | + +:::caution + +Les enregistrements `MX` exigent une **priorité**. Placez-la dans son propre champ et non dans la +valeur du serveur de courrier. L'API exige la priorité pour `MX` et la refuse pour tous les autres +types. + +::: + +## Créer + +Dans la console, choisissez le type `MX`, puis saisissez la **Priorité** et la valeur du serveur de +courrier dans leurs champs respectifs. + +```text +@ MX 10 mail.example.com. 3600 +``` + +CLI (`MX` exige `--priority`) : + +```bash +zcp dns record-create --domain examplecom --name @ --type MX \ + --content mail.example.com. --priority 10 --ttl 3600 +``` + +API (envoyez `priority` dans un champ distinct) : + +```bash +curl -s -X POST "https://api.zcp.zsoftly.ca/api/dns/domains/examplecom/records" \ + -H "Authorization: Bearer your-token" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -d '{ "name": "@", "type": "MX", "content": "mail.example.com.", "priority": 10, "ttl": 3600 }' +``` + +## Vérifier + +```bash +dig MX example.com +short +# 10 mail.example.com. +``` + +## Plusieurs serveurs de courrier + +Ajoutez plusieurs enregistrements `MX` avec des priorités différentes pour définir un serveur +principal et un serveur de secours : + +```bash +zcp dns record-create --domain examplecom --name @ --type MX --content mail1.example.com. --priority 10 +zcp dns record-create --domain examplecom --name @ --type MX --content mail2.example.com. --priority 20 +``` + +La livraison tente `mail1` en premier, puis passe à `mail2` si le serveur principal est +inaccessible. + +## Remarques + +- **La priorité est distincte.** N'insérez pas le nombre dans la valeur (`10 mail.example.com.`). La + console, le CLI et l'API reçoivent chacun la priorité dans son propre champ. +- **Le serveur de courrier exige une adresse.** La cible `MX` doit se résoudre en enregistrement `A` + ou `AAAA`. Elle ne peut pas pointer vers un `CNAME`. +- **Une priorité de `0` est valide** et est envoyée correctement. + +Voir aussi : [Enregistrements TXT](/fr/public-cloud/dns/records/txt) pour SPF et DKIM, +[Exemples pratiques](/fr/public-cloud/dns/examples), +[Types d'enregistrements](/fr/public-cloud/dns/records) diff --git a/src/content/docs/fr/public-cloud/dns/records/ns.md b/src/content/docs/fr/public-cloud/dns/records/ns.md new file mode 100644 index 0000000..310c813 --- /dev/null +++ b/src/content/docs/fr/public-cloud/dns/records/ns.md @@ -0,0 +1,69 @@ +--- +title: Enregistrements NS +description: + Déléguez un sous-domaine à un autre ensemble de serveurs de noms avec un enregistrement NS sur ZCP + DNS. +--- + +Un enregistrement `NS` désigne les serveurs de noms faisant autorité d'une zone. ZCP crée +automatiquement l'ensemble d'enregistrements `NS` de votre domaine, qui pointe vers `ns1.zsoftly.ca` +et `ns2.zsoftly.ca`. Ajoutez vos propres enregistrements `NS` pour **déléguer un sous-domaine** à un +autre fournisseur DNS. + +## Champs + +| Champ | Exemple | Remarques | +| ------- | -------------------- | ------------------------------------------------------- | +| Nom | `subzone` | Sous-domaine à déléguer. | +| Type | `NS` | | +| Contenu | `ns1.other-dns.com.` | Serveur de noms du sous-domaine. Terminez par un point. | +| TTL | `3600` | En secondes. | + +## Déléguer un sous-domaine + +Pour confier `subzone.example.com` à un autre fournisseur, ajoutez un enregistrement `NS` portant le +nom `subzone` pour chaque serveur de noms de ce fournisseur. + +Console (affichage sous forme de fichier de zone) : + +```text +subzone NS ns1.other-dns.com. 3600 +subzone NS ns2.other-dns.com. 3600 +``` + +CLI : + +```bash +zcp dns record-create --domain examplecom --name subzone --type NS --content ns1.other-dns.com. +zcp dns record-create --domain examplecom --name subzone --type NS --content ns2.other-dns.com. +``` + +Après cette modification, ZCP renvoie les résolveurs vers le fournisseur délégué pour +`subzone.example.com`. Ce fournisseur doit héberger la zone `subzone.example.com`. + +## Vérifier + +```bash +dig NS subzone.example.com +short +# ns1.other-dns.com. +# ns2.other-dns.com. +``` + +## Déléguer vers ZCP depuis un autre fournisseur + +L'inverse fonctionne aussi. Pour héberger un sous-domaine sur ZCP tout en gardant le domaine parent +chez un autre fournisseur, créez le sous-domaine comme domaine ZCP, par exemple `dev.example.com`. +Chez le fournisseur parent, ajoutez des enregistrements `NS` portant le nom `dev` et pointant vers +`ns1.zsoftly.ca` et `ns2.zsoftly.ca`. Voir [Domaines](/fr/public-cloud/dns/domains). + +## Remarques + +- **Déléguez vers au moins deux serveurs de noms** pour assurer la redondance. +- **Le fournisseur enfant doit héberger la zone.** La délégation achemine seulement les requêtes. + Les enregistrements résident chez le fournisseur auquel vous déléguez. +- **Ne supprimez pas l'ensemble `NS` du sommet.** ZCP gère les enregistrements `ns1` et + `ns2.zsoftly.ca` de votre domaine. + +Voir aussi : [Domaines](/fr/public-cloud/dns/domains), +[Exemples pratiques](/fr/public-cloud/dns/examples), +[Types d'enregistrements](/fr/public-cloud/dns/records) diff --git a/src/content/docs/fr/public-cloud/dns/records/txt.md b/src/content/docs/fr/public-cloud/dns/records/txt.md new file mode 100644 index 0000000..270e889 --- /dev/null +++ b/src/content/docs/fr/public-cloud/dns/records/txt.md @@ -0,0 +1,66 @@ +--- +title: Enregistrements TXT +description: + Stockez du texte dans un enregistrement TXT sur ZCP DNS pour SPF, DKIM, DMARC et la vérification + de domaine, en respectant les règles de guillemets. +--- + +Un enregistrement `TXT` stocke du texte libre sous un nom. Il sert souvent à l'authentification du +courrier électronique (SPF, DKIM et DMARC) et à prouver la propriété d'un domaine auprès d'un +service tiers. + +## Champs + +| Champ | Exemple | Remarques | +| ------- | --------------- | -------------------------------------------------------- | +| Nom | `@` ou un label | La vérification emploie souvent un label comme `_dmarc`. | +| Type | `TXT` | | +| Contenu | `"v=spf1 -all"` | Texte entouré de guillemets doubles. | +| TTL | `14400` | En secondes. | + +## Créer + +Console (affichage sous forme de fichier de zone) : + +```text +@ TXT "v=spf1 mx -all" 14400 +_dmarc TXT "v=DMARC1; p=reject; rua=mailto:dmarc@example.com" 14400 +``` + +CLI (protégez le contenu afin que les guillemets parviennent à l'enregistrement) : + +```bash +zcp dns record-create --domain examplecom --name @ --type TXT --content '"v=spf1 -all"' +``` + +API : envoyez une requête `POST` avec +`{ "name": "@", "type": "TXT", "content": "\"v=spf1 -all\"", "ttl": 14400 }`. + +## Vérifier + +```bash +dig TXT example.com +short +# "v=spf1 -all" +``` + +## Usages courants + +- **SPF** : `"v=spf1 mx -all"` désigne les hôtes autorisés à envoyer des courriels pour votre + domaine. +- **DKIM** : une longue clé publique sous un nom de sélecteur comme `selector._domainkey`. +- **DMARC** : une politique sous `_dmarc`, par exemple `"v=DMARC1; p=reject"`. +- **Vérification de domaine** : une valeur fournie par un service afin de prouver que vous contrôlez + le domaine. + +## Remarques + +- **Guillemets.** La valeur est une chaîne entre guillemets. Dans le CLI, protégez-la afin que + l'interpréteur de commandes transmette les guillemets, par exemple `'"v=spf1 -all"'`. +- **Une chaîne par enregistrement.** Conservez une longue clé DKIM dans un seul enregistrement. La + plateforme la stocke telle quelle. +- **Plusieurs enregistrements TXT.** Un résolveur renvoie tous les enregistrements TXT qui partagent + un nom. + +Voir aussi : [Enregistrements MX](/fr/public-cloud/dns/records/mx), +[Exemples pratiques](/fr/public-cloud/dns/examples), +[Types d'enregistrements](/fr/public-cloud/dns/records) diff --git a/src/content/docs/fr/public-cloud/dns/troubleshooting.md b/src/content/docs/fr/public-cloud/dns/troubleshooting.md new file mode 100644 index 0000000..3bc2101 --- /dev/null +++ b/src/content/docs/fr/public-cloud/dns/troubleshooting.md @@ -0,0 +1,101 @@ +--- +title: Dépannage DNS +description: + Vérifiez la propagation DNS, interrogez directement les serveurs de noms ZSoftly et corrigez les + problèmes d'enregistrements DNS les plus courants sur ZCP. +--- + +Utilisez ces vérifications pour confirmer une modification DNS et résoudre les problèmes courants. + +## Vérifier un enregistrement avant la propagation + +Un serveur de noms ZSoftly répond pour votre zone dès l'enregistrement d'une modification, même +avant que celle-ci soit visible partout. Interrogez-le directement pour vérifier l'enregistrement : + +```bash +dig A www.example.com @ns1.zsoftly.ca +short +dig A www.example.com @ns2.zsoftly.ca +short +``` + +Les deux serveurs de noms doivent renvoyer la même réponse. Si la requête directe est correcte, mais +que les résolveurs publics donnent une autre réponse, l'enregistrement est valide. Vous attendez la +propagation ou l'expiration d'une ancienne valeur en cache. + +## Confirmer la délégation + +Les résolveurs publics atteignent vos enregistrements ZCP après la délégation du domaine à ZSoftly. +Confirmez que la réponse publique contient les serveurs de noms ZSoftly : + +```bash +dig NS example.com +short +# ns1.zsoftly.ca. +# ns2.zsoftly.ca. +``` + +Si les anciens serveurs de noms apparaissent encore, la délégation ne s'est pas propagée ou n'a pas +été enregistrée chez le registraire. Voir [Domaines](/fr/public-cloud/dns/domains). + +## Vérifier la propagation mondiale + +Interrogez plusieurs résolveurs publics dans différentes régions. Ils doivent tous renvoyer la même +réponse : + +```bash +for r in 1.1.1.1 8.8.8.8 9.9.9.9 208.67.222.222; do + echo "$r:"; dig A www.example.com @$r +short +done +``` + +Pour obtenir une carte mondiale, utilisez un outil en ligne comme +[whatsmydns.net](https://www.whatsmydns.net/) et sélectionnez le type d'enregistrement. + +## Problèmes courants + +### La modification n'apparaît pas + +Les résolveurs conservent les enregistrements en cache pendant la durée du TTL. Avec la valeur par +défaut de `14400`, soit 4 heures, un résolveur qui possède l'ancienne valeur attend jusqu'à quatre +heures avant de l'actualiser. Réduisez le TTL à `300` un ou deux jours avant une modification +prévue, puis augmentez-le de nouveau après celle-ci. + +### Un CNAME à la racine ne fonctionne pas + +Un `CNAME` ne peut pas se trouver au sommet (`@`) ni partager un nom avec un autre enregistrement. +Utilisez un enregistrement `A` ou `AAAA` pour la racine. Voir +[Enregistrements CNAME](/fr/public-cloud/dns/records/cname). + +### Corriger le refus d'un enregistrement MX + +Un enregistrement `MX` exige une **priorité** dans son propre champ. Dans le CLI, passez +`--priority`. Dans l'API, envoyez `priority` dans un champ distinct. Voir +[Enregistrements MX](/fr/public-cloud/dns/records/mx). + +### L'enregistrement TXT semble incorrect + +Le contenu `TXT` est une chaîne entre guillemets. Dans le CLI, protégez-la afin que l'interpréteur +de commandes transmette les guillemets, par exemple `'"v=spf1 -all"'`. Voir +[Enregistrements TXT](/fr/public-cloud/dns/records/txt). + +### Un enregistrement SRV ou LOC échoue + +Les enregistrements `SRV` et `LOC` ne sont pas encore disponibles. Les autres types (`A`, `AAAA`, +`CNAME`, `MX`, `TXT`, `CAA` et `NS`) fonctionnent. + +### NXDOMAIN ou absence de réponse + +`NXDOMAIN` signifie que le nom n'existe pas dans la zone. Une réponse vide accompagnée de `NOERROR` +signifie que le nom existe, mais ne possède aucun enregistrement du type demandé. Vérifiez le nom et +le type demandés. + +## Lire la zone telle que la voit la plateforme + +`zcp dns show ` affiche le domaine et tous ses enregistrements, y compris ceux de type `SOA` +et `NS` gérés par ZCP. Comparez cette sortie avec celle de `dig` pour trouver un enregistrement +manquant ou une faute de frappe. + +```bash +zcp dns show examplecom +``` + +Voir aussi : [Vue d'ensemble du DNS](/fr/public-cloud/dns/overview), +[Domaines](/fr/public-cloud/dns/domains), [Exemples pratiques](/fr/public-cloud/dns/examples) diff --git a/src/content/docs/fr/tutorials/host-dns-on-zcp-cli.md b/src/content/docs/fr/tutorials/host-dns-on-zcp-cli.md new file mode 100644 index 0000000..76d116c --- /dev/null +++ b/src/content/docs/fr/tutorials/host-dns-on-zcp-cli.md @@ -0,0 +1,190 @@ +--- +title: 'Héberger un domaine sur ZCP DNS et gérer ses enregistrements avec le CLI' +description: + Faites pointer un domaine qui vous appartient vers les serveurs de noms ZSoftly et gérez tous ses + enregistrements DNS depuis le terminal avec le CLI zcp. +sidebar: + label: 'Héberger le DNS sur ZCP (CLI)' +--- + +Ce tutoriel transforme un domaine que vous possédez déjà en une zone DNS faisant autorité hébergée +par ZSoftly. Vous créez la zone, consultez les serveurs de noms, ajoutez des enregistrements, +déléguez le domaine chez votre registraire, puis confirmez sa résolution sur Internet. Chaque étape +s'exécute depuis votre terminal avec le CLI `zcp`. + +À la fin, vous disposez de ce qui suit : + +- Une zone DNS hébergée sur ZCP +- Des enregistrements A, CNAME, TXT et MX se résolvant sur Internet +- Un domaine délégué depuis votre registraire aux serveurs de noms ZSoftly + +Prévoyez environ 20 minutes de travail. Les changements de serveurs de noms se propagent ensuite +automatiquement. La propagation se termine souvent en quelques heures, mais prévoyez jusqu'à 48 +heures. + +:::note + +Les slugs et valeurs de ce tutoriel, soit le projet `default-9`, le domaine `example.com`, le slug +de zone généré `examplecom` et les exemples d'adresses IP, sont des **exemples**. Les vôtres seront +différents. Chaque étape indique la commande à utiliser pour afficher la bonne valeur pour votre +compte. + +::: + +## Avant de commencer + +- Un compte ZSoftly Public Cloud. [Créez-en un](/fr/public-cloud/getting-started/account-signup) si + vous n'en avez pas. +- Le CLI `zcp` installé. Voir le [guide d'installation du CLI](/fr/public-cloud/cli/installation). +- Un domaine que vous contrôlez chez un registraire, avec l'autorisation d'en modifier les serveurs + de noms. +- `dig` pour la vérification. Il est préinstallé sur macOS et Linux et fait partie de `bind-utils` + ou de `dnsutils` dans la plupart des distributions. + +:::caution + +Ajoutez vos enregistrements dans ZCP **avant** d'effectuer la délégation chez le registraire. Une +délégation effectuée avant l'ajout des enregistrements crée une période pendant laquelle le domaine +ne renvoie aucune réponse DNS. + +::: + +## Étape 1 : S'authentifier + +Créez un jeton dans le portail sous **Profil → Jetons d'API**, puis ajoutez un profil CLI et collez +le jeton. + +```bash +zcp profile add default +zcp auth validate +``` + +Les commandes DNS s'exécutent au niveau du compte. Vous ne leur fournissez donc ni région ni projet. +Seule `zcp dns create` reçoit l'option `--project`. + +## Étape 2 : Créer la zone + +Ajoutez votre domaine. Cette commande crée la zone DNS servie par ZSoftly. + +```bash +zcp dns create --name example.com --project default-9 +``` + +```text +FIELD VALUE +Slug examplecom +Name example.com +Status false +Created 2026-07-18T21:08:26.000000Z +``` + +Copiez le **Slug**. Toutes les commandes d'enregistrement l'emploient. Vous pouvez le retrouver en +tout temps : + +```bash +zcp dns list +``` + +## Étape 3 : Consulter vos serveurs de noms + +ZCP ajoute les enregistrements `SOA` et `NS` de la zone. L'ensemble d'enregistrements `NS` désigne +les deux serveurs auxquels vous effectuerez la délégation. + +```bash +zcp dns show examplecom +``` + +```text +Records (2): +NAME TYPE CONTENT TTL +example.com. SOA ns1.zsoftly.ca. hostmaster.zsoftly.ca. 2026071801 10800 3600 604800 3600 3600 +example.com. NS ns1.zsoftly.ca., ns2.zsoftly.ca. 3600 +``` + +Notez les deux serveurs de noms. Vous en aurez besoin à l'étape 5. + +## Étape 4 : Ajouter vos enregistrements + +Créez les enregistrements qui achemineront votre trafic. Utilisez `@` pour la racine de la zone et +un nom relatif pour les sous-domaines. + +```bash +# Point the root and www at your server +zcp dns record-create --domain examplecom --name @ --type A --content 203.0.113.10 +zcp dns record-create --domain examplecom --name www --type A --content 203.0.113.10 + +# Point an app subdomain at another host +zcp dns record-create --domain examplecom --name api --type A --content 203.0.113.20 + +# Alias blog to www +zcp dns record-create --domain examplecom --name blog --type CNAME --content www.example.com. + +# Publish an SPF policy +zcp dns record-create --domain examplecom --name @ --type TXT --content '"v=spf1 -all"' + +# Route mail (MX needs a priority) +zcp dns record-create --domain examplecom --name @ --type MX --content mail.example.com. --priority 10 +``` + +:::caution + +La valeur de `--name` est **relative** à la zone. Utilisez `www`, et non `www.example.com`. Utilisez +`@` pour la racine. Un nom complet comme `www.example.com` devient `www.example.com.example.com`. + +::: + +Confirmez que la zone contient les enregistrements attendus : + +```bash +zcp dns show examplecom +``` + +## Étape 5 : Effectuer la délégation chez votre registraire + +Faites maintenant de ZSoftly le fournisseur DNS faisant autorité. Chez le registraire où vous avez +acheté le domaine, remplacez les serveurs de noms par les deux valeurs ZSoftly obtenues à l'étape 3. +Le menu exact varie selon le registraire. La page [Domaines](/fr/public-cloud/dns/domains) fournit +une référence rapide pour chacun. + +:::note + +**Cloudflare Registrar** n'autorise pas les serveurs de noms tiers au sommet du domaine. Si votre +domaine est détenu par Cloudflare Registrar, déléguez plutôt un **sous-domaine**. Dans l'application +DNS de Cloudflare, ajoutez deux enregistrements `NS` pour le sous-domaine, par exemple sous le nom +`dev`. Faites-les pointer vers `ns1.zsoftly.ca` et `ns2.zsoftly.ca`. Créez ensuite la zone +`dev.example.com` dans ZCP. Voir +l'[exception Cloudflare](/fr/public-cloud/dns/domains#exception-cloudflare). + +::: + +## Étape 6 : Vérifier + +Avant la délégation, interrogez directement un serveur de noms ZSoftly. Il répond même lorsque les +anciens serveurs de noms demeurent actifs chez votre registraire. + +```bash +dig A www.example.com @ns2.zsoftly.ca +short +# 203.0.113.10 +``` + +Après la délégation et la propagation, tous les résolveurs publics renvoient la même réponse. + +```bash +dig NS example.com @1.1.1.1 +short +# ns1.zsoftly.ca. +# ns2.zsoftly.ca. + +dig A www.example.com @1.1.1.1 +short +# 203.0.113.10 +``` + +Pour suivre la propagation mondiale, utilisez un outil en ligne comme +[whatsmydns.net](https://www.whatsmydns.net/) avec le type d'enregistrement **NS**. + +## Prochaines étapes + +- [Gérer le DNS avec le CLI](/fr/public-cloud/dns/cli) : consultez la référence complète des + commandes d'enregistrement. +- [Gérer le DNS avec l'API](/fr/public-cloud/dns/api) : effectuez les mêmes opérations par REST. +- [Domaines](/fr/public-cloud/dns/domains) : consultez les étapes propres à chaque registraire et + l'exception Cloudflare. diff --git a/src/content/docs/public-cloud/cli/reference.md b/src/content/docs/public-cloud/cli/reference.md index 1f1241e..871f4f5 100644 --- a/src/content/docs/public-cloud/cli/reference.md +++ b/src/content/docs/public-cloud/cli/reference.md @@ -120,11 +120,17 @@ billing/support/dashboard, and the IAM commands `sub-user`/`role`/`permission`) ### Networking: DNS -| Command | Description | -| ------------------------- | ---------------- | -| `zcp dns list` | List DNS domains | -| `zcp dns create` | Add a domain | -| `zcp dns delete ` | Remove a domain | +Account-level. No `--region`/`--project` needed, except `zcp dns create` takes `--project`. See +[Manage DNS with the CLI](/public-cloud/dns/cli). + +| Command | Description | +| ------------------------- | --------------------------------------- | +| `zcp dns list` | List DNS domains | +| `zcp dns create` | Add a domain | +| `zcp dns show ` | Show a domain and its records | +| `zcp dns record-create` | Add a record by name, type, and content | +| `zcp dns record-delete` | Delete a record set by name and type | +| `zcp dns delete ` | Remove a domain | ### Networking: IP Addresses diff --git a/src/content/docs/public-cloud/dns/api.mdx b/src/content/docs/public-cloud/dns/api.mdx new file mode 100644 index 0000000..7f347b2 --- /dev/null +++ b/src/content/docs/public-cloud/dns/api.mdx @@ -0,0 +1,452 @@ +--- +title: Manage DNS with the API +description: + List DNS zones, read records, and add or remove records over the ZSoftly Cloud Platform API. +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +Manage DNS records over the REST API. Every request uses the base URL +`https://api.zcp.zsoftly.ca/api` and sends a Bearer token in the `Authorization` header. See +[Authentication](/public-cloud/api/authentication) to create a token. + +:::note + +Create the zone first in the [portal](/public-cloud/dns/domains) or with the CLI (`zcp dns create`), +then manage its records with the calls below. Each zone has a **slug** used by every record call. +Read the slug from `zcp dns list` or the list call below. + +::: + +## List Your Zones + + + + +```bash +curl -s "https://api.zcp.zsoftly.ca/api/dns/domains" \ + -H "Authorization: Bearer your-token" \ + -H "Accept: application/json" | jq '.data' +``` + + + + +```python +import requests + +BASE = "https://api.zcp.zsoftly.ca/api" +TOKEN = "your-token" + +resp = requests.get( + f"{BASE}/dns/domains", + headers={"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"}, +) +for zone in resp.json()["data"]: + print(zone["slug"], zone["name"], zone["status"]) +``` + + + + +```js +const BASE = 'https://api.zcp.zsoftly.ca/api'; +const TOKEN = 'your-token'; + +const res = await fetch(`${BASE}/dns/domains`, { + headers: { Authorization: `Bearer ${TOKEN}`, Accept: 'application/json' }, +}); +const { data } = await res.json(); +for (const zone of data) { + console.log(zone.slug, zone.name, zone.status); +} +``` + + + + +```go +package main + +import ( + "encoding/json" + "fmt" + "net/http" +) + +func main() { + const base = "https://api.zcp.zsoftly.ca/api" + const token = "your-token" + + req, _ := http.NewRequest("GET", base+"/dns/domains", nil) + req.Header.Set("Authorization", "Bearer "+token) + req.Header.Set("Accept", "application/json") + + resp, err := http.DefaultClient.Do(req) + if err != nil { + panic(err) + } + defer resp.Body.Close() + + var env struct { + Data []struct { + Slug string `json:"slug"` + Name string `json:"name"` + Status bool `json:"status"` + } `json:"data"` + } + json.NewDecoder(resp.Body).Decode(&env) + for _, zone := range env.Data { + fmt.Println(zone.Slug, zone.Name, zone.Status) + } +} +``` + + + + +Response: + +```json +{ + "status": "Success", + "message": "OK", + "total": 1, + "data": [{ "name": "example.com", "slug": "examplecom", "status": true }] +} +``` + +## Show a Zone and Its Records + +Pass the zone slug. The response lists every record, including the `SOA` and `NS` records ZCP adds +for you. + + + + +```bash +curl -s "https://api.zcp.zsoftly.ca/api/dns/domains/examplecom" \ + -H "Authorization: Bearer your-token" \ + -H "Accept: application/json" | jq '.data.records' +``` + + + + +```python +import requests + +BASE = "https://api.zcp.zsoftly.ca/api" +TOKEN = "your-token" + +resp = requests.get( + f"{BASE}/dns/domains/examplecom", + headers={"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"}, +) +for rec in resp.json()["data"]["records"]: + print(rec["name"], rec["type"], rec["contents"], rec["ttl"]) +``` + + + + +```js +const BASE = 'https://api.zcp.zsoftly.ca/api'; +const TOKEN = 'your-token'; + +const res = await fetch(`${BASE}/dns/domains/examplecom`, { + headers: { Authorization: `Bearer ${TOKEN}`, Accept: 'application/json' }, +}); +const { data } = await res.json(); +for (const rec of data.records) { + console.log(rec.name, rec.type, rec.contents, rec.ttl); +} +``` + + + + +```go +package main + +import ( + "encoding/json" + "fmt" + "net/http" +) + +func main() { + const base = "https://api.zcp.zsoftly.ca/api" + const token = "your-token" + + req, _ := http.NewRequest("GET", base+"/dns/domains/examplecom", nil) + req.Header.Set("Authorization", "Bearer "+token) + req.Header.Set("Accept", "application/json") + + resp, err := http.DefaultClient.Do(req) + if err != nil { + panic(err) + } + defer resp.Body.Close() + + var env struct { + Data struct { + Records []struct { + Name string `json:"name"` + Type string `json:"type"` + Contents []string `json:"contents"` + TTL int `json:"ttl"` + } `json:"records"` + } `json:"data"` + } + json.NewDecoder(resp.Body).Decode(&env) + for _, rec := range env.Data.Records { + fmt.Println(rec.Name, rec.Type, rec.Contents, rec.TTL) + } +} +``` + + + + +The API groups records by name and type. A record set holds one or more values under `contents`: + +```json +{ + "name": "www.example.com.", + "type": "A", + "ttl": 14400, + "contents": ["203.0.113.10"] +} +``` + +## Add a Record + +`POST` to the zone's `records` path. The `name` field is **relative** to the zone. Send `www`, not +`www.example.com`. Use `@` for the zone root. + +:::note + +Supported types are `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `CAA`, and `NS`. `SRV` and `LOC` are not +available yet. + +::: + + + + +```bash +curl -s -X POST "https://api.zcp.zsoftly.ca/api/dns/domains/examplecom/records" \ + -H "Authorization: Bearer your-token" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -d '{ "name": "www", "type": "A", "content": "203.0.113.10", "ttl": 14400 }' +``` + + + + +```python +import requests + +BASE = "https://api.zcp.zsoftly.ca/api" +TOKEN = "your-token" + +record = {"name": "www", "type": "A", "content": "203.0.113.10", "ttl": 14400} + +resp = requests.post( + f"{BASE}/dns/domains/examplecom/records", + headers={"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"}, + json=record, +) +print(resp.json()["message"]) +``` + + + + +```js +const BASE = 'https://api.zcp.zsoftly.ca/api'; +const TOKEN = 'your-token'; + +const res = await fetch(`${BASE}/dns/domains/examplecom/records`, { + method: 'POST', + headers: { + Authorization: `Bearer ${TOKEN}`, + 'Content-Type': 'application/json', + Accept: 'application/json', + }, + body: JSON.stringify({ name: 'www', type: 'A', content: '203.0.113.10', ttl: 14400 }), +}); +console.log((await res.json()).message); +``` + + + + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "net/http" +) + +func main() { + const base = "https://api.zcp.zsoftly.ca/api" + const token = "your-token" + + body := []byte(`{"name":"www","type":"A","content":"203.0.113.10","ttl":14400}`) + + req, _ := http.NewRequest("POST", base+"/dns/domains/examplecom/records", bytes.NewReader(body)) + req.Header.Set("Authorization", "Bearer "+token) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Accept", "application/json") + + resp, err := http.DefaultClient.Do(req) + if err != nil { + panic(err) + } + defer resp.Body.Close() + + var env struct { + Message string `json:"message"` + } + json.NewDecoder(resp.Body).Decode(&env) + fmt.Println(env.Message) +} +``` + + + + +Response: + +```json +{ "status": "Success", "message": "Domain record created successfully." } +``` + +There is no update endpoint. To change a record, delete it and create it again with the new value. + +### MX Records + +An `MX` record needs a **`priority`** field alongside `content`. Send the mail server in `content` +and the preference number in `priority`. + +```bash +curl -s -X POST "https://api.zcp.zsoftly.ca/api/dns/domains/examplecom/records" \ + -H "Authorization: Bearer your-token" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -d '{ "name": "@", "type": "MX", "content": "mail.example.com.", "priority": 10, "ttl": 3600 }' +``` + +The record then resolves as `10 mail.example.com.`. Omitting `priority` on an `MX` record fails. + +## Delete a Record + +`DELETE` the zone's `records` path with `name` and `type` query parameters. Here `name` is the +**fully qualified** record name with a trailing dot. + + + + +```bash +curl -s -X DELETE \ + "https://api.zcp.zsoftly.ca/api/dns/domains/examplecom/records?name=www.example.com.&type=A" \ + -H "Authorization: Bearer your-token" \ + -H "Accept: application/json" +``` + + + + +```python +import requests + +BASE = "https://api.zcp.zsoftly.ca/api" +TOKEN = "your-token" + +resp = requests.delete( + f"{BASE}/dns/domains/examplecom/records", + headers={"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"}, + params={"name": "www.example.com.", "type": "A"}, +) +print(resp.json()["message"]) +``` + + + + +```js +const BASE = 'https://api.zcp.zsoftly.ca/api'; +const TOKEN = 'your-token'; + +const url = new URL(`${BASE}/dns/domains/examplecom/records`); +url.search = new URLSearchParams({ name: 'www.example.com.', type: 'A' }).toString(); + +const res = await fetch(url, { + method: 'DELETE', + headers: { Authorization: `Bearer ${TOKEN}`, Accept: 'application/json' }, +}); +console.log((await res.json()).message); +``` + + + + +```go +package main + +import ( + "encoding/json" + "fmt" + "net/http" + "net/url" +) + +func main() { + const base = "https://api.zcp.zsoftly.ca/api" + const token = "your-token" + + q := url.Values{"name": {"www.example.com."}, "type": {"A"}} + endpoint := base + "/dns/domains/examplecom/records?" + q.Encode() + + req, _ := http.NewRequest("DELETE", endpoint, nil) + req.Header.Set("Authorization", "Bearer "+token) + req.Header.Set("Accept", "application/json") + + resp, err := http.DefaultClient.Do(req) + if err != nil { + panic(err) + } + defer resp.Body.Close() + + var env struct { + Message string `json:"message"` + } + json.NewDecoder(resp.Body).Decode(&env) + fmt.Println(env.Message) +} +``` + + + + +Response: + +```json +{ "status": "Success", "message": "Domain record deleted successfully." } +``` + +## Full API Reference + +The complete interactive reference is the Swagger UI: +[Open the Cloud Platform API](https://api.zcp.zsoftly.ca/api/docs/nimbo). + +See also: [DNS Overview](/public-cloud/dns/overview), [Domains](/public-cloud/dns/domains), +[DNS Records](/public-cloud/dns/records), [Worked examples](/public-cloud/dns/examples), +[Manage DNS with the CLI](/public-cloud/dns/cli), +[Troubleshooting](/public-cloud/dns/troubleshooting), [API Quickstart](/public-cloud/api/quickstart) diff --git a/src/content/docs/public-cloud/dns/cli.md b/src/content/docs/public-cloud/dns/cli.md new file mode 100644 index 0000000..f3ac0c1 --- /dev/null +++ b/src/content/docs/public-cloud/dns/cli.md @@ -0,0 +1,208 @@ +--- +title: Manage DNS with the CLI +description: + Create DNS zones, add and remove records, and delegate your domain to ZSoftly from the terminal + with the zcp CLI. +--- + +The `zcp` CLI manages your DNS zones and records from the terminal. This page covers each step: +create a zone, read the name servers to delegate to, add and remove records, and verify the result. + +## Before You Start + +- The `zcp` CLI installed and authenticated. See the + [CLI installation guide](/public-cloud/cli/installation) and + [CLI Quickstart](/public-cloud/cli/quickstart). +- A domain you control at its registrar. + +:::note + +DNS commands are account-level. They do not need `--region` or `--project`, unlike most other `zcp` +commands. The one exception is `zcp dns create`, which needs `--project` to place the new zone in a +project. + +::: + +## Create a Zone + +Add your domain to ZCP. This creates the DNS zone ZSoftly serves. + +```bash +zcp dns create --name example.com --project default-9 +``` + +Output: + +```text +FIELD VALUE +Slug examplecom +Name example.com +Status false +Created 2026-07-18T21:08:26.000000Z +``` + +ZCP generates a **slug** from the domain name. Every later command addresses the zone by this slug, +not by the domain name. Copy it from this output or from `zcp dns list`. The `Status` value turns +active shortly after creation. + +:::tip + +ZCP serves DNS from a single account-wide region, so `zcp dns create` ignores `ZCP_REGION` and sets +the region for you. Pass only `--name` and `--project`. + +::: + +## Read Your Name Servers + +When you create a zone, ZCP adds its `SOA` and `NS` records for you. The `NS` record set holds the +two name servers you point your registrar at. + +```bash +zcp dns show examplecom +``` + +Output: + +```text +FIELD VALUE +Slug examplecom +Name example.com +Status true +Created 2026-07-18T21:08:26.000000Z +Updated 2026-07-18T21:08:26.000000Z + +Records (2): +NAME TYPE CONTENT TTL +example.com. SOA ns1.zsoftly.ca. hostmaster.zsoftly.ca. 2026071801 10800 3600 604800 3600 3600 +example.com. NS ns1.zsoftly.ca., ns2.zsoftly.ca. 3600 +``` + +Point your registrar at both name servers before you send live traffic. See +[Domains](/public-cloud/dns/domains) for the per-registrar steps and the Cloudflare Registrar +exception. + +## Add Records + +Use `zcp dns record-create` with the zone slug, a relative name, a type, and the content. + +```bash +# Apex A record (use @ for the zone root) +zcp dns record-create --domain examplecom --name @ --type A --content 203.0.113.10 + +# Subdomain A record +zcp dns record-create --domain examplecom --name www --type A --content 203.0.113.10 + +# IPv6 address +zcp dns record-create --domain examplecom --name ipv6 --type AAAA --content 2001:db8::10 + +# Alias one name to another +zcp dns record-create --domain examplecom --name blog --type CNAME --content www.example.com. + +# Text record for SPF or domain verification +zcp dns record-create --domain examplecom --name @ --type TXT --content '"v=spf1 -all"' + +# Mail server (MX needs a priority) +zcp dns record-create --domain examplecom --name @ --type MX --content mail.example.com. --priority 10 +``` + +:::caution + +The `--name` value is **relative** to the zone. Pass `www`, not `www.example.com`. ZCP appends the +zone for you. Passing a full name like `www.example.com` creates `www.example.com.example.com`. Use +`@` for the zone root. + +::: + +Record rules: + +- The default TTL is `14400` seconds (4 hours). Override it with `--ttl`, for example `--ttl 3600`. +- Wrap `TXT` content in escaped quotes, for example `'"v=spf1 -all"'`, so the quotes reach the + record. +- End a `CNAME` target with a trailing dot (`www.example.com.`) to keep it fully qualified. +- An `MX` record needs `--priority`. Put the mail server in `--content` and the preference number in + `--priority`, for example `--priority 10`. The CLI stops with an error if you leave it off. +- Supported types are `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `CAA`, and `NS`. `SRV` and `LOC` are not + available yet. + +:::note + +Create `MX` records in the [portal](/public-cloud/dns/records) or with the +[API](/public-cloud/dns/api#mx-records) too. + +::: + +## List and Show Records + +`zcp dns show` prints the zone and every record it holds. + +```bash +zcp dns show examplecom +``` + +```text +Records (6): +NAME TYPE CONTENT TTL +www.example.com. A 203.0.113.10 14400 +ipv6.example.com. AAAA 2001:db8::10 14400 +blog.example.com. CNAME www.example.com. 14400 +example.com. TXT "v=spf1 -all" 14400 +example.com. SOA ns1.zsoftly.ca. hostmaster.zsoftly.ca. 2026071807 10800 3600 604800 3600 3600 +example.com. NS ns1.zsoftly.ca., ns2.zsoftly.ca. 3600 +``` + +For scripting, add `--output json` and pipe to `jq`. + +```bash +zcp dns list --output json +zcp dns show examplecom --output json +``` + +## Update a Record + +There is no update command. To change a record, delete it and create it again with the new value. + +```bash +zcp dns record-delete --domain examplecom --name www --type A --yes +zcp dns record-create --domain examplecom --name www --type A --content 203.0.113.20 +``` + +## Delete a Record + +Address the record set by name and type. + +```bash +zcp dns record-delete --domain examplecom --name www --type A +``` + +Add `--yes` to skip the confirmation prompt in scripts. Output: + +```text +DNS record A "www.example.com." deleted from domain "examplecom". +``` + +## Delete a Zone + +This removes the zone and all of its records. + +```bash +zcp dns delete examplecom +``` + +Add `--yes` to skip the confirmation prompt. + +## Verify + +Query the ZSoftly name servers directly to confirm a record before global propagation finishes. + +```bash +# Ask a ZSoftly name server for the record +dig A www.example.com @ns1.zsoftly.ca +short + +# After you delegate at your registrar, query any public resolver +dig A www.example.com @1.1.1.1 +short +``` + +See also: [DNS Overview](/public-cloud/dns/overview), [Domains](/public-cloud/dns/domains), +[DNS Records](/public-cloud/dns/records), [Worked examples](/public-cloud/dns/examples), +[Manage DNS with the API](/public-cloud/dns/api), +[Troubleshooting](/public-cloud/dns/troubleshooting), [CLI Reference](/public-cloud/cli/reference) diff --git a/src/content/docs/public-cloud/dns/domains.md b/src/content/docs/public-cloud/dns/domains.md index 0a87431..cc07ca9 100644 --- a/src/content/docs/public-cloud/dns/domains.md +++ b/src/content/docs/public-cloud/dns/domains.md @@ -167,5 +167,9 @@ values, removed any stale entries, and that the domain isn't locked or expired a ## Next Steps -- [Manage DNS records](/public-cloud/dns/records): add and edit A, CNAME, MX, TXT, and other records - once ZSoftly is authoritative. +- [DNS overview](/public-cloud/dns/overview): how zones, name servers, and records fit together. +- [Manage DNS records](/public-cloud/dns/records): add and edit A, AAAA, CNAME, MX, TXT, CAA, and NS + records once ZSoftly is authoritative. +- [Worked examples](/public-cloud/dns/examples): host a website, route email, verify ownership, + restrict certificate issuance, or delegate a subdomain. +- [Troubleshooting](/public-cloud/dns/troubleshooting): check propagation and fix common problems. diff --git a/src/content/docs/public-cloud/dns/examples.md b/src/content/docs/public-cloud/dns/examples.md new file mode 100644 index 0000000..11041bd --- /dev/null +++ b/src/content/docs/public-cloud/dns/examples.md @@ -0,0 +1,117 @@ +--- +title: DNS Examples +description: + End-to-end DNS recipes for ZCP. Host a website, route email, verify domain ownership, restrict + certificate issuance, and delegate a subdomain, each with verification. +--- + +Practical recipes for common DNS tasks. Each one uses the `zcp` CLI against a zone with the slug +`examplecom`, then verifies the result with `dig`. Read your slug from `zcp dns list`. The same +records work from the [console](/public-cloud/dns/records) and the [API](/public-cloud/dns/api). + +:::note + +Add your records **before** you delegate the domain to ZSoftly, then verify. See +[Domains](/public-cloud/dns/domains) for delegation and +[Troubleshooting](/public-cloud/dns/troubleshooting) for checking propagation. + +::: + +## Host a Website + +Point the root and `www` at your server. + +```bash +zcp dns record-create --domain examplecom --name @ --type A --content 203.0.113.10 +zcp dns record-create --domain examplecom --name www --type A --content 203.0.113.10 +``` + +Verify from a public resolver: + +```bash +dig A example.com +short # 203.0.113.10 +dig A www.example.com +short # 203.0.113.10 +``` + +## Route Email + +Add a mail server and an SPF policy. `MX` takes a priority in its own field. + +```bash +zcp dns record-create --domain examplecom --name @ --type MX --content mail.example.com. --priority 10 +zcp dns record-create --domain examplecom --name @ --type TXT --content '"v=spf1 mx -all"' +``` + +Verify: + +```bash +dig MX example.com +short # 10 mail.example.com. +dig TXT example.com +short # "v=spf1 mx -all" +``` + +See [MX records](/public-cloud/dns/records/mx) and [TXT records](/public-cloud/dns/records/txt). + +## Verify Domain Ownership + +Many services ask you to publish a `TXT` record to prove you own the domain. Paste the value they +give you. + +```bash +zcp dns record-create --domain examplecom --name @ --type TXT --content '"provider-verification=abc123"' +``` + +```bash +dig TXT example.com +short +``` + +## Restrict Certificate Issuance + +Allow only your certificate authority to issue certificates. + +```bash +zcp dns record-create --domain examplecom --name @ --type CAA --content '0 issue "letsencrypt.org"' +``` + +```bash +dig CAA example.com +short # 0 issue "letsencrypt.org" +``` + +## Delegate a Subdomain + +Hand `subzone.example.com` to another DNS provider. + +```bash +zcp dns record-create --domain examplecom --name subzone --type NS --content ns1.other-dns.com. +zcp dns record-create --domain examplecom --name subzone --type NS --content ns2.other-dns.com. +``` + +```bash +dig NS subzone.example.com +short +``` + +## Change a Record + +There is no update action. Delete the record, then create it with the new value. + +```bash +zcp dns record-delete --domain examplecom --name www --type A --yes +zcp dns record-create --domain examplecom --name www --type A --content 203.0.113.20 +``` + +Verify the new value, allowing for the record's TTL to expire in resolver caches: + +```bash +dig A www.example.com +short # 203.0.113.20 +``` + +## Remove a Record + +```bash +zcp dns record-delete --domain examplecom --name subzone --type NS +``` + +Add `--yes` to skip the confirmation prompt in scripts. + +See also: [Record types](/public-cloud/dns/records), +[Manage DNS with the CLI](/public-cloud/dns/cli), +[Troubleshooting](/public-cloud/dns/troubleshooting) diff --git a/src/content/docs/public-cloud/dns/overview.md b/src/content/docs/public-cloud/dns/overview.md new file mode 100644 index 0000000..b9b20ca --- /dev/null +++ b/src/content/docs/public-cloud/dns/overview.md @@ -0,0 +1,76 @@ +--- +title: DNS Overview +description: + Host authoritative DNS for your domains on the ZSoftly Cloud Platform. Learn how zones, name + servers, and records work together and choose a management method. +--- + +Host your domain's authoritative DNS on ZCP. You add a domain, point your registrar at ZSoftly's +name servers, and manage all your records from the console, the CLI, or the API. + +## How It Works + +A **domain** (also called a zone) is the container for your records, for example `example.com`. When +you add a domain, ZCP creates the zone and adds its `SOA` and `NS` records for you. You then +delegate the domain to ZSoftly at your registrar, and ZCP answers DNS queries for it. + +Use this workflow: + +1. **Add your domain** to ZCP. See [Domains](/public-cloud/dns/domains). +2. **Add your records** while the domain still resolves through its current provider. +3. **Delegate** the domain to ZSoftly's name servers at your registrar. +4. **Verify** global resolution for the new records. See + [Troubleshooting](/public-cloud/dns/troubleshooting). + +This order avoids an empty-zone window during the switch. + +## Name Servers + +ZCP serves every zone from two authoritative name servers: + +| Name server | Value | +| ----------- | ---------------- | +| Primary | `ns1.zsoftly.ca` | +| Secondary | `ns2.zsoftly.ca` | + +Point your domain at both. The exact values also appear in the console and in `zcp dns show`. + +## Supported Record Types + +| Type | Purpose | Details | +| ------------ | ------------------------------------------- | ---------------------------------------------- | +| `A` / `AAAA` | Map a name to an IPv4 or IPv6 address | [A and AAAA](/public-cloud/dns/records/a-aaaa) | +| `CNAME` | Alias one name to another | [CNAME](/public-cloud/dns/records/cname) | +| `MX` | Route email to a mail server | [MX](/public-cloud/dns/records/mx) | +| `TXT` | Store text (SPF, DKIM, verification) | [TXT](/public-cloud/dns/records/txt) | +| `CAA` | Restrict certificate issuance to chosen CAs | [CAA](/public-cloud/dns/records/caa) | +| `NS` | Delegate a subdomain to other name servers | [NS](/public-cloud/dns/records/ns) | + +:::note + +`SRV` and `LOC` records are not available yet. + +::: + +## Ways to Manage DNS + +- **Console**: the DNS section of the portal. See [Records](/public-cloud/dns/records) for the + per-type reference. +- **CLI**: [Manage DNS with the CLI](/public-cloud/dns/cli). +- **API**: [Manage DNS with the API](/public-cloud/dns/api). +- **Infrastructure as code**: the `zcp_dns_record` resource in the + [Terraform / OpenTofu provider](/tutorials/manage-infrastructure-terraform). + +DNS commands are account-level. They do not need a region or project, unlike most other resources. +The one exception is creating a domain, which takes a project. + +## Next Steps + +- [Add a domain and delegate it](/public-cloud/dns/domains) +- [Record types reference](/public-cloud/dns/records) +- [Worked examples](/public-cloud/dns/examples): host a website, route email, verify ownership, + restrict certificate issuance, and delegate a subdomain. + +See also: [Manage DNS with the CLI](/public-cloud/dns/cli), +[Manage DNS with the API](/public-cloud/dns/api), +[Troubleshooting](/public-cloud/dns/troubleshooting) diff --git a/src/content/docs/public-cloud/dns/records.md b/src/content/docs/public-cloud/dns/records.md deleted file mode 100644 index 7cae2bc..0000000 --- a/src/content/docs/public-cloud/dns/records.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: DNS Records -sidebar_position: 2 ---- - -DNS records connect your domain to specific services. To create a record, click **Create Record** in -your domain's dashboard. - -### Record Types - -**A Record**: maps a domain to an IPv4 address. - -```text -@ A 192.0.2.1 14400 -``` - -**AAAA Record**: maps a domain to an IPv6 address. - -```text -@ AAAA 2001:0db8:85a3::8a2e:0370:7334 14400 -``` - -**CNAME Record**: creates an alias pointing to another domain. - -```text -blog CNAME example.com. 14400 -``` - -**MX Record**: directs email to a mail server. - -```text -@ MX 10 mail.example.com. 14400 -``` - -**TXT Record**: stores text data (SPF, DKIM, domain verification). - -```text -@ TXT "v=spf1 mx -all" 14400 -``` - -**NS Record**: designates authoritative name servers. - -```text -@ NS ns1.example.com. 14400 -``` - -**SRV Record**: locates a specific service. - -```text -_sip._tcp SRV 10 60 5060 sipserver.example.com. 14400 -``` - -Use `@` for the root domain or enter a hostname for subdomains (e.g., `www`, `blog`). - -See also: [Domains](/public-cloud/dns/domains) diff --git a/src/content/docs/public-cloud/dns/records/a-aaaa.md b/src/content/docs/public-cloud/dns/records/a-aaaa.md new file mode 100644 index 0000000..50d3303 --- /dev/null +++ b/src/content/docs/public-cloud/dns/records/a-aaaa.md @@ -0,0 +1,58 @@ +--- +title: A and AAAA Records +description: + Point a hostname at an IPv4 (A) or IPv6 (AAAA) address on ZCP DNS, with console, CLI, and API + examples and verification. +--- + +An `A` record maps a name to an **IPv4** address. An `AAAA` record maps a name to an **IPv6** +address. Use these records to point a name to your server. + +## Fields + +| Field | Example | Notes | +| ------- | -------------- | -------------------------------------- | +| Name | `@` or `www` | Relative to the zone. `@` is the apex. | +| Type | `A` / `AAAA` | | +| Content | `203.0.113.10` | An IPv4 (`A`) or IPv6 (`AAAA`) address | +| TTL | `14400` | Seconds. Default 4 hours. | + +## Create + +Console (zone-file view): + +```text +@ A 203.0.113.10 14400 +www A 203.0.113.10 14400 +ipv6 AAAA 2001:db8::10 14400 +``` + +CLI: + +```bash +zcp dns record-create --domain examplecom --name @ --type A --content 203.0.113.10 +zcp dns record-create --domain examplecom --name www --type A --content 203.0.113.10 +zcp dns record-create --domain examplecom --name ipv6 --type AAAA --content 2001:db8::10 +``` + +API: `POST` with `{ "name": "www", "type": "A", "content": "203.0.113.10", "ttl": 14400 }`. See +[Manage DNS with the API](/public-cloud/dns/api#add-a-record). + +## Verify + +```bash +dig A www.example.com +short # 203.0.113.10 +dig AAAA ipv6.example.com +short # 2001:db8::10 +``` + +## Notes + +- **Apex and IP address.** Point the apex (`@`) at a fixed IP with an `A` or `AAAA` record. Do not + use a `CNAME` at the apex. See [CNAME](/public-cloud/dns/records/cname). +- **Multiple addresses.** Add several `A` records with the same name and different IPs to return + multiple addresses. This provides simple DNS-based distribution without health checks. +- **Dual stack.** Publish both an `A` and an `AAAA` record for a name to serve IPv4 and IPv6 + clients. + +See also: [CNAME](/public-cloud/dns/records/cname), [Worked examples](/public-cloud/dns/examples), +[Record types](/public-cloud/dns/records) diff --git a/src/content/docs/public-cloud/dns/records/caa.md b/src/content/docs/public-cloud/dns/records/caa.md new file mode 100644 index 0000000..2a70998 --- /dev/null +++ b/src/content/docs/public-cloud/dns/records/caa.md @@ -0,0 +1,58 @@ +--- +title: CAA Records +description: + Restrict certificate issuance for your domain to selected certificate authorities with a CAA + record on ZCP DNS. +--- + +A `CAA` record lists the certificate authorities allowed to issue certificates for your domain. +Certificate authorities check this policy before issuing a certificate. + +## Fields + +| Field | Example | Notes | +| ------- | --------------------------- | -------------------------------------------------- | +| Name | `@` | Usually the apex. Applies to the domain and below. | +| Type | `CAA` | | +| Content | `0 issue "letsencrypt.org"` | Flags, tag, and value. | +| TTL | `14400` | Seconds. | + +The value has three parts: **flags** (usually `0`), a **tag** (`issue`, `issuewild`, or `iodef`), +and a quoted **value** (the CA's domain, or a contact URL for `iodef`). + +## Create + +Console (zone-file view): + +```text +@ CAA 0 issue "letsencrypt.org" 14400 +@ CAA 0 iodef "mailto:security@example.com" 14400 +``` + +CLI (wrap the value so the quotes reach the record): + +```bash +zcp dns record-create --domain examplecom --name @ --type CAA --content '0 issue "letsencrypt.org"' +``` + +API: `POST` with +`{ "name": "@", "type": "CAA", "content": "0 issue \"letsencrypt.org\"", "ttl": 14400 }`. + +## Verify + +```bash +dig CAA example.com +short +# 0 issue "letsencrypt.org" +``` + +## Notes + +- **`issue`** allows a CA to issue non-wildcard certificates. **`issuewild`** covers wildcard + certificates. **`iodef`** sets a contact for policy-violation reports. +- **Allow every CA you use.** If you get certificates from more than one CA, add an `issue` record + for each. Unlisted certificate authorities must refuse issuance. +- **No CAA record means no restriction.** Without a `CAA` record, no policy restricts certificate + issuance. + +See also: [TXT records](/public-cloud/dns/records/txt), +[Worked examples](/public-cloud/dns/examples), [Record types](/public-cloud/dns/records) diff --git a/src/content/docs/public-cloud/dns/records/cname.md b/src/content/docs/public-cloud/dns/records/cname.md new file mode 100644 index 0000000..e12ed1c --- /dev/null +++ b/src/content/docs/public-cloud/dns/records/cname.md @@ -0,0 +1,58 @@ +--- +title: CNAME Records +description: + Alias one name to another with a CNAME record on ZCP DNS, including the apex and coexistence + rules. +--- + +A `CNAME` record makes one name an alias of another. A lookup for the alias returns the target's +records. Use it to point a subdomain at a hostname with an existing address, such as a load balancer +or a platform-as-a-service endpoint. + +## Fields + +| Field | Example | Notes | +| ------- | ------------------ | ------------------------------------------------ | +| Name | `blog` | Relative to the zone. | +| Type | `CNAME` | | +| Content | `www.example.com.` | The target hostname. End it with a trailing dot. | +| TTL | `14400` | Seconds. Default 4 hours. | + +## Create + +Console (zone-file view): + +```text +blog CNAME www.example.com. 14400 +``` + +CLI: + +```bash +zcp dns record-create --domain examplecom --name blog --type CNAME --content www.example.com. +``` + +API: `POST` with `{ "name": "blog", "type": "CNAME", "content": "www.example.com.", "ttl": 14400 }`. + +## Verify + +```bash +dig blog.example.com +short +# www.example.com. +# 203.0.113.10 +``` + +The answer shows the alias, then the target's address. + +## Notes + +- **Not at the apex.** A `CNAME` cannot sit at the zone root (`@`). The apex already has `SOA` and + `NS` records, and a `CNAME` cannot coexist with other records at the same name. Use an + [`A` or `AAAA`](/public-cloud/dns/records/a-aaaa) record for the apex. +- **Alone at its name.** A name with a `CNAME` cannot also hold an `A`, `MX`, `TXT`, or any other + record. Pick one. +- **Trailing dot.** End the target with a dot (`www.example.com.`) so ZCP treats it as an absolute + name and does not append your zone. + +See also: [A and AAAA](/public-cloud/dns/records/a-aaaa), +[Worked examples](/public-cloud/dns/examples), [Record types](/public-cloud/dns/records) diff --git a/src/content/docs/public-cloud/dns/records/index.md b/src/content/docs/public-cloud/dns/records/index.md new file mode 100644 index 0000000..1d9777b --- /dev/null +++ b/src/content/docs/public-cloud/dns/records/index.md @@ -0,0 +1,58 @@ +--- +title: DNS Records +description: + The DNS record types available on ZCP, plus shared naming and TTL rules and links to each record + type reference. +--- + +DNS records connect your domain to services. Each record has a **name**, a **type**, a **value**, +and a **TTL**. This page covers the shared rules. Each type has its own page with fields, examples, +and constraints. + +## Record Types + +| Type | Purpose | Page | +| ------------ | ------------------------------------------- | ---------------------------------------------- | +| `A` / `AAAA` | Point a name at an IPv4 or IPv6 address | [A and AAAA](/public-cloud/dns/records/a-aaaa) | +| `CNAME` | Alias one name to another | [CNAME](/public-cloud/dns/records/cname) | +| `MX` | Route email to a mail server | [MX](/public-cloud/dns/records/mx) | +| `TXT` | Store text (SPF, DKIM, verification) | [TXT](/public-cloud/dns/records/txt) | +| `CAA` | Restrict certificate issuance to chosen CAs | [CAA](/public-cloud/dns/records/caa) | +| `NS` | Delegate a subdomain to other name servers | [NS](/public-cloud/dns/records/ns) | + +:::note + +`SRV` and `LOC` records are not available yet. + +::: + +## Names Are Relative + +The record **name** is relative to your zone. Enter `www` for `www.example.com`, not the full name. +Use `@` for the zone root (the apex). In the CLI and API, ZCP appends the zone for you, so a full +name like `www.example.com` becomes `www.example.com.example.com`. + +## Values With a Trailing Dot + +Hostname values, such as a `CNAME` target, an `MX` mail server, or an `NS` name server, should end +with a trailing dot. For example, use `mail.example.com.`. The dot marks the name as fully qualified +so ZCP does not treat it as relative to your zone. + +## TTL + +The **TTL** (time to live) is how long, in seconds, resolvers cache the record. The default is +`14400` (4 hours). Lower it to `300` a day or two before you plan to change a record, so the change +propagates quickly. Raise it again once the record is stable. + +## How to Manage Records + +Every type works the same way across all surfaces: + +- **Console**: the DNS section of the portal, then **Create Record**. +- **CLI**: [Manage DNS with the CLI](/public-cloud/dns/cli). +- **API**: [Manage DNS with the API](/public-cloud/dns/api). + +There is no update action. To change a record, delete it and create it again with the new value. + +See also: [DNS Overview](/public-cloud/dns/overview), [Worked examples](/public-cloud/dns/examples), +[Troubleshooting](/public-cloud/dns/troubleshooting) diff --git a/src/content/docs/public-cloud/dns/records/mx.md b/src/content/docs/public-cloud/dns/records/mx.md new file mode 100644 index 0000000..57ef7f2 --- /dev/null +++ b/src/content/docs/public-cloud/dns/records/mx.md @@ -0,0 +1,81 @@ +--- +title: MX Records +description: + Route email to a mail server with an MX record on ZCP DNS. MX needs a priority, set in its own + field. +--- + +An `MX` record routes email for your domain to a mail server. Each `MX` record has a **priority** (a +preference number) and a **mail server** hostname. Mail delivery tries the lowest priority number +first. + +## Fields + +| Field | Example | Notes | +| -------- | ------------------- | -------------------------------------------------------- | +| Name | `@` | Usually the apex, so mail addresses are `@your-domain`. | +| Type | `MX` | | +| Priority | `10` | 0 to 65535. ZCP prefers lower values. Required for `MX`. | +| Content | `mail.example.com.` | The mail server hostname. End it with a trailing dot. | +| TTL | `3600` | Seconds. | + +:::caution + +`MX` records need a **priority**. Set it in its own field, not inside the mail server value. The API +requires priority for `MX` and rejects it for every other type. + +::: + +## Create + +Console: choose type `MX`, set **Priority** and the mail server value in their own fields. + +```text +@ MX 10 mail.example.com. 3600 +``` + +CLI (`MX` requires `--priority`): + +```bash +zcp dns record-create --domain examplecom --name @ --type MX \ + --content mail.example.com. --priority 10 --ttl 3600 +``` + +API (send `priority` as a separate field): + +```bash +curl -s -X POST "https://api.zcp.zsoftly.ca/api/dns/domains/examplecom/records" \ + -H "Authorization: Bearer your-token" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -d '{ "name": "@", "type": "MX", "content": "mail.example.com.", "priority": 10, "ttl": 3600 }' +``` + +## Verify + +```bash +dig MX example.com +short +# 10 mail.example.com. +``` + +## Multiple Mail Servers + +Add several `MX` records with different priorities for a primary and a backup: + +```bash +zcp dns record-create --domain examplecom --name @ --type MX --content mail1.example.com. --priority 10 +zcp dns record-create --domain examplecom --name @ --type MX --content mail2.example.com. --priority 20 +``` + +Mail delivers to `mail1` first, then falls back to `mail2` if the primary is unreachable. + +## Notes + +- **Priority is separate.** Do not put the number in the value (`10 mail.example.com.`). The + console, CLI, and API each take priority in its own field. +- **The mail server needs an address.** The `MX` target must resolve to an `A` or `AAAA` record. It + cannot point at a `CNAME`. +- **A `0` priority is valid** and is sent correctly. + +See also: [TXT records](/public-cloud/dns/records/txt) for SPF and DKIM, +[Worked examples](/public-cloud/dns/examples), [Record types](/public-cloud/dns/records) diff --git a/src/content/docs/public-cloud/dns/records/ns.md b/src/content/docs/public-cloud/dns/records/ns.md new file mode 100644 index 0000000..1116043 --- /dev/null +++ b/src/content/docs/public-cloud/dns/records/ns.md @@ -0,0 +1,64 @@ +--- +title: NS Records +description: Delegate a subdomain to another set of name servers with an NS record on ZCP DNS. +--- + +An `NS` record names the authoritative name servers for a zone. ZCP creates the `NS` record set for +your domain automatically (pointing at `ns1.zsoftly.ca` and `ns2.zsoftly.ca`). Add your own `NS` +records to **delegate a subdomain** to a different DNS provider. + +## Fields + +| Field | Example | Notes | +| ------- | -------------------- | --------------------------------------------------------- | +| Name | `subzone` | The subdomain to delegate. | +| Type | `NS` | | +| Content | `ns1.other-dns.com.` | A name server for the subdomain. End with a trailing dot. | +| TTL | `3600` | Seconds. | + +## Delegate a Subdomain + +To hand `subzone.example.com` to another provider, add an `NS` record for `subzone` for every +provider name server. + +Console (zone-file view): + +```text +subzone NS ns1.other-dns.com. 3600 +subzone NS ns2.other-dns.com. 3600 +``` + +CLI: + +```bash +zcp dns record-create --domain examplecom --name subzone --type NS --content ns1.other-dns.com. +zcp dns record-create --domain examplecom --name subzone --type NS --content ns2.other-dns.com. +``` + +After this change, ZCP returns a referral to the delegated provider for `subzone.example.com`. The +delegated provider must host the `subzone.example.com` zone. + +## Verify + +```bash +dig NS subzone.example.com +short +# ns1.other-dns.com. +# ns2.other-dns.com. +``` + +## Delegating to ZCP From Elsewhere + +The reverse also works. To host a subdomain on ZCP while the parent domain stays at another +provider, create the subdomain as a ZCP domain (for example, `dev.example.com`). At the parent +provider, add `NS` records for `dev` pointing at `ns1.zsoftly.ca` and `ns2.zsoftly.ca`. See +[Domains](/public-cloud/dns/domains). + +## Notes + +- **Delegate to at least two name servers** for redundancy. +- **The child provider must host the zone.** Delegation only forwards queries. The records live at + the provider you delegate to. +- **Do not delete the apex `NS` set.** ZCP manages your domain's own `ns1`/`ns2.zsoftly.ca` records. + +See also: [Domains](/public-cloud/dns/domains), [Worked examples](/public-cloud/dns/examples), +[Record types](/public-cloud/dns/records) diff --git a/src/content/docs/public-cloud/dns/records/txt.md b/src/content/docs/public-cloud/dns/records/txt.md new file mode 100644 index 0000000..5aeaa20 --- /dev/null +++ b/src/content/docs/public-cloud/dns/records/txt.md @@ -0,0 +1,60 @@ +--- +title: TXT Records +description: + Store text data with a TXT record on ZCP DNS for SPF, DKIM, DMARC, and domain verification, with + quoting rules. +--- + +A `TXT` record stores free text at a name. The common uses are email authentication (SPF, DKIM, +DMARC) and proving domain ownership to a third-party service. + +## Fields + +| Field | Example | Notes | +| ------- | --------------- | ----------------------------------------------------- | +| Name | `@` or a label | Verification records often use a label like `_dmarc`. | +| Type | `TXT` | | +| Content | `"v=spf1 -all"` | The text, wrapped in double quotes. | +| TTL | `14400` | Seconds. | + +## Create + +Console (zone-file view): + +```text +@ TXT "v=spf1 mx -all" 14400 +_dmarc TXT "v=DMARC1; p=reject; rua=mailto:dmarc@example.com" 14400 +``` + +CLI (wrap the content so the quotes reach the record): + +```bash +zcp dns record-create --domain examplecom --name @ --type TXT --content '"v=spf1 -all"' +``` + +API: `POST` with `{ "name": "@", "type": "TXT", "content": "\"v=spf1 -all\"", "ttl": 14400 }`. + +## Verify + +```bash +dig TXT example.com +short +# "v=spf1 -all" +``` + +## Common Uses + +- **SPF**: `"v=spf1 mx -all"` lists the hosts allowed to send mail for your domain. +- **DKIM**: a long public key at a selector name like `selector._domainkey`. +- **DMARC**: a policy at `_dmarc`, for example `"v=DMARC1; p=reject"`. +- **Domain verification**: a value a provider gives you to prove you control the domain. + +## Notes + +- **Quoting.** The value is a quoted string. On the CLI, wrap it so the shell passes the quotes + through, for example `'"v=spf1 -all"'`. +- **One string per record.** For a long DKIM key, keep it as a single record. The platform stores it + as given. +- **Multiple TXT records.** A resolver returns all TXT records sharing a name. + +See also: [MX records](/public-cloud/dns/records/mx), [Worked examples](/public-cloud/dns/examples), +[Record types](/public-cloud/dns/records) diff --git a/src/content/docs/public-cloud/dns/troubleshooting.md b/src/content/docs/public-cloud/dns/troubleshooting.md new file mode 100644 index 0000000..0690389 --- /dev/null +++ b/src/content/docs/public-cloud/dns/troubleshooting.md @@ -0,0 +1,93 @@ +--- +title: DNS Troubleshooting +description: + Check DNS propagation, query ZSoftly's name servers directly, and fix the most common DNS record + problems on ZCP. +--- + +Use these checks to confirm a DNS change and resolve common problems. + +## Check a Record Before Propagation + +A ZSoftly name server answers for your zone as soon as you save a record, even before the world sees +it. Query it directly to confirm the record is correct: + +```bash +dig A www.example.com @ns1.zsoftly.ca +short +dig A www.example.com @ns2.zsoftly.ca +short +``` + +Both name servers should return the same answer. If the direct query is right but public resolvers +are wrong, the record is fine and you are waiting on propagation or a cached old value. + +## Confirm Delegation + +Public resolvers reach your ZCP records after you delegate the domain to ZSoftly. Confirm the public +response lists the ZSoftly name servers: + +```bash +dig NS example.com +short +# ns1.zsoftly.ca. +# ns2.zsoftly.ca. +``` + +If this still shows the old name servers, the delegation has not propagated or was not saved at the +registrar. See [Domains](/public-cloud/dns/domains). + +## Check Worldwide Propagation + +Query several public resolvers in different regions. They should all agree: + +```bash +for r in 1.1.1.1 8.8.8.8 9.9.9.9 208.67.222.222; do + echo "$r:"; dig A www.example.com @$r +short +done +``` + +For a visual world map, use an online checker such as [whatsmydns.net](https://www.whatsmydns.net/) +and pick the record type. + +## Common Problems + +### The Change Has Not Shown Up + +Resolvers cache records for the TTL. With the default `14400` (4 hours), a resolver holding the old +value waits up to four hours before refreshing it. Lower the TTL to `300` a day or two before a +planned change, then raise it again afterward. + +### CNAME at the Root Does Not Work + +A `CNAME` cannot sit at the apex (`@`) and cannot share a name with any other record. Use an `A` or +`AAAA` record for the root. See [CNAME records](/public-cloud/dns/records/cname). + +### Fix MX Record Rejection + +An `MX` record needs a **priority** in its own field. From the CLI, pass `--priority`. From the API, +send `priority` as a separate field. See [MX records](/public-cloud/dns/records/mx). + +### TXT Record Looks Wrong + +`TXT` content is a quoted string. On the CLI, wrap it so the shell passes the quotes through, for +example `'"v=spf1 -all"'`. See [TXT records](/public-cloud/dns/records/txt). + +### SRV or LOC Record Fails + +`SRV` and `LOC` records are not available yet. The other types (`A`, `AAAA`, `CNAME`, `MX`, `TXT`, +`CAA`, `NS`) work. + +### NXDOMAIN Versus No Answer + +`NXDOMAIN` means the name does not exist in the zone. An empty answer with `NOERROR` means the name +exists but has no record of the requested type. Check the requested name and type. + +## Read the Zone as the Platform Sees It + +`zcp dns show ` prints the domain and every record it holds, including the `SOA` and `NS` +records ZCP manages. Compare it against what `dig` returns to find a missing or mistyped record. + +```bash +zcp dns show examplecom +``` + +See also: [DNS Overview](/public-cloud/dns/overview), [Domains](/public-cloud/dns/domains), +[Worked examples](/public-cloud/dns/examples) diff --git a/src/content/docs/tutorials/host-dns-on-zcp-cli.md b/src/content/docs/tutorials/host-dns-on-zcp-cli.md new file mode 100644 index 0000000..c56417b --- /dev/null +++ b/src/content/docs/tutorials/host-dns-on-zcp-cli.md @@ -0,0 +1,180 @@ +--- +title: 'Host a Domain on ZCP DNS and Manage Records with the CLI' +description: + Point a domain you own at ZSoftly name servers and manage its DNS records end to end from the + terminal with the zcp CLI. +sidebar: + label: 'Host DNS on ZCP (CLI)' +--- + +This tutorial takes a domain you already own and makes ZSoftly the authoritative DNS host for it. +You create the zone, read the name servers, add records, delegate the domain at your registrar, and +confirm it resolves on the public internet. Every step runs from your terminal with the `zcp` CLI. + +By the end you have: + +- A DNS zone hosted on ZCP +- A, CNAME, TXT, and MX records resolving on the public internet +- The domain delegated from your registrar to ZSoftly name servers + +Plan for about 20 minutes of hands-on work. Name server changes then propagate on their own. +Propagation often completes within a few hours. Allow up to 48 hours. + +:::note + +The slugs and values in this tutorial (project `default-9`, domain `example.com`, the generated zone +slug `examplecom`, and the sample IPs) are **examples**. Yours will differ. Each step shows the +command used to print the right value for your account. + +::: + +## Before You Start + +- A ZSoftly Public Cloud account. [Sign up](/public-cloud/getting-started/account-signup) first if + you do not have one. +- The `zcp` CLI installed. See the [CLI installation guide](/public-cloud/cli/installation). +- A domain you control at a registrar, with access to change its name servers. +- `dig` for verification (preinstalled on macOS and Linux, and part of `bind-utils` or `dnsutils` on + most distributions). + +:::caution + +Add your records in ZCP **before** you delegate at the registrar. Delegating first, then adding +records, leaves a window where the domain resolves to nothing. + +::: + +## Step 1: Authenticate + +Create a token in the portal under **Profile → API Tokens**, then add a CLI profile and paste it. + +```bash +zcp profile add default +zcp auth validate +``` + +DNS commands are account-level, so you do not set a region or project for them. The one exception is +`zcp dns create`, which takes `--project`. + +## Step 2: Create the Zone + +Add your domain. This creates the DNS zone ZSoftly serves. + +```bash +zcp dns create --name example.com --project default-9 +``` + +```text +FIELD VALUE +Slug examplecom +Name example.com +Status false +Created 2026-07-18T21:08:26.000000Z +``` + +Copy the **Slug**. Every record command uses it. List it again anytime: + +```bash +zcp dns list +``` + +## Step 3: Read Your Name Servers + +ZCP adds the zone's `SOA` and `NS` records for you. The `NS` record set names the two servers you +delegate to. + +```bash +zcp dns show examplecom +``` + +```text +Records (2): +NAME TYPE CONTENT TTL +example.com. SOA ns1.zsoftly.ca. hostmaster.zsoftly.ca. 2026071801 10800 3600 604800 3600 3600 +example.com. NS ns1.zsoftly.ca., ns2.zsoftly.ca. 3600 +``` + +Write down both name servers. You need them in Step 5. + +## Step 4: Add Your Records + +Create the records to route your traffic. Use `@` for the zone root and a relative name for +subdomains. + +```bash +# Point the root and www at your server +zcp dns record-create --domain examplecom --name @ --type A --content 203.0.113.10 +zcp dns record-create --domain examplecom --name www --type A --content 203.0.113.10 + +# Point an app subdomain at another host +zcp dns record-create --domain examplecom --name api --type A --content 203.0.113.20 + +# Alias blog to www +zcp dns record-create --domain examplecom --name blog --type CNAME --content www.example.com. + +# Publish an SPF policy +zcp dns record-create --domain examplecom --name @ --type TXT --content '"v=spf1 -all"' + +# Route mail (MX needs a priority) +zcp dns record-create --domain examplecom --name @ --type MX --content mail.example.com. --priority 10 +``` + +:::caution + +The `--name` is **relative** to the zone. Use `www`, not `www.example.com`. Use `@` for the root. A +full name like `www.example.com` becomes `www.example.com.example.com`. + +::: + +Confirm the zone holds what you expect: + +```bash +zcp dns show examplecom +``` + +## Step 5: Delegate at Your Registrar + +Now make ZSoftly authoritative. At the registrar where you bought the domain, replace the name +servers with the two ZSoftly values from Step 3. The exact menu differs per registrar. The +[Domains](/public-cloud/dns/domains) page has a per-registrar quick reference. + +:::note + +**Cloudflare Registrar** does not allow third-party name servers on the domain apex. If Cloudflare +Registrar holds your domain, delegate a **subdomain** instead. In the Cloudflare DNS app, add two +`NS` records for the subdomain (for example, name `dev`). Point them to `ns1.zsoftly.ca` and +`ns2.zsoftly.ca`. Then create the zone in ZCP as `dev.example.com`. See the +[Cloudflare exception](/public-cloud/dns/domains#cloudflare-exception). + +::: + +## Step 6: Verify + +Before you delegate, query a ZSoftly name server directly. It answers even while the old name +servers are still live at your registrar. + +```bash +dig A www.example.com @ns2.zsoftly.ca +short +# 203.0.113.10 +``` + +After you delegate and propagation catches up, any public resolver returns the same answer. + +```bash +dig NS example.com @1.1.1.1 +short +# ns1.zsoftly.ca. +# ns2.zsoftly.ca. + +dig A www.example.com @1.1.1.1 +short +# 203.0.113.10 +``` + +To watch global propagation, use an online checker such as +[whatsmydns.net](https://www.whatsmydns.net/) with the **NS** record type. + +## Next Steps + +- [Manage DNS with the CLI](/public-cloud/dns/cli): the full record command reference. +- [Manage DNS with the API](/public-cloud/dns/api): do the same over REST. +- [Domains](/public-cloud/dns/domains): per-registrar name server steps and the Cloudflare + exception.