# hamzaken/free5gc-gcp-terraform architecture

> Architecture diagram of the GitHub repository hamzaken/free5gc-gcp-terraform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hamzaken/free5gc-gcp-terraform
- Repository: https://github.com/hamzaken/free5gc-gcp-terraform

## Overview

This repository is a Terraform-based lab deployment for free5GC and UERANSIM on GKE. The main workflow is: an operator configures the lab, deploys GCP infrastructure, bootstraps subscriber secrets, deploys the Kubernetes platform, and verifies UE registration and traffic. The graph preserves those stages and the major core, RAN, data, and security capabilities. Relationships for unsampled Terraform subsystems follow README descriptions; the provisioner behavior is grounded in its excerpt. It does not imply detailed network-function call flows.

Main entry points: [`terraform/platform`](https://github.com/hamzaken/free5gc-gcp-terraform/tree/main/terraform/platform) (Kubernetes platform stage), [`scripts/deploy.sh`](https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/scripts/deploy.sh) (Deployment orchestrator), [`terraform/infra`](https://github.com/hamzaken/free5gc-gcp-terraform/tree/main/terraform/infra) (GCP infrastructure stage), [`config`](https://github.com/hamzaken/free5gc-gcp-terraform/tree/main/config) (Lab configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deploy["Configuration and operations"]
  node_config["Lab configuration"]
  node_validate["Offline validation<br/>[validate.sh]"]
  node_deploy_script["Deployment orchestrator<br/>[deploy.sh]"]
  node_verify["Functional verification<br/>[verify.sh]"]
end

subgraph group_infra["GCP infrastructure"]
  node_infra_tf["GCP infrastructure stage"]
  node_network["VPC and network ranges"]
  node_gke["Private GKE cluster"]
  node_iam_secrets["IAM and secret storage"]
end

subgraph group_platform["5G platform"]
  node_platform_tf["Kubernetes platform stage"]
  node_core["free5GC core network<br/>[free5gc.tf]"]
  node_database[("MongoDB subscriber store<br/>[free5gc.tf]")]
  node_ran["UERANSIM gNB and UEs<br/>[ueransim.tf]"]
  node_kernel["gtp5g node module<br/>[build-and-load.sh]"]
  node_policies["Network policies"]
end

subgraph group_subscriber["Subscriber provisioning"]
  node_bootstrap["Secret bootstrap"]
  node_provisioner["Subscriber provisioner<br/>[provision.js]"]
  node_subscriber_job["Provisioning Job<br/>[provisioning.tf]"]
end

node_operator(("Lab operator"))
node_secret_manager[("Google Secret Manager")]
node_internet(("Internet"))

node_operator -->|"configures"| node_config
node_config -->|"validates"| node_validate
node_operator -->|"runs"| node_deploy_script
node_deploy_script -->|"deploys first"| node_infra_tf
node_deploy_script -->|"runs between stages"| node_bootstrap
node_deploy_script -->|"deploys second"| node_platform_tf
node_infra_tf -->|"creates"| node_network
node_infra_tf -->|"creates"| node_gke
node_infra_tf -->|"provisions"| node_iam_secrets
node_bootstrap -->|"stores credentials"| node_secret_manager
node_platform_tf -->|"installs"| node_core
node_platform_tf -->|"deploys"| node_database
node_platform_tf -->|"deploys"| node_ran
node_platform_tf -->|"uses node script"| node_kernel
node_platform_tf -->|"applies"| node_policies
node_platform_tf -->|"creates"| node_subscriber_job
node_subscriber_job -->|"runs"| node_provisioner
node_provisioner -->|"upserts subscriber data"| node_database
node_secret_manager -.->|"syncs secrets"| node_platform_tf
node_operator -->|"checks deployment"| node_verify
node_ran -.->|"routes UE traffic via UPF"| node_internet

click node_config "https://github.com/hamzaken/free5gc-gcp-terraform/tree/main/config"
click node_validate "https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/scripts/validate.sh"
click node_deploy_script "https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/scripts/deploy.sh"
click node_verify "https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/scripts/verify.sh"
click node_infra_tf "https://github.com/hamzaken/free5gc-gcp-terraform/tree/main/terraform/infra"
click node_network "https://github.com/hamzaken/free5gc-gcp-terraform/tree/main/terraform/infra/modules/network"
click node_gke "https://github.com/hamzaken/free5gc-gcp-terraform/tree/main/terraform/infra/modules/gke"
click node_iam_secrets "https://github.com/hamzaken/free5gc-gcp-terraform/tree/main/terraform/infra/modules/secrets"
click node_platform_tf "https://github.com/hamzaken/free5gc-gcp-terraform/tree/main/terraform/platform"
click node_core "https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/terraform/platform/free5gc.tf"
click node_database "https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/terraform/platform/free5gc.tf"
click node_ran "https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/terraform/platform/ueransim.tf"
click node_kernel "https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/kubernetes/gtp5g/build-and-load.sh"
click node_policies "https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/terraform/platform/network_policies.tf"
click node_bootstrap "https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/scripts/bootstrap-secrets.sh"
click node_provisioner "https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/provisioning/subscribers/provision.js"
click node_subscriber_job "https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/terraform/platform/provisioning.tf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_validate,node_deploy_script,node_verify toneBlue
class node_infra_tf,node_network,node_gke,node_iam_secrets,node_secret_manager toneAmber
class node_platform_tf,node_core,node_database,node_ran,node_kernel,node_policies toneMint
class node_bootstrap,node_provisioner,node_subscriber_job toneRose
class node_operator,node_internet toneIndigo
```

## Components

### Configuration and operations

- [Lab configuration](https://github.com/hamzaken/free5gc-gcp-terraform/tree/main/config): `config`
- [Offline validation](https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/scripts/validate.sh): `scripts/validate.sh`
- [Deployment orchestrator](https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/scripts/deploy.sh): `scripts/deploy.sh`
- [Functional verification](https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/scripts/verify.sh): `scripts/verify.sh`

### GCP infrastructure

- [GCP infrastructure stage](https://github.com/hamzaken/free5gc-gcp-terraform/tree/main/terraform/infra): `terraform/infra`
- [VPC and network ranges](https://github.com/hamzaken/free5gc-gcp-terraform/tree/main/terraform/infra/modules/network): `terraform/infra/modules/network`
- [Private GKE cluster](https://github.com/hamzaken/free5gc-gcp-terraform/tree/main/terraform/infra/modules/gke): `terraform/infra/modules/gke`
- [IAM and secret storage](https://github.com/hamzaken/free5gc-gcp-terraform/tree/main/terraform/infra/modules/secrets): `terraform/infra/modules/secrets`

### 5G platform

- [Kubernetes platform stage](https://github.com/hamzaken/free5gc-gcp-terraform/tree/main/terraform/platform): `terraform/platform`
- [free5GC core network](https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/terraform/platform/free5gc.tf): `terraform/platform/free5gc.tf`
- [MongoDB subscriber store](https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/terraform/platform/free5gc.tf): `terraform/platform/free5gc.tf`
- [UERANSIM gNB and UEs](https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/terraform/platform/ueransim.tf): `terraform/platform/ueransim.tf`
- [gtp5g node module](https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/kubernetes/gtp5g/build-and-load.sh): `kubernetes/gtp5g/build-and-load.sh`
- [Network policies](https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/terraform/platform/network_policies.tf): `terraform/platform/network_policies.tf`

### Subscriber provisioning

- [Secret bootstrap](https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/scripts/bootstrap-secrets.sh): `scripts/bootstrap-secrets.sh`
- [Subscriber provisioner](https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/provisioning/subscribers/provision.js): `provisioning/subscribers/provision.js`
- [Provisioning Job](https://github.com/hamzaken/free5gc-gcp-terraform/blob/main/terraform/platform/provisioning.tf): `terraform/platform/provisioning.tf`

### Other components

- **Lab operator**
- **Google Secret Manager**
- **Internet**

## Connections

- Lab operator → Lab configuration: configures (evidence: `README.md`)
- Lab configuration → Offline validation: validates (evidence: `README.md`)
- Lab operator → Deployment orchestrator: runs (evidence: `README.md`)
- Deployment orchestrator → GCP infrastructure stage: deploys first (evidence: `README.md`)
- Deployment orchestrator → Secret bootstrap: runs between stages (evidence: `README.md`)
- Deployment orchestrator → Kubernetes platform stage: deploys second (evidence: `README.md`)
- GCP infrastructure stage → VPC and network ranges: creates (evidence: `README.md`)
- GCP infrastructure stage → Private GKE cluster: creates (evidence: `README.md`)
- GCP infrastructure stage → IAM and secret storage: provisions (evidence: `README.md`)
- Secret bootstrap → Google Secret Manager: stores credentials (evidence: `README.md`)
- Kubernetes platform stage → free5GC core network: installs (evidence: `README.md`)
- Kubernetes platform stage → MongoDB subscriber store: deploys (evidence: `README.md`)
- Kubernetes platform stage → UERANSIM gNB and UEs: deploys (evidence: `README.md`)
- Kubernetes platform stage → gtp5g node module: uses node script (evidence: `README.md`)
- Kubernetes platform stage → Network policies: applies (evidence: `README.md`)
- Kubernetes platform stage → Provisioning Job: creates (evidence: `README.md`)
- Provisioning Job → Subscriber provisioner: runs (evidence: `provisioning/subscribers/provision.js`)
- Subscriber provisioner → MongoDB subscriber store: upserts subscriber data (evidence: `provisioning/subscribers/provision.js`)
- Google Secret Manager → Kubernetes platform stage: syncs secrets (evidence: `README.md`)
- Lab operator → Functional verification: checks deployment (evidence: `README.md`)
- UERANSIM gNB and UEs → Internet: routes UE traffic via UPF (evidence: `README.md`)
