Skip to content

Project Layout Guidance

1. Category

1.1. C/C++

The Pitchfork Layout (PFL) is a convention for arranging source, build, and resource files in a file system to support uniformity, comprehensibility, and partitioning.

1.1.1. Library

  1. Layout and Structure

    Note

    Replace <...> brackets with the library-specific information.

    <library>/
│
. `Hierarchical Structure`
│
├── include/
│   └── <library>/
│       └── file.h
│
├── src/
│   │
│   . `Functional-based Structure`
│   │
│   ├── file.c
│   ├── file_test.cc
│   ├── CMakeLists.txt
│   └── README.md
│
├── external/
│   ├── <third-party>/
│   └── README.md
│
├── tests/
│   ├── performance/
│   │   ├── benchmark_test.cc
│   │   └── CMakeLists.txt
│   ├── CMakeLists.txt
│   └── README.md
│
├── examples/
│   ├── example.c
│   ├── CMakeLists.txt
│   └── README.md
│
├── docs/
│   ├── decisions/
│   │   └── adr-<topic>.md
│   └── README.md
│
├── build/
│   ├── debug/
│   │   └── lib/
│   │       └── libprojectd.a
│   └── release/
│       └── lib/
│           └── libproject.a
│
├── tools/
│   ├── cmake/
│   └── README.md
│
├── scripts/
│   ├── shell/
│   ├── python/
│   ├── bootstrap
│   ├── setup
│   ├── teardown
│   └── README.md
│
├── CMakeLists.txt
├── CMakePresets.json
├── LICENSE
└── README.md

  2. Files and Folders

    • include/<library>/

      Public header files for the library, organized under the library name to avoid name collisions when installed system-wide.

    • src/

      Implementation files and in-tree unit tests. Follows a Functional-based Structure to group related implementation and test files together.

      • file.c

        Source implementation file.

      • file_test.cc

        In-tree unit test file paired with the source file.

      • CMakeLists.txt

        CMake build definition for the source directory.

    • external/

      Third-party dependencies vendored into the project.

    • tests/

      Additional tests that are not co-located with the source, such as performance benchmarks.

      • performance/

        Benchmark tests measuring library performance.

    • examples/

      Standalone example programs demonstrating library usage.

    • docs/

      Project documentation and Architecture Decision Records (ADRs).

    • build/

      Build output artifacts, separated into debug/ and release/ sub-directories.

    • tools/

      Supporting development tools such as CMake helper scripts.

    • scripts/

      Shell and Python scripts for bootstrapping, setup, and teardown of the development environment.

    • CMakeLists.txt

      Root CMake build definition for the library.

    • CMakePresets.json

      CMake presets for configuring common build configurations.

    • LICENSE

      License file for the library.

    • README.md

      Project overview and usage instructions.

1.1.2. Application

  1. Layout and Structure

    Note

    Replace <...> brackets with the application-specific information.

    /<project>
│
. `Hierarchical Structure`
│
├── internal/
│   │
│   . `Layered Structure`
│   │
│   ├── presentation/
│   │   └── README.md
│   │
│   ├── application/
│   │   ├── CMakeLists.txt
│   │   └── README.md
│   │
│   ├── domain/
│   │   ├── CMakeLists.txt
│   │   └── README.md
│   │
│   ├── infrastructure/
│   │   ├── CMakeLists.txt
│   │   └── README.md
│   │
│   ├── CMakeLists.txt
│   └── README.md
│
├── external/
│   └── README.md
│
├── tests/
│   ├── performance/
│   │   ├── benchmark_test.cc
│   │   └── CMakeLists.txt
│   ├── integration/
│   │   ├── top_down_test.cc
│   │   └── CMakeLists.txt
│   ├── e2e/
│   │   ├── scenario_test.cc
│   │   └── CMakeLists.txt
│   ├── CMakeLists.txt
│   └── README.md
│
├── examples/
│   ├── example.c
│   ├── CMakeLists.txt
│   └── README.md
│
├── docs/
│   ├── decisions/
│   │   └── NNN-adr-<topic>.md
│   ├── api.md
│   └── README.md
│
├── build/
│   ├── bin/
│   │   └── project.exe
│   ├── lib/
│   │   └── project.a
│   └── cmake/
│
├── tools/
│   ├── cmake/
│   └── README.md
│
├── scripts/
│   ├── shell/
│   ├── python/
│   ├── bootstrap
│   ├── setup
│   ├── teardown
│   └── README.md
│
├── assets/
│   ├── dataset.csv
│   └── README.md
│
├── CMakeLists.txt
├── LICENSE
└── README.md

  2. Files and Folders

    • internal/

      Private application code organized using a Layered Structure. Code placed here cannot be imported by external packages.

      • presentation/

        Presentation layer handling user interface and API endpoints.

      • application/

        Application layer orchestrating use cases and business workflows.

      • domain/

        Domain layer containing business logic, entities, and domain services.

      • infrastructure/

        Infrastructure layer for persistence, messaging, and external service integrations.

    • external/

      Third-party dependencies and vendored libraries.

    • tests/

      Tests that are not co-located with the source, including performance benchmarks, integration tests, and end-to-end tests.

      • performance/

        Benchmark tests for measuring application performance.

      • integration/

        Integration tests exercising multiple components together.

      • e2e/

        End-to-end tests validating full application scenarios.

    • examples/

      Standalone example programs demonstrating application usage.

    • docs/

      Project documentation and Architecture Decision Records (ADRs).

    • build/

      Build output artifacts, including binaries and libraries.

    • tools/

      Supporting development tools such as CMake helper scripts.

    • scripts/

      Shell and Python scripts for bootstrapping, setup, and teardown of the development environment.

    • assets/

      Data files such as datasets, fixtures, and static assets.

    • CMakeLists.txt

      Root CMake build definition for the application.

    • LICENSE

      License file for the application.

    • README.md

      Project overview and usage instructions.

