docs: README.md improvements (#116)

* docs: update readme to reflect updatated quota name form 'Low Priority' to 'Spot'

* docs(readme): expand architecture details and component docs

* Added “How It Works” section outlining event flow from GitHub to VM teardown
* Documented roles of Service Bus, App Configuration, both Key Vaults, and Shared Image Gallery
* Clarified Runner-Controller responsibilities and queue consumption behavior

Closes #109

* docs: Add information notes in the docs for the different azure keyvault
authentication methods depending RBAC vs Access Policy.

Also includes a simple example to help get users started.

Author: jburns24

README.md

@@ -16,6 +16,19 @@ This project includes all necessary components to spin up the infrastructure for
 ## Architecture Diagram
 ![Terraform Azure GitHub Runners](https://user-images.githubusercontent.com/100593043/194669700-4cd851ab-b047-4dd4-87bd-81cb4e572e24.png)
 
+### How It Works
+1. **GitHub Actions event ➜ Event-Handler** – A `workflow_job` event is emitted by GitHub Enterprise/Cloud and forwarded by a GitHub App to the Event-Handler Azure Function.
+2. **Event-Handler ➜ Service Bus** – The function validates the request, filters on runner labels, and publishes a message to an Azure Service Bus queue.
+3. **Service Bus ➜ Runner-Controller** – The Runner-Controller Azure App Service continuously listens to the queue. Based on settings stored in Azure App Configuration it decides whether to spin up a new runner or rely on the warm-pool.
+4. **Runner-Controller ➜ Azure VM** – When a new runner is required the controller:
+   • Fetches the latest Packer-built image from an Azure Shared Image Gallery.  
+   • Retrieves a one-time registration token from GitHub, storing it in the Registration Key Vault.  
+   • Creates a spot/on-demand VM, injecting the token via cloud-init so the VM registers itself with GitHub on first boot.
+5. **Runner lifecycle** – The VM processes exactly one job, then a shutdown hook notifies the controller which de-registers the runner and deletes the VM, keeping the warm-pool at the desired size.
+6. **Secrets & config** – GitHub App credentials and webhook secret live in the App Key Vault; operational parameters are stored in Azure App Configuration. All resources use Managed Identities for least-privilege access.
+7. **Provisioning** – This entire architecture is provisioned reproducibly by the Terraform module contained in this repository.
+
+
 ## Components
 
 ### Terraform Module
@@ -25,15 +38,31 @@ This [Terraform](https://www.terraform.io/) module generates the infrastructure
 The event-handler will receive messages from the GitHub App during workflow run events.  It will act as a filter to ensure they are from GitHub with labels that match what is provided in the module.
 
 ### Runner-Controller (Azure App Service)
-This application will act as the controller for the warm pool and ensure that the pool size adheres to the parameters specified in the Terraform module.  It will consume events from the queue as necessary to create VMs and ensure a healthy number of VMs are always ready to process new workflow jobs.
+This application will act as the controller for the warm pool and ensure that the pool size adheres to the parameters specified in the Terraform module. It consumes Service Bus messages to create or delete VMs so that a healthy number of runners are always ready to process workflow jobs.
+
+### Service Bus (Azure Service Bus)
+A reliable message queue that buffers `workflow_job` events between the Event-Handler and Runner-Controller, ensuring no job is lost and enabling smooth scale-out.
+
+### App Configuration (Azure App Configuration)
+Central store for runtime settings such as warm-pool size, VM SKU, image version, and spot/on-demand preferences. Runner-Controller reads these values on startup and on a configurable interval.
+
+### App Key Vault (Azure Key Vault)
+Holds long-lived secrets used by the Event-Handler and Runner-Controller (GitHub App private key, webhook secret, etc.). Accessed via Managed Identity with the minimum required permissions.
+
+### Registration Key Vault (Azure Key Vault)
+Stores the short-lived registration tokens generated by Runner-Controller. Each token is valid for a single VM and is deleted once the runner registers with GitHub.
+
+### Shared Image Gallery
+Contains HashiCorp Packer-built VM images pre-loaded with the toolchain your organization needs. Runner-Controller always provisions the latest image version.
+
 
 ## Getting Started
 
 ### Pre-requisites
 - GitHub App for Organization (owner access)
 - Azure
   - Subscription
-    - *Note: Subscription quota for "Total Regional Low-priority vCPUs" should be increased to allow multiple spot instances*
+    - *Note: Subscription quota for "Total Regional Spot vCPUs" should be increased to allow multiple spot instances*
   - Resource Group
   - Subnet with internet access
   - KeyVault for GitHub App Credential
@@ -71,11 +100,11 @@ The GitHub App serves as the foundation for sending webhook events to App A and
 | Homepage URL                            | {insert-any-url}     |
 | Webhook Active                          | False                |
 | Webhook URL                             |                      |
-| Subscribe to events                     | Workflow job         |
+| Subscribe to events*                     | Workflow job         |
 | Where can this GitHub App be installed? | Only on this account |
 
 *Note: You will need one GitHub App per org. Allowing installation to "Any account" makes it difficult to change access if installed on orgs outside your control.
-
+*Note: Initially the webhook is disabled, but will be enabled in the next step. You will only see 'Subscribed to events' after the webhook is enabled.
 #### **Add secrets to Azure KeyVault**
 
 (optional) Set Key Vault name variable:
@@ -108,34 +137,119 @@ Webhook Secret:
 az keyvault secret set --name github-webhook-secret --value $(uuidgen) --vault-name $KEYVAULT_NAME
 ```
 
-*Note: The private key must be added via the [AZ CLI](https://learn.microsoft.com/en-us/cli/azure/), all other secrets can be added manually via the portal if you choose to do so.
+*Note: The private key must be added via the [AZ CLI](https://learn.microsoft.com/en-us/cli/azure/), all other secrets can be added manually via the portal if you choose to do so.*
+
+> **Key Vault authorization models**
+>
+> • If your Key Vault was created with **RBAC authorization** (`enableRbacAuthorization = true` or `az keyvault create --enable-rbac-authorization true`), you must grant the **Key Vault Secrets Officer** (or Administrator) role to **both** the Event-Handler Function **and** the Runner-Controller App Service managed identities. Terraform cannot assign this role unless you opt into the upcoming RBAC support variable.
+>
+> • If your vault uses the older **access-policy model** (`enableRbacAuthorization = false`, the module default), Terraform will automatically create an access policy that lets the Function and Controller read secrets.
+>
+> **Default behaviour:** The Azure portal and recent versions of the Azure CLI (*az* ≥ 2.51) create Key Vaults with **RBAC enabled by default**. In contrast, the Terraform `azurerm_key_vault` resource keeps **RBAC disabled by default**—you must set `enable_rbac_authorization = true` to opt-in. Keep this in mind when mixing manual and IaC-provisioned environments.
+
 
 ### Setup Terraform Module
 
-Consume this `azure_github_runner` module with inputs required for your GitHub Enterprise Cloud or GitHub Enterprise server configuration. Example of how to consume the module are coming soon.
+Below is a **minimal working example** you can copy-paste into a new `main.tf`. Replace the placeholder values with your own IDs.
+
+```hcl
+terraform {
+  required_providers {
+    azurerm = {
+      source  = "hashicorp/azurerm"
+      version = ">= 3.100"
+    }
+    azuread = {
+      source  = "hashicorp/azuread"
+      version = ">= 2.45"
+    }
+  }
+}
+
+provider "azurerm" {
+  features {}
+  tenant_id       = "00000000-0000-0000-0000-000000000000" # Azure AD tenant
+  subscription_id = "11111111-1111-1111-1111-111111111111" # Azure subscription
+}
+
+provider "azuread" {}
+
+module "github_runners" {
+  source  = "git::https://github.com/liatrio/terraform-azure-github-runner.git?ref=vX.Y.Z" # pin a release tag
+
+  # ---- Azure settings ----
+  azure_tenant_id                  = "00000000-0000-0000-0000-000000000000"
+  azure_subscription_id            = "11111111-1111-1111-1111-111111111111"
+  azure_resource_group_name        = "rg-github-runners"
+  azure_resource_group_location    = "eastus"
+  azure_subnet_id                  = "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Network/virtualNetworks/vnet-github-runners/subnets/subnet-runners"
+
+  # ---- GitHub App details ----
+  github_organization   = "my-org"
+  github_app_id         = "123456"
+  github_client_id      = "Iv1.abcdef123456"
+  github_installation_id = "7891011"
+
+  # ---- Key Vault secret IDs (Key Vault *ID* not value) ----
+  azure_secrets_key_vault_resource_id          = "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/kv-gh-secrets"
+  azure_runner_default_password_key_vault_id   = "/.../secrets/azure-runner-default-password"
+  github_client_secret_key_vault_id            = "/.../secrets/github-client-secret"
+  github_webhook_secret_key_vault_id           = "/.../secrets/github-webhook-secret"
+  github_private_key_key_vault_id              = "/.../secrets/github-private-key"
+
+  # ---- Misc ----
+  owners = ["00000000-0000-0000-0000-000000000000"] # Azure AD object IDs
+}
+
+output "function_webhook_url" {
+  value       = module.github_runners.function_webhook_url
+  description = "URL to paste into the GitHub App webhook settings"
+  sensitive   = true
+}
+```
 
-Run terraform by using the following commands
+Run Terraform:
 
-```zsh
+```bash
 terraform init
-terraform apply
+terraform plan -out tfplan
+terraform apply tfplan
+```
+
+After `terraform apply` completes, run:
+
+```bash
+terraform output -raw function_webhook_url
 ```
 
-The terraform output displays the Azure Function endpoint and secret, which you need in the next step.
+This returns **the full Azure Function URL**, including a `?code=` query-string.  Copy the **entire string** – the `code` value is the Function *host key* and must stay in the URL.
+
+You will also need the **GitHub webhook secret** that you stored in Key Vault earlier:
+
+```bash
+az keyvault secret show \
+  --vault-name <your-kv-name> \
+  --name github-webhook-secret \
+  --query value -o tsv
+```
+
+Keep both values handy for the next step.
 
 ### Deploy Function App and App Service
 
 This terraform module is set up by default to use the latest version of both apps and deploy them on `terraform apply`.  Specific versions found in our public [GitHub Packages](https://github.com/orgs/liatrio/packages?repo_name=terraform-azure-github-runner) and set in the terraform module inputs.  If you choose to publish your own images, functionality to do so will be implemented soon™.
 
-### Setup the webhook and install the GitHub App
+### Configure the GitHub App webhook and install the app
+
+In the GitHub UI navigate to **Settings → Developer settings → GitHub Apps → _Your App_** and:
 
-Go back to the GitHub App and update the following settings
+1. **Activate** the webhook toggle.
+2. **Webhook URL** – paste the Function URL you copied from `terraform output` (it already contains the `code` host key).
+3. **Webhook secret** – paste the value of `github-webhook-secret` you retrieved from Key Vault.
+4. **Save**.
+5. Open **Install App**, select the gear icon next to your organization, under 'Repository access' select 'All repositories' and click **Save**.
 
-1. Activate the webhook
-2. Provide the webhook url, which should be part of the terraform output
-3. Provide the webhook secret
-4. Save changes and navigate to the Install App tab
-5. Next to your GitHub App, select Install next to your org and select 'All Repositories'
+The system is now wired together: GitHub sends signed workflow-job events to your Function, the Function enqueues work, and the Runner Controller spins up VMs on demand.
 
 ## Required Inputs