Cross-Cloud DNS Configuration

When Fuzzball deploys a cluster, it requests TLS certificates from Let’s Encrypt and validates them with DNS-01 challenges. By default the challenge records are created in the same cloud that runs the cluster. The --dns-provider flag on the deploy and update commands tells cert-manager to create the challenge records in a different DNS provider instead. This is useful when:

• Your organization’s primary DNS infrastructure is in a different cloud
• You want to consolidate DNS management across multi-cloud deployments
• You’re using a third-party DNS provider like Cloudflare

The cluster’s own DNS records are not affected: an OCI deployment always creates its service records in an OCI DNS zone. The --dns-provider setting only controls where certificate validation records are written.

Support for Oracle Cloud Infrastructure (OCI) within Fuzzball is in preview status. This page shows OCI examples; the same --dns-provider flag family is available on the fuzzball cluster aws, fuzzball cluster gcp, and fuzzball cluster azure deploy and update commands.

• OCI DNS (ocidns) — Oracle Cloud Infrastructure DNS zones (the default for OCI deployments)
• AWS Route53 (route53) — Amazon Route53 hosted zones
• Cloudflare (cloudflare) — Cloudflare DNS zones
• Azure DNS (azuredns) — Microsoft Azure DNS zones

On the aws, gcp, and azure cluster commands the provider list is route53, cloudflare, clouddns (Google Cloud DNS), and azuredns; ocidns is specific to OCI deployments.

Before deploying with an external DNS provider:

1. Create the DNS zone in your chosen provider

2. Delegate the domain by updating NS records at your domain registrar (see the Requirements guide for delegation details)

3. Verify delegation using dig or nslookup:

   $ dig NS example.com

4. Obtain credentials with appropriate permissions (see the provider sections below)

Secret credentials should be supplied via environment variables rather than flags, because flag values are visible in shell history and process listings:

• FUZZBALL_DNS_ROUTE53_SECRET_ACCESS_KEY — AWS Route53 secret access key
• FUZZBALL_DNS_CLOUDFLARE_API_TOKEN — Cloudflare API token
• FUZZBALL_DNS_AZUREDNS_CLIENT_SECRET — Azure service principal client secret

When you deploy to OCI without --dns-provider, certificate validation uses OCI DNS in the deployment compartment. The cluster’s DNS zone is created automatically and is named after --domain; the --dns-zone-name and --dns-zone-compartment flags override the zone name and its compartment.

To point certificate validation at a specific OCI DNS zone, set the provider explicitly:

$ fuzzball cluster oci deploy \
  --dns-provider ocidns \
  --dns-ocidns-zone-name example.com \
  --dns-ocidns-compartment ocid1.compartment.oc1...

Both ocidns flags are optional: the zone name defaults to --dns-zone-name (then --domain), and the compartment defaults to the deployment compartment.

$ export FUZZBALL_DNS_ROUTE53_SECRET_ACCESS_KEY=<secret-access-key>

$ fuzzball cluster oci deploy \
  --dns-provider route53 \
  --dns-route53-hosted-zone-id <hosted-zone-id> \
  --dns-route53-access-key-id AKIAIOSFODNN7EXAMPLE \
  --dns-route53-region us-east-1

Flags:

• --dns-route53-hosted-zone-id — The Route53 hosted zone ID
• --dns-route53-region — AWS region for the Route53 zone
• Authentication, one of:
  • --dns-route53-role-arn — IAM role ARN for Route53 access (for IRSA)
  • --dns-route53-access-key-id together with the secret access key (prefer the FUZZBALL_DNS_ROUTE53_SECRET_ACCESS_KEY environment variable over the --dns-route53-secret-access-key flag)

Required IAM permissions:

The AWS credentials must have permissions to manage Route53 records:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "route53:ChangeResourceRecordSets",
        "route53:ListResourceRecordSets",
        "route53:GetChange"
      ],
      "Resource": [
        "arn:aws:route53:::hostedzone/Z1234567890ABC",
        "arn:aws:route53:::change/*"
      ]
    }
  ]
}

$ export FUZZBALL_DNS_CLOUDFLARE_API_TOKEN=<api-token>

$ fuzzball cluster oci deploy \
  --dns-provider cloudflare

Flags:

• --dns-cloudflare-api-token — Cloudflare API token (required; prefer the FUZZBALL_DNS_CLOUDFLARE_API_TOKEN environment variable)
• --dns-cloudflare-email — Cloudflare account email (optional)

The zone that challenge records are written to is determined by the API token’s scope, not by a flag.

API token permissions:

Create a Cloudflare API token with the following permissions:

• Zone / DNS / Edit — For the specific zone
• Zone / Zone / Read — For the specific zone

To create the token:

1. Go to the Cloudflare dashboard → My Profile → API Tokens
2. Click Create Token
3. Use the Edit zone DNS template
4. Set Zone Resources to include your specific zone
5. Create the token and save it securely

$ export FUZZBALL_DNS_AZUREDNS_CLIENT_SECRET=<client-secret>

$ fuzzball cluster oci deploy \
  --dns-provider azuredns \
  --dns-azuredns-subscription <subscription-id> \
  --dns-azuredns-resource-group <resource-group> \
  --dns-azuredns-zone-name example.com \
  --dns-azuredns-tenant-id <tenant-id> \
  --dns-azuredns-client-id <client-id>

Flags:

• --dns-azuredns-subscription — Azure subscription ID (required)
• --dns-azuredns-resource-group — Azure resource group containing the DNS zone (required)
• --dns-azuredns-zone-name — The Azure DNS zone name
• Authentication, one of:
  • Service principal: --dns-azuredns-tenant-id, --dns-azuredns-client-id, and a client secret (prefer the FUZZBALL_DNS_AZUREDNS_CLIENT_SECRET environment variable over the --dns-azuredns-client-secret flag)
  • --dns-azuredns-use-managed-identity — Use an Azure managed identity instead of a service principal

Service principal permissions:

The Azure service principal must have the DNS Zone Contributor role on the DNS zone resource group:

$ az role assignment create \
  --assignee <client-id> \
  --role "DNS Zone Contributor" \
  --resource-group <resource-group>

You can change the DNS provider for an existing deployment with the update command:

$ export FUZZBALL_DNS_CLOUDFLARE_API_TOKEN=<api-token>

$ fuzzball cluster oci update \
  --deployment-name my-cluster \
  --dns-provider cloudflare

Changing the DNS provider changes where Let’s Encrypt challenge records are created. The cluster’s DNS records remain in its OCI DNS zone.

• fuzzball cluster oci destroy --deployment-name my-cluster removes the resources the deployment owns, including its OCI DNS zone and records.

• fuzzball cluster oci cleanup removes leftover OCI resources by tag; pass --skip-dns to preserve OCI DNS zones and records:

  $ fuzzball cluster oci cleanup --name-prefix my-cluster --skip-dns

• External DNS providers only ever hold transient Let’s Encrypt challenge records, which cert-manager removes after certificate issuance. Teardown does not contact external DNS providers; if a challenge record is left behind, remove it manually in the provider’s console.

• Verify the credentials have the required permissions in the DNS provider
• Check that the DNS zone exists and is active
• Review deployment logs for DNS provider errors

• Ensure DNS records are publicly resolvable before Let’s Encrypt validation
• Check that --lets-encrypt-email is valid (it defaults to --keycloak-owner-email)
• Allow 5-10 minutes for DNS propagation after deployment