Vela命令行工具Docker镜像文档

镜像概述和主要用途

本镜像包含Vela命令行工具(CLI)，旨在提供一个隔离、一致的容器环境，用于执行Vela相关命令。Vela CLI是管理和部署应用到Kubernetes集群的核心工具，支持应用生命周期管理、资源配置及Kubernetes集群交互。通过本镜像，用户可避免本地环境依赖冲突，快速在各类环境（如CI/CD流水线、开发环境）中使用Vela功能。

核心功能和特性

核心功能

• 预安装Vela CLI：镜像内置最新稳定版Vela命令行工具，开箱即可使用。
• Kubernetes集群交互：支持通过挂载kubeconfig文件与Kubernetes集群通信，执行资源部署、查询等操作。
• 命令兼容性：完整支持Vela CLI原生命令集，包括vela deploy、vela status、vela env等核心功能。

特性

• 环境隔离：容器化运行，不影响主机系统配置及依赖。
• 版本可控：通过镜像标签指定Vela CLI版本（如:v1.8.0），确保环境一致性。
• 轻量级基础：基于Alpine等轻量级Linux发行版，镜像体积小，启动快速。
• 灵活配置：支持挂载本地文件（如kubeconfig）、设置环境变量以定制Vela行为。

使用场景和适用范围

典型使用场景

1. CI/CD流水线集成：在GitLab CI、GitHub Actions等流水线中，通过本镜像执行Vela部署命令，实现应用自动化发布。
2. 开发环境快速上手：开发者无需在本地安装Vela CLI，直接通过容器运行命令，减少环境配置时间。
3. 多版本并行使用：通过不同标签的镜像（如:v1.7.0、:v1.8.0），在同一主机上并行使用多个Vela CLI版本，满足不同项目需求。
4. 临时命令执行：需要临时执行Vela命令（如查询应用状态、修改配置）时，快速启动容器完成操作，避免本地环境污染。

适用范围

• Kubernetes集群管理员及应用开发者
• 需集成Vela工具的自动化部署流程
• 对环境一致性有要求的团队或项目
• 希望简化本地工具链配置的场景

使用方法和配置说明

基本使用方法

1. 拉取镜像

从Docker仓库拉取指定版本的镜像（默认拉取latest标签）：

bash
docker pull oamdev/vela-cli:latest  # 拉取最新版
# 或指定版本
docker pull oamdev/vela-cli:v1.8.0

2. 执行基本命令

启动容器并执行Vela CLI命令（如查看版本）：

bash
docker run --rm oamdev/vela-cli:latest vela version

• --rm：命令执行后自动删除容器，避免残留。
• vela version：Vela CLI命令，查看当前版本信息。

3. 与Kubernetes集群交互

Vela CLI需通过kubeconfig文件连接Kubernetes集群，可通过挂载本地kubeconfig实现：

bash
docker run --rm -v $HOME/.kube/config:/root/.kube/config oamdev/vela-cli:latest vela app list

• -v $HOME/.kube/config:/root/.kube/config：将本地kubeconfig文件挂载到容器内默认位置（/root/.kube/config），使Vela CLI能识别集群。
• vela app list：列出集群中所有Vela应用。

高级配置

环境变量

可通过-e参数设置环境变量，定制Vela CLI行为：

• VELA_CONFIG：指定Vela配置文件路径（默认：/root/.vela/config.yaml）。
• KUBECONFIG：覆盖kubeconfig文件路径（默认：/root/.kube/config）。

示例：指定自定义kubeconfig路径

bash
docker run --rm \
  -v /path/to/custom/kubeconfig:/custom/kubeconfig \
  -e KUBECONFIG=/custom/kubeconfig \
  oamdev/vela-cli:latest \
  vela app list

持久化配置

若需持久化Vela配置（如常用环境、应用模板），可挂载Vela配置目录：

bash
docker run --rm \
  -v $HOME/.kube/config:/root/.kube/config \
  -v $HOME/.vela:/root/.vela \  # 挂载本地Vela配置目录
  oamdev/vela-cli:latest \
  vela env set my-env --namespace default

挂载后，容器内的Vela配置（如环境设置）将持久化到本地$HOME/.vela目录。

docker-compose配置示例

若需在docker-compose中集成，可添加如下服务定义：

yaml
version: '3'
services:
  vela-cli:
    image: oamdev/vela-cli:latest
    volumes:
      - $HOME/.kube/config:/root/.kube/config
      - $HOME/.vela:/root/.vela
    environment:
      - KUBECONFIG=/root/.kube/config
    command: vela app list  # 默认执行的命令

启动服务：

bash
docker-compose up

注意事项

• 确保本地kubeconfig文件具有足够权限操作目标Kubernetes集群。
• 挂载文件/目录时，注意本地路径的正确性及权限（容器内默认用户为root，需确保挂载文件可被读取）。
• 如需使用特定版本的Vela CLI，建议在镜像标签中明确指定（如:v1.8.0），避免latest标签自动更新导致版本变化。

常用命令示例

• 查看应用列表：

  bash
  docker run --rm -v $HOME/.kube/config:/root/.kube/config oamdev/vela-cli:latest vela app list
  

• 部署应用：

  bash
  docker run --rm -v $HOME/.kube/config:/root/.kube/config -v $(pwd):/app oamdev/vela-cli:latest vela deploy -f /app/app.yaml
  

  （挂载当前目录到容器/app，使用本地app.yaml文件部署应用）
• 创建环境：

  bash
  docker run --rm -v $HOME/.kube/config:/root/.kube/config oamdev/vela-cli:latest vela env init prod --namespace production