Add user-assigned managed identity support for ACR cache rules

src/acrcache/HISTORY.rst

@@ -2,6 +2,45 @@
 
 Release History
 ===============
+1.0.0c8
+++++++
+* **BUGFIX**: Resolved issue with sync-referrers enabled without sync activesync
+  * Added validation to ensure `--sync-referrers` can only be used with `--sync activesync`
+  * Ensured proper validation and assignment of managed identities in `az acr cache create` and `az acr cache update` commands
+
+
+1.0.0c7
+++++++
+* **FEATURE**: Added `--assign-identity` parameter support for cache rules
+  * `az acr cache create --assign-identity` - Create cache rules with user-assigned managed identities
+  * `az acr cache update --assign-identity` - Update existing cache rules with managed identities
+  * Enables secure authentication for ACR-to-ACR caching across subscriptions within the same tenant
+  * Supports Azure resource ID format validation for managed identity resources
+* **ENHANCEMENT**: Improved error handling and validation for identity parameters
+* **TESTING**: Added comprehensive unit test coverage for identity processing functionality
+
+1.0.0c6
+++++++
+* **BREAKING**: Migrated to Container Registry SDK v2025-09-01-preview
+  * Updated SDK imports from v2025_07_01_preview to v2025_09_01_preview
+  * Updated SDK client factory to support new API version
+* **ENHANCEMENT**: Standardized enum values for sync and referrer status
+  * Sync parameter now uses ActiveSync/PassiveSync values
+  * Referrer status now uses Enabled/Disabled values
+  * Added case-insensitive comparisons and improved None handling
+* **REFACTOR**: Improved validation and state logic
+  * Refactored input validation logic in cache.py for sync/referrer options
+  * Modified CLI argument definitions in _params.py to reflect new enum values
+  * Enhanced error handling and parameter validation
+* **DOCUMENTATION**: Updated help examples for clarity
+  * Rewrote help examples in _help.py for alignment with new conventions
+  * Improved CLI documentation and usage examples
+* **TESTING**: Expanded test coverage
+  * Added comprehensive unit tests for cache operations and validation logic
+  * Updated test coverage to support the new API version
+  * Enhanced reliability testing under new SDK
+* **COMPATIBILITY**: No breaking changes to CLI interface, only behavioral improvements
+
 1.0.0
 ++++++
 * Initial release.

src/acrcache/README.rst

