Skip to content

copilot instructions

Jump to bottom
Emmanuel Knafo edited this page Apr 3, 2026 · 2 revisions

title: Wiki Copilot Instructions description: Copilot instructions for maintaining the aks-private-deployment wiki author: devopsabcs-engineering ms.date: 2026-04-03 ms.topic: reference keywords:

  • copilot
  • wiki
  • maintenance
  • conventions

Project Context

This wiki documents the aks-private-deployment proof of concept. The PoC validates that Azure Managed Identity bypasses Entra ID conditional access (CA) location policies when deploying private AKS clusters from a self-hosted GitHub Actions runner inside the target VNet.

The main repository lives at devopsabcs-engineering/aks-private-deployment and contains:

  • A three-job GitHub Actions workflow (deploy-private-aks.yml) that provisions a VNet, runner VM, deploys private AKS, validates with kubectl, and tears down all resources.
  • A safety-net cleanup workflow (cleanup-safety-net.yml).
  • Shell scripts for standalone deployment and runner management.

Key Technical Facts

  • Problem: Service principal az aks create fails when Entra ID CA policies restrict sign-ins to known perimeter IPs — AKS RP authenticates from Azure datacenter IPs, which CA blocks.
  • Solution: Managed identity tokens are acquired via IMDS (169.254.169.254), staying within the Azure fabric. CA does not evaluate managed identity token requests.
  • Architecture: Shared VNet 10.224.0.0/16 with subnet-aks (10.224.0.0/24) and subnet-runner (10.224.1.0/24). Runner VM reaches the private AKS API server via private endpoint because both subnets share the VNet.
  • Authentication flow: az login --identity → IMDS → Azure fabric token (no CA). Contrasts with service principal flow that routes through login.microsoftonline.com (CA evaluated).
  • Region: canadacentral (default).

Wiki Structure

The wiki is organized into these sections on the Home page:

Section Purpose
Overview Problem statement, solution summary, three-job workflow description
Proof: Self-Hosted Runner Execution Screenshots proving the workflow runs on the in-VNet self-hosted runner
Architecture and Network Layout VNet/subnet topology, resource group structure
Private Cluster Details AKS private endpoint configuration, kubectl validation
Troubleshooting Common issues table, diagnostic screenshots
Key References Links to Microsoft docs and main repo README

When adding new pages, use the sidebar to group them under the appropriate section. Keep the Home page as the primary entry point with a table of contents.

Screenshot Conventions

Every screenshot in the wiki must have:

  1. A descriptive paragraph above the image explaining what the screenshot shows, why it matters, and which PoC component it demonstrates.
  2. A meaningful alt attribute on the <img> tag that describes the visible content (not generic "image"). The alt text should mention:
    • The Azure service or GitHub Actions component shown
    • Key data visible (IPs, resource names, status)
    • Which part of the PoC flow it represents
  3. Section placement — screenshots must appear under the correct wiki section, not dumped at the top of the page.

Alt Text Examples

GOOD: "GitHub Actions deploy-and-log job running on self-hosted runner VM inside the Azure VNet, authenticated via managed identity"
GOOD: "Private AKS cluster configuration details showing enablePrivateCluster true, private FQDN resolving to 10.224.0.4"
BAD:  "image"
BAD:  "screenshot"
BAD:  "Screen Shot 2026-04-02"

Adding New Screenshots

When adding new screenshots to the wiki:

  1. Upload the image to GitHub (paste into wiki editor or use user-attachments).
  2. Write a descriptive paragraph above the <img> tag explaining context.
  3. Set the alt attribute to describe the screenshot content.
  4. Do not include width or height attributes on <img> tags — these cause images to stretch beyond the wiki viewport. Let the browser scale images naturally.
  5. Place the screenshot under the correct section heading.
  6. If the screenshot shows terminal output, transcribe key values (IPs, status codes, error messages) into the surrounding text so the information is searchable and accessible.

Image Inventory

Current screenshots and their context (as of April 2, 2026 verified run #23919580744):

Image ID Section Description
19deebd0 Proof: Self-Hosted Runner GitHub Actions deploy-and-log job executing on the self-hosted runner in subnet-runner
de4edeb0 Proof: Self-Hosted Runner Runner registration and workflow execution confirmation from the runner VM
66507832 Architecture High-level view of provisioned PoC Azure resources across infra and AKS resource groups
31eee8e4 Private Cluster Details AKS cluster properties — enablePrivateCluster: true, private FQDN, Azure CNI config
f37199be Private Cluster Details Kubectl validation — get nodes, cluster-info, nslookup of private FQDN
6d650177 Troubleshooting Diagnostic view — CA evaluation details, Activity Log IPs, or deployment error

Markdown Conventions

  • Use ATX-style headings (#, ##, ###).
  • Surround headings, code blocks, and lists with blank lines.
  • Use * for unordered lists (not - or +).
  • Specify a language identifier on all fenced code blocks (use text for plain output).
  • Do not end fragment bullet points with periods; end full-sentence bullets with periods.
  • Keep the table of contents in the Home page updated when adding or renaming sections.

Editing Guidelines

  • Do not remove screenshots without replacing them with updated ones from a new verified run.
  • When a new PoC run completes, update the verified run reference and replace screenshots if the workflow output changed.
  • Keep the troubleshooting table updated as new issues are discovered and resolved.
  • Cross-reference the main repository README for detailed workflow documentation, authentication flow diagrams, and verified run findings.
  • When describing IP addresses in text, always state which component they belong to (runner VM public IP, AKS API server private IP, AKS RP internal IP).

Clone this wiki locally