octodns/cloudflare

OctoDNS Docker镜像文档

一、镜像概述

OctoDNS 是一款实现“DNS即代码”（DNS as Code）的工具，支持跨多个DNS提供商管理DNS配置。OctoDNS Docker镜像将OctoDNS及其插件封装为容器化应用，提供便捷的部署与使用方式，适用于需要通过代码化方式管理DNS记录的场景。

二、核心功能与特性

2.1 OctoDNS核心功能

• 声明式配置：通过YAML/JSON文件定义DNS记录，支持版本控制与审计
• 多提供商支持：兼容Cloudflare、AWS Route53、Azure等主流DNS服务提供商
• 自动化同步：自动检测配置变更并同步至目标DNS提供商
• 预览与校验：支持预演同步操作，避免配置错误导致的服务中断

2.2 Docker镜像特性

• 轻量化设计：基于官方Python镜像构建，最小化镜像体积
• 按需选择变体：提供“全功能版”与“单一提供商版”多种镜像变体
• 即开即用：无需手动安装依赖，直接运行OctoDNS命令
• 易于集成：可无缝集成到CI/CD流水线或自动化脚本中

三、镜像变体

OctoDNS Docker镜像提供以下变体，分别针对不同DNS提供商优化：

3.1 octodns/octodns（全功能版）

• 描述：包含所有官方插件的OctoDNS完整版
• 插件列表：参见https://github.com/octodns/octodns/blob/main/all/requirements.txt
• Docker Hub：https://hub.docker.com/r/octodns/octodns

3.2 octodns/azure

• 描述：仅包含https://github.com/octodns/octodns-azure的OctoDNS
• 适用场景：使用Azure DNS服务的用户
• Docker Hub：https://hub.docker.com/r/octodns/azure

3.3 octodns/cloudflare

• 描述：仅包含https://github.com/octodns/octodns-cloudflare的OctoDNS
• 适用场景：使用Cloudflare DNS服务的用户
• Docker Hub：https://hub.docker.com/r/octodns/cloudflare

3.4 octodns/constellix

• 描述：仅包含https://github.com/octodns/octodns-constellix的OctoDNS
• 适用场景：使用Constellix DNS服务的用户
• Docker Hub：https://hub.docker.com/r/octodns/constellix

3.5 octodns/digitalocean

• 描述：仅包含https://github.com/octodns/octodns-digitalocean的OctoDNS
• 适用场景：使用DigitalOcean DNS服务的用户
• Docker Hub：https://hub.docker.com/r/octodns/digitalocean

3.6 octodns/dnsimple

• 描述：仅包含https://github.com/octodns/octodns-dnsimple的OctoDNS
• 适用场景：使用DNSimple服务的用户
• Docker Hub：https://hub.docker.com/r/octodns/dnsimple

3.7 octodns/dnsmadeeasy

• 描述：仅包含https://github.com/octodns/octodns-dnsmadeeasy的OctoDNS
• 适用场景：使用DNS Made Easy服务的用户
• Docker Hub：https://hub.docker.com/r/octodns/dnsmadeeasy

3.8 octodns/dyn

• 描述：仅包含https://github.com/octodns/octodns-dyn的OctoDNS
• 适用场景：使用Dyn DNS服务的用户
• Docker Hub：https://hub.docker.com/r/octodns/dyn

3.9 octodns/ns1

• 描述：仅包含https://github.com/octodns/octodns-ns1的OctoDNS
• 适用场景：使用NS1 DNS服务的用户
• Docker Hub：https://hub.docker.com/r/octodns/ns1

3.10 octodns/powerdns

• 描述：仅包含https://github.com/octodns/octodns-powerdns的OctoDNS
• 适用场景：使用PowerDNS服务的用户
• Docker Hub：https://hub.docker.com/r/octodns/powerdns

3.11 octodns/route53

• 描述：仅包含https://github.com/octodns/octodns-route53的OctoDNS
• 适用场景：使用AWS Route53服务的用户
• Docker Hub：https://hub.docker.com/r/octodns/route53

四、使用场景与适用范围

• 单一DNS提供商用户：选择对应提供商的镜像变体（如Cloudflare用户使用octodns/cloudflare），减少不必要依赖
• 多DNS提供商用户：使用全功能版镜像（octodns/octodns），统一管理跨平台DNS配置
• DevOps与SRE团队：通过代码化方式管理DNS，集成到Git版本控制与CI/CD流程
• 自动化运维场景：批量同步DNS配置、灾备切换、多环境一致性维护

五、使用方法与配置说明

5.1 前置准备

1. 准备OctoDNS配置文件（通常为config.yaml），定义DNS提供商认证信息与管理策略
2. 准备DNS记录文件（通常为YAML格式，存放于zones目录）

5.2 基本使用命令

通过docker run命令运行容器，核心参数说明：

• -v "$(pwd):/octodns"：挂载当前目录至容器内工作目录/octodns，用于读取配置文件
• --workdir /octodns：设置容器工作目录为/octodns
• 镜像名称：选择对应变体（如octodns/cloudflare）
• 命令：指定OctoDNS操作（如octodns-sync同步配置，octodns-validate校验配置）

示例：使用Cloudflare变体同步DNS配置

bash
docker run -v "$(pwd):/octodns" --workdir /octodns docker.xuanyuan.run/octodns/cloudflare octodns-sync

5.3 关键配置说明

• 配置文件挂载：必须将包含config.yaml和DNS记录文件的目录挂载至容器/octodns
• 认证信息管理：DNS提供商的API密钥等敏感信息通过config.yaml配置，建议通过环境变量或密钥管理工具注入，避免硬编码
• 命令参数：支持OctoDNS所有原生命令参数，如--dry-run预览同步结果、--debug开启调试日志

六、部署示例

6.1 Docker Compose配置（Cloudflare示例）

创建docker-compose.yml：

yaml
version: '3'
services:
  octodns:
    image: docker.xuanyuan.run/octodns/cloudflare
    volumes:
      - ./dns-config:/octodns  # 本地dns-config目录包含config.yaml和zones
    working_dir: /octodns
    command: octodns-sync --dry-run  # 先执行 dry-run 预览变更

运行命令：

bash
docker-compose up

6.2 定期同步任务（Cron集成）

通过Cron定时执行DNS同步：

bash
# 每天凌晨3点执行同步
0 3 * * * docker run -v "/path/to/dns-config:/octodns" --workdir /octodns octodns/cloudflare octodns-sync >> /var/log/octodns-sync.log 2>&1

七、扩展与版本更新

7.1 添加新镜像变体

如需添加支持其他DNS提供商的镜像变体：

1. 创建新子目录（如newprovider），并在目录中添加requirements.txt
2. 在requirements.txt中指定对应Provider依赖（如octodns-newprovider）
3. 更新GitHub Actions工作流，添加新变体的构建与发布任务

7.2 版本更新方法

更新OctoDNS版本时，仅需修改全功能版镜像的all/requirements.txt中OctoDNS核心版本号，该版本将自动同步至所有提供商特定变体。