## Cloudflare provider for octoDNS
An [octoDNS](https://github.com/octodns/octodns/) provider that targets [Cloudflare](https://www.cloudflare.com/dns/).
### Installation
#### Command line
```
pip install octodns-cloudflare
```
#### requirements.txt/setup.py
Pinning specific versions or SHAs is recommended to avoid unplanned upgrades.
##### Versions
```
# Start with the latest versions and don't just copy what's here
octodns==0.9.14
octodns-cloudflare==0.0.1
```
##### SHAs
```
# Start with the latest/specific versions and don't just copy what's here
-e git+https://git@github.com/octodns/octodns.git@9da19749e28f68407a1c246dfdf65663cdc1c422#egg=octodns
-e git+https://git@github.com/octodns/octodns-cloudflare.git@ec9661f8b335241ae4746eea467a8509205e6a30#egg=octodns_cloudflare
```
### Configuration
```yaml
providers:
cloudflare:
class: octodns_cloudflare.CloudflareProvider
# Your Cloudflare account email address (not needed if using token)
# setting email along with an API Token will raise an error.
email: env/CLOUDFLARE_EMAIL
# The API Token or API Key.
# Required permissions for API Tokens are Zone:Read, DNS:Read and DNS:Edit.
# Page Rules:Edit is required for managing Page Rules (URLFWD) records.
token: env/CLOUDFLARE_TOKEN
# Optional. Filter by account ID in environments where a token has access
# across more than the permitted number of accounts allowed by Cloudflare.
account_id: env/CLOUDFLARE_ACCOUNT_ID
# Import CDN enabled records as CNAME to {}.cdn.cloudflare.net. Records
# ending at .cdn.cloudflare.net. will be ignored when this provider is
# not used as the source and the cdn option is enabled.
#
# See: https://support.cloudflare.com/hc/en-us/articles/115000830351
#cdn: false
# Manage Page Rules (URLFWD) records
# pagerules: true
# Optional. Default: 4. Number of times to retry if a 429 response
# is received.
#retry_count: 4
# Optional. Default: 300. Number of seconds to wait before retrying.
#retry_period: 300
# Optional. Default: 50. Number of zones per page.
#zones_per_page: 50
# Optional. Default: 100. Number of dns records per page.
#records_per_page: 100
# Optional. Default: 120. Lowest TTL allowed to be set.
# A different limit for (non-)enterprise zone applies.
# See: https://developers.cloudflare.com/dns/manage-dns-records/reference/ttl
#min_ttl: 120
```
Note: The "proxied" flag of "A", "AAAA" and "CNAME" records can be managed via the YAML provider like so:
```yaml
name:
octodns:
cloudflare:
proxied: true
# auto-ttl true is implied by proxied true, but can be explicitly
# configured to be more complete
#auto-ttl: true
# with proxied=true, the TTL here will be ignored by CloudflareProvider
ttl: 120
type: A
value: 1.2.3.4
```
Note: All record types support "auto" ttl, which is effectively equivalent to 300s.
```yaml
name:
octodns:
cloudflare:
auto-ttl: true
# with proxied=true, the TTL here will be ignored by CloudflareProvider
ttl: 120
type: A
value: 1.2.3.4
```
### Support Information
#### Records
CloudflareProvider supports A, AAAA, ALIAS, CAA, CNAME, LOC, MX, NAPTR, NS, PTR, SPF, SRV, SSHFP, TXT, and URLFWD. There are restrictions on CAA tag support.
#### Root NS Records
CloudflareProvider does not supports root NS record management. They can partially be managed in the API, errors are thrown if you include the Cloudflare name servers in the values, but the system completely ignores the values set and serves up its own regardless.
#### Dynamic
CloudflareProvider does not support dynamic records.
#### Required API Token Permissions
Required Permissions for API Token are Zone:Read, DNS:Read, and DNS:Edit.
Page Rules:Edit is also required for managing Page Rules (URLFWD) records, otherwise an authentication error will be raised.
**Important Note:** When using a CloudFlare token you should **NOT** provide an email address or you will receive an error.
An example when using Page Rules (URLFWD) records -
#### TTL
Cloudflare has a different minimum TTL for enterprise and non-enterprise zones. See the [documentation](https://developers.cloudflare.com/dns/manage-dns-records/reference/ttl) for more information.
In the past the CloudflareProvider had a fixed minimum TTL set to 120 seconds and for backwards compatibility this is the current default.
### Processors
| Processor | Description |
|--|--|
| [ProxyCNAME](/octodns_cloudflare/processor/proxycname.py) | Allows Cloudflare proxied records to be used on other providers without exposing the proxied record value. Points other providers to the relevant `.cdn.cloudflare.net` subdomain. Useful to allow split authority with a secondary provider while still retaining Cloudflare benefits for certain records. |
| [TtlToProxy ](/octodns_cloudflare/processor/ttl.py) | Ensure Cloudflare's proxy status is setup depending on the TTL set for the record. This can be helpful for `octodns_bind.ZoneFileSource` or the like. |
### Developement
See the [/script/](/script/) directory for some tools to help with the development process. They generally follow the [Script to rule them all](https://github.com/github/scripts-to-rule-them-all) pattern. Most useful is `./script/bootstrap` which will create a venv and install both the runtime and development related requirements. It will also hook up a pre-commit hook that covers most of what's run by CI.
Raw data
{
"_id": null,
"home_page": "https://github.com/octodns/octodns-cloudflare",
"name": "octodns-cloudflare",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Ross McFarland",
"author_email": "rwmcfa1@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c6/96/886b20bf53ed4fdf8aa681bc4d75225460f47e55fe806b14fd1e3a0ee3dc/octodns_cloudflare-0.0.6.tar.gz",
"platform": null,
"description": "## Cloudflare provider for octoDNS\n\nAn [octoDNS](https://github.com/octodns/octodns/) provider that targets [Cloudflare](https://www.cloudflare.com/dns/).\n\n### Installation\n\n#### Command line\n\n```\npip install octodns-cloudflare\n```\n\n#### requirements.txt/setup.py\n\nPinning specific versions or SHAs is recommended to avoid unplanned upgrades.\n\n##### Versions\n\n```\n# Start with the latest versions and don't just copy what's here\noctodns==0.9.14\noctodns-cloudflare==0.0.1\n```\n\n##### SHAs\n\n```\n# Start with the latest/specific versions and don't just copy what's here\n-e git+https://git@github.com/octodns/octodns.git@9da19749e28f68407a1c246dfdf65663cdc1c422#egg=octodns\n-e git+https://git@github.com/octodns/octodns-cloudflare.git@ec9661f8b335241ae4746eea467a8509205e6a30#egg=octodns_cloudflare\n```\n\n### Configuration\n\n```yaml\nproviders:\n cloudflare:\n class: octodns_cloudflare.CloudflareProvider\n # Your Cloudflare account email address (not needed if using token)\n # setting email along with an API Token will raise an error.\n email: env/CLOUDFLARE_EMAIL\n # The API Token or API Key.\n # Required permissions for API Tokens are Zone:Read, DNS:Read and DNS:Edit.\n # Page Rules:Edit is required for managing Page Rules (URLFWD) records.\n token: env/CLOUDFLARE_TOKEN\n # Optional. Filter by account ID in environments where a token has access\n # across more than the permitted number of accounts allowed by Cloudflare.\n account_id: env/CLOUDFLARE_ACCOUNT_ID\n # Import CDN enabled records as CNAME to {}.cdn.cloudflare.net. Records\n # ending at .cdn.cloudflare.net. will be ignored when this provider is\n # not used as the source and the cdn option is enabled.\n #\n # See: https://support.cloudflare.com/hc/en-us/articles/115000830351\n #cdn: false\n # Manage Page Rules (URLFWD) records\n # pagerules: true\n # Optional. Default: 4. Number of times to retry if a 429 response\n # is received.\n #retry_count: 4\n # Optional. Default: 300. Number of seconds to wait before retrying.\n #retry_period: 300\n # Optional. Default: 50. Number of zones per page.\n #zones_per_page: 50\n # Optional. Default: 100. Number of dns records per page.\n #records_per_page: 100\n # Optional. Default: 120. Lowest TTL allowed to be set.\n # A different limit for (non-)enterprise zone applies.\n # See: https://developers.cloudflare.com/dns/manage-dns-records/reference/ttl\n #min_ttl: 120\n```\n\nNote: The \"proxied\" flag of \"A\", \"AAAA\" and \"CNAME\" records can be managed via the YAML provider like so:\n\n```yaml\nname:\n octodns:\n cloudflare:\n proxied: true\n # auto-ttl true is implied by proxied true, but can be explicitly\n # configured to be more complete\n #auto-ttl: true\n # with proxied=true, the TTL here will be ignored by CloudflareProvider\n ttl: 120\n type: A\n value: 1.2.3.4\n```\n\nNote: All record types support \"auto\" ttl, which is effectively equivalent to 300s.\n\n```yaml\nname:\n octodns:\n cloudflare:\n auto-ttl: true\n # with proxied=true, the TTL here will be ignored by CloudflareProvider\n ttl: 120\n type: A\n value: 1.2.3.4\n```\n\n### Support Information\n\n#### Records\n\nCloudflareProvider supports A, AAAA, ALIAS, CAA, CNAME, LOC, MX, NAPTR, NS, PTR, SPF, SRV, SSHFP, TXT, and URLFWD. There are restrictions on CAA tag support.\n\n#### Root NS Records\n\nCloudflareProvider does not supports root NS record management. They can partially be managed in the API, errors are thrown if you include the Cloudflare name servers in the values, but the system completely ignores the values set and serves up its own regardless.\n\n#### Dynamic\n\nCloudflareProvider does not support dynamic records.\n\n#### Required API Token Permissions\n\nRequired Permissions for API Token are Zone:Read, DNS:Read, and DNS:Edit. \nPage Rules:Edit is also required for managing Page Rules (URLFWD) records, otherwise an authentication error will be raised.\n\n**Important Note:** When using a CloudFlare token you should **NOT** provide an email address or you will receive an error.\n\nAn example when using Page Rules (URLFWD) records -\n\n\n\n#### TTL\n\nCloudflare has a different minimum TTL for enterprise and non-enterprise zones. See the [documentation](https://developers.cloudflare.com/dns/manage-dns-records/reference/ttl) for more information.\nIn the past the CloudflareProvider had a fixed minimum TTL set to 120 seconds and for backwards compatibility this is the current default.\n\n### Processors\n\n| Processor | Description |\n|--|--|\n| [ProxyCNAME](/octodns_cloudflare/processor/proxycname.py) | Allows Cloudflare proxied records to be used on other providers without exposing the proxied record value. Points other providers to the relevant `.cdn.cloudflare.net` subdomain. Useful to allow split authority with a secondary provider while still retaining Cloudflare benefits for certain records. |\n| [TtlToProxy ](/octodns_cloudflare/processor/ttl.py) | Ensure Cloudflare's proxy status is setup depending on the TTL set for the record. This can be helpful for `octodns_bind.ZoneFileSource` or the like. |\n\n### Developement\n\nSee the [/script/](/script/) directory for some tools to help with the development process. They generally follow the [Script to rule them all](https://github.com/github/scripts-to-rule-them-all) pattern. Most useful is `./script/bootstrap` which will create a venv and install both the runtime and development related requirements. It will also hook up a pre-commit hook that covers most of what's run by CI.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Cloudflare provider for octoDNS",
"version": "0.0.6",
"project_urls": {
"Homepage": "https://github.com/octodns/octodns-cloudflare"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1e06e6f74bd23d89af0a62d8ed68cbda30501ef7a2436a9033828eb4fea69ab7",
"md5": "93a4bd5e63ec87763783e08f2f6fea29",
"sha256": "4b20b8f32dbbda1ad414e7cc2c25e9879556c29548590b6eaa27af780047987b"
},
"downloads": -1,
"filename": "octodns_cloudflare-0.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "93a4bd5e63ec87763783e08f2f6fea29",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 16065,
"upload_time": "2024-05-22T19:32:01",
"upload_time_iso_8601": "2024-05-22T19:32:01.575016Z",
"url": "https://files.pythonhosted.org/packages/1e/06/e6f74bd23d89af0a62d8ed68cbda30501ef7a2436a9033828eb4fea69ab7/octodns_cloudflare-0.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c696886b20bf53ed4fdf8aa681bc4d75225460f47e55fe806b14fd1e3a0ee3dc",
"md5": "36d2a026cbd7ac7ad104740fc141d868",
"sha256": "9db6324198c3800c542bfa01a17dd7484a76635ecef93609613cdaa694649f73"
},
"downloads": -1,
"filename": "octodns_cloudflare-0.0.6.tar.gz",
"has_sig": false,
"md5_digest": "36d2a026cbd7ac7ad104740fc141d868",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 29622,
"upload_time": "2024-05-22T19:32:03",
"upload_time_iso_8601": "2024-05-22T19:32:03.760589Z",
"url": "https://files.pythonhosted.org/packages/c6/96/886b20bf53ed4fdf8aa681bc4d75225460f47e55fe806b14fd1e3a0ee3dc/octodns_cloudflare-0.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-22 19:32:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "octodns",
"github_project": "octodns-cloudflare",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "PyYAML",
"specs": [
[
"==",
"6.0.1"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2024.2.2"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.3.2"
]
]
},
{
"name": "dnspython",
"specs": [
[
"==",
"2.6.1"
]
]
},
{
"name": "fqdn",
"specs": [
[
"==",
"1.5.1"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.7"
]
]
},
{
"name": "natsort",
"specs": [
[
"==",
"8.4.0"
]
]
},
{
"name": "octodns",
"specs": [
[
"==",
"1.6.1"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.9.0.post0"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.31.0"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.16.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.2.1"
]
]
}
],
"lcname": "octodns-cloudflare"
}
JSON
