groq/kustomize-upsert

groq/kustomize-upsert

Description: Upsert transformer for kustomizations

Language: Go

Stars: 2

Forks: 0

Open issues: 8

Created: 2025-06-16T00:24:58Z

Pushed: 2026-06-07T00:52:46Z

Default branch: main

Fork: no

Archived: no

README:

Kustomize Upsert Transformer

A generic Go plugin for Kustomize that provides "append if exists, else create" behavior for array fields in Kubernetes resources. Supports regex-based resource targeting for gradual rollouts.

Problem Solved

Kustomize has fundamental limitations with array handling:

• Strategic merge patches clobber entire arrays in custom resources
• JSON patches fail if target paths don't exist
• No conditional logic for "append if exists, else create" behavior

This transformer provides transparent array upsert operations for any Kubernetes resource and field.

Features

• ✅ Generic: Works with any Kubernetes resource type and array field
• ✅ Transparent: Handles both "create" and "append" cases automatically
• ✅ Type safe: Pure Go implementation with proper error handling
• ✅ Configurable: Support for multiple operations and target selectors
• ✅ Duplicate handling: Optional deduplication of array values
• ✅ JSONPath support: Flexible path targeting (e.g., spec.containers[0].args)
• ✅ Regex targeting: Supports regex patterns for resource names (e.g., name: "web-.*")

Usage

1. Install the transformer

make build
# Binary created at ./kustomize-upsert
# Copy to your PATH or distribute via internal tooling

2. Create configuration file

apiVersion: groq.io/v1alpha1
kind: UpsertTransformer
metadata:
name: array-upsert
spec:
operations:
# Add OTEL environment variables to InferenceEngineDeployments
- target:
group: "inference-engine.groq.io"
version: "v1alpha1"
kind: "InferenceEngineDeployment"
path: "spec.dev.nova_args"
values:
- "--agent-env-vars=GROQ_ENABLE_DRIVER_OTEL=1"
- "--agent-env-vars=GROQ_QSFP_OTEL_MONITOR=1"
allowDuplicates: false

# Add debug flags using regex targeting (gradual rollout)
- target:
group: "apps"
version: "v1"
kind: "Deployment"
name: "(web-app|api-service|worker-.*)"
path: "spec.template.spec.containers[0].args"
values:
- "--debug"
- "--verbose"

# Add args to specific pods
- target:
version: "v1"
kind: "Pod"
name: "my-pod"
path: "spec.containers[0].args"
values:
- "--feature-flag=enabled"

3. Use in kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
- deployment.yaml

transformers:
- upsert-config.yaml

4. Build with kustomize

kustomize build --enable-alpha-plugins .

Configuration Reference

UpsertOperation Fields

| Field | Type | Description | |-------|------|-------------| | target | ResourceSelector | Specifies which resources to transform | | path | string | JSONPath to the array field (e.g., spec.dev.nova_args) | | values | []string | Values to append/set in the array | | allowDuplicates | bool | Whether to add values that already exist (default: false) |

ResourceSelector Fields

| Field | Type | Description | |-------|------|-------------| | group | string | API group to match (optional) | | version | string | API version to match (optional) | | kind | string | Resource kind to match (optional) | | name | string | Resource name to match - supports regex (optional) | | namespace | string | Resource namespace to match - supports regex (optional) |

Regex Rollout Pattern

The transformer supports a gradual rollout pattern using regex selectors:

Phase 1: Target specific instances

- target:
name: "(foo-instance|bar-instance)"
kind: "InferenceEngineDeployment"
path: "spec.dev.nova_args"
values: ["--new-feature=enabled"]

Phase 2: Add more instances to regex

- target:
name: "(foo-instance|bar-instance|baz-instance|qux-.*)"
kind: "InferenceEngineDeployment"
path: "spec.dev.nova_args"
values: ["--new-feature=enabled"]

Phase 3: Remove name selector (apply to all)

- target:
kind: "InferenceEngineDeployment"
path: "spec.dev.nova_args"
values: ["--new-feature=enabled"]

Examples

OTEL Environment Variables

operations:
- target:
group: "inference-engine.groq.io"
version: "v1alpha1"
kind: "InferenceEngineDeployment"
path: "spec.dev.nova_args"
values:
- "--agent-env-vars=GROQ_ENABLE_DRIVER_OTEL=1"
- "--agent-env-vars=GROQ_QSFP_OTEL_MONITOR=1"

Container Arguments

operations:
- target:
group: "apps"
version: "v1"
kind: "Deployment"
path: "spec.template.spec.containers[0].args"
values:
- "--feature-flag=new-ui"
- "--log-level=debug"

Pod Security Context

operations:
- target:
version: "v1"
kind: "Pod"
path: "spec.securityContext.supplementalGroups"
values:
- "1000"
- "2000"

Behavior Examples

Before (no array exists)

apiVersion: inference-engine.groq.io/v1alpha1
kind: InferenceEngineDeployment
spec:
replicas: 2

After (array created)

apiVersion: inference-engine.groq.io/v1alpha1
kind: InferenceEngineDeployment
spec:
replicas: 2
dev:
nova_args:
- "--agent-env-vars=GROQ_ENABLE_DRIVER_OTEL=1"
- "--agent-env-vars=GROQ_QSFP_OTEL_MONITOR=1"

Before (array exists)

spec:
dev:
nova_args:
- "--log-level=info"
- "--timeout=30s"

After (values appended)

spec:
dev:
nova_args:
- "--log-level=info" # ✅ Preserved
- "--timeout=30s" # ✅ Preserved
- "--agent-env-vars=GROQ_ENABLE_DRIVER_OTEL=1" # ✅ Added
- "--agent-env-vars=GROQ_QSFP_OTEL_MONITOR=1" # ✅ Added

Distribution

This transformer can be distributed using the same mechanism as other internal tools like kustomize-lint:

1. Build releases for multiple platforms 2. Distribute via internal package management 3. Version and update through standard internal processes 4. Document in internal developer guides

Benefits over Manual Patches

• ✅ Generic: Not limited to specific use cases
• ✅ Reusable: One tool for all array upsert needs
• ✅ Maintainable: Single codebase vs. many manual patches
• ✅ Reliable: No shell scripting or external dependencies
• ✅ Extensible: Easy to add new features and configurations