Skip to main content

GETTING STARTED WITH CLOUDFLARE DNS IN SWAMP

In this tutorial, we will add Cloudflare support to a Swamp repository and store a Cloudflare API token in a vault. Then we will write the vault reference that a Cloudflare DNS behavior uses to read that token.

What we will build

We will pull the @webframp/cloudflare extension into a repository and create a Cloudflare API token that can read and write DNS records. We will store the token in a vault named cloudflare and then write the global arguments a DNS behavior for one zone uses. When we finish, the repository has the Cloudflare behavior types installed. The token is stored encrypted and is never written in plain text.

Prerequisites

  • Swamp installed (see Install Swamp)
  • Signed in with swamp auth login (see Swamp Account Requirement)
  • A terminal open in a repository created with swamp repo init
  • A Cloudflare account with at least one zone

Pull the Cloudflare extension

First, we pull the extension that provides the Cloudflare behavior types:

swamp extension pull @webframp/cloudflare

You will see output like:

INF extension·pull: Pulling "@webframp/cloudflare"@"2026.10.14.1"
INF extension·pull: Identity verified: "@webframp/cloudflare"@"2026.10.14.1"
INF extension·pull: Pulled "@webframp/cloudflare"@"2026.10.14.1"
INF extension·pull: Extracted 14 files:

The repository now has five new behavior types: @webframp/cloudflare/zone, @webframp/cloudflare/dns, @webframp/cloudflare/waf, @webframp/cloudflare/worker and @webframp/cloudflare/cache. In this tutorial we prepare to use the DNS type.

Create a Cloudflare API token

Now we create the token in the Cloudflare dashboard. Under the profile's API Tokens page, we create a token with DNS read and write permission for one zone and copy its value.

While we are in the dashboard, we open that zone's overview page and copy its Zone ID. In this tutorial the zone ID is 023e105f4ecef8ad9ca31a8372d0c353.

Store the token in a vault

Next, we store the token in a vault named cloudflare under the key CLOUDFLARE_API_TOKEN. The Storing Secrets tutorial stores api-token in the same way. The value is encrypted at rest. swamp vault inspect shows its size and metadata, but never the value.

Reference the token from a DNS behavior

The @webframp/cloudflare/dns type requires two global arguments: apiToken and zoneId. A DNS behavior for our zone sets them like this:

globalArguments:
  apiToken: "${{ vault.get('cloudflare', 'CLOUDFLARE_API_TOKEN') }}"
  zoneId: "023e105f4ecef8ad9ca31a8372d0c353"

Notice that apiToken holds a vault.get() expression, not the token. Swamp resolves the expression when the behavior runs and redacts the value from logs and data.

What we built

We pulled the @webframp/cloudflare extension into a repository and created a Cloudflare API token with DNS permission for one zone. We stored the token in the cloudflare vault and wrote the global arguments that a DNS behavior uses to read the token from the vault and target that zone.