151 lines
6.3 KiB
Markdown
Executable File
151 lines
6.3 KiB
Markdown
Executable File
# What is Azure DevOps (AzDO)?
|
|
|
|
Azure DevOps is Microsoft's platform for DevOps workflows. It covers:
|
|
|
|
- **Repos** — Git source code repositories
|
|
- **Pipelines** — automated build and deployment (CI/CD)
|
|
- **Boards** — work items, epics, features, tasks
|
|
- **Artifacts** — storing build outputs (packages, DLLs, etc.)
|
|
|
|
For this project, the relevant parts are **Pipelines** and **Repos**.
|
|
|
|
# What is a YAML Pipeline?
|
|
|
|
AzDO pipelines can be defined in two ways: through a GUI (classic) or via a YAML file stored in the repo. We use **YAML pipelines** — this means the pipeline definition lives in source control alongside the code, making it versioned and auditable.
|
|
|
|
## Basic YAML Pipeline Structure
|
|
|
|
``` yaml
|
|
trigger:
|
|
branches:
|
|
include:
|
|
- main
|
|
|
|
pool:
|
|
vmImage: 'windows-latest' # or a self-hosted agent
|
|
|
|
stages:
|
|
- stage: Build
|
|
jobs:
|
|
- job: BuildJob
|
|
steps:
|
|
- task: PowerShell@2
|
|
inputs:
|
|
filePath: 'scripts/Invoke-Deployment.ps1'
|
|
arguments: '-Customer ROMAC -Environment DEV -Stages PREDEPLOY,DEPLOY'
|
|
```
|
|
|
|
## Key YAML Concepts
|
|
|
|
| Term | Meaning |
|
|
| ---------- | ------------------------------------------------------------------- |
|
|
| `trigger` | What causes the pipeline to run (e.g. a push to main) |
|
|
| `pool` | The agent (machine) that runs the pipeline |
|
|
| `stage` | A high-level grouping of jobs (e.g. Build, Deploy) |
|
|
| `job` | A unit of work that runs on one agent |
|
|
| `step` | An individual action within a job (run a script, call a task, etc.) |
|
|
| `task` | A pre-built step from the AzDO marketplace (e.g. PowerShell@2) |
|
|
| `artifact` | Output from one stage/job that can be consumed by another |
|
|
|
|
# The ESP Pipelines
|
|
|
|
There are two existing pipelines to be aware of:
|
|
|
|
## ESS.esp Main Build
|
|
|
|
- **Purpose:** Builds the ESP applications from source code
|
|
- **Output:** Build artifacts (DLLs, binaries)
|
|
- **Known Issue:** The artifact does not separate applications cleanly - it produces a large flat folder of DLLs. See [[ESP Known Issues and Risks]]
|
|
- **Location:** AzDO → Pipelines → Runs for `ESS.esp Main Build`
|
|
|
|
## ESS.esp Deploy
|
|
|
|
- **Purpose:** Deploys ESP to a customer environment
|
|
- **Status:** Started by Team Ludo, incomplete
|
|
- **Location:** AzDO → Pipelines → Runs for `ESS.esp Deploy`
|
|
- This is the primary pipeline your team is responsible for completing
|
|
|
|
# How the Pipeline Calls Our Scripts
|
|
|
|
The pipeline's job is relatively thin - it is an **orchestrator** that calls our PowerShell entry point with the correct parameters.
|
|
|
|
Pipeline (YAML)
|
|
└── Calls: Invoke-Deployment.ps1 -Customer ROMAC -Environment DEV -Stages PREDEPLOY,DEPLOY,POSTDEPLOY
|
|
└── Tier 1 script (loads manifest, loads modules)
|
|
└── Calls Tier 2 scripts (PreDeployment.ps1, Deployment.ps1, etc.)
|
|
└── Calls Tier 3 functions (Stop-WindowsService, Invoke-Sql, etc.)
|
|
|
|
See [[ESP Scripts]] for full detail on the script architecture.
|
|
|
|
# Pipeline Agents
|
|
|
|
An **agent** is the machine that actually runs the pipeline. There are two types:
|
|
|
|
| Type | Description |
|
|
| ---------------- | ----------------------------------------------------------- |
|
|
| Microsoft-hosted | Azure spins up a fresh VM for each run; ephemeral |
|
|
| Self-hosted | A persistent machine you manage; has access to your network |
|
|
|
|
For deploying to customer VMs (ROMAC DEV), we will almost certainly need a **self-hosted agent** — a Microsoft-hosted agent running in Azure would not have network access to the customer's internal servers.
|
|
|
|
# Pipeline Variables and Secrets
|
|
|
|
Pipelines can use variables for configuration. Sensitive values (passwords, connection strings) should be stored as **secret variables** or in **Azure Key Vault**, never hardcoded in the YAML.
|
|
|
|
``` yaml
|
|
variables:
|
|
- name: CustomerName
|
|
value: ROMAC
|
|
- name: DbPassword
|
|
value: $(DB_PASSWORD) # references a secret variable set in AzDO UI
|
|
```
|
|
|
|
# Approvals and Gates
|
|
|
|
For higher environments (PROD), AzDO supports **manual approval gates** between stages — a human must approve before the pipeline continues. This is important when the scope expands beyond DEV.
|
|
|
|
# Pipeline Run History
|
|
|
|
Each pipeline run is logged in AzDO with full step-by-step output. This is your primary debugging tool when a deployment fails.
|
|
|
|
# Relationship to Our PowerShell Scripts
|
|
|
|
A key design goal is that the PowerShell scripts should be able to run **independently of AzDO** — i.e. you could call `Invoke-Deployment.ps1` directly from a terminal if needed. AzDO is just a convenient trigger and logging wrapper. This means the logic must not be baked into the YAML itself.
|
|
|
|
# One other note on agents:
|
|
|
|
Almost certainly ****Virtual Machines (VMs)****. Physical ("bare metal") servers are rarely used in modern infrastructure for this kind of thing. A data centre typically runs a small number of powerful physical machines, and on top of those you run many VMs — each VM behaves like its own independent server but they're all sharing the underlying physical hardware.
|
|
|
|
So the full picture is probably:
|
|
|
|
```
|
|
Physical machine(s) in ESS Altrincham DC
|
|
└── VM: AzDO Self-Hosted Agent
|
|
└── VM: App Server (runs the Windows Services, Citrix apps)
|
|
└── VM: SQL Server (runs EspBroker database)
|
|
... possibly more VMs
|
|
|
|
```
|
|
|
|
And the flow when you kick off a deployment in AzDO:
|
|
|
|
```
|
|
|
|
You click "Run Pipeline" in AzDO (cloud)
|
|
│
|
|
▼
|
|
AzDO talks to the self-hosted agent VM in Altrincham
|
|
│
|
|
▼
|
|
The agent picks up the job and runs the PowerShell scripts
|
|
│
|
|
▼
|
|
The scripts connect (via PowerShell remoting) to the App Server VM
|
|
The scripts connect to the SQL Server VM
|
|
│
|
|
▼
|
|
Deployment happens
|
|
```
|
|
|
|
The agent itself isn't the thing being deployed **to** — it's just the middleman that has network access to the other VMs in the same DC. Which also ties back to why each customer needs unique credentials — even though they share that infrastructure in DEV, each customer's VMs are in their own domain, so the agent needs the right credentials to authenticate into each one.
|