Usage Guide¶

This guide covers common usage patterns for kfix.

Important

kfix formats valid YAML only. It will not fix malformed or syntactically incorrect YAML. Use a YAML validator first if you encounter issues.

Basic Usage¶

Format a single file:

kfix format deployment.yaml

Output:

Formatted YAML is printed to stdout
Original file is unchanged
Exit code 0 on success, 1 on error

Format multiple files:

kfix format deployment.yaml service.yaml configmap.yaml

Format all YAML files in a directory:

kfix format *.yaml
kfix format manifests/*.yaml

Format from stdin:

cat deployment.yaml | kfix format
kubectl get pod nginx -o yaml | kfix format

In-Place Editing¶

Use the -w (or --in-place) flag to modify files directly:

kfix format -w deployment.yaml

Warning

In-place editing modifies files directly. Consider version control or backups.

Format all manifests in place:

kfix format -w manifests/*.yaml

Safe in-place update pattern:

# Preview changes first
kfix format deployment.yaml

# If satisfied, apply in-place
kfix format -w deployment.yaml

Indentation Control¶

Customize indentation with the -i flag (default: 2 spaces):

kfix format -i 4 deployment.yaml

Standard indentations:

2 spaces (default, recommended for K8s)
4 spaces (alternative style)

Commands Reference¶

kfix format¶

Format Kubernetes YAML files with consistent styling.

Syntax:

kfix format [flags] [file...]

Arguments:

file... - One or more YAML files to format (optional)
If no files provided, reads from stdin

Flags:

-w, --in-place: Write formatted output back to the file instead of stdout
-i, --indent int: Number of spaces for indentation (default: 2)

What the formatter does:

Validates input is a Kubernetes resource (has apiVersion and kind)
Reorders top-level fields: apiVersion → kind → metadata → spec → data/status
Reorders metadata fields: name → namespace → labels → annotations
Reorders container fields: name → image → command → args → ports → env → resources
Applies consistent indentation throughout
Handles multi-document YAML (separated by ---)

kfix version¶

Display version information:

kfix version

Shows:

ASCII art banner
Version number
Source repository link
Documentation link

kfix help¶

Get help on any command:

kfix help
kfix help format
kfix format --help

Common Workflows¶

Format Before Commit¶

Integrate into your Git workflow:

# Format all manifests before commit
kfix format -w k8s/*.yaml
git add k8s/
git commit -m "style: format Kubernetes manifests"

Format CI/CD Pipeline¶

Check formatting in CI:

#!/bin/bash
# Check if manifests are formatted

for file in k8s/*.yaml; do
    if ! diff -u "$file" <(kfix format "$file"); then
        echo "ERROR: $file is not formatted"
        echo "Run: kfix format -w $file"
        exit 1
    fi
done

Format kubectl Output¶

Pipe kubectl output through kfix:

# Get and format a deployment
kubectl get deployment nginx -o yaml | kfix format > nginx-deployment.yaml

# Get all resources in a namespace
kubectl get all -n production -o yaml | kfix format > production-backup.yaml

Format Helm Output¶

Format Helm template output:

helm template myapp ./chart | kfix format > rendered.yaml

Format Kustomize Output¶

Format Kustomize build output:

kustomize build . | kfix format > manifest.yaml

Integration with Editors¶

Vim/Neovim¶

Format current buffer:

:%!kfix format

Or add to .vimrc:

autocmd FileType yaml nmap <leader>k :%!kfix format<CR>

VS Code¶

Add to tasks.json:

{
    "label": "Format with kfix",
    "type": "shell",
    "command": "kfix format -w ${file}"
}

Pre-commit Hook¶

Add to .git/hooks/pre-commit:

#!/bin/bash

# Format staged YAML files
git diff --cached --name-only --diff-filter=ACMR | grep '\.ya\?ml$' | while read file; do
    kfix format -w "$file"
    git add "$file"
done

Troubleshooting¶

Error: “file does not appear to be valid Kubernetes resource(s)”¶

Cause: Input YAML is either:

Malformed/invalid YAML syntax
Missing required fields (apiVersion and kind)
Not a Kubernetes resource

Solution:

Validate YAML syntax:
```
yamllint file.yaml
```
Ensure resource has both apiVersion and kind fields
kfix only formats Kubernetes resources, not generic YAML

Error: “failed to parse YAML”¶

Cause: YAML syntax error (malformed structure)

Solution:

Fix YAML syntax errors first
kfix formats valid YAML, it does not fix broken YAML
Use a linter: yamllint file.yaml

Multi-Document Files¶

kfix handles multiple documents separated by ---:

# Input
kind: Service
apiVersion: v1
---
kind: Deployment
apiVersion: apps/v1

# Output
apiVersion: v1
kind: Service
---
apiVersion: apps/v1
kind: Deployment

Each document is formatted independently.

Examples¶

Basic Deployment¶

Before:

kind: Deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
metadata:
  name: nginx
apiVersion: apps/v1

After:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx

Complex Container Spec¶