variantdev/mod

mod

mod 是一款通用包管理器，旨在补充 make 和 https://github.com/mumoshu/variant 等任务运行器与构建工具。它能将 Git/S3/GCS/HTTP 中的任意文件集转换为具有托管、版本化依赖的可重用模块，可视为适用于各类项目的 vgo、npm、bundle 替代方案。

核心功能与特性

• 通用依赖管理：支持从 GitHub Releases、Docker 镜像标签等源跟踪依赖版本，通过语义化版本约束筛选合适版本
• 模板渲染：基于模板文件（如 Dockerfile.tpl）自动生成配置文件，动态注入依赖版本
• 多阶段部署管理：支持定义开发、测试、生产等多阶段，按顺序更新各阶段配置，实现分阶段 GitOps 部署
• 灵活的配置器：提供文件渲染、正则替换、可执行文件管理等多种配置器，满足不同更新场景
• 自动化集成：可与 GitHub Actions 等 CI/CD 工具结合，自动提交依赖更新的 Pull Request

使用场景与适用范围

• 依赖版本自动更新：定期更新 Dockerfile、配置文件中的依赖版本（如 Helm、Golang 等）
• 容器镜像更新：自动更新容器镜像标签并生成新配置
• GitOps 部署：分阶段管理开发、测试、生产环境的配置，按顺序推进版本部署
• 项目模板初始化：从 GitHub 仓库模板创建新项目并自动初始化配置
• 多环境配置管理：为不同环境（测试、压力测试、生产）生成差异化配置文件

使用方法与配置说明

快速开始

以更新 Dockerfile 中的 Helm 版本为例：

1. 创建模板文件：将原 Dockerfile 改造为模板 Dockerfile.tpl，使用模板变量替换硬编码版本

   dockerfile
   FROM alpine:3.9
   
   ARG HELM_VERSION={{ .helm_version }}
   
   ADD http://storage.googleapis.com/kubernetes-helm/${HELM_FILE_NAME} /tmp
   RUN tar -zxvf /tmp/${HELM_FILE_NAME} -C /tmp \
     && mv /tmp/linux-amd64/helm /bin/helm \
     && rm -rf /tmp/* \
     && /bin/helm init --client-only
   

2. 配置 variant.mod：定义依赖源、版本约束及文件渲染规则

   yaml
   provisioners:
     files:
       Dockerfile:
         source: Dockerfile.tpl
         arguments:
           helm_version: "{{ .helm.version }}"
   
   helm:
       releasesFrom:
         githubReleases:
           source: helm/helm
       version: "> 1.0.0"
   

3. 运行 mod build：自动获取符合版本约束的最新 Helm 版本，渲染生成新的 Dockerfile

   dockerfile
   FROM alpine:3.9
   
   ARG HELM_VERSION=2.14.3  # 由 mod 自动更新
   
   ADD http://storage.googleapis.com/kubernetes-helm/${HELM_FILE_NAME} /tmp
   RUN tar -zxvf /tmp/${HELM_FILE_NAME} -C /tmp \
     && mv /tmp/linux-amd64/helm /bin/helm \
     && rm -rf /tmp/* \
     && /bin/helm init --client-only
   

分阶段 GitOps 部署

通过定义多阶段（如开发、测试、生产），按顺序更新各阶段配置：

1. 配置 variant.mod：定义阶段、环境及文件渲染规则

   yaml
   stages:
   - name: development
     environments:
     - test
   - name: staging
     environments:
     - qa
     - stress
   - name: production
     environments:
     - prod
   
   provisioners:
     files:
       helmfile:
         path: states/helmfile.{{ .stage.environment }}.yaml
         source: templates/helmfile.yaml.tpl
         arguments:
           MYAPP_VERSION: "{{ .stage.dependencies.myapp.version }}"
   
   dependencies:
     myapp:
       releasesFrom:
         dockerImageTags:
           source: example.com/myorg/myapp
       version: "> 0.1.0"
   

2. 按阶段更新配置：

   • 更新开发环境：mod up development --build --pull-request（生成 states/helmfile.test.yaml 并提交 PR）
   • 推广至测试环境：mod up staging --build --pull-request（生成 states/helmfile.qa.yaml 和 states/helmfile.stress.yaml）
   • 部署至生产环境：mod up production --build --pull-request（生成 states/helmfile.prod.yaml）

API 参考

regexpReplace 配置器

通过正则表达式更新文本文件（如 Dockerfile）中的版本：

yaml
provisioners:
  regexpReplace:
    Dockerfile:
      from: "(FROM helmfile:)(\\S+)(\\s+)"
      to: "${1}{{.Dependencies.helmfile.version}}${3}"

dependencies:
  helmfile:
    releasesFrom:
      dockerImageTags:
        source: quay.io/roboll/helmfile
    version: "> 0.94.0"

docker 可执行文件配置器

管理基于 Docker 镜像的可执行文件，通过 mod exec 运行：

yaml
parameters:
  defaults:
    version: "1.12.6"

provisioners:
  executables:
    dockergo:
      platforms:
      - docker:
          command: go
          image: golang
          tag: '{{.version}}'
          volume:
          - $PWD:/work
          workdir: /work

运行示例：

console
$ mod exec -- dockergo version
go version go1.12.6 linux/amd64

模板函数

• {{ hasKey .Foo.Bar "mykey" }}：检查 .Foo.Bar 是否为 map 且包含键 mykey
• {{ trimSpace .Str }}：移除字符串 .Str 中的空格、制表符和换行符

示例项目

• https://github.com/variantdev/mod/blob/master/examples/eks-k8s-vers%EF%BC%9A%E5%9C%A8%E6%96%B0 K8s 版本发布时更新 eksctl 集群配置
• https://github.com/variantdev/mod/tree/master/examples/image-tag-in-dockerfile-and-config%EF%BC%9A%E5%9C%A8%E6%96%B0 Golang 版本发布时更新 Dockerfile 和 .circleci/config.yml

类似项目

• https://github.com/dailymotion/octopilot