# mahdi2ba/private-aks-cluster-terraform-devops-1 architecture

> Architecture diagram of the GitHub repository mahdi2ba/private-aks-cluster-terraform-devops-1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mahdi2ba/private-aks-cluster-terraform-devops-1
- Repository: https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1

## Overview

##### Project type and purpose
- This is a full-stack Infrastructure-as-Code (IaC) + CI/CD solution that automates the provisioning of a private Azure Kubernetes Service (AKS) cluster and related Azure resources using Terraform, and the deployment of workloads (test web app, Redmine, self-hosted agents) via Azure DevOps pipelines and Helm.

##### File structure
- Top-level folders:
- agent – Terraform module to deploy a self-hosted Azure DevOps agent VM
- chart – Helm chart for the test web application
- pipelines – Azure DevOps YAML pipelines (CI/CD, destroy, self-hosted agent, Redmine via Helm, test web app)
- source – ASP.NET Core web app code + Dockerfile + Razor Pages
- storage-account – Terraform module + scripts to deploy a storage account for remote state
- terraform – Root Terraform configuration and modules for AKS, networking, firewall, ACR, key vault, diagnostics, bastion, node pools, etc.
- tfvars – Environment-specific variable files
- key-vault – Script to provision an Azure Key Vault and store secrets for DevOps variable groups

##### Extract architectural insights from the README
- The solution uses:
- Hub-and-spoke VNets with Azure Firewall and Bastion in the hub, AKS cluster & jumpbox VM in the spoke
- Private endpoints for ACR, Storage Account, Key Vault, plus Private DNS zones with VNet links
- Terraform remote state stored in an Azure Storage Account
- Azure DevOps pipelines orchestrating Terraform (`init`, `plan`, `apply`, `destroy`) and deploying workloads via Helm and Azure CLI on a self-hosted agent
- Log Analytics workspace for monitoring

##### Main components
a. Azure DevOps (organization, repo, pipelines, variable groups)
b. Terraform remote state (Azure Storage Account + Blob container)
c. Terraform modules (networking, AKS, ACR, storage, key vault, firewall, bastion, self-hosted agent)
d. Azure network topology (hub VNet + subnets: AzureFirewallSubnet, AzureBastionSubnet; spoke VNet + subnets: SystemSubnet, UserSubnet, VmSubnet; VNet peering)
e. Private endpoints & Private DNS zones (for ACR, storage, key vault) and DNS zone links
f. AKS cluster (private API server endpoint, system & user node pools, managed identity)
g. Azure Firewall (DNAT & UDR rules)
h. Jumpbox VM + Azure Bastion
i. Azure Container Registry (Premium SKU with private endpoint)
j. Azure Key Vault
k. Log Analytics workspace
l. Workloads:
– Test web app (Docker image in ACR, Helm chart)
– Redmine via Helm
– Azure DevOps self-hosted agent VM

##### Relationships and data flows
- Pipelines check out code → run Terraform on Azure DevOps agent → Terraform uses remote state in storage account → Terraform provisions Azure resources
- CI pipeline builds Docker image → pushes to ACR → pushes Helm chart to ACR
- CD pipeline (self-hosted agent) connects to private AKS endpoint through jumpbox → uses Helm to deploy workloads
- AKS cluster communicates privately with ACR, storage, Key Vault via private endpoints → uses Private DNS zones for name resolution
- Outbound egress from AKS node pools routed through Azure Firewall via UDRs
- Inbound workload traffic arrives at Azure Firewall public IP → DNAT rule → forwarded to internal Standard Load Balancer of AKS (or NGINX ingress) → pod
- Jumpbox VM is reachable via Azure Bastion