1.2. Go

1.2.1. Package

Go Package layout is a standard structure for organizing Go code, tests, and resources to facilitate maintainability, scalability, and collaboration.

  1. Layout and Structure

    Note

    Replace <...> brackets with the package-specific information.

    <package>/
│
. `Hierarchical Structure`
│
├── cmd/
│   └── app/
│       └── main.go
│
├── internal/
│   └── pkg/
│       ├── helper.go
│       └── helper_test.go
│
├── pkg/
│   └── <package>/
│       ├── <package>.go
│       └── <package>_test.go
│
├── go.mod
├── go.sum
│
├── LICENSE
└── README.md

  2. Files and Folders

    • cmd/

      Main applications for the project. Each sub-directory represents a single executable (e.g., cmd/app/).

    • internal/

      Private application and library code that cannot be imported by external packages.

    • pkg/

      Library code intended to be used by external applications.

    • go.mod

      Module definition file specifying the module path and dependency requirements.

    • go.sum

      Checksums for the module's dependencies, ensuring reproducible builds.

    • LICENSE

      License file for the package.

    • README.md

      Project overview and usage instructions.

1.2.2. Application

Go Project Layout is a standard structure for organizing Go code, tests, and resources to facilitate maintainability, scalability, and collaboration.

Note

It's not an official standard defined by the core Go dev team.

  1. Layout and Structure

    Note

    Replace <...> brackets with the application-specific information.

    <project>/
│
. `Hierarchical Structure`
│
├── cmd/
│   └── <project>/
│       └── main.go
│
├── internal/
│   ├── <package-a>/
│   │   ├── <package-a>.go
│   │   └── <package-a>_test.go
│   └── <package-b>/
│       ├── <package-b>.go
│       └── <package-b>_test.go
│
├── pkg/
│   └── <package>/
│       ├── <package>.go
│       └── <package>_test.go
│
├── api/
│   └── <api>.proto
│
├── configs/
│   └── <config>.yaml
│
├── scripts/
│   ├── bootstrap
│   ├── setup
│   └── teardown
│
├── build/
│   ├── ci/
│   └── package/
│
├── deployments/
│   └── <deployment>.yaml
│
├── test/
│   ├── integration/
│   └── e2e/
│
├── docs/
│   ├── decisions/
│   │   └── NNN-adr-<topic>.md
│   └── README.md
│
├── tools/
│
├── examples/
│   └── <example>/
│       └── main.go
│
├── go.mod
├── go.sum
├── Makefile
├── LICENSE
└── README.md

  2. Files and Folders

    • cmd/

      Main applications for the project. Each sub-directory name matches the executable to build.

    • internal/

      Private application and library code. This is the primary location for business logic that should not be exposed externally.

    • pkg/

      Library code intended for use by external applications. Other projects can import these packages.

    • api/

      OpenAPI/Swagger specs, JSON schema files, and protocol definition files.

    • configs/

      Configuration file templates or default configurations.

    • scripts/

      Scripts for building, installing, and performing various operations.

    • build/

      Packaging and Continuous Integration configurations and scripts.

    • deployments/

      IaaS, PaaS, system, and container orchestration deployment configurations.

    • test/

      Additional external test apps and test data that do not belong alongside source files.

    • docs/

      Design and user documentation, including Architecture Decision Records (ADRs).

    • tools/

      Supporting tools for this project.

    • examples/

      Examples for the application or public libraries.

    • go.mod

      Module definition file specifying the module path and dependency requirements.

    • go.sum

      Checksums for the module's dependencies, ensuring reproducible builds.

    • Makefile

      Build automation and task runner for common development operations.

    • LICENSE

      License file for the application.

    • README.md

      Project overview and usage instructions.

