This content originally appeared on DEV Community and was authored by Shiva Charan

A well-structured Kubernetes project repo usually looks like this:

k8s-project/
├── README.md
├── docs/
├── manifests/
│   ├── namespaces/
│   ├── deployments/
│   ├── services/
│   ├── ingresses/
│   ├── configmaps/
│   ├── secrets/
│   ├── storage/
│   └── crds/
├── overlays/
│   ├── dev/
│   ├── test/
│   └── prod/
├── charts/
├── scripts/
├── ci-cd/
└── templates/

Now let’s break down every folder, its purpose, what goes inside, and why it exists.

1. README.md

Your project documentation.

• Overview of the application
• How to deploy
• Pre-requisites (kubectl, kustomize, helm, cluster roles)
• CI/CD instructions

2. docs/ – Architecture Documentation

Used for:

• Architecture diagrams
• Flowcharts
• Troubleshooting guides
• Onboarding docs

Example:

docs/
├── architecture.png
├── sequence-flows.md
└── troubleshooting.md

3. manifests/ – Core Kubernetes YAML Files

This is your main folder containing all the raw Kubernetes manifests.

Typical structure:

manifests/
├── namespaces/
│   └── dev-namespace.yaml
│   └── prod-namespace.yaml
├── deployments/
│   └── app-deployment.yaml
│   └── worker-deployment.yaml
├── services/
│   └── app-service.yaml
│   └── internal-service.yaml
├── ingresses/
│   └── app-ingress.yaml
├── configmaps/
│   └── app-configmap.yaml
├── secrets/
│   └── db-secret.yaml
├── storage/
│   ├── pv.yaml
│   └── pvc.yaml
└── crds/
    └── custom-metrics.yaml

Why this folder exists?

To organise all “base” Kubernetes resources cleanly so you don’t mix environments.

4. overlays/ – Environment-Specific Patches (Kustomize)

This folder is used if you use Kustomize for environment-specific overrides.

overlays/
├── dev/
│   ├── kustomization.yaml
│   └── patch-replicas.yaml
├── test/
│   ├── kustomization.yaml
│   └── patch-image-tag.yaml
└── prod/
    ├── kustomization.yaml
    └── patch-resources.yaml

Purpose:

• Change CPU/memory only in prod
• Use latest tag in dev
• Increase replicas per environment
• Change configmaps per environment

5. charts/ – Helm Chart Folder

If the project is using Helm, you place custom charts here.

charts/
└── myapp/
    ├── templates/
    ├── values.yaml
    ├── values-prod.yaml
    └── Chart.yaml

Use-cases:

• Template large apps
• Parameterize configurations
• Reuse configs across multiple apps

6. scripts/ – Helper Scripts

Contains Bash/Python scripts for:

• Deployment automation
• kubectl wrappers
• Cleanup scripts
• Log collectors

Example:

scripts/
├── deploy.sh
├── validate-yamls.sh
└── cleanup.sh

7. ci-cd/ – Pipeline Definitions

Stores pipeline configuration for:

• GitHub Actions
• GitLab CI/CD
• Azure DevOps
• Jenkins
• ArgoCD / FluxCD manifests

Example:

ci-cd/
├── github-actions.yaml
├── gitlab-ci.yaml
└── argo-app.yaml

Purpose:
Automate deployments, validations, and image pushes.

8. templates/ – YAML Snippets / Boilerplate

Reusable YAML parts, such as:

• Pod templates
• Labels/annotations
• Resource-block templates
• Common affinity rules

Example:

templates/
├── pod-template.yaml
├── sidecar-template.yaml
└── affinity.yaml

Example Real-World Workflow

A developer wants to deploy a new version to dev:

1. Updates image version in overlays/dev/kustomization.yaml
2. Runs

   kubectl apply -k overlays/dev

1. Kustomize merges: Base manifests (in manifests/) + Dev patches (in overlays/dev/)
2. Resources get deployed to the cluster.

For Helm:

helm upgrade --install myapp charts/myapp -f charts/myapp/values-dev.yaml

Summary Table

This content originally appeared on DEV Community and was authored by Shiva Charan