Kubernetes Manifest File Organization

Kubernetes Manifest File Organization is the set of competing conventions teams adopt for arranging manifests across files, directories, and repositories as a project grows beyond a handful of objects, addressing questions the base manifest structure leaves open — whether to group files by application, by resource type, or by environment, whether to use one repository or many, and how naming conventions should scale so that a large manifest set remains navigable rather than becoming an undifferentiated pile of YAML.

Organizing by Application Versus by Resource Type

Application-Centric Grouping

The most common convention groups all manifests for a single application or service together — its Deployment, Service, ConfigMap, and any other objects it owns — in one directory, so that understanding or modifying everything related to one application means working within one clearly bounded location, which scales well as the number of distinct applications in a cluster grows.

Resource-Type-Centric Grouping

A less common alternative groups manifests by Kind across the whole project — all Deployments in one directory, all Services in another — which can suit projects with very few distinct applications but a need to review, say, every Service's configuration at once, though it tends to fragment the conceptual unity of a single application's configuration across many separate locations as the project grows.

Why Application-Centric Grouping Generally Wins at Scale

Because most day-to-day work involves reasoning about or changing one application at a time, application-centric grouping tends to minimize the number of directories a typical change touches, which is why it remains the dominant convention in larger, multi-application manifest repositories despite resource-type grouping having some appeal for narrower, cross-cutting audits.

Repository Structure: Monorepo Versus Polyrepo

Single Repository for All Manifests

A monorepo approach keeps every application's manifests, across every environment, in one repository, simplifying cross-application changes and giving a single place to search or audit the entire cluster's declared state, at the cost of requiring access controls scoped within the repository itself if different teams should not modify each other's applications.

Per-Application or Per-Team Repositories

A polyrepo approach splits manifests across multiple repositories, often aligned with team or application ownership boundaries, which more naturally maps repository-level access control onto ownership boundaries but complicates any change that needs to span multiple applications or requires a consistent, coordinated release across repositories.

GitOps Tooling Influence on the Choice

The choice is frequently influenced by whichever GitOps controller a team uses and how it discovers manifest sources, since some tooling has stronger native support for multi-repository source configurations than others, making repository structure as much a function of tooling capability as of pure organizational preference.

File and Directory Naming Conventions

Descriptive, Predictable File Names

Common convention names files after the object they primarily describe and its Kind — deployment.yaml, service.yaml, configmap.yaml — within an application-specific directory, trading uniqueness (many applications will have identically named files) for predictability, since a reader familiar with the convention immediately knows where to look for a given object type within any application's directory.

Kustomize's base/overlays Convention

Projects using Kustomize typically layer this naming convention within its own base and overlays directory structure, keeping the base's resource-type-named files as the canonical shared definition and overlay directories containing only the patches specific to each environment, rather than duplicating entire object definitions per environment.

Scaling Organization for Very Large Projects

Splitting Beyond a Single Application Directory

For applications complex enough to include many objects, a further subdivision — by component within the application, or by concern such as networking versus workload objects — sometimes becomes warranted, though this level of nesting is generally reserved for genuinely large applications, since excessive subdivision for small applications tends to add navigation overhead without a corresponding organizational benefit.

Index or README Files as Navigation Aids

Larger manifest repositories commonly include a top-level index or README describing the overall directory convention in use, giving new contributors a map of where to find or add manifests without needing to infer the convention purely from example, particularly valuable once a repository has grown large enough that no single contributor is likely to have memorized its full layout.