1.3. Python

1.3.1. Package

Python Package layout is a standard structure for organizing Python code, tests, and metadata to facilitate packaging, distribution, and installation based on a flat or src layout.

Tip

pyproject.toml is the modern standard for Python packaging, organizing build, project, dependency, and tool configuration.

  1. Layout and Structure

    Note

    Replace <...> brackets with the module-specific information.

    <package>/
│
. `Hierarchical Structure`
│
├── src/
│   └── <package>/
│       ├── __init__.py
│       └── <package>.py
│
├── tests/
│   ├── __init__.py
│   └── test_<package>.py
│
├── docs/
│   └── README.md
│
├── pyproject.toml
├── LICENSE
└── README.md

  2. Files and Folders

    • src/<package>/

      Source code for the package, placed under src/ to prevent accidental imports from the project root during development.

      • __init__.py

        Marks the directory as a Python package and defines the public API of the module.

      • <package>.py

        Package implementation file.

    • tests/

      Unit and integration tests for the module.

    • docs/

      Module documentation.

    • pyproject.toml

      Project metadata, build configuration, and tool settings (replaces setup.py and setup.cfg).

    • LICENSE

      License file for the module.

    • README.md

      Module overview and usage instructions.

1.3.2. Application

  1. Layout and Structure

    Note

    Replace <...> brackets with the application-specific information.

    <project>/
│
. `Hierarchical Structure`
│
├── src/
│   └── <project>/
│       ├── __init__.py
│       ├── main.py
│       └── <module>/
│           ├── __init__.py
│           └── <module>.py
│
├── tests/
│   ├── __init__.py
│   ├── unit/
│   │   └── test_<module>.py
│   └── integration/
│       └── test_<module>.py
│
├── docs/
│   └── README.md
│
├── scripts/
│   ├── bootstrap
│   ├── setup
│   └── teardown
│
├── pyproject.toml
├── requirements.txt
├── LICENSE
└── README.md

  2. Files and Folders

    • src/<project>/

      Application source code, placed under src/ to prevent accidental imports from the project root.

      • __init__.py

        Marks the directory as a Python package.

      • main.py

        Application entry point.

      • <module>/

        Sub-module containing related functionality.

    • tests/

      Unit tests, integration tests, and execution tests for the application.

    • docs/

      Application documentation.

    • scripts/

      Shell scripts for bootstrapping, setup, and teardown of the development environment.

    • pyproject.toml

      Project metadata, build configuration, and tool settings.

    • requirements.txt

      Package dependency and version management for pinned runtime dependencies.

    • LICENSE

      License file for the application.

    • README.md

      Project overview and usage instructions.

1.4. Ansible

1.4.1. Collection

An Ansible Collection packages and distributes roles, modules and plugins. Organizing Ansible Collection content under a directory structure, it is crucial to follow a specific layout to ensure that Ansible can recognize and properly utilize the collection.

  1. Layout and Structure

    The project path is based on the collections/ansible_collections keywords and the Fully Qualified Collection Name (FQCN) <namespace>.<collection>, in accordance with the naming convention.

    Note

    None of the directories are required.

    Note

    Replace <...> brackets with the project-specific information.

    <project>-ansible-collection/
