# pacroy/microk8s-azure-vm architecture

> Architecture diagram of the GitHub repository pacroy/microk8s-azure-vm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pacroy/microk8s-azure-vm
- Repository: https://github.com/pacroy/microk8s-azure-vm

## Overview

##### Project type and purpose
- This is a Terraform-based infrastructure-as-code (IaC) project that automates provisioning of a single-node MicroK8s Kubernetes cluster on an Azure VM.
- Its primary goal is to minimize cost by running non-critical workloads on a single VM, while exposing SSH, kubectl and application ingress endpoints via an Azure public load balancer.

##### File structure
- Top-level Terraform files define providers, variables, locals, resources, outputs, and the load balancer:
- providers.tf – Azure provider setup
- variables.tf – input variables (resource group, suffix, IP ranges)
- locals.tf – computed locals for naming conventions and port ranges
- main.tf – core resources (VNet, subnet, NSG, NIC, VM)
- loadbalancer.tf – public IP and load balancer + rules for SSH, kubectl, HTTP/HTTPS, outbound SNAT
- outputs.tf – exposed Terraform outputs (SSH port, public IP, FQDN, kubectl port)
- init.cfg.tftpl – cloud-init template for VM bootstrap (install/upgrades, MicroK8s, ingress, cert-manager, Let’s Encrypt, OS upgrades)
- CI/CD and quality checks via GitHub Actions (linter.yml, mdlink.yml), mdlink config, and sync workflows.

##### README for additional insights
- Resources created: virtual network → subnet → NSG → VM with public load balancer
- Cloud-init config installs and configures MicroK8s with DNS, storage, Helm3, ingress-nginx, cert-manager, ACME issuer
- Two execution modes: Terraform Cloud (remote) or local with Azure CLI
- End-to-end workflow: terraform init → apply → SSH & kubectl connectivity → download KUBECONFIG → DNS record update.

##### Final reminders
- Don’t omit the cloud-init bootstrap step—this is critical for the immutable setup of MicroK8s and add-ons.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Terraform Layer
    subgraph "Terraform IaC Layer"
        direction TB
        TFCLI["Developer Workstation\nTerraform CLI"]:::terraform
        TFC["Terraform Cloud"]:::terraform
        TFCLI -->|“terraform init/apply”| AzureAPI
        TFC -->|“terraform apply”| AzureAPI

        providers["providers.tf"]:::terraform
        variables["variables.tf"]:::terraform
        locals["locals.tf"]:::terraform
        main["main.tf"]:::terraform
        lb["loadbalancer.tf"]:::terraform
        outputs["outputs.tf"]:::terraform
        initTmpl["init.cfg.tftpl"]:::terraform

        TFCLI --> providers
        TFCLI --> variables
        TFCLI --> locals
        TFCLI --> main
        TFCLI --> lb
        TFCLI --> outputs
        TFCLI --> initTmpl
    end

    click providers "https://github.com/pacroy/microk8s-azure-vm/blob/main/providers.tf"
    click variables "https://github.com/pacroy/microk8s-azure-vm/blob/main/variables.tf"
    click locals "https://github.com/pacroy/microk8s-azure-vm/blob/main/locals.tf"
    click main "https://github.com/pacroy/microk8s-azure-vm/blob/main/main.tf"
    click lb "https://github.com/pacroy/microk8s-azure-vm/blob/main/loadbalancer.tf"
    click outputs "https://github.com/pacroy/microk8s-azure-vm/blob/main/outputs.tf"
    click initTmpl "https://github.com/pacroy/microk8s-azure-vm/blob/main/init.cfg.tftpl"

    %% Azure Control Plane
    AzureAPI["Azure Resource Manager API"]:::azure

    %% Azure Resources
    subgraph "Azure Managed Services" 
        direction TB
        VNet["azurerm_virtual_network"]:::azure
        Subnet["azurerm_subnet"]:::azure
        NSG["azurerm_network_security_group"]:::azure
        PubIP["azurerm_public_ip"]:::azure
        LB["azurerm_lb\n(SSH, kubectl, HTTP/HTTPS, SNAT)"]:::azure
        NIC["azurerm_network_interface"]:::azure
        VM["azurerm_linux_virtual_machine\nUbuntu 20.04"]:::azure
    end

    AzureAPI --> VNet
    VNet --> Subnet
    Subnet --> NSG
    NSG --> NIC
    NIC --> VM
    AzureAPI --> PubIP
    PubIP --> LB
    LB --> NIC

    %% VM Provisioning and Kubernetes
    subgraph "VM Provisioning" 
        direction TB
        CI["cloud-init bootstrap"]:::vm
        CI --> MicroK8s["MicroK8s Kubernetes"]:::k8s
        MicroK8s --> API["API Server"]:::k8s
        MicroK8s --> Kubelet["kubelet"]:::k8s
        MicroK8s --> DNS["CoreDNS"]:::k8s
        MicroK8s --> Storage["Local PV Storage"]:::k8s
        MicroK8s --> Ingress["ingress-nginx"]:::k8s
        MicroK8s --> CertManager["cert-manager"]:::k8s
        CertManager --> Issuer["Let’s Encrypt ClusterIssuer"]:::k8s
    end

    VM --> CI

    %% Data Plane
    ExternalUser["External User\n(SSH, kubectl, HTTP/HTTPS)"]:::external
    ExternalUser -->|“traffic”| PubIP
    PubIP --> LB
    LB -->|"routes to VM"| VM
    VM -->|"KUBECONFIG download & outputs"\nSSH port, Public IP, FQDN, kubectl port| TFCLI

    %% GitHub Actions
    subgraph "CI/CD & Quality" 
        direction TB
        Linter[".github/workflows/linter.yml"]:::ci
        MDLink[".github/workflows/mdlink.yml"]:::ci
        SyncWF[".github/workflows/sync.yml"]:::ci
        Config[".github/mdlink/mlc_config.json"]:::ci
        Readme["README.md"]:::ci
    end

    classDef terraform fill:#f9f,stroke:#333,stroke-width:1px;
    classDef azure fill:#bbf,stroke:#333,stroke-width:1px;
    classDef vm fill:#bfb,stroke:#333,stroke-width:1px;
    classDef k8s fill:#ffb,stroke:#333,stroke-width:1px;
    classDef external fill:#fdd,stroke:#333,stroke-width:1px;
    classDef ci fill:#dfd,stroke:#333,stroke-width:1px;

    click Linter "https://github.com/pacroy/microk8s-azure-vm/blob/main/.github/workflows/linter.yml"
    click MDLink "https://github.com/pacroy/microk8s-azure-vm/blob/main/.github/workflows/mdlink.yml"
    click SyncWF "https://github.com/pacroy/microk8s-azure-vm/blob/main/.github/workflows/sync.yml"
    click Config "https://github.com/pacroy/microk8s-azure-vm/blob/main/.github/mdlink/mlc_config.json"
    click Readme "https://github.com/pacroy/microk8s-azure-vm/blob/main/README.md"
```
