# azure/jenkins architecture

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

- Interactive diagram: https://gitdiagram.com/azure/jenkins
- Repository: https://github.com/azure/jenkins

## Overview

##### Project type and purpose
- This is an Azure “Solution Template” repository that defines infrastructure-as-code (IaC) for deploying a Jenkins master on a Linux VM within Azure, plus accompanying artifacts for:
- Initializing Windows-based Jenkins agents via PowerShell
- Disaster-recovery guidance
- “Quickstart” blue-green or rolling-update pipelines targeting either AKS or VM Scale Sets

##### File structure
- Top-level folders:
- solution_template/ & solution_template_fairfax/ – ARM JSON templates, UI definition, parameter files, nginx web page assets, install scripts
- agents_scripts/ – PowerShell scripts (JNLP & SSH) and XML configs for bootstrapping Windows Jenkins agents
- quickstart_templates/ – subfolders for shared credentials and zero-downtime deployment (kubernetes & vmss)
- disaster_recovery/ – markdown doc describing DR steps
- Key IaC artifacts: mainTemplate.json, createUiDefinition.json, parameter files (publicIP, VM, vnet), ARM-linked custom script extensions (install_jenkins.sh, install-web-page.sh)
- Deployment scenarios: single Linux VM + nginx front end, optional AKS cluster or VMSS for blue/green or rolling updates

##### Extract additional architecture insights from the README
- Azure Marketplace template deploys an Ubuntu VM, installs Jenkins and plugins
- Windows VMs can be auto-provisioned as agents via the provided scripts
- Quickstart pipelines use Azure CLI, kubectl, Packer for image baking and deployment orchestration