└── collections/
    └── ansible_collections/
        └── <namespace>/
            └── <collection>/
                │
                ├── meta/
                │   └── runtime.yml
                │
                ├── plugins/
                │   ├── action/
                │   ├── become/
                │   ├── cache/
                │   ├── callback/
                │   ├── cliconf/
                │   ├── connection/
                │   ├── filter/
                │   ├── httpapi/
                │   ├── inventory/
                │   ├── lookup/
                │   ├── module_utils/
                │   ├── modules/
                │   │   ├── __init__.py
                │   │   └── <module>.py
                │   ├── netconf/
                │   ├── shell/
                │   ├── strategy/
                │   ├── terminal/
                │   ├── test/
                │   └── vars/
                │
                ├── roles/
                │   ├── <role-a>/
                │   │   ├── defaults/
                │   │   │   └── main.yml
                │   │   ├── files/
                │   │   │   └── LICENSE
                │   │   ├── handlers/
                │   │   │   └── main.yml
                │   │   ├── tasks/
                │   │   │   └── main.yml
                │   │   ├── templates/
                │   │   │   ├── config.yml.j2
                │   │   │   └── docker-compose.yml.j2
                │   │   ├── vars/
                │   │   │   └── main.yml
                │   │   └── README.md
                │   └── <role-b>/
                │       ├── defaults/
                │       │   └── main.yml
                │       ├── handlers/
                │       │   └── main.yml
                │       ├── tasks/
                │       │   └── main.yml
                │       └── README.md
                │
                ├── playbooks/
                │   ├── files/
                │   ├── vars/
                │   ├── templates/
                │   └── tasks/
                │
                ├── galaxy.yml
                └── README.md

  2. Files and Folders

    • galaxy.yml

      The source of the metadata file used to generate a collection on Galaxy and to build a collection artifact.

    • meta/

      Collection metadata directory.

      • runtime.yml

        Declares the minimum required Ansible version and plugin routing for the collection.

    • plugins/

      The collections plugins directory ships various plugins inside an Ansible collection. Each plugin is placed in a folder named after its type. It also includes module_utils and modules directories for module utilities and modules respectively.

      • modules/

        Custom Ansible modules. At least one module is required for most collections.

      • __init__.py

        A required empty file to initialize the namespace and allow Python to import the files.

      • inventory/

        Custom inventory plugins. At least one plugin is required for inventory collections.

    • roles/

      Ansible roles bundled with the collection, each following the standard role directory structure.

    • playbooks/

      Playbooks distributed as part of the collection.

    • docs/

      Describes the use of the roles, plugins, and role requirements provided by the collection.

    • README.md

      Collection overview and usage instructions.

1.4.2. Playbook

Ansible Playbook directory layout organizes tasks in roles, with a inventory file for each environment and a playbooks.

Tip

The layout promotes separation of concerns and enables scalable management across multiple environments.

  1. Layout and Structure

    Note

    Replace <...> brackets with the project-specific information.

    <project>-ansible-playbook/
│
. `Modular Structure`
│
├── collections/
│   └── ansible_collections/
│       └── <namespace>/
│           ├── <collection-a>/
│           │   ├── meta/
│           │   │   └── runtime.yml
│           │   ├── roles/
│           │   │   ├── <role-a>/
│           │   │   └── <role-b>/
│           │   ├── tests/
│           │   ├── docs/
│           │   ├── galaxy.yml
│           │   └── README.md
│           │
│           └── <collection-b>/
│               ├── meta/
│               │   └── runtime.yml
│               ├── roles/
│               │   ├── <role-a>/
│               │   └── <role-b>/
│               ├── tests/
│               ├── docs/
│               ├── galaxy.yml
│               └── README.md
│
. `Hierarchical Structure`
│
├── playbooks/
│   ├── <playbook-a>.yml
│   └── <playbook-b>.yml
│
├── inventory/
│   ├── dev/
│   │   ├── group_vars/
│   │   │   ├── all/
│   │   │   │   ├── all.yml
│   │   │   │   └── vault.yml
│   │   │   ├── <group-a>.yml
│   │   │   └── <group-b>.yml
│   │   ├── host_vars/
│   │   │   ├── <host-a.localhost>.yml
│   │   │   └── <host-b.localhost>.yml
│   │   └── hosts.yml
│   ├── stage/
│   │   ├── group_vars/
│   │   │   ├── all/
│   │   │   │   ├── all.yml
│   │   │   │   └── vault.yml
│   │   │   ├── <group-a>.yml
│   │   │   └── <group-b>.yml
│   │   ├── host_vars/
│   │   │   ├── <staging.host-a.com>.yml
│   │   │   └── <staging.host-b.com>.yml
│   │   └── hosts.yml
│   └── prod/
│       ├── group_vars/
│       │   ├── all/
│       │   │   ├── all.yml
│       │   │   └── vault.yml
│       │   ├── <group-a>.yml
│       │   └── <group-b>.yml
│       ├── host_vars/
│       │   ├── <host-a.com>.yml
│       │   └── <host-b.com>.yml
│       └── hosts.yml
│
├── site.yml
├── requirements.yml
├── ansible.cfg
└── README.md

  2. Files and Folders

    • collections/

      Vendored Ansible collections installed locally, organized by namespace and collection name under ansible_collections/.

    • playbooks/

      Ansible playbooks that define the automation workflows applied to the inventory.

    • inventory/

      Host inventory files and variable definitions, organized per environment (dev/, stage/, prod/).

      • group_vars/

        Variable files applied to host groups, including an all/ sub-directory for variables shared across all hosts.

      • host_vars/

        Variable files applied to specific hosts.

      • hosts.yml

        Inventory file listing the hosts and their group memberships for the environment.

    • site.yml

      Top-level playbook entry point that includes all other playbooks.

    • requirements.yml

      Declares the Ansible collections and roles required by the project.

    • ansible.cfg

      Ansible configuration file defining project-level settings.

    • README.md

      Project overview and usage instructions.

