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.

Agentic Friendly

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.

ProviderDNS_PROVIDERTypical DNS servers
Azure DNSazure (default)Azure DNS zones
RFC2136 dynamic updatesrfc2136BIND 9, PowerDNS, Knot DNS, Infoblox and other servers that accept TSIG-signed updates and zone transfers
Amazon Route 53route53Route 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

PathUse it whenThe platform managesYou manage
Automated on a supported providerThe base domain sits in a zone on a supported providerRecords, certificate issuance and renewalThe zone and the provider credentials
Delegated subdomainThe organisation's DNS is unsupported, but a subdomain can be delegated to Azure DNS or Route 53Records, certificate issuance and renewal in the subdomainThe delegation and the provider account
Self-managedNo supported provider applies, or the certificate must come from the organisation's PKINothing for DNSThe 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.com for the base domain platform.ai.example.com
  • a TSIG key, algorithm hmac-sha256 by default
  • update rights for that key on the zone, for A, TXT and CNAME records
  • 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>
VariableDefaultDescription
RFC2136_HOST(empty)Address of the primary server. Required
RFC2136_PORT53DNS 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_ALGORITHMhmac-sha256hmac-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:

  1. Confirm that the wildcard certificate is ready:

    kubectl -n cert-manager get certificate acme-crt-secret-wildcard
  2. Confirm that the wildcard record resolves to the gateway address:

    kubectl -n gateway-api get gateway gateway-api
    dig +short portal.<base-domain>
  3. 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_result of 0 means 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 challenges shows the provider's error, for example DNS update failed: dns: bad authentication, and the certificate stays not ready
  • wrong or missing record credentials: the external-dns pod logs the provider's error, for example AXFR 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:

  1. Create a zone for the subdomain, for example ai.example.com, in Azure DNS or Route 53.
  2. In the organisation's parent zone, add NS records for the subdomain that point at the name servers of the new zone.
  3. 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>
SettingEffect
DNS_PROVIDER=noneLeaves 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=trueThe gateway serves the supplied certificate. The render fails when one of the three values is empty
CUSTOM_TLS_CRTWildcard 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_KEYPrivate key of that certificate, PEM, base64-encoded
CUSTOM_TLS_CA_CRTCA 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

  1. 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.

  2. After Argo CD has synced the gateway-api application, read the address the gateway received:

    kubectl -n gateway-api get gateway gateway-api
  3. Create one record for *.<base-domain> that points at that address: an A record for an IP address or a CNAME record for a load balancer hostname.

  4. 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

ItemResponsibility
Wildcard recordCreate it, and update it when the gateway address changes
CertificateRenew it before expiry, update CUSTOM_TLS_CRT and CUSTOM_TLS_KEY, render and push the manifests
Expiry monitoringAlert well before the certificate's notAfter date
CA trustDistribute 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

On this page