ansible-role-shipyard

关于 Shipyard

Shipyard 是一个用于从 Ansible playbook 管理 Docker swarm 集群和堆栈的工具。

它受到 Helm 和 helmfile 的启发，并在不依赖 Kubernetes 的环境中提供相似的概念。

概念：

• Shipyard Chart：一个定义 Docker Compose 堆栈及其相关文件（配置文件、环境等）的包，类似于 Helm Chart、yum RPM 文件或 Homebrew 公式。一个 Chart 包含部署和运行应用程序所需的所有资源定义，按特定结构排列。一个 Chart 可用于部署简单应用程序，也可用于部署具有多个依赖项的完整 Web 应用程序堆栈，如 HTTP 服务器、数据库、缓存等。（类似于 Helm Chart）
• Shipyard Stack：一个被自定义的 Shipyard Chart 实例，通过 values.yaml 文件进行定制。（类似于 Helm Release）
• shipyard.yaml：一个文件，定义了在哪些 Docker 主机上使用哪些值实例化哪些 Charts。（类似于 helmfile.yaml 文件）

如你所见，这些概念与 Helm 和 helmfile 非常相似。主要区别在于 Shipyard 不特定于 Kubernetes，运行不需要 Kubernetes 集群。相反，它使用 Docker Swarm 来部署堆栈。

先决条件

Ansible 角色假设你已经预配置了目标主机，要求如下：

• Docker Swarm（即 docker swarm deploy 可用）
• Docker Compose（即 docker-compose 可用）
• 用于使用的镜像的 Docker 拉取认证（即 docker pull my-image 可用）

角色变量

该角色可以通过一些可选变量进行自定义：

• shipyard_filename：你的 shipyard.yaml 文件的路径。默认值：{{inventory_path}}/shipyard.yaml。该文件可以是 Jinja2 模板。
• shipyard_charts_path：你的 Charts 目录的路径。默认值：{{inventory_path}}/shipyard/charts
• shipyard_stacks_path：你的堆栈（values.yaml / values.sops.yaml）目录的路径。默认值：{{inventory_path}}/shipyard/stacks
• shipyard_stacks_docker_secrets：Docker Secrets 的列表。默认值 []
• shipyard_tag：可选，仅部署带有此标签的堆栈。默认：空

用法

从 Ansible Galaxy 获取角色

设置你的 requirements.yml 文件以包含该角色：

roles:
  - name: linkorb.shipyard

然后运行 ansible-galaxy install -r requirements.yml 安装该角色。

创建 shipyard.yaml 文件：

shipyard.yaml 文件定义了将哪些堆栈部署到哪些主机。它与 helmfile.yaml 文件相似。

# shipyard.yaml
stacks:
  - name: my-traefik
    chart: traefik
    host: swarm-host-a
    values: my-traefik/values.yaml
    tag: lb

  - name: my-whoami
    chart: whoami
    host: swarm-host-a
    values: my-whoami/values.yaml
    tag: apps

  - name: my-mariadb
    chart: mariadb
    host: swarm-host-a
    values: my-mariadb/values.yaml
    tag: db

  - name: my-whoami-b
    chart: whoami
    host: swarm-host-b
    values: my-whoami-b/values.yaml
    tag: apps

将 Shipyard 角色添加到你的 Ansible Playbook

在你的 Ansible Playbook（通常是 site.yml）中，添加以下内容：

- name: Docker shipyard 主机配置
  hosts: my-swarm-hosts # 或一组主机 - 预期是配置了 Docker 拉取认证的 Docker Swarm 管理器
  tags:
    - shipyard # 或任何其他你想用来运行此 Playbook 的标签
  roles:
    - role: linkorb.shipyard # 来自 Ansible Galaxy 的角色
      vars:
        shipyard_tag: apps

这将查找 Playbook 目录根目录中的 shipyard.yaml 文件。 它将把标记为 apps 的堆栈部署到管理主机上。

创建一个 Shipyard Chart

一个 Shipyard Chart 的目录结构：

my-shipyard-chart/
  Chart.yaml # chart 元数据
  LICENSE # 该 chart 的许可证
  README.md # 该 chart 的说明
  values.yaml # 该 chart 的默认值
  templates/ # 该 chart 的 jinja2 模板
    docker-compose.yml # 该 chart 的 docker compose 模板文件
    example.conf # 该 chart 的示例配置文件模板
    env.example # 该 chart 的另一个示例配置文件模板
    a-directory/ # 一个将被复制到目标主机的目录

Shipyard 角色将把 templates/ 目录中的所有文件和文件夹复制到目标主机上，然后使用 Chart 和 Stack 值渲染文件（有关更多信息，请参见下节）。

values.yaml / values.sops.yaml 和 chart 默认值

每个堆栈（一个 Chart 实例）都需要一个值文件，该文件包含该 Chart 实例的值。 这些值从 {{shipyard_stacks_path}}/{{stack_name}}/values.yaml 加载。如果检测到 values.sops.yaml，它也将被自动加载和解密（基于你存储库根目录中的 .sops.yaml 文件）。

每个 Chart 还提供默认的 values.yaml。任何未定义的堆栈层级值将被设置为 Chart 的默认值。

加载（和覆盖优先级）顺序为：

1. Chart 的默认值
2. 堆栈中的 values.yaml
3. 堆栈中的 values.sops.yaml

特殊值

• primed_volumes：将为堆栈创建的 Docker 卷信息对象的列表。

  此值仅当 Chart 支持时才有意义。

  每个卷信息对象具有以下属性：

  • name：卷的名称
  • target：在容器中挂载卷的位置
  • path：在远程主机上堆栈路径下的路径，将递归复制到卷中。

  例如，可以创建一个包含 MariaDB 数据库初始化脚本的卷，如下所示：

  # my-stack/values.yaml
  primed_volumes:
  - name: mariadb_init_data
    target: /docker-entrypoint-initdb.d # MariaDB 容器查找初始化数据的地方
    path: docker-entrypoint-initdb.d # 该目录存在于 Chart 的 templates/ 目录中
  

目标主机目录结构

在目标主机（Docker Swarm 管理器）上，角色将创建以下目录结构：

/opt/shipyard/stacks/
  my-shipyard-stack/
    docker-compose.yml # 渲染后的 docker compose 文件
    example.conf # 渲染后的示例配置文件
    # ... 等等

将堆栈部署到 Docker Swarm

在模板渲染并写入主机后，角色将在目标主机上运行 docker stack deploy 来部署 Docker Swarm 堆栈。

示例 Shipyard Chart

请查看 example/shipyard/charts/whoami 目录以获取示例 Shipyard Chart。

贡献

我们欢迎贡献，使这个存储库变得更好。无论是修复错误、添加功能，还是改善文档，我们都非常感谢你的帮助。要开始，先 fork 这个存储库，然后克隆你的 fork。

请确保熟悉 LinkORB 的 贡献指南，了解我们对提交、分支和拉取请求的标准，以及在提交更改之前，请遵守我们的 行为准则。

如果你无法自己实现你想要的更改，欢迎提出新的问题报告，以便我们或其他人处理它。

由 LinkORB 工程团队提供支持

请查看我们在 linkorb.com/engineering 的其他项目。 顺便提一下，我们正在招聘！