1.5. Terraform

1.5.1. Module

Terraform modules define self-contained, reusable resources of Infrastructure-as-Code (IaC). The Terraform module structure for reusable modules distributed in separate repositories.

  1. Layout and Structure

    Note

    Replace <...> brackets with the module-specific information.

    terraform-<provider>-<project>/
├── modules/
│   ├── <module-a>/
│   │   ├── main.tf
│   │   ├── data.tf
│   │   ├── locals.tf
│   │   ├── outputs.tf
│   │   ├── variables.tf
│   │   ├── versions.tf
│   │   └── README.md
│   └── <module-b>/
│       ├── main.tf
│       ├── data.tf
│       ├── locals.tf
│       ├── outputs.tf
│       ├── variables.tf
│       ├── versions.tf
│       └── README.md
│
├── examples/
│   ├── simple/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── outputs.tf
│   │   ├── versions.tf
│   │   └── README.md
│   └── complete/
│       ├── main.tf
│       ├── variables.tf
│       ├── outputs.tf
│       ├── versions.tf
│       └── README.md
│
├── tests/
│   ├── unit/
│   │   ├── bucket_name.tftest.hcl
│   │   ├── input_validation.tftest.hcl
│   │   └── provider.tftest.hcl
│   ├── integration/
│   │   └── modules.tftest.hcl
│   └── README.md
│
├── main.tf
├── variables.tf
├── outputs.tf
├── versions.tf
│
├── LICENSE
└── README.md

  2. Files and Folders

    • modules/

      Reusable Terraform sub-modules that can be composed to build the root module.

      • <module>/

        An individual sub-module with its own set of Terraform files.

      • main.tf

        Primary resource definitions for the module.

      • data.tf

        Data source definitions for the module.

      • locals.tf

        Local value definitions to simplify expressions within the module.

      • outputs.tf

        Output value definitions exposed by the module.

      • variables.tf

        Input variable declarations for the module.

      • versions.tf

        Provider version constraints for the module.

    • examples/

      Example configurations demonstrating how to use the module in simple and complete scenarios.

    • tests/

      Terraform test files using the native HCL test framework.

      • unit/

        Unit tests validating individual module inputs and resource naming.

      • integration/

        Integration tests validating the composition of multiple modules.

    • main.tf

      Root module entry point defining the primary resources.

    • variables.tf

      Input variable declarations for the root module.

    • outputs.tf

      Output value definitions exposed by the root module.

    • versions.tf

      Provider and Terraform version constraints for the root module.

    • LICENSE

      License file for the module.

    • README.md

      Module overview, usage instructions, and input/output documentation.

1.5.2. Project

A Terraform project for structured multiple environments designed to facilitate the management of Terraform configurations, reusable modules, and environment-specific settings.

Tip

The layout promotes separation of concerns and enables scalable management across multiple environments.

  1. Layout and Structure

    Note

    Replace <...> brackets with the project-specific information.

    terraform-<project>/
│
. `Modular Structure`
│
├── modules/
│   ├── <module-a>/
│   └── <module-b>/
│
. `Hierarchical Structure`
│
├── environments/
│   ├── dev/
│   ├── stage/
│   │   ├── <stack-a>/
│   │   │   ├── main.tf
│   │   │   ├── backend.tf
│   │   │   ├── provider.tf
│   │   │   ├── locals.tf
│   │   │   ├── variables.tf
│   │   │   ├── outputs.tf
│   │   │   ├── data.tf
│   │   │   └── versions.tf
│   │   └── <stack-b>/
│   └── prod/
│       ├── <stack-a>/
│       │   ├── main.tf
│       │   ├── backend.tf
│       │   ├── provider.tf
│       │   ├── locals.tf
│       │   ├── variables.tf
│       │   ├── outputs.tf
│       │   ├── data.tf
│       │   └── versions.tf
│       └── <stack-b>/
│
├── tests/
│
└── README.md

  2. Files and Folders

    • modules/

      Local reusable Terraform modules shared across environments.

    • environments/

      Environment-specific Terraform configurations, each environment containing one or more stacks.

      • <env>/<stack>/

        A single deployable stack within the environment.

      • main.tf

        Primary resource definitions and module calls for the stack.

      • backend.tf

        Remote state backend configuration for the stack.

      • provider.tf

        Provider configurations for the stack.

      • locals.tf

        Local value definitions to simplify expressions within the stack.

      • variables.tf

        Input variable declarations for the stack.

      • outputs.tf

        Output value definitions exposed by the stack.

      • data.tf

        Data source definitions for the stack.

      • versions.tf

        Provider and Terraform version constraints for the stack.

    • tests/

      Terraform test files validating project configurations.

    • README.md

      Project overview and usage instructions.

  3. Examples and Explanations

    • Initialize workspace

      Initialize the Terraform working directory for a specific environment and stack.

      ## Initialize Terraform workspace
