GitHub Monorepo Structure for Terraform Modules, Infrastructure, and GitOps Apps

This document describes the recommended folder and repository structure for managing cloud infrastructure and applications using Terraform modules, a dedicated infrastructure repo, and a GitOps apps repo.

---

1. terraform-modules (Reusable Terraform Modules)

This repository contains reusable, versioned Terraform modules for networking, databases, Kubernetes clusters, and more. Each module is self-contained and documented.

terraform-modules/
├── README.md
├── vpc/
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   └── README.md
├── rds/
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   └── README.md
├── redis/
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   └── README.md
└── ... (other modules as needed)

• Each directory under the root is a module (e.g., vpc, rds, redis).
• Modules are referenced in other repos by their Git URL and path.

---

2. devops-services (Infrastructure as Code)

This repository is the source of truth for cloud infrastructure deployments. It references modules from terraform-modules and organizes infrastructure per environment (dev, prod, etc.).

devops-services/
├── README.md
├── environments/
│   ├── dev/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── vpc-app.tf
│   │   ├── vpc-redis.tf
│   │   ├── vpc-rds.tf
│   │   ├── rds.tf
│   │   ├── redis.tf
│   │   ├── kops-cluster.tf
│   │   ├── outputs.tf
│   │   └── ... (other infra files)
│   └── prod/
│       ├── main.tf
│       ├── variables.tf
│       ├── vpc-app.tf
│       ├── vpc-redis.tf
│       ├── vpc-rds.tf
│       ├── rds.tf
│       ├── redis.tf
│       ├── kops-cluster.tf
│       ├── outputs.tf
│       └── ... (other infra files)
└── modules/ (optional: for custom wrappers/compositions)

• Each environment is fully isolated in its own directory.
• References modules in terraform-modules via source = "git::https://github.com/<org>/terraform-modules.git//vpc?ref=main"

---

3. dc (GitOps Repository for Apps & Kubernetes Manifests)

This repository stores all application definitions, Kubernetes manifests, and GitOps configurations for each environment.

dc/
├── README.md
├── environments/
│   ├── dev/
│   │   ├── apps/
│   │   │   ├── website-deployment.yaml
│   │   │   ├── website-service.yaml
│   │   │   └── ... (other apps)
│   │   ├── kustomization.yaml
│   │   └── flux/
│   │       └── ... (Flux sync, sources, etc.)
│   └── prod/
│       ├── apps/
│       │   └── ... (prod app manifests)
│       ├── kustomization.yaml
│       └── flux/
└── clusters/
    ├── dev-k8s/
    │   └── flux-system/
    └── prod-k8s/
        └── flux-system/

• Use Kustomize overlays or Helm charts for environment-specific configuration.
• Managed by Flux or Argo CD for continuous delivery to Kubernetes clusters.

---

Relationships

• terraform-modules provides reusable building blocks for infrastructure.
• devops-services assembles and deploys infrastructure using these modules, per environment.
• dc manages application delivery to clusters created by devops-services.

---

Best Practices

• All changes are made via pull requests for auditability and review.
• Use semantic versioning and tags for modules in terraform-modules.
• Integrate CI/CD for validating Terraform plans and Kubernetes manifests.
• Use clear documentation (README.md) in every repo and module directory.
• Separate secrets using tools like SOPS or SealedSecrets in the dc repo.

---

Example Workflow

1. Add/Update Module: Propose a change in terraform-modules via PR, tag a release.
2. Infra Change: Update devops-services to use/upgrade module, propose PR, review, and merge.
3. App Change: Update manifests in dc, propose PR, review, and merge. Flux/Argo applies change.

---

See Also

• Terraform Module Registry
• FluxCD Documentation
• Kustomize Documentation