##### Architectural patterns and principles
- Hub-and-spoke networking for multitenancy and isolation
- Modular Terraform code with separate modules per resource type
- Remote state management for collaboration and locking
- Git-Ops style pipelines (CI builds artifacts, CD deploys infra + apps)
- Private Link for service access and least-privilege networking
- Clear separation of infrastructure provisioning (Terraform) and application deployment (Helm + Azure CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer / DevOps Tier
    subgraph "Developer / DevOps Tier"
        ADO["Azure DevOps Org & Repo"]:::graytooling
        Pipelines["Pipelines"]:::graytooling
        VarGroups["Variable Groups"]:::graytooling
        KV_Script["Key Vault Provisioning Script"]:::graytooling
    end

    ADO --> Pipelines
    Pipelines --> VarGroups
    VarGroups --> KV_Script

    %% Infrastructure Tier
    subgraph "Infrastructure Tier"
        RemoteState["Terraform Remote State\n(Storage Account)"]:::azureblue
        TerraformRoot["Terraform Root Configuration"]:::graytooling
        subgraph "Terraform Modules"
            Networking["Networking Module"]:::orangnet
            Firewall["Azure Firewall Module"]:::orangnet
            Bastion["Bastion Host Module"]:::orangnet
            AKSModule["AKS Cluster Module"]:::greencompute
            ACRModule["ACR Module"]:::azureblue
            KVModule["Key Vault Module"]:::azureblue
            LogAnalytics["Log Analytics Module"]:::azureblue
            StorageModule["Storage Account Module"]:::azureblue
            DNSZones["Private DNS Zones Module"]:::orangnet
            PrivateEP["Private Endpoints Module"]:::orangnet
            NodePools["Node Pools Module"]:::greencompute
            VMModule["VM Module"]:::greencompute
        end
    end

    Pipelines --> TerraformRoot
    TerraformRoot --> RemoteState
    TerraformRoot --> Networking
    TerraformRoot --> Firewall
    TerraformRoot --> Bastion
    TerraformRoot --> AKSModule
    TerraformRoot --> ACRModule
    TerraformRoot --> KVModule
    TerraformRoot --> LogAnalytics
    TerraformRoot --> StorageModule
    TerraformRoot --> DNSZones
    TerraformRoot --> PrivateEP
    TerraformRoot --> NodePools
    TerraformRoot --> VMModule

    %% Network Tier
    subgraph "Network Tier"
        HubVNet["Hub VNet"]:::orangnet
        SpokeVNet["Spoke VNet"]:::orangnet
        HubVNet --> AzureFirewall["Azure Firewall"]:::orangnet
        HubVNet --> BastionSubnet["Azure Bastion Subnet"]:::orangnet
        SpokeVNet --> AKSSubnet["AKS Subnet"]:::orangnet
        SpokeVNet --> VMSubnet["Jumpbox VM Subnet"]:::orangnet
        HubVNet --- SpokeVNet
    end

    Networking --> HubVNet
    Networking --> SpokeVNet

    %% Platform Tier
    subgraph "Platform Tier"
        AKS["AKS Cluster\n(Private Endpoint)"]:::greencompute
        JumpboxVM["Jumpbox VM"]:::greencompute
        Bastion["Azure Bastion"]:::greencompute
    end

    AKSModule --> AKS
    Bastion --> JumpboxVM
    Bastion --> Bastion

    %% Runtime Tier
    subgraph "Runtime Tier"
        ACR["Azure Container Registry"]:::azureblue
        StorageAccount["Storage Account"]:::azureblue
        KeyVault["Key Vault"]:::azureblue
        LogAnalyticsWS["Log Analytics Workspace"]:::azureblue
        SelfHostAgent["Self-Hosted Agent VM"]:::greencompute
        TestAppChart["Helm Chart\n(Test Web App)"]:::graytooling
        TestAppSource["Test Web App Source"]:::graytooling
        RedmineChart["Helm Chart\n(Redmine)"]:::graytooling
    end

    ACRModule --> ACR
    StorageModule --> StorageAccount
    KVModule --> KeyVault
    LogAnalytics --> LogAnalyticsWS
    VMModule --> SelfHostAgent
    Bastion --> SelfHostAgent
    TestAppChart --> TestAppSource

    %% Data Flows
    Pipelines -->|"run Terraform"| TerraformRoot
    TerraformRoot -->|"provisions"| HubVNet
    TerraformRoot -->|"provisions"| SpokeVNet
    Pipelines -->|"build & push image"| ACR
    Pipelines -->|"deploy via Helm"| AKS
    AKS -->|"pull image"| ACR
    AKS -->|"use secrets"| KeyVault
    AKS -->|"send logs"| LogAnalyticsWS
    AKS -->|"egress via"| AzureFirewall
    ClientTraffic["Client Traffic"]:::external
    ClientTraffic -->|"public IP"| AzureFirewall
    AzureFirewall -->|"DNAT"| AKS
    JumpboxVM -->|"SSH (via Bastion)"| AKS

    %% Click Events
    click Pipelines "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/pipelines/"
    click RemoteState "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/blob/master/storage-account/az-remote-backend-main.tf"
    click RemoteState "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/blob/master/storage-account/az-remote-backend-variables.tf"
    click RemoteState "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/blob/master/storage-account/create-storage-account.sh"
    click RemoteState "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/blob/master/storage-account/az-remote-backend-output.tf"
    click TerraformRoot "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/blob/master/terraform/main.tf"
    click TerraformRoot "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/blob/master/terraform/variables.tf"
    click TerraformRoot "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/blob/master/terraform/outputs.tf"
    click Networking "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/terraform/modules/virtual_network/"
    click Networking "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/terraform/modules/network_security_group/"
    click Networking "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/terraform/modules/route_table/"
    click Networking "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/terraform/modules/virtual_network_peering/"
    click Firewall "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/terraform/modules/firewall/"
    click Bastion "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/terraform/modules/bastion_host/"
    click AKSModule "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/terraform/modules/aks/"
    click ACRModule "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/terraform/modules/container_registry/"
    click KVModule "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/terraform/modules/key_vault/"
    click LogAnalytics "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/terraform/modules/log_analytics/"
    click StorageModule "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/terraform/modules/storage_account/"
    click DNSZones "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/terraform/modules/private_dns_zone/"
    click PrivateEP "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/terraform/modules/private_endpoint/"
    click NodePools "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/terraform/modules/node_pool/"
    click VMModule "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/terraform/modules/virtual_machine/"
    click SelfHostAgent "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/blob/master/agent/main.tf"
    click SelfHostAgent "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/agent/modules/virtual_machine/"
    click SelfHostAgent "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/agent/modules/storage_account/"
    click SelfHostAgent "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/blob/master/agent/scripts/configure-self-hosted-agent.sh"
    click TestAppChart "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/chart/"
    click TestAppSource "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/tree/master/source/"
    click KV_Script "https://github.com/mahdi2ba/private-aks-cluster-terraform-devops-1/blob/master/key-vault/create-key-vault-and-secrets.sh"

    %% Styles
    classDef azureblue fill:#0078D4,stroke:#005A9E,color:white;
    classDef greencompute fill:#107C10,stroke:#0B6A0B,color:white;
    classDef orangnet fill:#D35400,stroke:#A84300,color:white;
    classDef graytooling fill:#6B6B6B,stroke:#4A4A4A,color:white;
    classDef external fill:#AAAAAA,stroke:#666666,color:black;
```
