Add missing identity and RBAC prerequisites for PIS with private ACR - #466
Conversation
…luding role assignments for private ACR access Signed-off-by: PixelRobots <littlehoops@gmail.com>
|
Richard Hooper (@PixelRobots) : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. |
|
Richard Hooper (@PixelRobots) : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. |
|
Learn Build status updates of commit 131d6e7: ✅ Validation status: passed
For more details, please refer to the build report. |
|
Learn Build status updates of commit 9078ae0: ✅ Validation status: passed
For more details, please refer to the build report. |
|
Can you review the proposed changes? IMPORTANT: When the changes are ready for publication, adding a #label:"aq-pr-triaged" |
There was a problem hiding this comment.
Pull request overview
This PR updates the AKS Prepared Image Specification (PIS) preview documentation to include missing identity and RBAC prerequisites that otherwise cause confusing failures when creating node pools from a PIS, especially when caching images from a private ACR.
Changes:
- Added prerequisites and a new step to grant the AKS control plane managed identity Reader access to the resource group that contains the PIS.
- Documented private ACR requirements for PIS image caching using
--assign-identity, including an example using the kubelet identity and troubleshooting guidance. - Added a new CLI reference link for
az role assignment create.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| CLUSTER_IDENTITY=$(az aks show \ | ||
| --resource-group $RESOURCE_GROUP \ | ||
| --name $CLUSTER_NAME \ | ||
| --query identity.principalId -o tsv) |
| --cluster-name $CLUSTER_NAME \ | ||
| --name userpool \ | ||
| --query "{state:provisioningState, pisId:preparedImageSpecificationId}" | ||
| --query "{state:provisioningState, pisId:preparedImageSpecificationProfile.preparedImageSpecificationId}" |
| ``` | ||
|
|
||
| > [!NOTE] | ||
| > Allow 30-60 seconds for the role assignment to propagate before proceeding to the next step. |
|
This pull request has been inactive for at least 14 days. If you are finished with your changes, don't forget to sign off. See the contributor guide for instructions. |
Problem
The current documentation for creating a node pool with a Prepared Image Specification (PIS) is missing several prerequisites that cause cryptic failures in practice. Testing against the preview revealed three undocumented requirements:
Control plane Reader role - The AKS cluster's control plane managed identity requires the
Readerrole on the resource group containing the PIS resource. Without this,nodepool addfails withResourceMissingPermissionError: Check access result not allowed for action Microsoft.ContainerService/preparedImageSpecifications/read.Private ACR requires
--assign-identity- When images are in a private ACR, the PIS must be created with--assign-identitypointing to a managed identity withAcrPull. Without it, the build VM has no managed identity and cannot authenticate to pull images. This causesFailedToCreateNodeCustomizationVHDwith registry authentication failures.--assign-identityrequires user-assigned cluster identity - Using--assign-identityon the PIS requires the AKS cluster to have been created with a user-assigned managed identity (not the default system-assigned). If the cluster uses system-assigned identity,nodepool addfails with: "The prepared image specification references a managed identity. As a result, this cluster must have a user-assigned managed identity."Changes
--assign-identity/user-assigned identity requirement--assign-identityexample using the kubelet identity, with a NOTE explaining when it's optional (public/anon-pull registries)nodepool addaz-role-assignment-createreferenceVerification
All three issues were reproduced and confirmed against the live preview feature (
AKSPreparedImageSpecificationPreviewfeature flag,aks-preview21.0.0b5+, UK South region).