diff --git a/src/acrcache/HISTORY.rst b/src/acrcache/HISTORY.rst index 1cc6fb8020f..21b59a476df 100644 --- a/src/acrcache/HISTORY.rst +++ b/src/acrcache/HISTORY.rst @@ -4,9 +4,10 @@ Release History =============== 1.0.0c8 ++++++ -* **BUGFIX**: Resolved issue with sync-referrers enabled without sync activesync +* **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 + * Improved README documentation for clarity on parameter dependencies and usage examples 1.0.0c7 diff --git a/src/acrcache/README.rst b/src/acrcache/README.rst index 841abc61a37..ddc487e1e11 100644 --- a/src/acrcache/README.rst +++ b/src/acrcache/README.rst @@ -40,35 +40,36 @@ Installation 3. After forking `azure-cli`, follow the below commands to setup - # Clone your forked repository + Clone your forked repository - - git clone `https://github.com//azure-cli.git` + - git clone `https://github.com//azure-cli.git` - - cd azure-cli + - cd azure-cli - # Add the Azure/azure-cli repository as upstream + Add the Azure/azure-cli repository as upstream - - git remote add upstream https://github.com/Azure/azure-cli.git + - git remote add upstream https://github.com/Azure/azure-cli.git - - git fetch upstream + - git fetch upstream - # Reset the default dev branch to track dev branch of Azure/azure-cli so you can use it to track the latest azure-cli code. + Reset the default dev branch to track dev branch of Azure/azure-cli so you can use it to track the latest azure-cli code. - - git branch dev --set-upstream-to upstream/dev + - git branch dev --set-upstream-to upstream/dev - # Develop with a new branch + Develop with a new branch - - git checkout -b + - git checkout -b - Do the same for `azure-cli-extensions` except that the default branch for it is main, run git branch main --set-upstream-to upstream/main instead. - Note: The ACR cache extension is in the `feature/artifactcache` branch of the `azure-cli-extensions` repository, do NOT merge changes into main. + Do the same for `azure-cli-extensions` except that the default branch for it is main, run git branch main --set-upstream-to upstream/main instead. + Note: The ACR cache extension is in the `feature/artifactcache` branch of the `azure-cli-extensions` repository, do NOT merge changes into main. 4. Create a virtual environment in the directory that contains both your CLI and CLI extension clones ```sh python -m venv .venv ``` + 5. Activate the virtual environment Windows CMD.exe: @@ -83,30 +84,29 @@ Installation `source .venv/bin/activate` -5. Install the required packages - - Install python dependencies +6. Install the required packages + Install python dependencies + - python -m pip install -U pip + + Due to a known issue, the Azure CLI currently requires an older version of setuptools (70.0.0) and wheel (0.30.0) because newer versions are incompatible and may cause installation or build failures. + For more details, see the related issue: https://github.com/Azure/azure-cli/issues/29467 - - python -m pip install -U pip - - Due to a known issue, the Azure CLI currently requires an older version of setuptools (70.0.0) and wheel (0.30.0) because newer versions are incompatible and may cause installation or build failures. - For more details, see the related issue: https://github.com/Azure/azure-cli/issues/29467 - - - pip install setuptools==70.0.0 + - pip install setuptools==70.0.0 - - pip install --force-reinstall wheel==0.30.0 + - pip install --force-reinstall wheel==0.30.0 - - Install azdev + - Install azdev + + - pip install -U azdev - - pip install -U azdev - - - Setup azdev - - azdev setup -c -r azure-cli-extensions/ + Setup azdev + - azdev setup -c -r azure-cli-extensions/ - 6. Build extension +7. Build extension - azdev extension build acrcache + azdev extension build acrcache -Developing with the ACR Cache Extension +**Developing with the ACR Cache Extension** ========================================== Please write the description of changes which can be perceived by customers into HISTORY.rst. @@ -115,139 +115,70 @@ If you want to release a new extension version, please update the version in set If you make changes to the extension, you can test it by running: -azdev extension build "acrcache" - -this will build your new changes into the extension package which you will see immediately. - -## Usage - -### List cache rules - -```sh -az acr cache list -r -``` - -### Create a cache rule - -#### Basic cache rule (pull-through cache) -```sh -az acr cache create -r -n -s -t -``` - -#### Cache rule with credential set -```sh -az acr cache create -r -n -s -t -c -``` - -#### Cache rule with user-assigned managed identity (ACR-to-ACR authentication) -```sh -az acr cache create -r -n -s .azurecr.io/ -t \ - --assign-identity /subscriptions//resourceGroups//providers/Microsoft.ManagedIdentity/userAssignedIdentities/ -``` - -#### Advanced cache rule with artifact sync and filtering -```sh -az acr cache create -r -n -s -t \ - --sync activesync --platforms linux/amd64,linux/arm64 --sync-referrers enabled \ - --include-artifact-types images,notary-project-signature -``` + - azdev extension build "acrcache" -### Update a cache rule + **this will build your new changes into the extension package which you will see immediately.** -#### Update credential set -```sh -az acr cache update -r -n -c -``` +After building the extension, if you dont see your changes immediately outputed in the cli, you can run the following command to reinstall the newly built extension: -#### Update with managed identity -```sh -az acr cache update -r -n \ - --assign-identity /subscriptions//resourceGroups//providers/Microsoft.ManagedIdentity/userAssignedIdentities/ -``` + - az extension remove --name acrcache + - az extension add --source "path\dist\acrcache-1.0.<0rc8>-py3-none-any.whl" -#### Update sync settings and filters -```sh -az acr cache update -r -n --sync activesync --platforms linux/amd64 \ - --sync-referrers enabled --include-artifact-types images -``` -#### Remove credential set -```sh -az acr cache update -r -n --remove-cred-set -``` - -### Show a cache rule - -```sh -az acr cache show -r -n -``` - -### Sync a specific tag immediately - -```sh -az acr cache sync -r -n --image -``` - -### Delete a cache rule - -```sh -az acr cache delete -r -n -``` - -## Authentication Methods +**Usage** +============== -### User-Assigned Managed Identity +**cache rules Create, update, list, show, and sync ** -The `--assign-identity` parameter enables secure authentication between Azure Container Registries using user-assigned managed identities. This is particularly useful for: + see `az acr cache -h` for more information and examples. -- **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 +**Authentication Methods** -#### 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 + ** User-Assigned Managed Identity** -#### Resource ID Format -``` -/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identity-name} -``` + The `--assign-identity` parameter enables secure authentication between Azure Container Registries using user-assigned managed identities. This is particularly useful for: -#### 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 + - **Cross-subscription ACR caching**: Cache images from ACR to ACR 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 -```sh -# Create managed identity -az identity create -g -n + Create cache rule with managed identity + ``` + az acr cache create -r -n -s .azurecr.io/ -t \ + --assign-identity /subscriptions//resourceGroups//providers/Microsoft.ManagedIdentity/userAssignedIdentities/ + ``` -# Assign AcrPull permissions to source registry -az role assignment create --assignee --role AcrPull --scope + ** Credentials** -# Create cache rule with managed identity -az acr cache create -r -n -s .azurecr.io/ -t \ - --assign-identity /subscriptions//resourceGroups//providers/Microsoft.ManagedIdentity/userAssignedIdentities/ -``` + If `--assign-identity` is not specified in a cache rule command, the extension will fall back to using existing credentials configured for the target registry. This may include: -## Artifact Sync and Filtering + - Admin user credentials + - Service principal credentials + + Create cache rule with credentials + ``` + az acr cache create -r -n -s .azurecr.io/ -t --credential-set + ``` -### Sync Modes -- **PassiveSync** (default): Pull-through cache behavior - images are cached when pulled -- **ActiveSync**: Proactive synchronization - images are automatically pulled and cached +** Important Notes** +============== -### 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** + ** Sync Modes ** + - **PassiveSync** (default): Pull-through cache behavior - images are cached when pulled + - **ActiveSync**: Proactive synchronization - images are automatically pulled and cached + + ** Parameter Dependencies ** + - --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 +** Minimum Azure CLI Version ** +============== -This extension requires Azure CLI version **2.57.0** or higher. + This extension requires Azure CLI version **2.57.0** or higher. + You can check your Azure CLI version with: -## Documentation + az version For more details, see the official [Azure CLI documentation](https://learn.microsoft.com/cli/azure/acr). diff --git a/src/acrcache/azext_acrcache/_client_factory.py b/src/acrcache/azext_acrcache/_client_factory.py index af6722568cb..0bbd8921be9 100644 --- a/src/acrcache/azext_acrcache/_client_factory.py +++ b/src/acrcache/azext_acrcache/_client_factory.py @@ -14,4 +14,4 @@ def cf_acrreg(cli_ctx, *_): from azure.cli.core.commands.client_factory import get_mgmt_service_client, get_subscription_id from azext_acrcache.vendored_sdks.containerregistry.v2025_09_01_preview.generated.container_registry_management_client import ContainerRegistryManagementClient subscription_id = get_subscription_id(cli_ctx) - return get_mgmt_service_client(cli_ctx, ContainerRegistryManagementClient, subscription_id=subscription_id).registries + return get_mgmt_service_client(cli_ctx, ContainerRegistryManagementClient, subscription_id=subscription_id) diff --git a/src/acrcache/azext_acrcache/cache.py b/src/acrcache/azext_acrcache/cache.py index ad2c58a2482..ce13bfacc27 100644 --- a/src/acrcache/azext_acrcache/cache.py +++ b/src/acrcache/azext_acrcache/cache.py @@ -464,12 +464,13 @@ def acr_cache_sync(cmd, rg = get_resource_group_name_by_registry_name(cmd.cli_ctx, registry_name, resource_group_name) rule = client.cache_rules.get(resource_group_name=rg, - registry_name=registry_name, - cache_rule_name=name) + registry_name=registry_name, + cache_rule_name=name) + tag = image rule_id = rule.id - source_repo = rule.source_repository - target_repo = rule.target_repository + source_repo = rule.properties.source_repository + target_repo = rule.properties.target_repository source_image_str = source_repo[source_repo.find('/') + 1:] + ":" + tag import_source = ImportSource(source_image=source_image_str, @@ -481,6 +482,6 @@ def acr_cache_sync(cmd, target_tags=[target_repo + ":" + tag]) return client.registries.begin_import_image(resource_group_name=rg, - registry_name=registry_name, - parameters=params) + registry_name=registry_name, + parameters=params)