@@ -8,6 +8,8 @@ The `acrcache` extension adds support for managing Azure Container Registry (ACR
 ## Features
 
 - Create, update, list, show, and delete cache rules for ACR.
+- **Managed Identity Authentication**: Configure user-assigned managed identities for secure cross-registry authentication.
+  - **--assign-identity**: Specify a user-assigned managed identity for authenticating with source registries.
 - Configure artifact sync with flexible filters:
   - **--platforms**: Filter which platforms to sync (e.g., `linux/amd64`, `linux/arm64`).
   - **--sync-referrers**: Enable or disable syncing of referrers.
@@ -115,28 +117,51 @@ az acr cache list -r <registry-name>
 
 ### Create a cache rule
 
+#### Basic cache rule (pull-through cache)
 ```sh
-az acr cache create -r <registry-name> -n <rule-name> -s <source-repo> -t <target-repo> \
-  --sync true --platforms linux/amd64,linux/arm64 --sync-referrers enabled \
-  --include-artifact-types images,notary-project-signature --exclude-image-types <image-types>
+az acr cache create -r <registry-name> -n <rule-name> -s <source-repo> -t <target-repo>
+```
+
+#### Cache rule with credential set
 ```sh
-az acr cache list -r <registry-name>
-az acr cache list -r <registry-name>
+az acr cache create -r <registry-name> -n <rule-name> -s <source-repo> -t <target-repo> -c <credential-set>
 ```
 
-### Create a cache rule
+#### Cache rule with user-assigned managed identity (ACR-to-ACR authentication)
+```sh
+az acr cache create -r <registry-name> -n <rule-name> -s <upstream-acr>.azurecr.io/<source-repo> -t <target-repo> \
+  --assign-identity /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>
+```
 
+#### Advanced cache rule with artifact sync and filtering
 ```sh
 az acr cache create -r <registry-name> -n <rule-name> -s <source-repo> -t <target-repo> \
-  --sync true --platforms linux/amd64,linux/arm64 --sync-referrers enabled \
-  --include-artifact-types images,notary-project-signature --exclude-image-types <image-types>
+  --sync activesync --platforms linux/amd64,linux/arm64 --sync-referrers enabled \
+  --include-artifact-types images,notary-project-signature
 ```
 
 ### Update a cache rule
 
+#### Update credential set
 ```sh
-az acr cache update -r <registry-name> -n <rule-name> --platforms linux/amd64 --sync-referrers disabled \
-  --include-artifact-types images --exclude-artifact-types <image-types>
+az acr cache update -r <registry-name> -n <rule-name> -c <new-credential-set>
+```
+
+#### Update with managed identity
+```sh
+az acr cache update -r <registry-name> -n <rule-name> \
+  --assign-identity /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>
+```
+
+#### Update sync settings and filters
+```sh
+az acr cache update -r <registry-name> -n <rule-name> --sync activesync --platforms linux/amd64 \
+  --sync-referrers enabled --include-artifact-types images
+```
+
+#### Remove credential set
+```sh
+az acr cache update -r <registry-name> -n <rule-name> --remove-cred-set
 ```
 
 ### Show a cache rule
@@ -145,12 +170,67 @@ az acr cache update -r <registry-name> -n <rule-name> --platforms linux/amd64 --
 az acr cache show -r <registry-name> -n <rule-name>
 ```
 
+### Sync a specific tag immediately
+
+```sh
+az acr cache sync -r <registry-name> -n <rule-name> --image <tag>
+```
+
 ### Delete a cache rule
 
 ```sh
 az acr cache delete -r <registry-name> -n <rule-name>
 ```
 
+## Authentication Methods
+
+### User-Assigned Managed Identity
+
+The `--assign-identity` parameter enables secure authentication between Azure Container Registries using user-assigned managed identities. This is particularly useful for:
+
+- **Cross-subscription ACR caching**: Cache images from ACRs in different subscriptions within the same tenant
+- **Enhanced security**: Eliminates the need for credential sets in many scenarios
+- **Simplified authentication**: Uses Azure's managed identity infrastructure for secure access
+
+#### Requirements
+- **Same tenant**: Both source and target registries must be in the same Azure AD tenant
+- **Permissions**: The managed identity must have `AcrPull` permissions on the source registry
+- **Identity location**: The managed identity must be in the same subscription as the target registry
+- **Cross-subscription support**: Registries can be in different subscriptions within the same tenant
+
+#### Resource ID Format
+```
+/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identity-name}
+```
+
+#### Example Setup
+1. Create a user-assigned managed identity
+2. Assign `AcrPull` role to the identity on the source registry
+3. Create cache rule with the identity resource ID
+
+```sh
+# Create managed identity
+az identity create -g <resource-group> -n <identity-name>
+
+# Assign AcrPull permissions to source registry
+az role assignment create --assignee <identity-principal-id> --role AcrPull --scope <source-registry-id>
+
+# Create cache rule with managed identity
+az acr cache create -r <target-registry> -n <rule-name> -s <source-registry>.azurecr.io/<repo> -t <target-repo> \
+  --assign-identity /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>
+```
+
+## Artifact Sync and Filtering
+
+### Sync Modes
+- **PassiveSync** (default): Pull-through cache behavior - images are cached when pulled
+- **ActiveSync**: Proactive synchronization - images are automatically pulled and cached
+
+### Important Notes
+- **--sync-referrers enabled** requires **--sync activesync**
+- Artifact filtering parameters (--platforms, --include-artifact-types, etc.) require **--sync activesync**
+- Tag filters (--starts-with, --ends-with, --contains) require **--sync activesync**
+
 ## Minimum Azure CLI Version
 
 This extension requires Azure CLI version **2.57.0** or higher.

src/acrcache/azext_acrcache/_help.py

@@ -23,9 +23,6 @@
 helps['acr cache list'] = """
 type: command
 short-summary: List the cache rules in an Azure Container Registry.
-long-summary: |
-  NOTE: The parameters --platforms, --sync-referrers, --include-artifact-types, and --exclude-artifact-types are not yet implemented. Using any of these parameters will return a 'not implemented' error message.
-
 examples:
   - name: List the cache rules in an Azure Container Registry.
     text: az acr cache list -r myregistry
@@ -34,11 +31,23 @@
 helps['acr cache create'] = """
 type: command
 short-summary: Create a cache rule.
+parameters:
+  - name: --assign-identity
+    short-summary: Resource ID of the user-assigned managed identity.
+    long-summary: |
+      Resource ID of the user-assigned managed identity for authenticating with the ACR source registry. 
+      Must be in the same tenant as both registries. 
+      Format: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}
+  - name: --sync-referrers
+    short-summary: Enable or disable sync referrers.
+    long-summary: Requires --sync activesync to be enabled.
 examples:
   - name: Create a cache rule without a credential set.
     text: az acr cache create -r myregistry -n MyRule -s docker.io/library/ubuntu -t ubuntu
   - name: Create a cache rule with a credential set.
     text: az acr cache create -r myregistry -n MyRule -s docker.io/library/ubuntu -t ubuntu -c MyCredSet
+  - name: Create a cache rule with a user-assigned managed identity (using test registry domain).
+    text: az acr cache create -r myregistry -n MyRule -s upstreamacrregistry.azurecr-test.io -t acr-to-acr-cacherule --assign-identity /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identity-name}
   - name: Create a cache rule with artifact sync enabled and set a tag filter.
     text: az acr cache create -r myregistry -n MyRule -s docker.io/library/ubuntu -t ubuntu --sync activesync --starts-with v1 --ends-with beta
   - name: Create a cache rule with artifact sync enabled, set a tag filter, and specify platforms and sync referrers.
@@ -55,15 +64,24 @@
 
 helps['acr cache update'] = """
 type: command
-short-summary: Update the credential set on a cache rule.
-long-summary: |
-  NOTE: The parameters --platforms, --sync-referrers, --include-artifact-types, and --exclude-artifact-types are not yet implemented. Using any of these parameters will return a 'not implemented' error message.
-
+short-summary: Update a cache rule.
+parameters:
+  - name: --assign-identity
+    short-summary: Resource ID of the user-assigned managed identity.
+    long-summary: |
+      Resource ID of the user-assigned managed identity for authenticating with the ACR source registry. 
+      Must be in the same tenant as both registries. 
+      Format: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}
+  - name: --sync-referrers
+    short-summary: Enable or disable syncing of referrers.
+    long-summary: Requires --sync activesync to be enabled.
 examples:
   - name: Change or add a credential set to an existing cache rule.
     text: az acr cache update -r myregistry -n MyRule -c NewCredSet
   - name: Remove a credential set from an existing cache rule.
     text: az acr cache update -r myregistry -n MyRule --remove-cred-set
+  - name: Update a cache rule with a user-assigned managed identity.
+    text: az acr cache update -r myregistry -n MyRule --assign-identity /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identity-name} 
   - name: Enable artifact sync and set a tag filter.
     text: az acr cache update -r myregistry -n MyRule --sync activesync --starts-with v1 --ends-with beta
   - name: Enable artifact sync, set a tag filter, and specify platforms and sync referrers.

src/acrcache/azext_acrcache/_params.py

@@ -12,6 +12,7 @@ def load_arguments(self, _):
         c.argument('registry_name', options_list=['--registry', '-r'], help='The name of the container registry. It should be specified in lower case. You can configure the default registry name using `az configure --defaults acr=<registry name>`')
         c.argument('name', options_list=['--name', '-n'], help='The name of the cache rule.')
         c.argument('cred_set', options_list=['--cred-set', '-c'], help='The name of the credential set.')
+        c.argument('assign_identity', options_list=['--assign-identity', '-i'], help='Resource ID of the user-assigned managed identity for authenticating with the ACR source registry. Must be in the same tenant as both registries. Format: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}')
         c.argument('source_repo', options_list=['--source-repo', '-s'], help="The full source repository path such as 'docker.io/library/ubuntu'.")
         c.argument('target_repo', options_list=['--target-repo', '-t'], help="The target repository namespace such as 'ubuntu'.")
         c.argument('remove_cred_set', action="store_true", help='Optional boolean indicating whether to remove the credential set from the cache rule. False by default.')