wetwire-k8s 1.0.0
Kubernetes manifest synthesis for wetwire
Requires Python: >=3.11
Keywords: dataclasses, iac, infrastructure, k8s, kubernetes

# wetwire-k8s-python

[![CI](https://github.com/lex00/wetwire-k8s-python/actions/workflows/ci.yml/badge.svg)](https://github.com/lex00/wetwire-k8s-python/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/wetwire-k8s)](https://pypi.org/project/wetwire-k8s/)
[![Python](https://img.shields.io/pypi/pyversions/wetwire-k8s)](https://pypi.org/project/wetwire-k8s/)
[![Coverage](https://codecov.io/gh/lex00/wetwire-k8s-python/branch/main/graph/badge.svg)](https://codecov.io/gh/lex00/wetwire-k8s-python)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Python implementation of wetwire for Kubernetes manifests.

## Overview

wetwire-k8s enables defining Kubernetes resources using Python dataclasses, with full type safety and IDE support. Write your infrastructure as code with the power of Python, then generate production-ready Kubernetes YAML manifests.

**Key Features:**
- Type-safe Kubernetes resource definitions using Python dataclasses
- Full IDE support with autocomplete and inline documentation
- Generate, validate, and lint Kubernetes manifests
- Import existing YAML manifests to Python code
- AI-assisted design and validation
- Support for all core Kubernetes resources

## Installation

Install using pip or uv:

```bash
# Using pip
pip install wetwire-k8s

# Using uv (recommended for development)
uv pip install wetwire-k8s

# With all extras
pip install wetwire-k8s[dev,agent,mcp]
```

**Requirements:**
- Python 3.11 or higher
- kubectl (optional, for cluster validation)

## Quick Start

Create a Python file with your Kubernetes resources:

```python
from wetwire_k8s.resources.apps.v1 import Deployment
from wetwire_k8s.resources.core.v1 import Container, PodSpec, Service

# Define a Deployment
deployment = Deployment(
    metadata={
        "name": "my-app",
        "labels": {
            "app.kubernetes.io/name": "my-app",
            "app.kubernetes.io/version": "1.0.0"
        }
    },
    spec={
        "replicas": 3,
        "selector": {"matchLabels": {"app": "my-app"}},
        "template": {
            "metadata": {"labels": {"app": "my-app"}},
            "spec": PodSpec(
                containers=[
                    Container(
                        name="app",
                        image="nginx:1.21",
                        ports=[{"containerPort": 80}],
                        resources={
                            "requests": {"cpu": "100m", "memory": "128Mi"},
                            "limits": {"cpu": "500m", "memory": "512Mi"}
                        }
                    )
                ]
            )
        }
    }
)

# Define a Service
service = Service(
    metadata={"name": "my-app"},
    spec={
        "selector": {"app": "my-app"},
        "ports": [
            {"name": "http", "port": 80, "targetPort": 80}
        ],
        "type": "ClusterIP"
    }
)
```

Generate Kubernetes manifests:

```bash
# Build manifests from Python code
wetwire-k8s build my_app.py

# Validate resources
wetwire-k8s validate

# Lint for best practices
wetwire-k8s lint

# Apply to cluster
kubectl apply -f manifests/
```

## Commands

| Command | Description |
|---------|-------------|
| `wetwire-k8s build` | Generate Kubernetes manifests from Python code |
| `wetwire-k8s lint` | Lint Kubernetes definitions for best practices |
| `wetwire-k8s import` | Import existing YAML manifests to Python |
| `wetwire-k8s validate` | Validate resources against Kubernetes schemas |
| `wetwire-k8s list` | List available Kubernetes resources |
| `wetwire-k8s init` | Initialize a new wetwire-k8s project |
| `wetwire-k8s graph` | Generate dependency graph of resources |
| `wetwire-k8s design` | AI-assisted resource design |
| `wetwire-k8s test` | Run synthesis tests with AI personas |
| `wetwire-k8s diff` | Show differences between builds |
| `wetwire-k8s watch` | Watch for changes and rebuild automatically |

See the [CLI documentation](docs/CLI.md) for detailed command reference.

## Documentation

- [CLAUDE.md](CLAUDE.md) - AI assistant context and development guide
- [CLI Reference](docs/CLI.md) - Complete command documentation
- [FAQ](docs/FAQ.md) - Common questions and troubleshooting
- [Lint Rules](docs/LINT_RULES.md) - Comprehensive lint rule reference

## Why wetwire-k8s?

### Type Safety and IDE Support

```python
# Catch errors before deployment
deployment = Deployment(
    metadata={"name": "my-app"},
    spec={
        "replicas": "three",  # Type error caught by IDE!
        ...
    }
)
```

### Code Reuse and Modularity

```python
# Define reusable components
def create_deployment(name: str, image: str, replicas: int = 3):
    return Deployment(
        metadata={"name": name},
        spec={
            "replicas": replicas,
            "selector": {"matchLabels": {"app": name}},
            "template": {
                "metadata": {"labels": {"app": name}},
                "spec": PodSpec(
                    containers=[Container(name=name, image=image)]
                )
            }
        }
    )

# Use across multiple environments
dev_deployment = create_deployment("my-app", "myapp:dev", replicas=1)
prod_deployment = create_deployment("my-app", "myapp:1.0.0", replicas=5)
```

### Validation and Best Practices

```bash
# Lint catches common issues
$ wetwire-k8s lint
[WK8100] Warning: Container running as root (deployment.py:15)
[WK8200] Warning: Missing resource requests (deployment.py:20)
[WK8300] Warning: Missing liveness probe (deployment.py:25)
```

## Examples

### Deployment with ConfigMap

```python
from wetwire_k8s.resources.apps.v1 import Deployment
from wetwire_k8s.resources.core.v1 import ConfigMap, Container, PodSpec

# Create ConfigMap
config = ConfigMap(
    metadata={"name": "app-config"},
    data={
        "app.json": '{"debug": false, "port": 8080}'
    }
)

# Reference in Deployment
deployment = Deployment(
    metadata={"name": "my-app"},
    spec={
        "replicas": 2,
        "selector": {"matchLabels": {"app": "my-app"}},
        "template": {
            "metadata": {"labels": {"app": "my-app"}},
            "spec": PodSpec(
                containers=[
                    Container(
                        name="app",
                        image="myapp:1.0.0",
                        volumeMounts=[
                            {"name": "config", "mountPath": "/config"}
                        ]
                    )
                ],
                volumes=[
                    {
                        "name": "config",
                        "configMap": {"name": "app-config"}
                    }
                ]
            )
        }
    }
)
```

### Import Existing YAML

```bash
# Convert YAML to Python
wetwire-k8s import deployment.yaml --output deployment.py

# Edit in Python with type safety
# Then rebuild
wetwire-k8s build deployment.py
```

## Integration

### CI/CD Pipeline

```yaml
# GitHub Actions example
- name: Generate and validate manifests
  run: |
    pip install wetwire-k8s
    wetwire-k8s build --output manifests/
    wetwire-k8s validate --strict
    wetwire-k8s lint --severity error

- name: Apply to cluster
  run: kubectl apply -f manifests/
```

### Claude Desktop (MCP)

Install the MCP server for AI-assisted Kubernetes development:

```bash
pip install wetwire-k8s[mcp]
```

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "wetwire-k8s": {
      "command": "wetwire-k8s-mcp"
    }
  }
}
```

## Development

```bash
# Clone repository
git clone https://github.com/lex00/wetwire-k8s-python.git
cd wetwire-k8s-python

# Install dependencies with uv
uv sync --all-extras

# Install pre-commit hooks
pre-commit install

# Run tests
uv run pytest

# Run linter
uv run ruff check

# Format code
uv run ruff format
```

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Related Projects

- [wetwire-core](https://github.com/lex00/wetwire-core) - Core wetwire abstractions
- [wetwire-terraform-python](https://github.com/lex00/wetwire-terraform-python) - Terraform domain
- [wetwire-pulumi-python](https://github.com/lex00/wetwire-pulumi-python) - Pulumi domain

## License

MIT - See [LICENSE](LICENSE) for details.

## Support

- [Documentation](https://github.com/lex00/wetwire-k8s-python#readme)
- [Issue Tracker](https://github.com/lex00/wetwire-k8s-python/issues)
- [Discussions](https://github.com/lex00/wetwire-k8s-python/discussions)