{"id":47768475,"url":"https://github.com/kitstream/initium","last_synced_at":"2026-04-03T08:01:53.076Z","repository":{"id":340212912,"uuid":"1165058403","full_name":"KitStream/initium","owner":"KitStream","description":"Swiss-army toolbox for Kubernetes initContainers","archived":false,"fork":false,"pushed_at":"2026-03-11T23:21:05.000Z","size":208,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-12T01:59:04.947Z","etag":null,"topics":["cloud-native","container","database-seeding","devops","initcontainer","kubernetes","kubernetes-tools","migration","rust","sidecar"],"latest_commit_sha":null,"homepage":"https://github.com/KitStream/initium#readme","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KitStream.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-23T19:27:50.000Z","updated_at":"2026-03-11T23:21:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/KitStream/initium","commit_stats":null,"previous_names":["kitstream/initium"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/KitStream/initium","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KitStream%2Finitium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KitStream%2Finitium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KitStream%2Finitium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KitStream%2Finitium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KitStream","download_url":"https://codeload.github.com/KitStream/initium/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KitStream%2Finitium/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31342716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T06:57:30.245Z","status":"ssl_error","status_checked_at":"2026-04-03T06:57:29.849Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud-native","container","database-seeding","devops","initcontainer","kubernetes","kubernetes-tools","migration","rust","sidecar"],"created_at":"2026-04-03T08:00:47.204Z","updated_at":"2026-04-03T08:01:53.069Z","avatar_url":"https://github.com/KitStream.png","language":"Rust","readme":"# Initium\n\n**Swiss-army toolbox for Kubernetes initContainers.**\n\nInitium replaces fragile bash scripts in your initContainers with a single, security-hardened, multi-tool binary. Wait for dependencies, seed databases, render config files, fetch secrets, and more — all with structured logging, retries, and safe defaults.\n\n[![CI](https://github.com/kitstream/initium/actions/workflows/ci.yml/badge.svg)](https://github.com/kitstream/initium/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n\n## Features\n\n- **Single static binary** — zero runtime dependencies, built `FROM scratch`\n- **Tiny image** — ~5 MB multi-arch container (amd64 + arm64)\n- **Zero CVEs** — no OS packages, no shell, no attack surface\n- **PSA `restricted` compatible** — runs as non-root (UID 65534), read-only filesystem, all capabilities dropped\n- **Sidecar mode** — `--sidecar` flag keeps the process alive for use as a Kubernetes sidecar container\n- **Structured logging** — JSON or text output with automatic secret redaction\n- **Retries with backoff** — exponential backoff, jitter, and configurable deadlines on all network operations\n- **Declarative database seeding** — YAML/JSON specs with MiniJinja templating, cross-table references, and idempotency\n- **Multi-database support** — PostgreSQL, MySQL, and SQLite drivers (optional Cargo features)\n- **Environment variable config** — all flags configurable via `INITIUM_*` env vars\n\n## Quickstart\n\n### Wait for Postgres before starting your app\n\n```yaml\ninitContainers:\n  - name: wait-for-postgres\n    image: ghcr.io/kitstream/initium:latest\n    args:\n      - wait-for\n      - --target\n      - tcp://postgres:5432\n      - --timeout\n      - \"120s\"\n    securityContext:\n      runAsNonRoot: true\n      runAsUser: 65534\n      readOnlyRootFilesystem: true\n      allowPrivilegeEscalation: false\n      capabilities:\n        drop: [ALL]\n```\n\n### Apply a full example\n\n```bash\nkubectl apply -f https://raw.githubusercontent.com/kitstream/initium/main/examples/nginx-waitfor/deployment.yaml\n```\n\n## Why Initium?\n\n|                           | Bash scripts                     | Initium                            |\n| ------------------------- | -------------------------------- | ---------------------------------- |\n| **Retries with backoff**  | DIY, error-prone                 | Built-in, configurable             |\n| **Structured logging**    | `echo` statements                | JSON or text with timestamps       |\n| **Security**              | Runs as root, full shell         | Non-root, no shell, read-only FS   |\n| **Secret handling**       | Easily leaked in logs            | Automatic redaction                |\n| **Multiple tools**        | Install curl, netcat, psql…      | Single small image                 |\n| **Reproducibility**       | Shell differences across distros | Single Rust binary, `FROM scratch` |\n| **Vulnerability surface** | Full OS + shell utils            | Zero OS packages                   |\n\n## Subcommands\n\n| Command    | Description                                                          | Status       |\n| ---------- | -------------------------------------------------------------------- | ------------ |\n| `wait-for` | Wait for TCP/HTTP/HTTPS endpoints                                    | ✅ Available |\n| `seed`     | Structured database seeding from YAML/JSON with MiniJinja templating | ✅ Available |\n| `render`   | Render config templates                                              | ✅ Available |\n| `fetch`    | Fetch secrets/config from HTTP                                       | ✅ Available |\n| `exec`     | Run commands with structured logging                                 | ✅ Available |\n\n### wait-for\n\n```bash\n# Wait for a TCP endpoint\ninitium wait-for --target tcp://postgres:5432\n\n# Wait for an HTTP health check\ninitium wait-for --target http://api:8080/healthz\n\n# Wait for multiple endpoints\ninitium wait-for \\\n  --target tcp://postgres:5432 \\\n  --target tcp://redis:6379 \\\n  --target http://config:8080/healthz\n\n# HTTPS with self-signed certificates\ninitium wait-for --target https://vault:8200/v1/sys/health --insecure-tls\n```\n\n## Cargo Features\n\nDatabase drivers are optional Cargo features, all enabled by default. Disable unused drivers for a smaller binary:\n\n```bash\n# All drivers (default)\ncargo build --release\n\n# PostgreSQL + SQLite only (no MySQL)\ncargo build --release --no-default-features --features postgres,sqlite\n\n# SQLite only (smallest binary)\ncargo build --release --no-default-features --features sqlite\n```\n\n| Feature    | Default | Description          |\n| ---------- | ------- | -------------------- |\n| `sqlite`   | ✅      | SQLite driver        |\n| `postgres` | ✅      | PostgreSQL driver    |\n| `mysql`    | ✅      | MySQL/MariaDB driver |\n\n## Helm Chart\n\nThe Helm chart makes it easy to inject Initium initContainers into your deployments.\n\n```bash\nhelm install my-app charts/initium \\\n  --set sampleDeployment.enabled=true \\\n  --set 'initContainers[0].name=wait-for-db' \\\n  --set 'initContainers[0].command[0]=wait-for' \\\n  --set 'initContainers[0].args[0]=--target' \\\n  --set 'initContainers[0].args[1]=tcp://postgres:5432'\n```\n\nSee [`charts/initium/values.yaml`](charts/initium/values.yaml) for all options.\n\n## Security\n\nInitium is designed to run in security-restricted environments:\n\n- **Non-root**: Runs as UID 65534 (nobody)\n- **Read-only filesystem**: Compatible with `readOnlyRootFilesystem: true`\n- **No capabilities**: Drops all Linux capabilities\n- **No shell**: Commands executed via `execve`, not through a shell\n- **Secret redaction**: Sensitive values automatically redacted in logs\n- **Minimal image**: Built `FROM scratch` — zero OS packages, zero CVEs\n- **PSA `restricted`**: Fully compatible with the Kubernetes restricted Pod Security Standard\n\nSee [docs/security.md](docs/security.md) for the full threat model and [SECURITY.md](SECURITY.md) for vulnerability reporting.\n\n## FAQ\n\n### How do I wait for Postgres?\n\n```yaml\ninitContainers:\n  - name: wait-for-postgres\n    image: ghcr.io/kitstream/initium:latest\n    args: [\"wait-for\", \"--target\", \"tcp://postgres:5432\", \"--timeout\", \"120s\"]\n```\n\nInitium will retry connecting to `postgres:5432` with exponential backoff until it succeeds or the timeout is reached.\n\n### How do I wait for multiple services?\n\nPass multiple `--target` flags. They are checked sequentially:\n\n```yaml\nargs:\n  - wait-for\n  - --target\n  - tcp://postgres:5432\n  - --target\n  - tcp://redis:6379\n  - --target\n  - http://config-service:8080/healthz\n```\n\n### How do I seed data?\n\nUse the `seed` subcommand with a YAML/JSON spec file that defines your seed data declaratively:\n\n```yaml\ninitContainers:\n  - name: seed-data\n    image: ghcr.io/kitstream/initium:latest\n    args: [\"seed\", \"--spec\", \"/seeds/seed.yaml\"]\n    env:\n      - name: DATABASE_URL\n        valueFrom:\n          secretKeyRef:\n            name: db-credentials\n            key: url\n    volumeMounts:\n      - name: seed-specs\n        mountPath: /seeds\n        readOnly: true\n```\n\nSee [docs/seeding.md](docs/seeding.md) for the full schema, features, and examples.\n\n### How do I render config templates?\n\nUse the `render` subcommand with environment variable substitution:\n\n```yaml\ninitContainers:\n  - name: render-config\n    image: ghcr.io/kitstream/initium:latest\n    args: [\n      \"render\",\n      \"--template\",\n      \"/templates/app.conf.tmpl\",\n      \"--output\",\n      \"app.conf\",\n      \"--workdir\",\n      \"/work\",\n    ]\n    env:\n      - name: DB_HOST\n        value: postgres\n```\n\n### How do I run initium as a sidecar container?\n\nUse the `--sidecar` global flag to keep the process alive after tasks complete:\n\n```yaml\ncontainers:\n  - name: initium-sidecar\n    image: ghcr.io/kitstream/initium:latest\n    restartPolicy: Always\n    args: [\"--sidecar\", \"wait-for\", \"--target\", \"tcp://postgres:5432\"]\n```\n\nThe process sleeps indefinitely after success. On failure it exits with code `1` immediately.\n\n### How do I get JSON logs?\n\nAdd the `--json` global flag:\n\n```yaml\nargs: [\"--json\", \"wait-for\", \"--target\", \"tcp://postgres:5432\"]\n```\n\nOutput: `{\"time\":\"2025-01-15T10:30:00Z\",\"level\":\"INFO\",\"msg\":\"target is reachable\",\"target\":\"tcp://postgres:5432\",\"attempts\":\"1\"}`\n\n### How do I allow self-signed TLS certificates?\n\nUse `--insecure-tls` (must be explicitly opted in):\n\n```yaml\nargs: [\n  \"wait-for\",\n  \"--target\",\n  \"https://vault:8200/v1/sys/health\",\n  \"--insecure-tls\",\n]\n```\n\n### Can I use Initium outside Kubernetes?\n\nYes. Initium is a standalone binary. Use it in Docker Compose, CI pipelines, or anywhere you need to wait for services:\n\n```bash\ndocker run --rm ghcr.io/kitstream/initium:latest wait-for --target tcp://db:5432\n```\n\n### Does Initium need special permissions?\n\nNo. Initium runs as a non-root user with no capabilities and a read-only filesystem. It is compatible with the Kubernetes `restricted` Pod Security Standard.\n\n### How do I customize retry behavior?\n\nAll retry parameters are configurable:\n\n```yaml\nargs:\n  - wait-for\n  - --target\n  - tcp://postgres:5432\n  - --max-attempts\n  - \"30\"\n  - --initial-delay\n  - \"500ms\"\n  - --max-delay\n  - \"10s\"\n  - --backoff-factor\n  - \"1.5\"\n  - --jitter\n  - \"0.2\"\n```\n\n## Examples\n\n- [**nginx-waitfor**](examples/nginx-waitfor/): Nginx deployment waiting for a backend service\n- [**postgres-seed**](examples/postgres-seed/): Wait → Seed workflow with PostgreSQL\n- [**config-render**](examples/config-render/): Render config from templates before app starts\n\n## How to Run Locally\n\n```bash\n# Build\nmake build\n\n# Run wait-for against a local service\n./bin/initium wait-for --target tcp://localhost:5432 --max-attempts 5\n\n# Run with JSON logs\n./bin/initium --json wait-for --target http://localhost:8080/healthz\n\n# Run all tests\nmake test\n```\n\n## How to Try in a Cluster\n\n```bash\n# Option 1: Use the pre-built image\nkubectl apply -f examples/nginx-waitfor/deployment.yaml\n\n# Option 2: Cross-build and push multi-arch images\nmake docker-multiarch VERSION=dev\n\n# Option 3: Use the Helm chart\nhelm install my-app charts/initium \\\n  --set sampleDeployment.enabled=true \\\n  --set 'initContainers[0].name=wait-db' \\\n  --set 'initContainers[0].command[0]=wait-for' \\\n  --set 'initContainers[0].args[0]=--target' \\\n  --set 'initContainers[0].args[1]=tcp://postgres:5432'\n```\n\n## Alternatives\n\nInitium was built to address limitations in existing init container tools:\n\n| Tool                                                       | Language | Image size  | Multi-tool | Database seeding | Security posture         |\n| ---------------------------------------------------------- | -------- | ----------- | ---------- | ---------------- | ------------------------ |\n| **Initium**                                                | Rust     | ~5 MB       | Yes        | Yes              | PSA `restricted`, no OS  |\n| [wait-for-it](https://github.com/vishnubob/wait-for-it)    | Bash     | Needs shell | No         | No               | Requires shell + netcat  |\n| [dockerize](https://github.com/jwilder/dockerize)          | Go       | ~17 MB      | Partial    | No               | Full OS image            |\n| [k8s-wait-for](https://github.com/groundnuty/k8s-wait-for) | Bash     | Needs shell | No         | No               | Requires shell + kubectl |\n| [wait4x](https://github.com/atkrad/wait4x)                 | Go       | ~12 MB      | No         | No               | Minimal OS               |\n\nIf you only need TCP/HTTP readiness checks, any of these tools work. Initium is designed for teams that also need seeding, config rendering, and secret fetching in a single security-hardened binary.\n\n## Documentation\n\n- [FAQ](FAQ.md) — Common questions about functionality, security, and deployment\n- [Usage Guide](docs/usage.md) — All subcommands, flags, and examples\n- [Security](docs/security.md) — Threat model, safe defaults, PSA compatibility\n- [Architecture \u0026 Design](docs/design.md) — How Initium works and how to extend it\n\n## Development\n\n### Prerequisites\n\n- [Rust toolchain](https://rustup.rs/) with musl targets:\n  ```bash\n  rustup target add x86_64-unknown-linux-musl aarch64-unknown-linux-musl\n  ```\n- [Zig](https://ziglang.org/) for cross-compilation: `brew install zig`\n- [cargo-zigbuild](https://github.com/rust-cross/cargo-zigbuild): `cargo install cargo-zigbuild`\n- (Optional) [sccache](https://github.com/mozilla/sccache) for build caching across worktrees:\n  ```bash\n  brew install sccache\n  export RUSTC_WRAPPER=sccache\n  ```\n\n### Cross-compile for linux/amd64 and linux/arm64\n\n```bash\nmake cross-build\nfile bin/initium-amd64 bin/initium-arm64\n```\n\n### Build and push multi-arch Docker images\n\n```bash\nmake docker-multiarch VERSION=dev IMAGE=ghcr.io/kitstream/initium\n```\n\nThis runs `cross-build` then uses `docker buildx` to assemble and push multi-arch images for both `initium` (scratch) and `initium-jyq` (alpine + jq/yq).\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions, test commands, and PR expectations. See the [design doc](docs/design.md) for how to add new subcommands.\n\n## License\n\n[Apache License 2.0](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitstream%2Finitium","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkitstream%2Finitium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitstream%2Finitium/lists"}