A comprehensive guide to mastering yq, the lightweight and portable command-line YAML processor.
yq is a powerful command-line tool for processing YAML files, similar to how jq works for JSON. It enables you to query, create, modify, and validate YAML documents programmatically, making it essential for modern DevOps, GitOps, and cloud-native workflows.
- Cloud-Native Workflows: Essential for Kubernetes, Crossplane, and GitOps
- CI/CD Integration: Automate configuration updates in pipelines
- Infrastructure as Code: Manipulate Terraform, Ansible, and cloud templates
- Developer Productivity: Quick YAML transformations without manual editing
- Cross-Platform: Works on macOS, Linux, and Windows
learning-yq/
├── README.md # This file
├── 01-installation/
│ ├── macos.md # macOS installation guide
│ ├── linux.md # Linux installation guide
│ ├── windows.md # Windows installation guide
│ └── vscode-integration.md # VS Code setup
├── 02-basics/
│ ├── 01-reading-yaml.md # Basic queries
│ ├── 02-creating-yaml.md # Creating YAML from scratch
│ ├── 03-editing-yaml.md # Modifying existing files
│ └── 04-data-types.md # Working with different types
├── 03-advanced/
│ ├── 01-array-operations.md # Array manipulation
│ ├── 02-conditional-logic.md # Conditionals and filters
│ ├── 03-merging-files.md # Combining YAML files
│ └── 04-operators.md # Advanced operators
├── 04-kubernetes/
│ ├── 01-deployments.md # Working with deployments
│ ├── 02-configmaps-secrets.md # ConfigMaps and Secrets
│ └── 03-helm-values.md # Helm values files
├── 05-crossplane/
│ ├── 01-compositions.md # Crossplane Compositions
│ ├── 02-composite-resources.md # XRDs and XRs
│ ├── 03-provider-configs.md # Provider configurations
│ └── 04-patches.md # Patching strategies
├── 06-automation/
│ ├── 01-cicd-integration.md # CI/CD pipeline examples
│ ├── 02-githooks.md # Git hooks with yq
│ ├── 03-scripts.md # Automation scripts
│ └── 04-best-practices.md # Best practices
├── 07-azure/
│ ├── 01-aks-manifests.md # AKS-specific YAML
│ ├── 02-bicep-params.md # Bicep parameter files
│ └── 03-azure-devops.md # Azure DevOps integration
├── 08-examples/
│ ├── kubernetes/ # K8s examples
│ ├── crossplane/ # Crossplane examples
│ │ ├── azure-aks-composition.md # AKS cluster composition
│ │ ├── azure-subscription-xrd.md # Subscription XRD
│ │ └── azure-subscription-composition.md # Subscription composition
│ ├── helm/ # Helm examples
│ └── generic/ # Generic YAML examples
└── 09-troubleshooting/
├── common-errors.md # Common issues
└── debugging.md # Debugging techniques
macOS:
brew install yqLinux:
wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq
chmod +x /usr/local/bin/yqWindows (PowerShell):
choco install yqSee 01-installation for detailed setup instructions.
Read a value:
yq '.metadata.name' deployment.yamlUpdate a value:
yq -i '.spec.replicas = 5' deployment.yamlCreate new YAML:
yq -n '.apiVersion = "v1" | .kind = "ConfigMap"'- Dynamic manifest generation
- ConfigMap and Secret management
- Multi-environment deployments
- Helm values customization
- Composition template manipulation
- Provider configuration updates
- Composite Resource Definition editing
- Patch and transform operations
- Automated PR updates
- Configuration drift detection
- Multi-cluster deployments
- Environment promotion
- Pipeline variable injection
- Dynamic task configuration
- Infrastructure parameter updates
- Release automation
- JSONPath-like syntax: Familiar querying for JSON/YAML
- In-place editing: Direct file modification with
-i - Multiple file operations: Merge, compare, and combine
- Format conversion: YAML ↔ JSON ↔ XML ↔ Properties
- Scripting friendly: Excellent for automation
- Type preservation: Maintains YAML types and formatting
- Comments: Can preserve YAML comments (v4+)
This guide covers yq v4 (mikefarah/yq), the most widely used version. Note that there are multiple tools named “yq” - this repository focuses on the Go-based implementation by Mike Farah.
Verify your version:
yq --versionExpected output: yq (https://github.com/mikefarah/yq/) version v4.x.x
For optimal productivity, integrate yq with Visual Studio Code:
- Install the yq extension
- Configure YAML language server
- Set up keyboard shortcuts
- Create snippets for common operations
See vscode-integration.md for complete setup.
This repository includes practical examples for:
- NATO/Atos IDP Project: Backstage catalog manipulation, Crossplane templates
- Azure Cloud Engineering: AKS configuration, Azure resource YAML, subscription management
- Azure Subscription Governance: Enterprise subscription provisioning with policies, RBAC, and budgets
- DevSecOps: Security policy injection, compliance automation
- Multi-Environment: Dev/staging/production configuration management
This is a personal learning repository, but suggestions and improvements are welcome through issues and pull requests.
- jq - JSON processor
- kubectl - Kubernetes CLI
- Crossplane - Cloud-native control plane
This learning material is provided as-is for educational purposes.
Willem van Heemstra - Cloud Engineer | Security Domain Expert
Last Updated: January 2026 yq Version: v4.40+ Target Audience: DevOps Engineers, Cloud Engineers, Platform Engineers