如何在Ubuntu18.04上使用OctoDNS部署和管理DNS
作为 Write for DOnations 计划的一部分,作者选择了 Electronic Frontier Foundation 来接受捐赠。
介绍
OctoDNS 是一种 基础设施即代码 工具,可让您使用标准软件开发原则(包括版本控制、测试和自动化部署)来部署和管理 DNS 区域。 OctoDNS 由 GitHub 创建并用 Python 编写。
使用 OctoDNS 消除了手动 DNS 管理的许多缺陷,因为区域文件以结构化格式 (YAML) 存储。 这使您可以同时将区域部署到多个 DNS 提供商、识别语法错误并自动推出您的 DNS 配置,从而降低人为错误的风险。 OctoDNS 的另一个常见用途是在不同的提供商之间同步您的 DNS 配置,例如测试和生产系统,或者在实时和故障转移环境之间。
OctoDNS 类似于 DNSControl,后者是由 Stack Exchange 创建并用 Go 编写的等效工具。 与 OctoDNS 不同,DNSControl 使用基于 JavaScript 的配置语言来定义 DNS 区域,这允许您使用高级编程功能(例如循环)来指定同一区域内的多个相似记录。 文章 如何在 Ubuntu 18.04 上使用 DNSControl 部署和管理 DNS 涵盖了 DNSControl 的基本设置和配置。
在本教程中,您将安装和配置 OctoDNS,创建基本 DNS 配置,并开始将 DNS 记录部署到实时提供商。 作为本教程的一部分,我们将使用 DigitalOcean 作为示例 DNS 提供程序。 如果您希望使用 不同的提供程序 ,设置非常相似。 完成后,您将能够在安全的离线环境中管理和测试您的 DNS 配置,然后自动将其部署到生产环境中。
先决条件
在开始本指南之前,您需要以下内容:
- 按照 Initial Server Setup 和 Ubuntu 18.04 设置一台 Ubuntu 18.04 服务器,包括 sudo 非 root 用户并启用防火墙以阻止非必要端口。
your-server-ipv4-address
和your-server-ipv6-address
是指您托管网站或域的服务器的 IP 地址。 - 由 支持的提供商 托管的具有 DNS 的完全注册域名。 本教程将始终使用
your-domain
并使用 DigitalOcean 作为服务提供者。 - 具有读写权限的 DigitalOcean API 密钥(个人访问令牌)。 要创建一个,请访问 如何创建个人访问令牌。
准备好这些后,以非 root 用户身份登录到您的服务器即可开始。
第 1 步 — 安装 OctoDNS
OctoDNS 作为 Python pip 包分发,并在 Python 虚拟环境 (virtualenv) 中运行,因此您将通过安装所需的包来开始这一步。 virtualenv
是一个独立的 Python 环境,可以拥有自己的库和配置,与系统范围的主要 Python 安装分开。 Python 和 virtualenv
在 Ubuntu 的默认软件存储库中可用,因此可以使用传统的包管理工具进行安装。
首先更新本地包索引以反映任何新的上游更改:
sudo apt update
然后,安装 python
和 virtualenv
软件包:
sudo apt install python virtualenv
确认安装后,apt
将下载并安装 Python、virtualenv
及其所需的所有依赖项。
接下来,您将为 OctoDNS 创建所需的目录,其中将存储您的 DNS 和程序配置。 首先创建 ~/octodns
和 ~/octodns/config
目录:
mkdir ~/octodns ~/octodns/config
现在进入 ~/octodns
:
cd ~/octodns
接下来,您需要创建 Python 虚拟环境——一个独立的 Python 环境,具有自己的库和配置来运行 OctoDNS:
virtualenv env
使用以下命令激活您的环境:
source env/bin/activate
这将输出类似于以下内容:
OutputRunning virtualenv with interpreter /usr/bin/python2 New python executable in /home/user/octodns/env/bin/python2 Also creating executable in /home/user/octodns/env/bin/python Installing setuptools, pkg_resources, pip, wheel...done.
您的 Bash shell 提示符现在也将以虚拟环境的名称为前缀。 这说明你当前在virtualenv
内操作:
(env) user@digitalocean:~/octodns$
如果您想退出 virtualenv
,您可以随时使用 deactivate
命令。 但是,您应该留在 virtualenv
中以继续本教程。
现在您已经安装并配置了 Python 和 virtualenv
,您可以安装 OctoDNS。 OctoDNS 作为 Python pip 包分发,它是 Python 包和库的标准包管理工具。
您可以在 virtualenv
中使用以下命令安装 OctoDNS pip 包:
pip install octodns
完成后,您可以检查已安装的版本以确保一切正常:
octodns-sync --version
您的输出将类似于以下内容:
OutputoctoDNS 0.9.6
如果您看到 octodns-sync: command not found
错误,请仔细检查您是否仍在 virtualenv
中。
现在您已经安装了 OctoDNS,您可以创建所需的配置文件以将 OctoDNS 连接到您的 DNS 提供商,以允许它更改您的 DNS 记录。
第 2 步 — 配置 OctoDNS
在此步骤中,您将为 OctoDNS 创建所需的配置文件,并将其连接到您的 DNS 提供商,以便它可以开始对您的 DNS 记录进行实时更改。
注意:本教程将重点介绍OctoDNS的初始设置; 但是,对于生产用途,建议将您的 OctoDNS 配置存储在版本控制系统 (VCS) 中,例如 Git。 这样做的优点包括完整的版本控制、与 CI/CD 集成以进行测试、无缝回滚部署等。
首先,您需要配置 config.yaml
文件,该文件定义了 OctoDNS 要管理的 DNS 区域,并允许它向您的 DNS 提供商进行身份验证并进行更改。
config.yaml
的格式因您使用的 DNS 提供商而略有不同。 请参阅 OctoDNS 官方文档中的 支持的提供商列表 以找到您自己的提供商的配置。 查看此超链接时,配置详细信息会在您的提供程序的实际 Python 代码中以代码注释的形式呈现,链接在表的“提供程序”列中。 找到提供程序的 Python 代码后,例如 cloudflare.py
或 route53.py
,可直接在 class
ProviderNameProvider
下找到相关代码注释。 例如:
octodns/provider/route53.py 的摘录
class Route53Provider(BaseProvider): ''' AWS Route53 Provider route53: class: octodns.provider.route53.Route53Provider # The AWS access key id access_key_id: # The AWS secret access key secret_access_key: # The AWS session token (optional) # Only needed if using temporary security credentials session_token:
Move into the ~/octodns/config
directory:
cd ~/octodns/config
Then create and open config.yaml
for editing:
nano config.yaml
Add the sample config.yaml
configuration for your DNS provider to the file. If you’re using DigitalOcean as your DNS provider, you can use the following:
~/octodns/config/config.yaml
--- providers: config: class: octodns.provider.yaml.YamlProvider directory: ./config default_ttl: 300 enforce_order: True digitalocean: class: octodns.provider.digitalocean.DigitalOceanProvider token: your-digitalocean-oauth-token zones: your-domain.: sources: - config targets: - digitalocean
This file tells OctoDNS which DNS providers you want it to connect to, and which DNS zones it should manage for those providers.
You’ll need to provide some form of authentication for your DNS provider. This is usually an API key or OAuth token.
If you do not wish to store your access token in plain text in the configuration file, you can instead pass it as an environment variable when the program runs. To do this, you should use the following token:
line instead in config.yaml
:
~/octodns/config/config.yaml
token: env/DIGITALOCEAN\_OAUTH\_TOKEN
Then, before running OctoDNS, set the relevant environment variable to your access token, and OctoDNS will read it from there when run:
export DIGITALOCEAN\_OAUTH\_TOKEN=your-digitalocean-oauth-token
Warning: This token will grant access to your DNS provider account, so you should protect it as you would a password. Also, ensure that if you’re using a version control system, either the file containing the token is excluded (e.g. using .gitignore
), or is securely encrypted in some way.
If you’re using DigitalOcean as your DNS provider, you can use the required OAuth token in your DigitalOcean account settings that you generated as part of the prerequisites.
If you have multiple different DNS providers—for example, for multiple domain names, or delegated DNS zones—you can define these all in the same config.yaml
file.
You’ve set up the initial OctoDNS configuration file to allow the program to authenticate to your DNS provider and make changes. Next you’ll create the configuration for your DNS zones.
Step 3 — Creating a DNS Configuration File
In this step, you’ll create an initial DNS configuration file, which will contain the DNS records for your domain name or delegated DNS zone.
Each DNS zone that you want to manage using OctoDNS has its own file, for example your-domain.yaml
. In this file, the DNS records for the zone are defined using YAML.
To begin, move into the ~/octodns/config
directory:
cd ~/octodns/config
Then create and open your-domain.yaml
for editing:
nano your-domain.yaml
Add the following sample configuration to the file:
~/octodns/config/your-domain.yaml
--- '': - type: A value: your-server-ipv4-address www: - type: A value: your-server-ipv4-address
This sample file defines a DNS zone for your-domain
with two A
records, pointing to the IPv4 address that you’re hosting your domain or website on. One A
record is for the root domain (e.g. your-domain
), and the other is for the www
subdomain (e.g. www.your-domain
).
Once complete, save and close the file.
You’ve set up a basic DNS zone configuration file for OctoDNS, with two basic A
records pointing to the IPv4 address of your domain or website. Next, you’ll expand the file with some useful DNS records.
Step 4 — Populating Your DNS Configuration File
Next, you can populate the DNS configuration file with a practical set of DNS records for your website or service, using the YAML structured configuration language.
Unlike traditional BIND zone files, where DNS records are written in a raw, line-by-line format, DNS records within OctoDNS are defined as YAML keys and subkeys with a number of associated values, as shown briefly in Step 3.
The top-level key is usually the 'name'
, which is essentially the record identifier. www
, subdomain1
, and mail
are all examples of DNS 'name'
. In OctoDNS, there are two special-use names, which are , for the root record (usually referred to as
@
), and '*'
, for wildcard records. A required value of each key (DNS record) is type
. This defines which type of DNS record you are defining within that YAML top-level key. A type
exists for each of the standard DNS record types, including A
, AAAA
, MX
, TXT
, NS
, CNAME
, and so on. A full list of available record types is available in the Records section of the OctoDNS documentation.
The values for your DNS records are defined either directly as values to the top-level keys (if you only have one value), or as a list (if you have multiple values, e.g. multiple IP addresses or MX addresses).
For example, to define a single value, you could use the following configuration:
~/octodns/config/your-domain.yaml
'www': type: A value: 203.0.113.1
Alternatively, to define multiple values for a single record:
~/octodns/config/your-domain.yaml
'www': type: A values: - 203.0.113.1 - 203.0.113.2
The syntax for setting DNS records varies slightly for each record type. Following are some examples for the most common record types:
A
records:
Purpose: To point to an IPv4 address.
Syntax:
'name': type: A value: ipv4-address
Example:
'www': type: A value: your-server-ipv4-address
AAAA
records:
Purpose: To point to an IPv6 address.
Syntax:
'name': type: AAAA value: ipv6-address
Example:
'www': type: AAAA value: your-server-ipv6-address
CNAME
records:
Purpose: To make your domain/subdomain an alias of another.
Syntax:
'name': type: CNAME value: fully-qualified-domain-name
Example:
'www': type: CNAME value: www.example.org
MX
records:
Purpose: To direct email to specific servers/addresses.
Syntax:
'name': type: MX value: exchange: mail-server preference: priority-value
Note that a trailing .
must be included if there are any dots in the MX value.
Example:
'': type: MX value: exchange: mail.your-domain. preference: 10
TXT
records:
Purpose: To add arbitrary plain text, often used for configurations without their own dedicated record type.
Syntax:
'name': type: TXT value: content
Example:
'': type: TXT value: This is a TXT record.
In order to begin adding DNS records for your domain or delegated DNS zone, edit your DNS configuration file:
cd ~/octodns/config nano your-domain.yaml
Next, you can begin populating your DNS zone using the syntax described in the previous list, as well as the Records section of the official OctoDNS documentation.
For reference, the code block here contains a full sample configuration for an initial DNS setup:
~/octodns/config/your-domain.yaml
--- '': - type: A value: your-server-ipv4-address - type: AAAA value: your-server-ipv6-address - type: MX value: exchange: mail.your-domain. preference: 10 - type: TXT value: v=spf1 -all _dmarc: type: TXT value: v=DMARC1\; p=reject\; rua=mailto:abuse@your-domain\; aspf=s\; adkim=s\; mail: - type: A value: your-server-ipv4-address - type: AAAA value: your-server-ipv6-address www: - type: A value: your-server-ipv4-address - type: AAAA value: your-server-ipv6-address
Once you have completed your initial DNS configuration, save and close the file.
In this step, you set up the initial DNS configuration file, containing your DNS records. Next, you will test the configuration and deploy it.
Step 5 — Testing and Deploying Your DNS Configuration
In this step, you will run a local syntax check on your DNS configuration, and then deploy the changes to the live DNS server/provider.
Firstly, move into your octodns
directory:
cd ~/octodns
Double check that you’re still operating within your Python virtualenv
by looking for the name of it before your Bash prompt:
(env) user@digitalocean:~/octodns$
Next, use the octodns-validate
command to check the syntax of your configuration file(s). You’ll need to specify the path to your configuration file:
octodns-validate --config=./config/config.yaml
If the YAML syntax of your DNS configuration file is correct, OctoDNS will return with no output.
If you see an error or warning in your output, OctoDNS will provide details on what and where the error is located within your YAML file.
Next, you can perform a dry-run push of the DNS configuration, which will output which changes will be made, without actually making them:
octodns-sync --config=./config/config.yaml
This should produce an output similar to the following:
Output******************************************************************************** * your-domain. ******************************************************************************** * digitalocean (DigitalOceanProvider) * Create <ARecord A 300, mail.your-domain., ['your-server-ipv4-address']> (config) * Create <AaaaRecord AAAA 300, mail.your-domain., ['your-server-ipv6-address']> (config) * Create <TxtRecord TXT 300, your-domain., ['v=spf1 -all']> (config) * Create <AaaaRecord AAAA 300, your-domain., ['your-server-ipv6-address']> (config) * Create <ARecord A 300, your-domain., ['your-server-ipv4-address']> (config) * Create <ARecord A 300, www.your-domain., ['your-server-ipv4-address']> (config) * Create <MxRecord MX 300, your-domain., [''10 mail.your-domain.'']> (config) * Create <TxtRecord TXT 300, _dmarc.your-domain., ['v=DMARC1\; p=reject\; rua=mailto:abuse@your-domain\; aspf=s\; adkim=s\;']> (config) * Create <AaaaRecord AAAA 300, www.your-domain., ['your-server-ipv6-address']> (config) * Summary: Creates=9, Updates=0, Deletes=0, Existing Records=2 ********************************************************************************
Warning: The next command will make live changes to your DNS records and possibly other settings. Please ensure that you are prepared for this, including taking a backup of your existing DNS configuration, as well as ensuring that you have the means to roll back if needed.
Finally, you can push out the changes to your live DNS provider:
octodns-sync --config=./config/config.yaml --doit
Note: In some cases, OctoDNS will refuse to push changes if it is making a significant number of adjustments. This is an automatic protection feature to prevent accidental misconfigurations. If you encounter this refusal, you can re-run octodns-sync
using the --force
option, but please ensure you are ready to do so.
You’ll see an output like the dry-run earlier in this step, but with the addition of something similar to the following:
Output2019-07-07T23:17:27 INFO DigitalOceanProvider[digitalocean] apply: making changes 2019-07-07T23:17:30 INFO Manager sync: 9 total changes
Now, if you check the DNS settings for your domain in the DigitalOcean control panel, you’ll see the changes.
You can also check the record creation by running a DNS query for your domain/delegated zone. You’ll see that the records have been updated accordingly:
dig +short your-domain
You’ll see output showing the IP address and relevant DNS record from your zone that was deployed using OctoDNS. DNS records can take some time to propagate, so you may need to wait and run this command again.
In this final step, you ran a local syntax check of the DNS configuration file, then deployed it to your live DNS provider, and tested that the changes were made successfully.
Conclusion
In this article you set up OctoDNS and deployed a DNS configuration to a live provider. Now you can manage and test your DNS configuration changes in a safe, offline environment before deploying them to production.
If you wish to explore this subject further, OctoDNS is designed to be integrated into your CI/CD pipeline, allowing you to run in-depth tests and have more control over your deployment to production. You could also look into integrating OctoDNS into your infrastructure build/deployment processes, allowing you to deploy servers and add them to DNS completely automatically.
If you wish to go further with OctoDNS, the following DigitalOcean articles provide some interesting next steps to help integrate OctoDNS into your change management and infrastructure deployment workflows: