flipenergy/yq-ubuntu

yq-Ubuntu镜像文档

镜像概述

本镜像基于Ubuntu系统构建，集成了yq命令行工具，提供稳定的yq运行环境。yq是一款轻量级数据处理工具，专注于解析、查询、修改YAML、JSON、XML等结构化数据，支持类jq语法的表达式操作，适用于各类自动化场景和命令行数据处理需求。

核心功能与特性

• 多格式兼容：支持YAML、JSON、XML、Properties等多种结构化数据格式的解析与处理
• 强大查询能力：提供类jq的表达式语法，支持路径查询、条件过滤、函数计算等复杂数据提取
• 数据修改支持：可直接对数据进行添加、删除、更新字段等操作，支持原地修改文件
• 命令行交互：简洁的命令行接口，支持管道操作和批量处理，易于集成到Shell脚本
• Ubuntu基础：基于稳定的Ubuntu系统，确保运行环境的兼容性和安全性，依赖库完善

使用场景

• CI/CD流程：在持续集成/部署管道中处理配置文件（如动态修改k8s YAML配置、解析CI参数）
• 自动化脚本：集成到Shell/Python脚本中，实现配置文件的动态生成、校验或转换
• 开发调试：本地开发环境中快速验证和调整YAML/JSON配置文件
• 数据转换：实现YAML与JSON/XML的格式互转，或从结构化数据中提取特定字段生成报告

使用方法

拉取镜像

bash
docker pull docker.xuanyuan.run/<image-name>  # 替换为实际镜像名称（如仓库中指定的镜像标签）

基本运行命令

通过挂载本地目录到容器内的/data路径，实现本地文件处理：

bash
docker run --rm -v $(pwd):/data <image-name> yq [选项] <表达式> <目标文件>

• --rm：容器退出后自动删除，避免残留容器实例
• -v $(pwd):/data：将当前工作目录挂载到容器内/data，用于访问本地文件
• [选项]：yq命令选项（如-i原地修改文件、-o json指定输出格式为JSON）
• <表达式>：yq查询或操作表达式（如.metadata.name获取YAML中指定字段）
• <目标文件>：容器内文件路径（需位于挂载的/data目录下，如/data/config.yaml）

常用操作示例

1. 查询数据

提取YAML文件中特定字段：

bash
docker run --rm -v $(pwd):/data <image-name> yq eval '.spec.replicas' /data/deployment.yaml

2. 修改数据

原地更新YAML文件中的字段值：

bash
docker run --rm -v $(pwd):/data <image-name> yq eval '.spec.replicas = 5' -i /data/deployment.yaml

3. 格式转换

将YAML文件转换为JSON格式输出：

bash
docker run --rm -v $(pwd):/data <image-name> yq eval -o json /data/config.yaml

4. 批量处理

通过管道传递数据并处理（如从JSON文件中提取数组元素）：

bash
cat data.json | docker run --rm -i <image-name> yq eval '.users[].name' -

Docker Compose配置

创建docker-compose.yml集成到项目中：

yaml
version: '3'
services:
  yq:
    image: docker.xuanyuan.run/<image-name>
    volumes:
      - ./local-data:/data  # 挂载本地数据目录到容器
    command: yq eval '.version' /data/version.yaml  # 执行具体yq命令

启动服务：

bash
docker-compose up

注意事项

• 确保挂载目录有读写权限，避免文件操作失败（可通过-u $(id -u):$(id -g)指定用户权限）
• 复杂表达式建议使用单引号包裹，避免Shell解析导致语法错误
• 完整yq命令及表达式语法可参考https://github.com/mikefarah/yq