terraform-init:
terraform -chdir=environments/$(ENV)/$(STACK) init
.PHONY: terraform-init

    • Plan changes

      Generate and review an execution plan for a specific environment and stack.

      ## Plan Terraform changes
terraform-plan:
terraform -chdir=environments/$(ENV)/$(STACK) plan
.PHONY: terraform-plan

    • Apply changes

      Apply the Terraform execution plan for a specific environment and stack.

      ## Apply Terraform changes
terraform-apply:
terraform -chdir=environments/$(ENV)/$(STACK) apply
.PHONY: terraform-apply

1.6. Kubernetes

Kubernetes configuration represents declarative desired state, so repositories are commonly organized by deployment responsibility and composition. Helm defines the internal structure of charts, Kustomize defines reusable bases and overlays, and GitOps repositories commonly separate application workloads, platform capabilities, reusable components, and cluster entry points.

1.6.1. Charts

A Helm Charts is a package of files that describes a related set of Kubernetes resources. Helm defines the Chart File Structure and reserves specific file and directory names within a chart.

Note

Helm reserves use of the charts/, crds/, and templates/ directories, and of the listed file names.

  1. Layout and Structure

    Note

    Replace <...> brackets with the chart-specific information.

    <chart>/
├── Chart.yaml
├── values.yaml
├── values.schema.json
│
├── crds/
│
├── charts/
│
├── templates/
│   ├── _helpers.tpl
│   ├── deployment.yaml
│   ├── hpa.yaml
│   ├── ingress.yaml
│   ├── service.yaml
│   ├── serviceaccount.yaml
│   └── NOTES.txt
│
├── .helmignore
│
├── LICENSE
└── README.md

  2. Files and Folders

    Note

    The template files follow the standard conventions for writing Go templates.

    • Chart.yaml

      Required chart metadata, including the chart name, version, and API version.

    • values.yaml

      Default configuration values consumed by chart templates.

    • values.schema.json

      OPTIONAL JSON Schema for validating and documenting the structure of chart values.

    • charts/

      Chart dependencies packaged or downloaded as subcharts. This directory is part of the Helm chart format and should not be confused with a project-level directory for third-party charts.

    • crds/

      CustomResourceDefinition (CRD) manifests installed before the chart's templated resources.

    • templates/

      Templates that Helm renders with values to produce Kubernetes manifests.

      • _helpers.tpl

        Reusable named template definitions, commonly used for labels, selectors, and resource names.

      • deployment.yaml

        Template for a Kubernetes Deployment resource managing application pod replicas.

      • hpa.yaml

        Template for a Kubernetes HorizontalPodAutoscaler resource enabling automatic scaling based on metrics.

      • ingress.yaml

        Template for a Kubernetes Ingress resource exposing HTTP and HTTPS routes to services.

      • service.yaml

        Template for a Kubernetes Service resource providing stable network access to pods.

      • serviceaccount.yaml

        Template for a Kubernetes ServiceAccount resource used by workloads requiring a Kubernetes identity.

      • NOTES.txt

        OPTIONAL plain text file containing usage notes displayed after chart installation.

    • .helmignore

      Patterns identifying files that should be excluded when packaging the chart.

    • LICENSE

      OPTIONAL chart license information.

    • README.md

      OPTIONAL chart documentation and usage instructions.

  3. Examples and Explanations

    • Create Local Chart

      Create the skeleton for a Helm chart.

      ## Create a new Helm chart
helm-create-chart:
helm create <chart>
.PHONY: helm-create-chart

    • Pull Published Chart

      Pull an exact published chart version from a trusted Helm repository or OCI registry rather than copying third-party chart source into the project by default.

      ## Pull a published Helm chart
helm-pull-chart:
helm pull <repository>/<chart> --version <version>
.PHONY: helm-pull-chart

      Note

      Vendor third-party charts only when hermetic or offline rendering is an explicit project requirement.

    • Render Chart

      Render a chart locally to validate templates and the resulting Kubernetes manifests.

      ## Render a Helm chart
helm-render-chart:
helm template <release> ./<chart> \
  --namespace=default \
  --values=./<chart>/values.yaml \
  --output-dir=./render
.PHONY: helm-render-chart

