Cloudflare (DNS)

Nanokit integrates with Cloudflare to provide automated DNS management and SSL termination. When using Cloudflare as your DNS provider, Nanokit can automatically synchronize your service hostnames with their corresponding public IP addresses or AWS DNS names.

Prerequisites

Before using Cloudflare with Nanokit, ensure you have:

1. Cloudflare Account: An active account with at least one domain (Zone) added.
2. API Token: A Cloudflare API Token (not the Global API Key) with the following permissions:
   • Zone - DNS - Edit
   • Zone - Zone - Read (Optional, for auto-discovery)

Configuration

To enable the Cloudflare provider, update your nanokit.yml and provide the necessary credentials.

1. nanokit.yml Setup

Specify cloudflare as your DNS provider in the infra section:

infra:
  provider: aws
  dns: cloudflare
  autoCreateDomain: false # Set to true to allow Nanokit to add missing zones

2. Authentication

Provide your Cloudflare credentials using environment variables (recommended) or the auth configuration file.

Environment Variables

Add these to your .env or project secrets:

CLOUDFLARE_API_TOKEN=your_api_token_here
CLOUDFLARE_ZONE_ID=optional_zone_id
CLOUDFLARE_ACCOUNT_ID=optional_account_id

Auth JSON (.nanokit/auth.json)

Alternatively, you can use the Nanokit auth file:

{
  "cloudflare": {
    "apiToken": "your_api_token_here",
    "zoneId": "optional_zone_id"
  }
}

How it Works

When you run nk up or nk deploy, Nanokit performs the following steps:

1. Identify Resources: Collects the public IP addresses or DNS names of your deployed services (e.g., Fargate Tasks or EC2 Instances).
2. Match Hosts: Scans your services configuration for host entries that do not end in .localhost.
3. DNS Sync:
   • If a Zone ID is provided, it immediately attempts to update records in that zone.
   • If no Zone ID is provided, it lists all zones available to your token and matches the hostname suffix (e.g., api.myapp.com matches the myapp.com zone).
4. Upsert Records: Creates or updates A or CNAME records pointing to your environment.

Troubleshooting

”No DNS provider registered”

Ensure that the cloudflare provider is correctly specified in your infra: dns field and that you have built the latest version of the CLI.

Permission Denied

Verify that your API Token has DNS Edit permissions. Global API Keys are discouraged for security reasons.

Domain Not Found

If Nanokit cannot find a matching zone in your account, ensure the domain is added to Cloudflare and that the token has access to it.