DNS record for the octavia load balancer.

s2i2s/project-setup/README.md

@@ -24,7 +24,8 @@ An OVN-based Octavia load balancer (`s2i2s-cloud-l4-load-balancer`) provides L4
 - **Provider**: `ovn` (not amphora)
 - **VIP**: 10.10.0.20, on the main private subnet
 - **Floating IP**: Yes
-- **DNS Record**: `octavia-main-lb.s2i2s.cloud.isti.cnr.it`
+- **DNS Record**: `main-lb.s2i2s.cloud.isti.cnr.it` — see [DNS](#dns) below. Renamed from
+  `octavia-main-lb`, which no longer resolves
 - **Backend**: HAProxy L7 instances (anti-affinity for HA)
 
 | Listener | Port | Protocol | Pool method | Health Check |
@@ -33,6 +34,47 @@ An OVN-based Octavia load balancer (`s2i2s-cloud-l4-load-balancer`) provides L4
 | HTTPS | 443 | TCP | SOURCE_IP_PORT | TCP connect |
 | Stats | 8880 | TCP | SOURCE_IP_PORT | TCP connect |
 
+#### DNS
+
+The load balancer floating IP is published as a single **A record**:
+
+| Record | Type | Points to |
+| --- | --- | --- |
+| `main-lb.s2i2s.cloud.isti.cnr.it.` | A | Floating IP of the Octavia load balancer |
+
+It is created by `openstack_dns_recordset_v2.main_lb_dns_recordset` in `octavia.tf`; the hostname
+comes from `local.octavia_lb_hostname` in `main.tf`, and the record is exported as the
+`main_loadbalancer_hostname` output.
+
+**Every service published through the load balancer must be a CNAME pointing at this A record** —
+never a second A record repeating the IP address. The floating IP is then written down in exactly
+one place, so a change of address (rebuild of the load balancer, migration, DR) is a single-record
+update instead of a sweep across every service.
+
+```hcl
+resource "openstack_dns_recordset_v2" "my_service" {
+  zone_id     = local.dns_zone_id
+  name        = "my-service.${local.dns_zone.name}"
+  description = "My service, published through the main load balancer"
+  ttl         = 8600
+  type        = "CNAME"
+  records     = ["main-lb.s2i2s.cloud.isti.cnr.it."]
+}
+```
+
+Notes:
+
+- Designate expects fully qualified names **with the trailing dot**, both in `name` and in
+  `records`. `local.dns_zone.name` already ends with one.
+- These CNAMEs normally live in the configuration of the service that owns them, not here. When
+  the service is defined in another workspace, read the target from this state rather than
+  hardcoding it: `data.terraform_remote_state.project_setup.outputs.main_loadbalancer_hostname`.
+- The CNAME only brings the client to the load balancer. Routing the hostname to the right backend
+  is a separate step in the HAProxy L7 configuration (SNI / `Host` header), and the backend VM must
+  carry the `traffic_from_the_main_load_balancers` security group to accept the traffic.
+- A CNAME cannot coexist with other records for the same name, so a hostname published this way
+  cannot also carry its own A record.
+
 #### Consequences of the OVN provider
 
 The OVN driver is lighter than amphora (no amphora VMs, uses the main subnet directly), but it

s2i2s/project-setup/main.tf

@@ -67,5 +67,5 @@ locals {
   # Octavia LB settings for OVN driver
   octavia_lb_name        = module.project_variables.main_octavia_lb_name
   octavia_lb_description = module.project_variables.main_octavia_lb_description
-  octavia_lb_hostname    = "octavia-main-lb"
+  octavia_lb_hostname    = "main-lb"
 }