1.6.2. Project

The declarative management of Kubernetes objects using Kustomize involves organizing resources into reusable and composable configurations.

Tip

The Flux CD template repository follows the repository-structure recommendations for organising Kustomize resources with Helm charts in alignment with the project’s deployment model and operational requirements.

  1. Layout and Structure

    Note

    Replace <...> brackets with the project-specific information.

    <project>/
│
. `Modular Monolith`
│
├── README.md
├── Makefile
├── CODEOWNERS
│
├── services/                               # Optional application source
│   ├── <app-a>/
│   │   ├── src/
│   │   ├── tests/
│   │   └── Dockerfile
│   └── <app-b>/
│
├── charts/                                 # Versioned Helm packages
│   ├── <app-a>/
│   │   ├── Chart.yaml                      # Chart metadata and dependencies
│   │   ├── Chart.lock                      # Present when dependencies exist
│   │   ├── values.yaml                     # Portable defaults
│   │   ├── values.schema.json              # Configuration contract
│   │   ├── README.md
│   │   ├── .helmignore
│   │   ├── charts/                         # Dependencies restored during packaging
│   │   └── templates/
│   │       ├── `_helpers.tpl`
│   │       ├── deployment.yaml
│   │       ├── service.yaml
│   │       ├── serviceaccount.yaml
│   │       ├── configmap.yaml
│   │       ├── ingress.yaml                # Optional chart capability
│   │       ├── hpa.yaml                    # Optional autoscaling
│   │       ├── pdb.yaml                    # Optional disruption budget
│   │       └── tests/
│   │           └── smoke-test.yaml
│   └── <app-b>/
│
├── apps/                                   # Desired application deployments
│   ├── <app-a>/
│   │   ├── README.md
│   │   ├── base/
│   │   │   ├── kustomization.yaml
│   │   │   └── networkpolicy.yaml          # Shared application-specific resources
│   │   └── overlays/
│   │       ├── dev/
│   │       │   ├── kustomization.yaml      # Pinned chart reference and namespace: app-a-dev
│   │       │   └── values.yaml             # Image digest, hostname, resources
│   │       ├── stage/
│   │       │   ├── kustomization.yaml      # Pinned chart reference and namespace: app-a-stage
│   │       │   └── values.yaml
│   │       └── prod/
│   │           ├── kustomization.yaml      # Pinned chart reference and namespace: app-a-prod
│   │           └── values.yaml
│   └── <app-b>/
│
. `Responsibility-based Structure`
│
├── infrastructure/                         # Platform ownership and lifecycle
│   ├── controllers/
│   │   ├── ingress-controller/
│   │   │   ├── README.md
│   │   │   ├── base/
│   │   │   │   └── kustomization.yaml
│   │   │   └── overlays/
│   │   │       ├── dev/
│   │   │       │   ├── kustomization.yaml
│   │   │       │   └── values.yaml
│   │   │       ├── stage/
│   │   │       │   ├── kustomization.yaml
│   │   │       │   └── values.yaml
│   │   │       └── prod/
│   │   │           ├── kustomization.yaml
│   │   │           └── values.yaml
│   │   └── secret-controller/
│   │       ├── README.md
│   │       ├── base/
│   │       │   └── kustomization.yaml
│   │       └── overlays/
│   │           ├── dev/
│   │           │   ├── kustomization.yaml
│   │           │   └── values.yaml
│   │           ├── stage/
│   │           │   ├── kustomization.yaml
│   │           │   └── values.yaml
│   │           └── prod/
│   │               ├── kustomization.yaml
│   │               └── values.yaml
│   └── configs/
│       ├── base/
│       │   ├── kustomization.yaml
│       │   └── policies/
│       │       └── kustomization.yaml
│       └── overlays/
│           ├── dev/
│           │   ├── kustomization.yaml
│           │   ├── namespaces.yaml         # app-a-dev, app-b-dev
│           │   ├── rbac.yaml
│           │   ├── quotas.yaml
│           │   └── networkpolicies.yaml
│           ├── stage/
│           │   ├── kustomization.yaml
│           │   ├── namespaces.yaml         # app-a-stage, app-b-stage
│           │   ├── rbac.yaml
│           │   ├── quotas.yaml
│           │   └── networkpolicies.yaml
│           └── prod/
│               ├── kustomization.yaml
│               ├── namespaces.yaml         # app-a-prod, app-b-prod
│               ├── rbac.yaml
│               ├── quotas.yaml
│               └── networkpolicies.yaml
│
├── components/                             # Optional reusable Kustomize components
│   └── README.md
│
├── clusters/                               # Desired composition per independent cluster
│   ├── dev/
│   │   ├── README.md                       # Target identity and prerequisites
│   │   ├── kustomization.yaml              # Complete composition for rendering
│   │   ├── controllers/
│   │   │   └── kustomization.yaml          # References controller dev overlays
│   │   ├── configs/
│   │   │   └── kustomization.yaml          # References infrastructure configs/dev
│   │   └── apps/
│   │       └── kustomization.yaml          # References both application dev overlays
│   ├── stage/
│   │   ├── README.md
│   │   ├── kustomization.yaml
│   │   ├── controllers/
│   │   │   └── kustomization.yaml
│   │   ├── configs/
│   │   │   └── kustomization.yaml
│   │   └── apps/
│   │       └── kustomization.yaml
│   └── prod/
│       ├── README.md
│       ├── kustomization.yaml
│       ├── controllers/
│       │   └── kustomization.yaml
│       ├── configs/
│       │   └── kustomization.yaml
│       └── apps/
│           └── kustomization.yaml
│
├── tests/
│   ├── manifests/
│   │   ├── <app-a>/
│   │   └── <app-b>/
│   └── integration/
│       ├── <app-a>/
│       └── <app-b>/
│
└── docs/
    ├── architecture.md
    ├── project-layout.md
    ├── configuration.md
    ├── reconciliation.md                   # Delivery-system integration contract
    ├── applications/
    │   ├── <app-a>.md
    │   └── <app-b>.md
    └── runbooks/
        ├── bootstrap.md
        ├── promotion.md
        ├── rollback.md
        └── disaster-recovery.md

  2. Files and Folders

    Path Responsibility and Convention
    services/<app>/ Application source and unit tests. Omit this directory in a deployment-only repository.
    charts/<app>/ Reusable Helm package source. Keep defaults portable; publish a new chart version when chart content changes.
    apps/<app>/base/ Shared Kubernetes resources not already owned by the chart. Omit an unused base instead of creating placeholder resources.
    apps/<app>/overlays/<env>/ Independent environment configuration, including an exact chart version and image digest. Each overlay references the shared base; stage and prod do not inherit from dev.
    infrastructure/controllers/ Installation of operators and controllers, including their installation namespaces and required CRDs.
    infrastructure/configs/ Platform configuration, application namespaces, RBAC, quotas, and policies. Controller-dependent custom resources also belong here.
    components/ Optional, explicitly selected Kustomize components for reusable behavior. Introduce these only when composition removes meaningful duplication.
    clusters/<cluster>/ Selects application and platform overlays for one concrete cluster. Contains composition, not copied workload manifests.
    tests/ Assertions on rendered resources and integration tests, distinct from application unit tests.
    docs/ Architecture, configuration contracts, delivery integration, and operational runbooks.

  3. Examples and Explanations

    Helm defines application packaging and templates. Kustomize assembles a target environment and applies Kubernetes-level customizations. The Kubernetes Kustomize guide supports reusable bases and overlays.

    Tip

    Store shared application defaults in the chart's values.yaml, place only environment differences in overlay values. Prefer a chart value over a patch when the chart exposes the intended setting.

    • apps/app-a/overlays/dev/kustomization.yaml

      Kustomize overlay for the development environment of app-a.

      apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: app-a-dev

