github.com/StackExchange/dnscontrol/v4@v4.11.0/documentation/provider/cloudflareapi.md (about)

     1  This is the provider for [Cloudflare](https://www.cloudflare.com/).
     2  
     3  ## Important notes
     4  
     5  * SPF records are silently converted to RecordType `TXT` as Cloudflare API fails otherwise. See [StackExchange/dnscontrol#446](https://github.com/StackExchange/dnscontrol/issues/446).
     6  * This provider currently fails if there are more than 1000 corrections on one domain. This only affects "push". This usually when moving a domain with many records to Cloudflare.  Try commenting out most records, then uncomment groups of 999. Typical updates are less than 1000 corrections and will not trigger this bug. See [StackExchange/dnscontrol#1440](https://github.com/StackExchange/dnscontrol/issues/1440).
     7  
     8  ## Configuration
     9  
    10  To use this provider, add an entry to `creds.json` with `TYPE` set to `CLOUDFLAREAPI`.
    11  
    12  Optional fields include:
    13  
    14  * `accountid` and `apitoken`: Authentication information
    15  * `apikey` and `apiuser`: Old-style authentication
    16  
    17  Example:
    18  
    19  {% code title="creds.json" %}
    20  ```json
    21  {
    22    "cloudflare": {
    23      "TYPE": "CLOUDFLAREAPI",
    24      "accountid": "your-cloudflare-account-id",
    25      "apitoken": "your-cloudflare-api-token"
    26    }
    27  }
    28  ```
    29  {% endcode %}
    30  
    31  # Authentication
    32  
    33  The Cloudflare API supports two different authentication methods.
    34  
    35  NOTE: You can not mix the two authentication methods.  If you try, DNSControl will report an error.
    36  
    37  ## API Tokens (recommended)
    38  
    39  The recommended (newer) method is to
    40  provide a [Cloudflare API token](https://dash.cloudflare.com/profile/api-tokens).
    41  
    42  This method is enabled by setting the `apitoken` value in `creds.json`:
    43  
    44  {% code title="creds.json" %}
    45  ```json
    46  {
    47    "cloudflare": {
    48      "TYPE": "CLOUDFLAREAPI",
    49      "accountid": "your-cloudflare-account-id",
    50      "apitoken": "your-cloudflare-api-token"
    51    }
    52  }
    53  ```
    54  {% endcode %}
    55  
    56  * `accountid` is found in the Cloudflare portal ("Account ID") on any "Website" page.  Click on any site and you'll see the "Account ID" on the lower right side of the page.
    57  * `apitoken` is something you must create. See [Cloudflare's documentation](https://support.cloudflare.com/hc/en-us/articles/200167836-Managing-API-Tokens-and-Keys) for instructions on how to generate and configure permissions on API tokens.  (Spoiler alert: [link](https://dash.cloudflare.com/profile/api-tokens). The token must be granted rights (authorization to do certain tasks) at a very granular level.
    58  
    59  DNSControl requires the token to have the following permissions:
    60  
    61  * Add: Read zones (`Zone → Zone → Read`)
    62  * Add: Edit DNS records (`Zone → DNS → Edit`)
    63  * Add: Enable SSL controls (`Zone → SSL and Certificates → Edit`)
    64  * Editing Page Rules?
    65    * Add: Edit Page Rules (`Zone → Page Rules → Edit`)
    66  * Managing Cloudflare Workers? (if `manage_workers`: set to `true` or `CF_WORKER_ROUTE()` is in use.)
    67    * Add: Edit Worker Scripts (`Account → Workers Scripts → Edit`)
    68    * Add: Edit Worker Scripts (`Zone → Workers Routes → Edit`)
    69  
    70  ![Example permissions configuration](../assets/providers/cloudflareapi/example-permissions-configuration.png)
    71  
    72  ## Username+Key (not recommended)
    73  
    74  The other (older, not recommended) method is to
    75  provide your Cloudflare API username and access key.
    76  
    77  This method is not recommended because these credentials give DNSControl access to everything (think of it as "super user" for your account).
    78  
    79  This method is enabled by setting the `apikey` and `apiuser` values in `creds.json`:
    80  
    81  {% code title="creds.json" %}
    82  ```json
    83  {
    84    "cloudflare": {
    85      "TYPE": "CLOUDFLAREAPI",
    86      "accountid": "your-cloudflare-account-id",
    87      "apikey": "your-cloudflare-api-key",
    88      "apiuser": "your-cloudflare-email-address"
    89    }
    90  }
    91  ```
    92  {% endcode %}
    93  
    94  * `accountid` (see above)
    95  * `apiuser` is the email address associated with the account.
    96  * `apikey` is found on [My Profile / API Tokens](https://dash.cloudflare.com/profile/api-tokens).
    97  
    98  ## Meta configuration
    99  
   100  This provider accepts some optional metadata:
   101  
   102  Record level metadata available:
   103     * `cloudflare_proxy` ("on", "off", or "full")
   104  
   105  Domain level metadata available:
   106     * `cloudflare_proxy_default` ("on", "off", or "full")
   107     * `cloudflare_universalssl` (unset to leave this setting unmanaged; otherwise use "on" or "off")
   108       * NOTE: If "universal SSL" isn't working, verify the API key has `Zone → SSL and Certificates → Edit` permissions. See above.
   109  
   110  Provider level metadata available:
   111     * `ip_conversions`
   112     * `manage_redirects`: set to `true` to manage page-rule based redirects
   113     * `manage_workers`: set to `true` to manage cloud workers (`CF_WORKER_ROUTE`)
   114  
   115  What does on/off/full mean?
   116  
   117     * "off" disables the Cloudflare proxy
   118     * "on" enables the Cloudflare proxy (turns on the "orange cloud")
   119     * "full" is the same as "on" but also enables Railgun.  DNSControl will prevent you from accidentally enabling "full" on a CNAME that points to an A record that is set to "off", as this is generally not desired.
   120  
   121  You can also set the default proxy mode using `DEFAULTS()` function. For example:
   122  
   123  {% code title="dnsconfig.js" %}
   124  ```javascript
   125  DEFAULTS(
   126    CF_PROXY_DEFAULT_OFF // turn proxy off when not specified otherwise
   127  );
   128  ```
   129  {% endcode %}
   130  
   131  **Aliases:**
   132  
   133  To make configuration files more readable and less prone to errors,
   134  the following aliases are *pre-defined*:
   135  
   136  {% code title="dnsconfig.js" %}
   137  ```javascript
   138  // Meta settings for individual records.
   139  var CF_PROXY_OFF = {"cloudflare_proxy": "off"};     // Proxy disabled.
   140  var CF_PROXY_ON = {"cloudflare_proxy": "on"};       // Proxy enabled.
   141  var CF_PROXY_FULL = {"cloudflare_proxy": "full"};   // Proxy+Railgun enabled.
   142  // Per-domain meta settings:
   143  // Proxy default off for entire domain (the default):
   144  var CF_PROXY_DEFAULT_OFF = {"cloudflare_proxy_default": "off"};
   145  // Proxy default on for entire domain:
   146  var CF_PROXY_DEFAULT_ON = {"cloudflare_proxy_default": "on"};
   147  // UniversalSSL off for entire domain:
   148  var CF_UNIVERSALSSL_OFF = { cloudflare_universalssl: "off" };
   149  // UniversalSSL on for entire domain:
   150  var CF_UNIVERSALSSL_ON = { cloudflare_universalssl: "on" };
   151  ```
   152  {% endcode %}
   153  
   154  The following example shows how to set meta variables with and without aliases:
   155  
   156  {% code title="dnsconfig.js" %}
   157  ```javascript
   158  var REG_NONE = NewRegistrar("none");
   159  var DSP_CLOUDFLARE = NewDnsProvider("cloudflare");
   160  
   161  D("example.com", REG_NONE, DnsProvider(DSP_CLOUDFLARE),
   162      A("www1","1.2.3.11", CF_PROXY_ON),        // turn proxy ON.
   163      A("www2","1.2.3.12", CF_PROXY_OFF),       // default is OFF, this is a no-op.
   164      A("www3","1.2.3.13", {"cloudflare_proxy": "on"}), // Old format.
   165  END);
   166  ```
   167  {% endcode %}
   168  
   169  ## Usage
   170  An example configuration:
   171  
   172  {% code title="dnsconfig.js" %}
   173  ```javascript
   174  var REG_NONE = NewRegistrar("none");
   175  var DSP_CLOUDFLARE = NewDnsProvider("cloudflare");
   176  
   177  // Example domain where the CF proxy abides by the default (off).
   178  D("example.com", REG_NONE, DnsProvider(DSP_CLOUDFLARE),
   179      A("proxied", "1.2.3.4", CF_PROXY_ON),
   180      A("notproxied", "1.2.3.5"),
   181      A("another", "1.2.3.6", CF_PROXY_ON),
   182      ALIAS("@", "www.example.com.", CF_PROXY_ON),
   183      CNAME("myalias", "www.example.com.", CF_PROXY_ON),
   184  END);
   185  
   186  // Example domain where the CF proxy default is set to "on":
   187  D("example2.tld", REG_NONE, DnsProvider(DSP_CLOUDFLARE),
   188      CF_PROXY_DEFAULT_ON, // Enable CF proxy for all items unless otherwise noted.
   189      A("proxied", "1.2.3.4"),
   190      A("notproxied", "1.2.3.5", CF_PROXY_OFF),
   191      A("another", "1.2.3.6"),
   192      ALIAS("@", "www.example2.tld."),
   193      CNAME("myalias", "www.example2.tld."),
   194  END);
   195  ```
   196  {% endcode %}
   197  
   198  ## New domains
   199  If a domain does not exist in your Cloudflare account, DNSControl
   200  will automatically add it when `dnscontrol push` is executed.
   201  
   202  
   203  ## Redirects
   204  The Cloudflare provider can manage "Forwarding URL" Page Rules (redirects) for your domains. Simply use the `CF_REDIRECT` and `CF_TEMP_REDIRECT` functions to make redirects:
   205  
   206  {% code title="dnsconfig.js" %}
   207  ```javascript
   208  // chiphacker.com should redirect to electronics.stackexchange.com
   209  
   210  var REG_NONE = NewRegistrar("none");
   211  var DSP_CLOUDFLARE = NewDnsProvider("cloudflare", {"manage_redirects": true}); // enable manage_redirects
   212  
   213  D("chiphacker.com", REG_NONE, DnsProvider(DSP_CLOUDFLARE),
   214      // ...
   215  
   216      // 302 for meta subdomain
   217      CF_TEMP_REDIRECT("meta.chiphacker.com/*", "https://electronics.meta.stackexchange.com/$1"),
   218  
   219      // 301 all subdomains and preserve path
   220      CF_REDIRECT("*chiphacker.com/*", "https://electronics.stackexchange.com/$2"),
   221  
   222      // A redirect must have A records with orange cloud on. Otherwise the HTTP/HTTPS request will never arrive at Cloudflare.
   223      A("meta", "1.2.3.4", CF_PROXY_ON),
   224  
   225      // ...
   226  END);
   227  ```
   228  {% endcode %}
   229  
   230  Notice a few details:
   231  
   232  1. We need an A record with cloudflare proxy on, or the page rule will never run.
   233  2. The IP address in those A records may be mostly irrelevant, as cloudflare should handle all requests (assuming some page rule matches).
   234  3. Ordering matters for priority. CF_REDIRECT records will be added in the order they appear in your js. So put catch-alls at the bottom.
   235  4. if _any_ `CF_REDIRECT` or `CF_TEMP_REDIRECT` functions are used then `dnscontrol` will manage _all_ "Forwarding URL" type Page Rules for the domain. Page Rule types other than "Forwarding URL" will be left alone. In other words, `dnscontrol` will delete any Forwarding URL it doesn't recognize. Be careful!
   236  
   237  ## Worker routes
   238  The Cloudflare provider can manage Worker Routes for your domains. Simply use the `CF_WORKER_ROUTE` function passing the route pattern and the worker name:
   239  
   240  {% code title="dnsconfig.js" %}
   241  ```javascript
   242  var REG_NONE = NewRegistrar("none");
   243  var DSP_CLOUDFLARE = NewDnsProvider("cloudflare", {"manage_workers": true}); // enable managing worker routes
   244  
   245  D("foo.com", REG_NONE, DnsProvider(DSP_CLOUDFLARE),
   246      // Assign the patterns `api.foo.com/*` and `foo.com/api/*` to `my-worker` script.
   247      CF_WORKER_ROUTE("api.foo.com/*", "my-worker"),
   248      CF_WORKER_ROUTE("foo.com/api/*", "my-worker"),
   249  END);
   250  ```
   251  {% endcode %}
   252  
   253  The API key you use must be enabled to edit workers.  In the portal, edit the API key,
   254  under "Permissions" add "Account", "Workers Scripts", "Edit". Without this permission you may see errors that mention "failed fetching worker route list from cloudflare: bad status code from cloudflare: 403 not 200"
   255  
   256  Please notice that if _any_ `CF_WORKER_ROUTE` function is used then `dnscontrol` will manage _all_
   257  Worker Routes for the domain. To be clear: this means it will delete existing routes that
   258  were created outside of DNSControl.
   259  
   260  ## Integration testing
   261  
   262  The integration tests assume that Cloudflare Workers are enabled and the credentials used
   263  have the required permissions listed above.  The flag `-cfworkers=false` will disable tests related to Workers.
   264  This flag is intended for use with legacy domains where the integration test credentials do not
   265  have access to read/edit Workers. This flag will eventually go away.
   266  
   267  ```shell
   268  cd integrationTest              # NOTE: Not needed if already in that subdirectory
   269  go test -v -verbose -provider CLOUDFLAREAPI -cfworkers=false
   270  ```
   271  
   272  When `-cfworkers=false` is set, tests related to Workers are skipped.  The Account ID is not required.
   273  
   274  
   275  ## Cloudflare special TTLs
   276  
   277  Cloudflare plays tricks with TTLs.  Cloudflare uses "1" to mean "auto-ttl";
   278  which as far as we can tell means 300 seconds (5 minutes) with the option that
   279  CloudFlare may dynamically adjust the actual TTL. In the Cloudflare API,
   280  setting the TTL to 300 results in the TTL being set to 1.
   281  
   282  If the TTL isn't set to 1, Cloudflare has a minimum of 1 minutes.
   283  
   284  A TTL of 0 tells DNSControl to use the default TTL for that provider, which is 1.
   285  
   286  In summary:
   287  * TTL of 0, 1 and 300 are all the same ("auto TTL").
   288  * TTL of 2-60 are all the same as 60.
   289  * TTL of 61-299, and 301 to infinity are not magic.
   290  
   291  Some of this is documented on the Cloudflare website's [Time to Live (TTL)](https://developers.cloudflare.com/dns/manage-dns-records/reference/ttl/) page.