Skip to main content

kubectl Plugin

The kubectl-headwind plugin provides a convenient CLI for managing Headwind updates and rollbacks directly from your terminal.

Installation​

Manual Installation​

# Copy the plugin to your PATH
sudo cp kubectl-headwind /usr/local/bin/

# Make it executable
sudo chmod +x /usr/local/bin/kubectl-headwind

# Verify installation
kubectl headwind help

Using Krew (Future)​

# Once published to krew
kubectl krew install headwind

Prerequisites​

  • kubectl installed and configured
  • jq (for JSON formatting)
  • curl (for API calls)
  • Access to the Headwind API (via port-forward or external URL)

Configuration​

The plugin connects to the Headwind API. Configure the connection using one of these methods:

Port Forwarding (Default)​

# In one terminal, port-forward the Headwind API
kubectl port-forward -n headwind-system svc/headwind-api 8081:8081

# In another terminal, use the plugin
kubectl headwind list

External URL​

If Headwind is exposed externally:

export HEADWIND_API_URL=https://headwind.example.com
kubectl headwind list

Custom Service Name​

If you've deployed Headwind with a custom service name:

export HEADWIND_API_SERVICE=my-headwind-api.my-namespace.svc.cluster.local:8081
kubectl headwind list

Commands​

List Pending Updates​

View all pending update requests across all namespaces:

kubectl headwind list

Output:

Namespace  | Name                 | Deployment       | Current Image | New Image    | Phase
-----------|----------------------|------------------|---------------|--------------|--------
production | nginx-update-v1-27-0 | nginx-deployment | nginx:1.26.0  | nginx:1.27.0 | Pending
staging    | redis-update-v7-2-0  | redis-deployment | redis:7.0.0   | redis:7.2.0  | Pending

Approve Update​

Approve a pending update request:

kubectl headwind approve nginx-update-v1-27-0 -n production --approver admin@example.com

Using environment variable for approver:

export HEADWIND_APPROVER=admin@example.com
kubectl headwind approve nginx-update-v1-27-0 -n production

Reject Update​

Reject a pending update request with a reason:

kubectl headwind reject nginx-update-v1-27-0 "Not ready for production" -n production --approver admin@example.com

View Update History​

See the history of updates for a deployment:

kubectl headwind history nginx-deployment -n production

Output:

Container | Image           | Timestamp            | Approved By       | Update Request
----------|-----------------|----------------------|-------------------|------------------
nginx     | nginx:1.26.0    | 2025-11-06T10:30:00Z | admin@example.com | nginx-update-v1-26-0
nginx     | nginx:1.25.0    | 2025-11-05T14:20:00Z | webhook           | nginx-update-v1-25-0

Rollback Deployment​

Rollback a deployment to its previous image:

# Rollback (auto-detects first container)
kubectl headwind rollback nginx-deployment -n production

# Rollback a specific container
kubectl headwind rollback nginx-deployment nginx -n production

Command Reference​

list​

kubectl headwind list [options]

List all pending update requests.

Options:

  • --api-url - Custom Headwind API URL

Examples:

kubectl headwind list

approve​

kubectl headwind approve <update-request> [options]

Approve a pending update request.

Arguments:

  • update-request - Name of the UpdateRequest CRD (required)

Options:

  • -n, --namespace - Namespace (defaults to current context namespace)
  • --approver - Email of the approver (defaults to $HEADWIND_APPROVER or "system")
  • --api-url - Custom Headwind API URL

Examples:

kubectl headwind approve nginx-update-v1-27-0 --approver admin@example.com
export HEADWIND_APPROVER=admin@example.com
kubectl headwind approve nginx-update-v1-27-0 -n production

reject​

kubectl headwind reject <update-request> [reason] [options]

Reject a pending update request.

Arguments:

  • update-request - Name of the UpdateRequest CRD (required)
  • reason - Reason for rejection (optional, defaults to "No reason provided")

Options:

  • -n, --namespace - Namespace (defaults to current context namespace)
  • --approver - Email of the approver (defaults to $HEADWIND_APPROVER or "system")
  • --api-url - Custom Headwind API URL

Examples:

kubectl headwind reject nginx-update-v1-27-0 "Not ready for production" --approver admin@example.com
kubectl headwind reject nginx-update-v1-27-0 -n production

history​

kubectl headwind history <deployment> [options]

Show update history for a deployment.

Arguments:

  • deployment - Name of the deployment (required)

Options:

  • -n, --namespace - Namespace (defaults to current context namespace)
  • --api-url - Custom Headwind API URL

Examples:

kubectl headwind history nginx-deployment
kubectl headwind history nginx-deployment -n production

rollback​

kubectl headwind rollback <deployment> [container] [options]

Roll back a deployment to its previous image.

Arguments:

  • deployment - Name of the deployment to rollback (required)
  • container - Name of the container (optional, defaults to first container)

Options:

  • -n, --namespace - Namespace (defaults to current context namespace)
  • --api-url - Custom Headwind API URL

Examples:

kubectl headwind rollback nginx-deployment
kubectl headwind rollback nginx-deployment nginx -n production

Environment Variables​

  • HEADWIND_API_URL - Override the default API URL (default: http://headwind-api.headwind-system.svc.cluster.local:8081)
  • HEADWIND_API_SERVICE - Override the default service name (default: headwind-api.headwind-system.svc.cluster.local:8081)
  • HEADWIND_APPROVER - Default approver email for approve/reject operations

Common Workflows​

Complete Update Workflow​

# 1. Port forward the API (in background or separate terminal)
kubectl port-forward -n headwind-system svc/headwind-api 8081:8081 &

# 2. List pending updates
kubectl headwind list

# 3. View deployment history before approving
kubectl headwind history nginx-deployment -n production

# 4. Approve an update
kubectl headwind approve nginx-update-v1-27-0 -n production --approver admin@example.com

# 5. If something goes wrong, rollback
kubectl headwind rollback nginx-deployment -n production

# 6. Check history to confirm rollback
kubectl headwind history nginx-deployment -n production

Automated Approvals in CI/CD​

#!/bin/bash
# Example CI/CD script

# Set approver for automated approvals
export HEADWIND_APPROVER=ci-bot@example.com
export HEADWIND_API_URL=https://headwind-api.production.example.com

# Approve all pending updates in staging
kubectl headwind list | grep staging | awk '{print $2, $1}' | while read name ns; do
    kubectl headwind approve "$name" -n "$ns"
done

Troubleshooting​

Cannot reach Headwind API​

If you see this error:

Cannot reach Headwind API at http://headwind-api.headwind-system.svc.cluster.local:8081

Solution 1: Port Forward

kubectl port-forward -n headwind-system svc/headwind-api 8081:8081

Solution 2: Use External URL

export HEADWIND_API_URL=https://headwind.example.com

jq not installed​

If jq is not installed, you'll see raw JSON output. Install it for better formatting:

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# RHEL/CentOS
sudo yum install jq

Permission Denied​

If you get permission denied:

chmod +x /usr/local/bin/kubectl-headwind

Plugin Not Found​

Verify the plugin is in your PATH:

# Check if plugin is executable and in PATH
which kubectl-headwind

# If not found, ensure it's in a directory in your PATH
echo $PATH

# Or add directory to PATH
export PATH=$PATH:/path/to/kubectl-headwind

Next Steps​