Ever since we implemented support for configuring Cloudflare via Terraform, we’ve been steadily expanding the set of features and services you can manage via this popular open-source tool.

If you're unfamiliar with how Terraform works with Cloudflare, check out our developer docs.

We are Terraform users ourselves, and we believe in the stability and reproducibility that can be achieved by defining your infrastructure as code.

Terraform is an open-source tool that allows you to describe your infrastructure and cloud services (think virtual machines, servers, databases, network configurations, Cloudflare API resources, and more) as human-readable configurations.

Once you’ve done this, you can run the Terraform command-line tool and it will figure out the difference between your desired state and your current state, and make the API calls in the background necessary to reconcile the two.

Unlike other solutions, Terraform does not require you to run software on your hosts, and instead of spending time manually configuring machines, creating DNS records, and specifying Page Rules, you can simply run:

$ terraform apply

and the state described in your configuration files will be built for you.

Terraform is a tremendous time-saver once you have your configuration files in place, but what do you do if you’re already a Cloudflare user and you need to convert your particular setup, records, resources and rules into Terraform config files in the first place?

Today, we’re excited to share a new open-source utility to make the migration of even complex Cloudflare configurations into Terraform simple and fast.

It’s called cf-terraforming and it downloads your Cloudflare setup, meaning everything you’ve defined via the Cloudflare dashboard and API, into Terraform-compliant configuration files in a few commands.

Cf-terraforming is open-source and available on Github now. You need a working Golang installation and a Cloudflare account with some resources defined. That’s it!

Let’s first install cf-terraforming, while also pulling down all dependencies and updating them as necessary:

$ go get -u github.com/cloudflare/cf-terraforming/...

Cf-terraforming is a command line tool that you invoke with your Cloudflare credentials, some zone information and the resource type that you want to export. The output is a valid Terraform configuration file describing your resources.

To use cf-terraforming, first get your API key and Account ID from the Cloudflare dashboard. You can find your account id at the bottom right of the overview page for any zone in your account. It also has a quick link to get your API key as well. You can store your key and account ID in environment variables to make it easier to work with the tool:

export CLOUDFLARE_TOKEN=”<your-key>” 
export CLOUDFLARE_EMAIL=”<your-email>”
export CLOUDFLARE_ACCT_ID=”<your-id>” 

Cf-terraforming can create configuration files for any of the resources currently available in the official Cloudflare Terraform provider, but sometimes it’s also handy to export individual resources as needed.

Let’s say you’re migrating your Cloudflare configuration to Terraform and you want to describe your Spectrum applications. You simply call cf-terraforming with your credentials, zone, and the spectrum_application command, like so:

go run cmd/cf-terraforming/main.go --email $CLOUDFLARE_EMAIL --key $CLOUDFLARE_TOKEN --account $CLOUDFLARE_ACCT_ID spectrum_application

Cf-terraforming will contact the Cloudflare API on your behalf and define your resources in a format that Terraform understands:

resource"cloudflare_spectrum_application""1150bed3f45247b99f7db9696fffa17cbx9" {    
    protocol = "tcp/8000"    
    dns = {        
        type = "CNAME"        
        name = "example.com"    
    }    
    ip_firewall = "true"    
    tls = "off"    
    origin_direct = [ "tcp://37.241.37.138:8000", ]
}

You can redirect the output to a file and then start working with Terraform. First, ensure you are in the cf-terraforming directory, then run:

go run cmd/cf-terraforming/main.go --email $CLOUDFLARE_EMAIL --key $CLOUDFLARE_TOKEN --account $CLOUDFLARE_ACCT_ID spectrum_application > my_spectrum_applications.tf 

The same goes for Zones, DNS records, Workers scripts and routes, security policies and more.

Use the all command to download everything and convert it into Terraform config.

go run cmd/cf-terraforming/main.go --email $CLOUDFLARE_EMAIL --key $CLOUDFLARE_TOKEN --account $CLOUDFLARE_ACCT_ID all

Currently, cf-terraforming supports every resource type that you can manage via the official Cloudflare Terraform provider:

• access_application

• access_rule

• access_policy

• account_member

• custom_pages

• filter

• firewall_rule

• load_balancer

• load_balancer_pool

• load_balancer_monitor

• page_rule

• rate_limit

• record

• spectrum_application

• waf_rule

• worker_route

• worker_script

• zone

• zone_lockdown

• zone_settings_override

