Add ARO SP to MI migration guide (Part 1 & Part 2)#935
Conversation
Part 1: SP vs MI explained — what is different, why MI, migration guidelines Part 2: Hands-on migration demo with two Python apps (keyvault-reader, blob-writer) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Rename to 'ARO Service Principal to Managed Identity: What Changes in Authentication and How to Move' - Restructure TL;DR: what changed/stays and how to move - Introduce SP/MI abbreviations on first use - Standardize pronouns to 'we' - Fix SP diagram: ARO platform injects credentials, correct expiry default 1yr/max 2yr - Fix MI diagram: replace Workload Identity Webhook with CCO for cluster operators - Remove dismissive language about Microsoft docs
The workload identity webhook also injects AZURE_AUTHORITY_HOST per official docs.
…upport status Portal automates MI setup today; az aro CLI support coming soon.
…sion table - Add missing migration scenario: apps using connection strings deploy as-is - Add .spec.serviceAccountName to required manifest changes - Add Azure SDK minimum version table for workload identity support - Remove speculative az aro assign-roles command name
…teps; reframe PVC as local cache
…escribe actual demos)
✅ Deploy Preview for rh-cloud-experts ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
paulczar
left a comment
paulczar
left a comment
There was a problem hiding this comment.
This is well-researched content and the technical accuracy looks good. Three things need addressing before merge:
1. Demo app code should live in a separate repo
The demo-apps/ directory (Python apps, Dockerfiles, K8s manifests) doesn't belong in a docs repo — this code has its own lifecycle (dependency updates, SDK version bumps, bug fixes) that is separate from the article. The standard pattern is a dedicated repo (e.g. rh-mobb/aro-sp-mi-demo) that readers git clone at the start of Part 2. The article keeps the relevant snippets inline — just not the full source files.
2. Part 2 is a 404
Because index.md exists in aro-sp-mi/, Hugo treats this as a leaf bundle. migration-demo.md becomes a page resource with no URL — both /experts/aro/aro-sp-mi/migration-demo/ and every link to Part 2 in the article return 404. Fix: restructure as a branch bundle (matching how content/aro/setup-quay/ works):
- rename
index.md→_index.md - move
migration-demo.md→migration-demo/index.md
3. Mermaid diagrams render as raw code
The fenced ```mermaid ``` syntax is not processed by the rhds theme — the three sequence diagrams display as line-numbered code blocks showing raw mermaid syntax. Please replace with static images (PNG or SVG exported from https://mermaid.live).
4. Em dashes
Site style prohibits em dashes. There are 33 instances across both files. Please replace with commas, semicolons, or rewrite the sentence (e.g. "operators authenticate to Azure APIs" not "operators — how they authenticate to Azure APIs").
|
|
||
| A single service principal is shared by all eight cluster operators. The SP has broad Contributor access to the VNet and the entire managed resource group. The ARO platform injects the SP credentials into the cluster — operators read the same client ID and client secret at runtime. | ||
|
|
||
| ```mermaid |
There was a problem hiding this comment.
The rhds theme does not render fenced mermaid blocks — this displays as a raw code block showing the mermaid syntax. Please replace with a static image (PNG or SVG exported from https://mermaid.live).
|
|
||
| Each of the eight cluster operators gets its own user-assigned managed identity with only the Azure permissions it needs. A ninth identity (the cluster identity) manages federated credentials for the other eight. No secrets are stored in the cluster. | ||
|
|
||
| ```mermaid |
There was a problem hiding this comment.
Same issue as above — this mermaid block renders as raw code. Replace with a static image.
|
|
||
| **On an MI cluster**, the OIDC issuer is enabled. Your applications can use workload identity to authenticate without any secrets: | ||
|
|
||
| ```mermaid |
There was a problem hiding this comment.
Same issue — replace with a static image exported from https://mermaid.live.
2 participants
Summary
Two-part guide for ARO Service Principal to Managed Identity migration:
index.md) — What changes in authentication (cluster operators + application workloads), why MI matters, and migration methodologymigration-demo.md) — Hands-on walkthrough with two demo apps: keyvault-reader (requires code change fromClientSecretCredentialtoDefaultAzureCredential) and blob-writer (requires only K8s manifest changes)Both demo apps have been deployed and validated on an MI cluster with workload identity.
Files
Test plan