a. Main components
- Azure Resource Manager (ARM) orchestration
- Resource Group containing:
– Virtual Network & Subnet
– Network Security Group (firewall rules)
– Public IP & optional Load Balancer
– Linux VM (Ubuntu) running Jenkins master
– nginx web server (optional front end)
– Windows VMs (as Jenkins agents)
– (Optional) AKS cluster or VM Scale Set for application deployment
- External: users (DevOps engineers), Azure Marketplace, Azure Storage (for ARM scripts & images)
b. Relationships & interactions
- ARM template → provisions all Azure resources
- Jenkins master ← uses Custom Script Extension to run install_jenkins.sh
- Jenkins UI served via nginx or directly on VM’s public endpoint
- Jenkins master → spawns agent processes on Windows VMs (PowerShell scripts via JNLP/SSH)
- Jenkins jobs → call Azure CLI, kubectl or Packer to deploy apps to AKS/VMSS
- Disaster recovery guide interacts with Azure Backup or snapshotting of VM disks
c. Architectural patterns & principles
- Declarative IaC (ARM JSON)
- Separation of control plane (ARM) vs. data plane (VM workloads)
- Blue-Green and Rolling Update strategies encapsulated in quickstart pipelines
- Extensibility: agent bootstrap scripts can be swapped out or extended
d. Core technologies & frameworks
- Azure Resource Manager (mainTemplate.json, parameter files)
- Azure Marketplace solution template conventions
- Bash scripts, PowerShell scripts, Custom Script Extension
- nginx for static content or reverse proxy
- Jenkins (master/agent architecture)
- Kubernetes (AKS) or VM Scale Set for zero-downtime deployments
- Packer (for VMSS image baking)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    U["DevOps Engineers"]:::external
    AM["Azure Marketplace"]:::external
    AS["Azure Storage"]:::storage

    %% Deployment Orchestration
    subgraph "Deployment Orchestration"
        ARM["ARM Template\n(mainTemplate.json)"]:::iac
        UI["ARM UI Definition\n(createUiDefinition.json)"]:::iac
    end

    %% Parameter Files
    subgraph "Parameter Files"
        PW["VM Password\n(VM-password.json)"]:::iac
        SSHKey["VM SSH Public Key\n(VM-sshPublicKey.json)"]:::iac
        IPExist["Public IP Existing\n(publicIP-existing.json)"]:::iac
        IPNew["Public IP New\n(publicIP-new.json)"]:::iac
        VNetExist["VNet Existing\n(vnet-existing.json)"]:::iac
        VNetNew["VNet New\n(vnet-new.json)"]:::iac
    end

    %% Resource Group
    subgraph "Resource Group" 
        subgraph "Networking Resources"
            VNet["Virtual Network"]:::network
            NSG["Network Security Group"]:::network
            IP["Public IP"]:::network
            LB["Load Balancer"]:::network
        end

        subgraph "Compute Resources"
            JM["Jenkins Master\n(Ubuntu VM)"]:::compute
            NG["nginx Front End"]:::compute
            subgraph "Windows Agent Pool"
                WA1["Windows Agent VM"]:::compute
                WA2["Windows Agent VM"]:::compute
            end
            subgraph "Optional Deployment Targets"
                AKS["AKS Cluster"]:::compute
                VMSS["VM Scale Set"]:::compute
            end
        end
    end

    %% Scripts & Configurations
    subgraph "Bootstrap & Scripts"
        CSE["Custom Script Extensions"]:::script
        PSJNLP["PowerShell JNLP Init\n(Jenkins-Windows-Init-Script-Jnlp.ps1)"]:::script
        PSSSH["PowerShell SSH Init\n(Jenkins-Windows-Init-Script-SSH.ps1)"]:::script
        XML["Agent XML Config\n(jenkins-slave.xml)"]:::script
        EXE["Agent EXE Config\n(jenkins-slave.exe.config)"]:::script
        DR["Disaster Recovery Guide\n(disaster-recovery.md)"]:::doc
        QSShared["Shared Credentials\n(sp-credentials.xml,\nssh-credentials.xml)"]:::script
        QSK8Entry["AKS Deployment Script\n(301-jenkins-aks-zero-downtime-deployment.sh)"]:::script
        QSVmssEntry["VMSS Deployment Script\n(301-jenkins-vmss-zero-downtime-deployment.sh)"]:::script
    end

    %% Connections
    U --> ARM
    AM --> ARM
    AS --> ARM

    ARM --> UI
    ARM --> PW
    ARM --> SSHKey
    ARM --> IPExist
    ARM --> IPNew
    ARM --> VNetExist
    ARM --> VNetNew

    ARM --> VNet
    ARM --> NSG
    ARM --> IP
    ARM --> LB
    ARM --> JM
    ARM --> WA1
    ARM --> WA2
    ARM --> AKS
    ARM --> VMSS

    JM --> CSE
    CSE -->|"runs install_jenkins.sh,\ninstall-web-page.sh"| JM

    JM -->|"Serves UI"| NG
    JM -->|"JNLP/SSH"| WA1
    JM -->|"JNLP/SSH"| WA2

    JM -->|"Azure CLI, kubectl"| AKS
    JM -->|"Azure CLI, Packer"| VMSS

    DR -->|"Guides backup/snapshots"| JM

    %% Click Events
    click ARM "https://github.com/azure/jenkins/blob/master/solution_template/mainTemplate.json"
    click UI "https://github.com/azure/jenkins/blob/master/solution_template/createUiDefinition.json"
    click PW "https://github.com/azure/jenkins/blob/master/solution_template/VM-password.json"
    click SSHKey "https://github.com/azure/jenkins/blob/master/solution_template/VM-sshPublicKey.json"
    click IPExist "https://github.com/azure/jenkins/blob/master/solution_template/publicIP-existing.json"
    click IPNew "https://github.com/azure/jenkins/blob/master/solution_template/publicIP-new.json"
    click VNetExist "https://github.com/azure/jenkins/blob/master/solution_template/vnet-existing.json"
    click VNetNew "https://github.com/azure/jenkins/blob/master/solution_template/vnet-new.json"
    click PSJNLP "https://github.com/azure/jenkins/blob/master/agents_scripts/Jenkins-Windows-Init-Script-Jnlp.ps1"
    click PSSSH "https://github.com/azure/jenkins/blob/master/agents_scripts/Jenkins-Windows-Init-Script-SSH.ps1"
    click XML "https://github.com/azure/jenkins/blob/master/agents_scripts/jenkins-slave.xml"
    click EXE "https://github.com/azure/jenkins/blob/master/agents_scripts/jenkins-slave.exe.config"
    click DR "https://github.com/azure/jenkins/blob/master/disaster_recovery/disaster-recovery.md"
    click QSK8Entry "https://github.com/azure/jenkins/blob/master/quickstart_templates/zero_downtime_deployment/301-jenkins-aks-zero-downtime-deployment.sh"
    click QSVmssEntry "https://github.com/azure/jenkins/blob/master/quickstart_templates/zero_downtime_deployment/301-jenkins-vmss-zero-downtime-deployment.sh"

    classDef external fill:#E8E8E8,stroke:#333,stroke-width:1px
    classDef storage fill:#FDF5E6,stroke:#DAA520,stroke-width:1px
    classDef iac fill:#E0FFFF,stroke:#5F9EA0,stroke-width:1px
    classDef network fill:#FFE4E1,stroke:#CD5C5C,stroke-width:1px
    classDef compute fill:#E6E6FA,stroke:#9370DB,stroke-width:1px
    classDef script fill:#F0FFF0,stroke:#32CD32,stroke-width:1px
    classDef doc fill:#FFF5EE,stroke:#FFA07A,stroke-width:1px
```