resources:
- ../../base

helmCharts:
- name: app-a
  repo: https://charts.example.com
  version: 1.4.2
  releaseName: app-a
  namespace: app-a-dev
  valuesFile: values.yaml
  skipTests: true

    • clusters/dev/apps/kustomization.yaml

      Kustomize overlay for the development environment of the cluster.

      apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../../apps/app-a/overlays/dev
- ../../../apps/app-b/overlays/dev

    • clusters/dev/kustomization.yaml

      Kustomize overlay for the development environment of the cluster.

      apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- controllers
- configs
- apps

  4. Tasks and Instructions

    • Render

      Render the complete desired state for a cluster.

      k8s-render:
mkdir -p "$(dir $(K8S_RENDER_FILE))"
kustomize build "$(K8S_CLUSTER_PATH)" --enable-helm > "$(K8S_RENDER_FILE)"
.PHONY: k8s-render

      make k8s-render

    • Deploy

      Deploy the complete desired state for a cluster.

      k8s-deploy:
kustomize build "$(K8S_CLUSTER_PATH)" --enable-helm | kubectl apply -f -
.PHONY: k8s-deploy

      make k8s-deploy

    • Destroy

      Destroy the complete desired state for a cluster.

      k8s-destroy:
kustomize build "$(K8S_CLUSTER_PATH)" --enable-helm | kubectl delete -f -
.PHONY: k8s-destroy

      make k8s-destroy

2. References