If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/kubernetes/kompose shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3w ago
• 16 active contributors
• Distributed ownership (top contributor 32% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live kubernetes/kompose repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kubernetes/kompose.

What it runs against: a local clone of kubernetes/kompose — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in kubernetes/kompose | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 51 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of kubernetes/kompose. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/kubernetes/kompose.git
#   cd kompose
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of kubernetes/kompose and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kubernetes/kompose(\\.git)?\\b" \\
  && ok "origin remote is kubernetes/kompose" \\
  || miss "origin remote is not kubernetes/kompose (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "client/convert.go" \\
  && ok "client/convert.go" \\
  || miss "missing critical file: client/convert.go"
test -f "cmd/convert.go" \\
  && ok "cmd/convert.go" \\
  || miss "missing critical file: cmd/convert.go"
test -f "client/client.go" \\
  && ok "client/client.go" \\
  || miss "missing critical file: client/client.go"
test -f "client/types.go" \\
  && ok "client/types.go" \\
  || miss "missing critical file: client/types.go"
test -f "cmd/root.go" \\
  && ok "cmd/root.go" \\
  || miss "missing critical file: cmd/root.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 51 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~21d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/kubernetes/kompose"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Kompose is a CLI tool that converts Docker Compose YAML files into Kubernetes manifests (Deployments, Services, ConfigMaps, etc.). It bridges the gap for developers familiar with docker-compose who need to deploy to Kubernetes by automatically translating service definitions, volumes, environment variables, and networking rules from Compose format to idiomatic Kubernetes YAML. Monolithic CLI application: cmd/ contains command handlers (convert.go, completion.go, root.go), client/ houses the core conversion logic (convert.go does the actual Docker Compose → Kubernetes transformation), and client/testdata/ provides docker-compose.yaml fixtures for testing. The main entry point wires commands via Cobra (codegangsta/negroni in dependencies).

DevOps engineers and application developers transitioning from Docker Compose-based local development to Kubernetes orchestration; teams migrating existing Compose configurations to production-grade Kubernetes clusters without manual manifest rewriting.

Production-ready and actively maintained. The project is part of the official Kubernetes organization, follows Go best practices (golangci.yml linting, GitHub Actions CI/CD), includes comprehensive test coverage (client/convert_test.go, testdata fixtures), and maintains a regular 3-week release cycle. Last activity and issue tracking indicate ongoing community engagement.

Low risk for core functionality; the tool is battle-tested in the Kubernetes ecosystem. Main considerations: conversion is not always exact (noted in README as 'may not be exact'), complex Compose features may not translate perfectly to Kubernetes idioms, and the tool depends on accurate Compose Specification compliance. No apparent single-maintainer dependency issues given Kubernetes org backing.

Active development with CI/CD pipelines (GitHub Actions in .github/workflows for go.yml, lint.yml, test.yml), security scanning via OpenVEX, and dependabot maintenance (dependabot.yaml). Recent work includes profile support (docker-compose-profiles.yaml in testdata) and ongoing test coverage expansion. No breaking changes visible in standard release cadence.

git clone https://github.com/kubernetes/kompose.git
cd kompose
make build
./kompose convert -f examples/compose.yaml

Requires Go 1.21.2+ (from go.mod); make targets are available in the Makefile for compilation and testing.

Daily commands:

make build          # Builds binary to ./kompose
make test           # Runs Go test suite
make install        # Installs to /usr/local/bin
./kompose convert -f <compose-file.yaml>

Development feedback loop: edit Go files in client/ or cmd/, run make build && ./kompose convert with test fixtures in client/testdata/.

• client/convert.go — Core conversion logic that transforms Docker Compose specifications into Kubernetes resources; essential entry point for the kompose library.
• cmd/convert.go — CLI command handler for the convert operation; shows how to invoke the conversion pipeline and handle user-facing options.
• client/client.go — Main client interface that orchestrates the conversion workflow; required to understand the public API and service initialization.
• client/types.go — Type definitions for Compose and Kubernetes resources; foundational data structures used throughout the codebase.
• cmd/root.go — Root CLI command setup using Cobra; defines the entry point and global configuration for all kompose commands.
• README.md — Project overview and usage examples; critical for understanding the tool's purpose, scope, and supported workflows.

• CLI Layer (cmd/*) (Cobra CLI framework, Go flag parsing) — Parses user input, manages flags and options, invokes client library, and formats output for terminal or file system.
  • Failure mode: Missing or invalid CLI flags, file I/O errors, malformed command invocation.
• Client Library (client/client.go) (Go interfaces, error handling) — Orchestrates the overall conversion workflow, managing options, reading input, invoking conversion engine, and writing output.
  • Failure mode: Invalid input files, unsupported Compose versions, resource validation failures.
• Conversion Engine (client/convert.go) (YAML marshaling, Kubernetes manifest generation) — Core transformation logic mapping Compose primitives (services, networks, volumes) to Kubernetes resources (Deployments, Services, PersistentVolumes).
  • Failure mode: Unsupported Compose fields, conflicting resource constraints, unrepresentable configurations.
• Type System (client/types.go) (Go struct tags, JSON/YAML marshaling directives) — Defines Go struct representations of Compose and Kubernetes resources, enabling type-safe transformation and serialization.
  • Failure mode: Struct definition mismatches with actual Compose/Kubernetes specs, serialization errors.
• Options Handler (client/options.go) (Go option pattern, validation logic) — Manages conversion configuration and behavior flags, providing defaults and validation for user-supplied options.
  • Failure mode: Invalid option combinations, missing required parameters.

• User filesystem → CLI layer (cmd/convert.go) — Docker Compose YAML file provided via -f flag or environment.
• CLI layer → Client library (client/client.go) — Parsed command-line options and file path passed to conversion client.
• Client library → Conversion engine (client/convert.go) — Parsed Compose structures and options passed to transformation logic.
• Conversion engine → Type system (client/types.go) — Intermediate Compose objects mapped to

Add support for a new Compose field

1. Define the field in the appropriate type struct (e.g., service, volume, network) (client/types.go)
2. Add parsing logic in the conversion function to extract and map the field (client/convert.go)
3. Add a test case to verify the field is correctly converted to Kubernetes resources (client/convert_test.go)

Add a new CLI command or option

1. Define the command struct and flag options following Cobra conventions (cmd/root.go)
2. Create a new file in the cmd directory for the command implementation (cmd/convert.go)
3. Update the client options to support the new configuration parameter (client/options.go)
4. Add integration tests in the cmd tests to verify CLI behavior (client/convert_test.go)

Extend conversion with custom Kubernetes resource transformation

1. Add helper types or structures to support the new transformation logic (client/types.go)
2. Implement the transformation function and integrate it into the conversion pipeline (client/convert.go)
3. Add test cases with sample Compose files demonstrating the feature (client/testdata)

Update the conversion options or behavior

1. Add the new option field and default value to the options structure (client/options.go)
2. Update the conversion logic to use the new option parameter (client/convert.go)
3. Expose the option via CLI flag in the convert command (cmd/convert.go)

• Go 1.21.2 — Compiled language enabling fast, single-binary distribution; strong standard library for YAML/JSON parsing and CLI tooling.
• Cobra (CLI framework) — Mature Go CLI framework with built-in flag parsing, help generation, and shell completion support for professional CLI UX.
• YAML/JSON marshaling — Native Go support for Compose and Kubernetes manifest serialization/deserialization without heavy external dependencies.

• Direct YAML-to-Kubernetes conversion without intermediate DSL

  • Why: Simpler implementation path, lower learning curve, and faster transformation for common cases.
  • Consequence: Complex or non-standard Compose files may require manual post-conversion fixes; not all Compose features map cleanly to Kubernetes primitives.

• Single-pass conversion without multiple transformation stages

  • Why: Faster execution and simpler codebase with fewer moving parts.
  • Consequence: Limited ability to apply complex orchestration rules or cross-resource dependencies; harder to optimize generated manifests.

• Kompose as a convenience tool rather than production-grade translator

  • Why: Clear scope boundaries, faster time-to-usefulness, and lower maintenance burden.
  • Consequence: Users must validate and potentially refactor generated Kubernetes manifests before production use; not suitable for automated CI/CD conversion without manual review.

• Real-time Kubernetes deployment orchestration or cluster management
• Enforcement of Kubernetes security policies or RBAC configurations
• Automatic performance tuning or resource optimization
• Full feature parity with Docker Compose (e.g., build-time only features)
• Support for custom Compose extensions beyond Compose Specification
• Container image building or registry interaction

Compose Specification compliance: the tool expects valid docker-compose files following the official spec—non-standard extensions may be silently dropped or cause unexpected behavior. Conversion lossy for some features (e.g., build context, non-Kubernetes-compatible networking modes). Environment variable ordering and interpolation may differ between Compose and Kubernetes. No automatic namespace creation; users must ensure target Kubernetes namespace exists before applying generated manifests. Healthchecks in Compose map to Kubernetes probes but may not perfectly replicate timing or failure behavior.

• Docker Compose Specification (Compose Spec) — Kompose's entire purpose is parsing and transforming Compose Spec YAML; understanding the spec (services, volumes, networks, environment, healthchecks) is essential to predict what the tool will convert
• Kubernetes Resource Manifests (YAML/API Objects) — The output of kompose is Kubernetes YAML; contributors must understand Deployments, Services, ConfigMaps, and PersistentVolumeClaims to validate correct conversion behavior
• Visitor/Transformation Pattern — Kompose uses a conversion pipeline that visits Compose service definitions and transforms them into Kubernetes resources; recognizing this pattern aids understanding code flow in client/convert.go
• Cobra CLI Framework — Kompose CLI commands (convert, completion, version) are built with Cobra; contributors adding new flags or commands must understand Cobra's command, flag, and subcommand structure
• YAML Marshalling and Schema Validation — Kompose reads unstructured Compose YAML and outputs structured Kubernetes YAML; understanding Go's yaml/json struct tags and validation patterns is critical for adding new field mappings
• Lossy Conversion and Mapping Gaps — Not all Compose features map 1:1 to Kubernetes concepts (e.g., build context, service dependencies); understanding these gaps prevents contributors from implementing impossible conversions
• Kubernetes Init Containers and Sidecar Patterns — Complex Compose service relationships and startup ordering sometimes map to Kubernetes init containers or sidecars; recognizing when to use these patterns improves conversion accuracy

• docker/compose — Official Docker Compose reference implementation; kompose depends on understanding the Compose Specification this project defines
• kubernetes/kubernetes — The target platform; kompose generates Kubernetes manifests compatible with the core API objects defined here
• compose-spec/compose-spec — Canonical Compose Specification standard; kompose implements parsing and validation against this spec
• stakater/Reloader — Complementary Kubernetes tool for auto-reloading deployments on ConfigMap/Secret changes—often used with kompose-generated manifests
• kubectx/kubectx — Context/namespace switching utility frequently paired with kompose workflows for managing converted Kubernetes deployments across clusters

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for Docker Compose profile support

The repo has a test data file client/testdata/docker-compose-profiles.yaml but lacks corresponding integration tests in client/convert_test.go. Compose profiles are a key feature for environment-specific configurations, and thorough testing would ensure the conversion handles them correctly across different Kubernetes scenarios.

• [ ] Review client/testdata/docker-compose-profiles.yaml to understand profile structure
• [ ] Examine existing tests in client/convert_test.go to understand test patterns
• [ ] Add unit tests for profile parsing in client/convert_test.go
• [ ] Add integration tests that verify profiles are correctly converted to Kubernetes resources
• [ ] Test edge cases: missing profiles, invalid profile names, conflicting profile configurations

Implement pre-commit hooks validation in CI workflow

The repo has .pre-commit-config.yaml configured but no GitHub Actions workflow validates that contributors run pre-commit checks before submission. Adding this to .github/workflows/lint.yml would catch linting, formatting, and security issues automatically and reduce back-and-forth on PRs.

• [ ] Review .pre-commit-config.yaml to understand configured hooks (likely Go formatting, linting)
• [ ] Check .github/workflows/lint.yml for current linting steps
• [ ] Add a pre-commit GitHub Action step that runs all configured hooks in CI
• [ ] Ensure the workflow fails if pre-commit checks fail
• [ ] Document in CONTRIBUTING.md that developers should install and run pre-commit locally

Add tests for kompose command-line options in cmd/ package

The cmd/ directory contains core CLI commands (convert.go, completion.go, root.go, options.go) but options_test.go is minimal. Given that client/options_test.go exists, there's an inconsistency. Adding comprehensive CLI option parsing tests would catch regressions in argument handling and flag validation.

• [ ] Review cmd/options.go to identify all supported flags and their validation logic
• [ ] Check cmd/convert.go to understand how options are used in the conversion command
• [ ] Expand cmd/options_test.go with tests for: invalid flag combinations, mutually exclusive options, default values
• [ ] Add tests for completion functionality in cmd/completion.go (currently untested)
• [ ] Cross-reference with client/options_test.go to ensure consistent test coverage patterns

• Add conversion support for healthcheck.start_period from docker-compose.yaml (Compose spec feature not yet in Kubernetes probe mapping in client/convert.go); would involve updating the struct in client/types.go and adding test cases in client/convert_test.go
• Expand test coverage for docker-compose-profiles.yaml feature (profiles support added but testdata fixture present with minimal test assertions in client/convert_test.go); add test cases validating profile filtering and selective service inclusion
• Document conversion limitations and warnings in a new CONVERSION_GUIDE.md (README mentions 'may not be exact' but lacks concrete examples); catalog known gaps like unsupported Compose keywords and their Kubernetes alternatives for end-user reference

The codebase has moderate security posture with several issues of concern. The most critical vulnerability is the unverified binary download in the Dockerfile, which creates a significant supply chain risk. Additional concerns include missing package verification, incomplete Alpine base image hardening, and potential module declaration mismatches. The security infrastructure (SECURITY.md, openvex config) is in place but needs strengthening in CI/CD automation and dependency verification practices. Immediate attention should be paid to implementing cryptographic verification for downloaded binaries and establishing automated vulnerability scanning in the pipeline.

• High · Insecure Direct Object Reference in Dockerfile - Version Download — Dockerfile (builder stage). The Dockerfile downloads kompose binary from GitHub releases using a version number read from a file without integrity verification. The downloaded binary is not validated via checksum or signature, creating a supply chain attack vector. If the VERSION file is tampered with or the download is intercepted, a malicious binary could be executed with elevated privileges during container build. Fix: Implement binary verification by: 1) Download and verify SHA256 checksums from GitHub releases, 2) Use cryptographic signature verification if available, 3) Consider pinning to specific commit hashes, 4) Implement binary scanning/attestation checks
• High · Missing Package Manager Update in Alpine Container — Dockerfile (builder stage - line with 'apk add --no-cache curl'). The Dockerfile uses 'apk add --no-cache' without updating the Alpine package index. This can lead to installing outdated packages with known vulnerabilities. The base image layers may contain unpatched security issues. Fix: Run 'apk update' before installing packages or use 'apk add --no-cache -U' to check for latest versions. Consider using specific package versions pinned to known-good releases.
• Medium · Unrestricted GitHub Release Download — Dockerfile (curl command in builder stage). The Dockerfile downloads binaries directly from GitHub over HTTPS without any rate limiting or retry mechanisms. This could be exploited for denial of service or used as a vector for timing attacks. Additionally, no fallback mechanism exists if the download fails. Fix: Implement: 1) curl with retry options and timeout, 2) Rate limiting awareness, 3) Fallback mechanisms, 4) Consider mirroring releases to a private registry, 5) Add --fail flag to curl to fail on HTTP errors
• Medium · Implicit Bash Assumptions in Dockerfile — Dockerfile (RUN command with piped commands). The Dockerfile uses pipe operators and sed commands in RUN instruction that assume bash/sh behavior. Alpine Linux uses ash by default, which may have subtle differences in command parsing and could lead to unexpected behavior or bypass of intended logic. Fix: Explicitly specify the shell: use 'RUN ['/bin/sh', '-c', 'commands']' or add '#!/bin/sh' shebang. Test scripts across different shell implementations.
• Low · Exposed Module Declaration Mismatch — go.mod (module declaration). The go.mod file declares 'module github.com/redhat-developer/podman-desktop-demo' but the repository is 'kubernetes/kompose'. This indicates the dependency file may be incorrect or from a different project, causing confusion about the actual codebase identity and potential supply chain issues. Fix: Verify the correct module path matches the repository. Update to 'module github.com/kubernetes/kompose' if this is the kompose repository. Ensure go.mod reflects the actual project identity.
• Low · Missing Security Scanning Configuration — .github/workflows/. While .openvex configuration exists, there's no evidence of active vulnerability scanning in CI/CD pipeline configuration (.github/workflows files are referenced but content not fully visible). Dependencies like redigo and negroni should be regularly scanned. Fix: Implement automated dependency scanning in CI/CD: 1) Enable Dependabot alerts, 2) Use OWASP Dependency Check or Snyk, 3) Add vulnerability scanning to pull request checks, 4) Monitor for transitive dependency vulnerabilities

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.