DNS and TLS outside Azure
Publish platform hostnames and obtain the gateway certificate on RFC2136 servers, Amazon Route 53 or DNS and certificates you manage yourself.
BullSequana AI serves every platform host, such as the Portal, identity and the BSQAI API, through one shared gateway under one base domain. Each host needs a DNS record that points at the gateway and a certificate the gateway serves. This playbook is for the platform engineer who deploys the platform and the DNS or PKI owner who provides the zone, keys or certificates.
All platform hosts sit one level below the base domain, for example portal.<base-domain> and iam.<base-domain>. One wildcard record and one wildcard certificate for *.<base-domain> cover them.
Supported DNS providers
BullSequana AI automates DNS records and certificates on these providers. ExternalDNS publishes the records and cert-manager obtains a Let's Encrypt wildcard certificate through a DNS-01 challenge in the same zone.
| Provider | DNS_PROVIDER | Typical DNS servers |
|---|---|---|
| Azure DNS | azure (default) | Azure DNS zones |
| RFC2136 dynamic updates | rfc2136 | BIND 9, PowerDNS, Knot DNS, Infoblox and other servers that accept TSIG-signed updates and zone transfers |
| Amazon Route 53 | route53 | Route 53 public hosted zones |
Every other provider uses the self-managed path in section 4, or a subdomain delegated to a supported provider in section 3. This includes Cloudflare, OVHcloud, Google Cloud DNS, and Microsoft DNS, which accepts only Kerberos-signed (GSS-TSIG) updates.
Choose a path
| Path | Use it when | The platform manages | You manage |
|---|---|---|---|
| Automated on a supported provider | The base domain sits in a zone on a supported provider | Records, certificate issuance and renewal | The zone and the provider credentials |
| Delegated subdomain | The organisation's DNS is unsupported, but a subdomain can be delegated to Azure DNS or Route 53 | Records, certificate issuance and renewal in the subdomain | The delegation and the provider account |
| Self-managed | No supported provider applies, or the certificate must come from the organisation's PKI | Nothing for DNS | The wildcard record, the certificate, its renewal and expiry monitoring |
Let's Encrypt validates the DNS-01 challenge from the internet, so the automated paths need a zone that public resolvers can reach. A zone that only internal resolvers can see uses the self-managed path.
1. Automate DNS on an RFC2136 server
Prepare the zone
The DNS owner provides:
- a zone that contains the base domain, for example
ai.example.comfor the base domainplatform.ai.example.com - a TSIG key, algorithm
hmac-sha256by default - update rights for that key on the zone, for
A,TXTandCNAMErecords - zone transfer (AXFR) rights for that key, because ExternalDNS reads the zone's records through a transfer
- the address of the primary server, reachable from the cluster on port 53 over UDP and TCP
For BIND 9, generate the key with tsig-keygen -a hmac-sha256 bsqai and grant it the zone:
key "bsqai" { algorithm hmac-sha256; secret "<base64 secret>"; };
zone "ai.example.com" {
type primary;
file "/var/lib/bind/ai.example.com.zone";
update-policy { grant bsqai zonesub ANY; };
allow-transfer { key bsqai; };
};Configure the platform
Set the provider in platform.env:
COMMON_BASE_DOMAIN=platform.ai.example.com
DNS_PROVIDER=rfc2136
RFC2136_HOST=192.0.2.53
RFC2136_ZONE=ai.example.com
RFC2136_TSIG_KEY_NAME=bsqai
RFC2136_TSIG_SECRET=<base64 secret>| Variable | Default | Description |
|---|---|---|
RFC2136_HOST | (empty) | Address of the primary server. Required |
RFC2136_PORT | 53 | DNS port of the primary server |
RFC2136_ZONE | (empty) | Zone that contains COMMON_BASE_DOMAIN. Required |
RFC2136_TSIG_KEY_NAME | (empty) | Name of the TSIG key. Required |
RFC2136_TSIG_ALGORITHM | hmac-sha256 | hmac-md5, hmac-sha1, hmac-sha256 or hmac-sha512 |
RFC2136_TSIG_SECRET | (empty) | Base64 secret of the key, as in the server's key definition. Required |
The render fails and names the missing setting when a required value is empty, when the algorithm is not supported, or when COMMON_BASE_DOMAIN is not inside RFC2136_ZONE. The platform seals the TSIG secret like its other secrets.
ExternalDNS and the cert-manager controller reach the server through the egress CIDRs in NETWORK_POLICY_EXTERNAL_EGRESS_CIDRS. When the site narrows them, include the server's address.
2. Automate DNS on Amazon Route 53
Prepare the hosted zone
The AWS account owner provides a public hosted zone that contains the base domain, and an IAM user with an access key and this policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["route53:ChangeResourceRecordSets", "route53:ListResourceRecordSets"],
"Resource": "arn:aws:route53:::hostedzone/<hosted zone ID>"
},
{
"Effect": "Allow",
"Action": ["route53:GetChange"],
"Resource": "arn:aws:route53:::change/*"
},
{
"Effect": "Allow",
"Action": ["route53:ListHostedZones", "route53:ListHostedZonesByName"],
"Resource": "*"
}
]
}Configure the platform
COMMON_BASE_DOMAIN=platform.aws.example.com
DNS_PROVIDER=route53
ROUTE53_REGION=eu-west-1
ROUTE53_HOSTED_ZONE_ID=<hosted zone ID>
ROUTE53_ZONE=aws.example.com
ROUTE53_ACCESS_KEY_ID=<access key ID>
ROUTE53_SECRET_ACCESS_KEY=<secret access key>All five Route 53 settings are required. The render fails and names any that is empty, or when COMMON_BASE_DOMAIN is not inside ROUTE53_ZONE. ExternalDNS writes only to the hosted zone that ROUTE53_HOSTED_ZONE_ID names.
Verify an automated provider
After Argo CD has synced the cert-manager, external-dns and gateway-api applications:
-
Confirm that the wildcard certificate is ready:
kubectl -n cert-manager get certificate acme-crt-secret-wildcard -
Confirm that the wildcard record resolves to the gateway address:
kubectl -n gateway-api get gateway gateway-api dig +short portal.<base-domain> -
Confirm that a platform host serves a trusted certificate:
curl -sS -o /dev/null -w '%{http_code} %{ssl_verify_result}\n' https://portal.<base-domain>/A
ssl_verify_resultof0means the client trusts the certificate.
cert-manager renews the certificate on the same provider before it expires. A provider failure shows up in standard status and logs, not as a missing record:
- wrong or missing certificate credentials:
kubectl -n cert-manager get challengesshows the provider's error, for exampleDNS update failed: dns: bad authentication, and the certificate stays not ready - wrong or missing record credentials: the
external-dnspod logs the provider's error, for exampleAXFR error: dns: bad authentication
3. Delegate a subdomain to a supported provider
An organisation whose DNS is not supported can keep full automation by delegating a subdomain to Azure DNS or Route 53:
- Create a zone for the subdomain, for example
ai.example.com, in Azure DNS or Route 53. - In the organisation's parent zone, add
NSrecords for the subdomain that point at the name servers of the new zone. - Configure the platform for that provider, with the base domain inside the subdomain, as in section 2 or the Azure environment profile.
The parent zone owner manages only the delegation. The platform manages every record below it.
4. Manage DNS and TLS yourself
This path needs no DNS provider credentials and no change to the platform. You create the wildcard record and supply the certificate.
Configure the platform
COMMON_BASE_DOMAIN=platform.example.com
DNS_PROVIDER=none
CUSTOM_TLS_ENABLED=true
CUSTOM_TLS_CRT=<base64 PEM wildcard certificate>
CUSTOM_TLS_KEY=<base64 PEM private key>
CUSTOM_TLS_CA_CRT=<base64 PEM CA certificate>| Setting | Effect |
|---|---|
DNS_PROVIDER=none | Leaves ExternalDNS out of the platform and requests no Let's Encrypt certificate. AZURE_ENABLED=false has the same effect while DNS_PROVIDER keeps its default |
CUSTOM_TLS_ENABLED=true | The gateway serves the supplied certificate. The render fails when one of the three values is empty |
CUSTOM_TLS_CRT | Wildcard certificate for *.<base-domain>, with its intermediate certificates, PEM, base64-encoded. With agent sandbox previews, it also names *.<preview_host_prefix>.<base-domain> |
CUSTOM_TLS_KEY | Private key of that certificate, PEM, base64-encoded |
CUSTOM_TLS_CA_CRT | CA certificate that signed it, PEM, base64-encoded. The platform adds it to the trust bundle its own services use |
Without CUSTOM_TLS_ENABLED, the platform's self-signed CA issues the wildcard certificate, with the preview name when agent sandbox previews are on, and the render warns. Only clients that trust the platform CA accept that certificate, so use it for development only.
If the cluster's DNS service is not kube-dns in kube-system with the domain cluster.local, also set COMMON_INTERNAL_RESOLVER, COMMON_INTERNAL_RESOLVER_NAMESPACE and COMMON_CLUSTER_DOMAIN. When the DNS pods carry a label other than k8s-app=kube-dns, for example k8s-app=coredns, set NETWORK_POLICY_DNS_POD_LABEL_VALUE, so the platform's network policies allow DNS.
Create the record
-
Reserve an address for the gateway's load balancer before the deployment, where the load balancer allows it. For example, give MetalLB a pool with that address or create a static public IP with the cloud provider. A stable address keeps the record valid when the gateway is recreated.
-
After Argo CD has synced the
gateway-apiapplication, read the address the gateway received:kubectl -n gateway-api get gateway gateway-api -
Create one record for
*.<base-domain>that points at that address: anArecord for an IP address or aCNAMErecord for a load balancer hostname. -
With agent sandbox previews on (
LLM_BACKEND_SANDBOX_PREVIEW_ENABLED=true), create a second record for*.<preview_host_prefix>.<base-domain>,*.sandbox.<base-domain>by default, that points at the same address. A wildcard record matches one DNS label, so*.<base-domain>does not answer for a preview host such as<chat-id>.sandbox.<base-domain>. See Prepare app preview hosts.
Verify the result
dig +short portal.<base-domain>
curl -sS -o /dev/null -w '%{http_code} %{ssl_verify_result}\n' https://portal.<base-domain>/
curl -sS -o /dev/null -w '%{http_code} %{ssl_verify_result}\n' https://iam.<base-domain>/With agent sandbox previews on, also run dig +short test.<preview_host_prefix>.<base-domain>.
Each host resolves to the gateway address, and ssl_verify_result is 0 on a client that trusts the CA. Distribute the CA certificate to every browser and client that reaches the platform when it comes from a private PKI.
What you own
| Item | Responsibility |
|---|---|
| Wildcard record | Create it, and update it when the gateway address changes |
| Certificate | Renew it before expiry, update CUSTOM_TLS_CRT and CUSTOM_TLS_KEY, render and push the manifests |
| Expiry monitoring | Alert well before the certificate's notAfter date |
| CA trust | Distribute the CA certificate to clients outside the platform |
Check the expiry date of the served certificate with:
echo | openssl s_client -connect portal.<base-domain>:443 -servername portal.<base-domain> 2>/dev/null | openssl x509 -noout -enddate