pykustomize

Python bindings for Kustomize - Kubernetes configuration customization.

pykustomize provides a complete Python wrapper for the Kustomize Go API, enabling you to build and customize Kubernetes configurations directly from Python. Following the architecture pattern of helm-sdkpy, it creates a self-contained package with no system dependencies.

✨ Features

• 🚀 Async-first API - All operations use Python's async/await for non-blocking execution
• 📦 Self-contained - Bundles the Go library, no external kustomize binary needed
• 🔒 Type-safe - Full type hints for IDE support and static analysis
• 🎯 Simple API - Easy-to-use interface mirroring kustomize functionality
• ⚡ Fast - Native Go performance through FFI

📦 Installation

pip install pykustomize

The wheel bundles the Kustomize Go library for Linux x86_64; no kustomize binary is needed.

📖 Documentation

Full documentation, including the generated Python and Go shim reference, is at https://docs.vantagecompute.ai/developer/pykustomize/ (sources in docusaurus/).

🚀 Quick Start

import asyncio
from pykustomize import build, build_json, BuildOptions, LoadRestrictions

async def main():
    # Simple build - returns YAML
    result = await build("/path/to/kustomization")
    print(result.yaml)
    
    # Build with options
    options = BuildOptions(
        load_restrictions=LoadRestrictions.NONE,
        add_managedby_label=True,
    )
    result = await build("/path/to/overlay", options)
    
    # Build to JSON for programmatic access
    result_json = await build_json("/path/to/kustomization")
    for resource in result_json.resources:
        print(f"{resource['kind']}: {resource['metadata']['name']}")

asyncio.run(main())

📚 API Reference

Kustomizer

The main class for performing kustomize operations.

from pykustomize import Kustomizer, BuildOptions

kustomizer = Kustomizer()

# Build and get YAML
result = await kustomizer.build("/path/to/kustomization")
print(result.yaml)

# Build and get JSON
result = await kustomizer.build_json("/path/to/kustomization")
for resource in result.resources:
    print(resource)

# Get available plugins
plugins = await kustomizer.get_builtin_plugins()
print(plugins)

BuildOptions

Configure how kustomize processes the kustomization.

from pykustomize import BuildOptions, LoadRestrictions, ReorderOption

options = BuildOptions(
    # Control file loading (ROOT_ONLY is secure default)
    load_restrictions=LoadRestrictions.ROOT_ONLY,
    
    # Control output ordering
    reorder=ReorderOption.LEGACY,
    
    # Add managed-by label
    add_managedby_label=True,
    
    # Enable plugins
    enable_plugins=False,
    
    # Enable Helm chart inflation
    enable_helm=False,
    helm_command="/usr/local/bin/helm",
)

LoadRestrictions

Controls what files can be loaded during kustomization.

ReorderOption

Controls the order of resources in the output.

Convenience Functions

For simple use cases, use the module-level functions:

from pykustomize import build, build_json

# Build to YAML
result = await build("/path/to/kustomization")

# Build to JSON
result = await build_json("/path/to/kustomization")

🛠️ Development

Prerequisites: Python 3.14, uv, just and Docker.

git clone https://github.com/vantagecompute/pykustomize.git
cd pykustomize
just env          # create the virtual environment
just build-lib    # build the native library in Docker
just check        # lint, typecheck, build the library and run the tests

Run just to list every recipe. See the development guide and release process.

🏗️ Architecture

pykustomize follows a three-layer architecture:

┌─────────────────────────────────────┐
│     Python Application              │
│  (async/await, type hints)          │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│     Python Layer (pykustomize)      │
│  - Kustomizer class                 │
│  - BuildOptions configuration       │
│  - Exception hierarchy              │
└──────────────┬──────────────────────┘
               │ asyncio.to_thread()
┌──────────────▼──────────────────────┐
│     FFI Layer (CFFI)                │
│  - C function bindings              │
│  - Type marshalling                 │
│  - Error handling                   │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│     Go Shim Layer (CGO)             │
│  - Wraps kustomize/api/krusty       │
│  - Thread-safe with mutex           │
│  - JSON serialization               │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│     Kustomize Go Library            │
│  sigs.k8s.io/kustomize/api          │
└─────────────────────────────────────┘

📝 Examples

See the examples/ directory for more usage examples.

📝 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright 2025 Vantage Compute

🤝 Contributing

Contributions welcome! Please ensure:

• Code follows existing style (ruff formatting)
• Tests pass and coverage is maintained
• Type hints are included
• Documentation is updated