We’re looking for feedback and any issues you might encounter while getting up and running with cf-terraforming. Please open any issues against the GitHub repo.

Cf-terraforming is open-source, so if you want to get involved feel free to pick up an open issue or make a pull request.

We’ll continue to expand the set of Cloudflare resources that you can manage via Terraform, and that you can export via cf-terraforming. Be sure to keep and eye on the cf-terraforming repo for updates.

A recent compliance project had a requirement of detecting certain end user request data at the edge, and reacting to it both in API responses as well as visually in the dashboard. We realized that this was an excellent opportunity to dogfood Cloudflare Workers.

In this blog post, we’ll break down the problem we solved using a single worker that we shipped to multiple hosts, share the annotated source code of our worker, and share some best practices and tips and tricks we discovered along the way.

Since being deployed, our worker has served over 400 million requests for both calls to api.cloudflare.com and the www.cloudflare.com dashboard.

First, we needed to detect when a client was connecting to our services using an outdated TLS protocol. Next, we wanted to pass this information deeper into our application stack so that we could act upon it and conditionally decorate our responses with notices providing a heads up about the imminent changes.

Our Edge team was quick to create a patch to capture TLS connection information for every incoming request, but how would we propagate it to our application layer where it could be acted upon?

The Workers team made a modification to the core platform to ingest the TLS protocol version data sent from the edge, making it available in the workers environment as a property of the cf object available to the worker Javascript context (You can now use this property in your own workers).

With our workers able to inspect the TLS protocol versions of requests, we needed only to append a custom HTTP header containing this information before forwarding them into our application layer.

Our APIs use this data to add deprecation warnings to responses, and our UI uses it to display banners explaining the upcoming changes.

Let's now take a look at the source code for our worker.

/**
 * Cloudflare workers implement the service worker spec
 * See: https://developers.cloudflare.com/workers/about/ for an intro
 *
 * Binding an event handler to the fetch event allows your worker to intercept a request for your zone
 */
addEventListener('fetch', event => {
    /**
     * In the event of an uncaught exception, fail open as if the  worker did not exist
     * If you're not sure what you're doing, it's recommended you include this call
     * as the very first thing your worker does in its fetch event listener
     *
     * If you do not include this call, but your worker encounters an uncaught exception
     * while processing your request, your user will see an edge-level error page
     * instead of a response from your site, app or API
     *
     * Read on below for more info on deciding whether to
     * fail open or fail closed in your workers
     */
    event.passThroughOnException()
    //This allows you to return your own Response object from your worker
    event.respondWith(requestWithTLSHeader(event))
})
/**
 * Calls out to our Sentry account to create an exception event
 *
 * Note that for this to work properly with the event.waitUntil() call in the
 * exception block within requestWithTLSHeader, this function must return a promise
 *
 * @returns {Promise}
 */
function promisifiedSentryLog(ex) {
    //Change these constants to your own Sentry values if you want to use this script
    const sentryProjectId = '<Replace-Me-With-Your-Sentry-Project-Id>'
    const sentryAPIKey = '<Replace-Me-With-Your-Sentry-API-Key>'
    const sentrySecretKey = '<Replace-Me-With-Your-Sentry-Secret-Key>'
    //Manually configure our call to Sentry
    let b = {
        project: sentryProjectId,
        logger: "javascript",
        platform: "javascript",
        exception: {
            values: [
                { type: "Error", value: ((ex) && (ex.message)) ? ex.message : 'Unknown' }
            ]
        }
    }
    let sentryUrl = `https://sentry.io/api/${sentryProjectId}/store/?sentry_version=7&sentry_client=raven-js%2F3.24.2&sentry_key=${sentryAPIKey}&sentry_secret=${sentrySecretKey}`
    /**
     * Fire off a POST request to Sentry's API, which includes our project
     * and credentials information, plus arbitrary logging data
     *
     * In this case, we're passing along the exception message,
     * but you could use this pattern to log anything you want
     *
     * Keep in mind that fetch returns a promise,
     * which is what makes this function compatible with event.waitUntil
     */
    return fetch(sentryUrl, { body: JSON.stringify(b), method: 'POST' })
}
/**
 * Creates a new request for the backend that mirrors the incoming request,
 * with the addition of a new header that specifies which TLS version was used
 * in the connection to the edge
 *
 * This is the main function that contains the core logic for this worker
 *
 * It works by checking for the presence of a property 'tlsVersion' that is being forwarded
 * from the edge into the workers platform so that worker scripts can access it
 *
 * The worker starts with a default TLS header. If the tlsVersion property,
 * which represents the version of the TLS protocol the client connected with,
 * is present, the worker sets its local tlsVersion variable to the value of this property
 *
 * It then wraps the incoming request headers in a new headers object,
 * which enables us to append our own custom X-Client-SSL-Protocol header
 *
 * The worker then forwards the original request
 * (overriding the headers with our new headers object) to the origin
 *
 * Now, our application layer can act upon this information
 * to show modals and include deprecation warnings as necessary
 *
 * @returns {Promise}
 */
