Miko-Manifest

Declarative, hierarchical configuration and robust templating for Kubernetes manifests. Fast, deterministic, script‑friendly.

---

1. Purpose

Miko-Manifest unifies three concerns normally spread across ad‑hoc scripts:

1. Structured, hierarchical environment configuration (YAML with controlled merging).
2. Deterministic manifest generation via Go templates (single, repeated-in-file, or repeated-to-multiple-files patterns).
3. Integrated validation (YAML structure, Kubernetes schemas, and custom CRDs) before and after generation.

The result: repeatable builds, early failure detection, and transparent configuration provenance.

2. Quick Start

Easy installation (recommended):

curl -sSL https://raw.githubusercontent.com/jepemo/miko-manifest/main/install.sh | bash

Easy uninstallation:

curl -sSL https://raw.githubusercontent.com/jepemo/miko-manifest/main/install.sh | bash -s -- --uninstall

Alternative installations:

# Using Go
go install github.com/jepemo/miko-manifest@latest

# Using Docker
docker pull ghcr.io/jepemo/miko-manifest:latest

Check installation:

miko-manifest version

Scaffold a project:

miko-manifest init

Generate manifests for an environment:

miko-manifest build --env dev --output-dir output

Validate generated manifests:

miko-manifest validate --dir output

Inspect effective configuration (recommended before first build):

miko-manifest config --env dev --tree --verbose

For comprehensive flags and advanced scenarios consult: DOCS.md

3. Core Concepts (Essentials Only)

Concept	Summary
Hierarchical Resources	resources: lists files or directories. They are merged in order. Later variables override earlier ones. Includes and schema lists are concatenated (deduplicated logically).
Templates	Standard Go templates located under templates/. Supports: plain render, same-file repetition (multiple YAML docs), multi-file repetition (one output per list item).
Variables	Declared in config YAML (variables: as name/value pairs) or overridden with --var key=value at build time. Unified into a final map fed to templates.
Includes	include: drives which template(s) render and how (optionally with repeat + list).
Schemas	Optional schemas: entries (local file, directory, or URL). Used to validate generated manifests (including CRDs).
Output Modes	Standard (concise) vs --verbose (steps + context). Consistent across commands.

4. Typical Workflow

# (Optional) Understand configuration and inheritance
miko-manifest config --env dev --tree

# Lint configuration inputs early
miko-manifest check

# Generate manifests
miko-manifest build --env dev --output-dir output

# Validate output (YAML + Kubernetes + custom schemas)
miko-manifest validate --dir output

5. Minimal Example

config/dev.yaml:

variables:
  - name: app_name
    value: demo
include:
  - file: deployment.yaml

templates/deployment.yaml (fragment):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: { { .app_name } }
spec:
  replicas: 1
  template:
    spec:
      containers:
        - name: { { .app_name } }
          image: nginx:latest

Build:

miko-manifest build --env dev --output-dir output

Result: output/deployment.yaml

6. Command Overview (Condensed)

Command	Purpose	Typical Additions
init	Scaffold directories and example templates	–
config	Inspect merged configuration / schemas / tree / variables	--tree, --schemas, --variables, --verbose
check	Validate configuration YAML before build	--verbose
build	Render templates into manifest files	--var, --validate, --verbose
validate	Validate generated manifests (YAML + schemas)	--env, --skip-schema-validation, --verbose
version	Show version, commit and build information	–
version	Show version, commit hash, and build date	–

Complete flag descriptions: see DOCS.md.

7. Advanced Highlights

Topic	Detail
Deterministic Order	Directories processed alphabetically; merging order = declaration order.
Override Strategy	Variable last-write-wins; template includes accumulate; schemas aggregated (duplicates ignored).
Safety	Circular resource inclusion detection + maximum depth guard.
Auto Environment	build records environment; validate reuses it if --env omitted.
Schema Sources	Local file, directory (recursive), or remote URL (fetched once per run).

8. Docker & CI

Run without local toolchain:

# Check configuration
docker run --rm -v "$(pwd):/workspace" -w /workspace ghcr.io/jepemo/miko-manifest:latest check

# Build manifests
docker run --rm -v "$(pwd):/workspace" -w /workspace ghcr.io/jepemo/miko-manifest:latest build --env dev --output-dir output

# Validate generated manifests
docker run --rm -v "$(pwd):/workspace" -w /workspace ghcr.io/jepemo/miko-manifest:latest validate --dir output

Typical pipeline: check -> build -> validate. Minimal GitHub Actions and GitLab CI templates are provided in the documentation.

9. Development

For a reproducible, containerized development experience:

# Install miko-shell
curl -sSL https://raw.githubusercontent.com/jepemo/miko-shell/main/install.sh | bash

# Build development environment (auto-detects host architecture)
miko-shell image build

# Run tests
miko-shell run test
miko-shell run test-coverage

# Build binary
miko-shell run build          # Build for host architecture

# Code quality
miko-shell run lint
miko-shell run precommit      # All pre-commit checks

# Interactive development
miko-shell open              # Open shell in development environment

Benefits of miko-shell:

• ✅ Reproducible environment (same Go version, tools across all machines)
• ✅ No local dependencies (only Docker/Podman required)
• ✅ Cross-platform compatibility
• ✅ Automatic host architecture detection (MIKO_HOST_OS, MIKO_HOST_ARCH)

For more development details and programmatic usage, see DOCS.md.

10. Contributing

Contributions are welcome. Please open an issue to propose significant changes before submitting a pull request. Ensure tests cover new behaviour and run miko-shell run test locally.

11. License

MIT — see LICENSE.

---

Further detail (all flags, schema handling, repetition patterns, error modes): DOCS.md