6.23 Kubernetes Manifest File Organization

Kubernetes Manifest File Organization is the set of conventions teams adopt for arranging manifest files and directories within a repository, covering how files are named, how they are grouped by application, kind, or team ownership, and how these choices interact with tooling expectations, code review ergonomics, and the scale of the systems being described.

Organizing by Application or Component

Grouping Everything a Component Needs Together

A widely used pattern groups every manifest belonging to a single application component, its Deployment, Service, ConfigMap, and any other supporting objects, into one directory or file, so that understanding or modifying that component only requires looking in one place rather than hunting across a repository organized by unrelated criteria.

Benefits for Ownership and Review

Component-based organization aligns naturally with team ownership boundaries, since a team responsible for a given service typically owns the entire directory containing that service's manifests, simplifying both code review assignment and access control over the repository itself.

Organizing by Resource Kind

Grouping All Deployments, All Services, and So On

An alternative pattern groups manifests by their kind across the entire system, placing all Deployment manifests in one directory and all Service manifests in another, which can suit contexts where reviewers or automation need to reason about a specific resource type across the whole system at once, such as auditing every Ingress definition for a consistent TLS configuration.

Trade-Offs Versus Component Grouping

Kind-based organization tends to scale poorly as the number of applications grows, since understanding one application's full configuration now requires piecing it together from files scattered across many kind-specific directories, a cost that component-based organization avoids at the expense of making cross-cutting, kind-specific audits somewhat less convenient.

File Naming Conventions

Descriptive, Predictable Filenames

Common naming conventions include the resource kind and a descriptive name in the filename itself, such as payments-deployment.yaml or payments-svc.yaml, making it possible to identify a file's likely contents from its name alone without opening it, which matters when scanning a large directory listing.

Consistency Across a Repository

Whatever convention a team adopts, consistency matters more than the specific choice, since inconsistent naming, mixing kind-first and component-first naming within the same repository, for example, makes navigation noticeably harder for anyone not already deeply familiar with the repository's specific history.

Monorepo Versus Polyrepo Approaches

Single Repository for All Manifests

A monorepo approach keeps every team's and application's manifests within one shared repository, simplifying cross-cutting changes and giving a single, unified view of the entire cluster's declared state, at the cost of potentially larger access-control surface and busier commit history shared across unrelated teams.

Per-Team or Per-Application Repositories

A polyrepo approach splits manifests across multiple repositories, often aligned with team or application boundaries, narrowing each repository's blast radius and access scope, at the cost of making cross-cutting, cluster-wide changes or audits require coordinating across several separate repositories.

GitOps Tooling Support for Both Models

Modern GitOps tooling generally supports both models, watching either a single large repository or many smaller ones, meaning the choice is primarily a matter of organizational preference around ownership boundaries and review workflow rather than a hard technical constraint imposed by the tooling itself.

Interaction With Overlay and Templating Tools

Base and Overlay Directory Conventions

As covered under environment variation, overlay-based tools like Kustomize impose their own directory expectations, typically a base directory alongside overlays subdirectories per environment, meaning a repository's overall organization needs to accommodate these tool-specific structural conventions alongside whatever component or kind-based grouping principle otherwise governs the repository.

Chart-Centric Organization for Helm

Repositories built around Helm typically organize manifests as chart templates within a chart-specific directory structure dictated by Helm's own conventions, templates, values.yaml, and Chart.yaml, meaning the broader organizational choices described here apply more directly to plain-manifest or Kustomize-based repositories than to Helm chart source layout.

Scaling Considerations

Organization Choices Compound at Scale

The consequences of a chosen organizational pattern become more pronounced as a repository grows from a handful of manifests to hundreds or thousands, making it worth deliberately choosing and documenting a convention early, since retrofitting a large, inconsistently organized repository into a new structure later is considerably more disruptive than starting with a clear, agreed-upon pattern from the outset.