async function requestWithTLSHeader(event) {
    //It's strongly recommended that you wrap your core worker logic in a try / catch block
    try {
        let tlsVersion = "NONE"
        //Create a new Headers object that includes the original request's headers
        let reqHeaders = new Headers(request.headers)
        if (event && event.request && event.request.cf && event.request.cf.tlsVersion && typeof event.request.cf.tlsVersion === "string" && event.request.cf.tlsVersion !== "") {
            tlsVersion = event.request.cf.tlsVersion
        }
        //Add our new header
        reqHeaders.append('X-Client-SSL-Protocol', tlsVersion)
        //Extend the original request's headers with our own, but otherwise fetch the original request
        return await fetch(event.request, { headers: reqHeaders })
    } catch (ex) {
        /**
         * Signal the runtime that it should wait until the promise resolves
         *
         * This avoids race conditions where the runtime stops execution before
         * our async Sentry task completes
         *
         * If you do not do this, the passthrough subrequest will race
         * your pending asychronous request to Sentry, and you will
         * miss many events / fail to capture them correctly
         */
        event.waitUntil(promisifiedSentryLog(ex))
        /**
         * Intentionally throw the exception in order to trigger the pass-through
         * behavior defined by event.passThroughOnException()
         *
         * This means that our worker will fail open - and not block requests
         * to our backend services due to unexpected exceptions
         */
        throw ex
    }
}

The above Workers script was updated on 5/17/18 to correct how the Sentry's API works.

We decided to use Sentry to capture events we sent from our worker, but you could follow this same pattern with any similar service.

The critical piece to making this work is understanding that you must signal the Cloudflare worker runtime that it needs to wait upon your asynchronous logging subrequest (and not cancel it).

You do this by:

1. Ensuring that your logging function returns a promise (what your promise resolves to does not matter)

2. Wrapping your call to your logging function in event.waitUntil as we have done above

This pattern fixes a common race condition: if you don't leverage event.waitUntil, the runtime will race the passthrough subrequest and your logging subrequest.

If the passthrough subrequest completes significantly faster than your logging subrequest, the logging request could be cancelled. In practice, you'll notice this issue manifesting as dropped logging messages - whether or not a given exception will be logged properly becomes a roll of the dice on every request.

For additional insight, check out our official guide to debugging Cloudflare workers.

A key consideration when designing your worker is failure behavior. Depending on what your particular worker is accomplishing, you either want it to fail open or failed closed. Failing open means that if something goes horribly wrong, the original request will be passed through as if your worker did not exist, while failing closed means that a request that raises an exception in your worker will not be processed further.

If you are editing metadata, collecting metrics, or adding new non-critical HTTP headers, to name a few examples, you probably don't want an unhandled exception in your worker to prevent the request from being serviced.

In this case, you can leverage event.passThroughOnException as we have above, and it's recommended that you call this method in the first line of your fetch event handler. This sets a flag that the Cloudflare worker request handler can inspect in case of an exception to determine the desired passthrough behavior.

On the other hand, if you're employing your worker in a security-centric role, tasking it with blocking malicious requests from nefarious bots, or blocking access to sensitive endpoints when valid security credentials are not supplied, you may want your worker to fail closed. This is the default behavior, and it will prevent requests that raise exceptions in your worker from being processed further.

Our services are in the critical path for our customers, yet our use case was to conditionally add a new HTTP header, so we knew we wanted to fail open.

Now that you've done the work to get data from your worker logged to Sentry, you can leverage Sentry's PagerDuty integration to configure alerts for exceptions that occur in your workers.

This will increase your team's confidence in your worker-based solutions, and alert you immediately to any new issues that occur in production.

You can find additional worker recipes and examples in our official documentation.

Have you written a worker that you'd like to share? Send it to us and you might get featured on our blog or added to our Cloudflare worker recipe collection with a credit.