feat: avm/ptn/deployment-script/import-image-to-acr adds ability to…

… rename the imported image (#2738)

## Description

Allow changing the image name during import.

Being able to rename the image during the import allows you to import
e.g. mcr.microsoft.com/k8se/quickstart-jobs:latest and store it in the
ACR as <acr>/your-image-name:tag. With this, you can import a
placeholder image, set other services to use it and later update it from
a pipeline.

Closes #2737

## Pipeline Reference

<!-- Insert your Pipeline Status Badge below -->

| Pipeline |
| -------- |
|
[![avm.ptn.deployment-script.import-image-to-acr](https://github.com/ReneHezser/bicep-registry-modules/actions/workflows/avm.ptn.deployment-script.import-image-to-acr.yml/badge.svg)](https://github.com/ReneHezser/bicep-registry-modules/actions/workflows/avm.ptn.deployment-script.import-image-to-acr.yml)
|

## Type of Change

<!-- Use the checkboxes [x] on the options that are relevant. -->

- [ ] Update to CI Environment or utilities (Non-module affecting
changes)
- [x] Azure Verified Module updates:
- [ ] Bugfix containing backwards-compatible bug fixes, and I have NOT
bumped the MAJOR or MINOR version in `version.json`:
- [ ] Someone has opened a bug report issue, and I have included "Closes
#{bug_report_issue_number}" in the PR description.
- [ ] The bug was found by the module author, and no one has opened an
issue to report it yet.
- [x] Feature update backwards compatible feature updates, and I have
bumped the MINOR version in `version.json`.
- [ ] Breaking changes and I have bumped the MAJOR version in
`version.json`.
  - [ ] Update to documentation

## Checklist

- [x] I'm sure there are no other open Pull Requests for the same
update/change
- [x] I have run `Set-AVMModule` locally to generate the supporting
module files.
- [x] My corresponding pipelines / checks run clean and green without
any errors or warnings

---------

Co-authored-by: Alexander Sehr <[email protected]>

avm/ptn/deployment-script/import-image-to-acr/README.md

@@ -115,6 +115,7 @@ module importImageToAcr 'br/public:avm/ptn/deployment-script/import-image-to-acr
     cleanupPreference: 'OnExpiration'
     location: '<location>'
     managedIdentities: '<managedIdentities>'
+    newImageName: 'your-image-name:tag'
     overwriteExistingImage: true
     storageAccountResourceId: '<storageAccountResourceId>'
     subnetResourceIds: '<subnetResourceIds>'
@@ -161,6 +162,9 @@ module importImageToAcr 'br/public:avm/ptn/deployment-script/import-image-to-acr
     "managedIdentities": {
       "value": "<managedIdentities>"
     },
+    "newImageName": {
+      "value": "your-image-name:tag"
+    },
     "overwriteExistingImage": {
       "value": true
     },
@@ -274,6 +278,7 @@ module importImageToAcr 'br/public:avm/ptn/deployment-script/import-image-to-acr
 | [`enableTelemetry`](#parameter-enabletelemetry) | bool | Enable/Disable usage telemetry for module. |
 | [`initialScriptDelay`](#parameter-initialscriptdelay) | int | A delay in seconds before the script import operation starts. Primarily to allow Azure AAD Role Assignments to propagate. Default is 30s. |
 | [`location`](#parameter-location) | string | Location for all Resources. |
+| [`newImageName`](#parameter-newimagename) | string | The new image name in the ACR. You can use this to import a publically available image with a custom name for later updating from e.g., your build pipeline. |
 | [`overwriteExistingImage`](#parameter-overwriteexistingimage) | bool | The image will be overwritten if it already exists in the ACR with the same tag. Default is false. |
 | [`retryMax`](#parameter-retrymax) | int | The maximum number of retries for the script import operation. Default is 3. |
 | [`runOnce`](#parameter-runonce) | bool | How the deployment script should be forced to execute. Default is to force the script to deploy the image to run every time. |
@@ -378,6 +383,15 @@ Location for all Resources.
 - Type: string
 - Default: `[resourceGroup().location]`
 
+### Parameter: `newImageName`
+
+The new image name in the ACR. You can use this to import a publically available image with a custom name for later updating from e.g., your build pipeline.
+
+- Required: No
+- Type: string
+- Default: `[last(split(parameters('image'), '/'))]`
+- Example: `your-image-name:tag`
+
 ### Parameter: `overwriteExistingImage`
 
 The image will be overwritten if it already exists in the ACR with the same tag. Default is false.
@@ -450,17 +464,25 @@ This section gives you an overview of all local-referenced module files (i.e., o
 
 ## Notes
 
-The deployment script service will need and provision a Storage Account as well as a Container Instance to execute the provided script. *The deployment script resource is available only in the regions where Azure Container Instances is available.*
+The deployment script service will need and provision a Storage Account as well as a Container Instance to execute the provided script. _The deployment script resource is available only in the regions where Azure Container Instances is available._
 
 > The service cleans up these resources after the deployment script finishes. You incur charges for these resources until they're removed.
 
+### Private network access
+
 Using a Container Registry that is not available via public network access is possible as well. In this case a subnet needs to be passed to the module. A working configuration is in the max examples for this module.
 
 Links:
 
 - [Access a private virtual network from a Bicep deployment script](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/deployment-script-vnet)
 - [Run Bicep deployment script privately over a private endpoint](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/deployment-script-vnet-private-endpoint)
 
+### Renaming the image
+
+In the case an image is updated later from a pipeline, it can makes sense to initially upload a dummy image from e.g. a public registry. However, you might want to change the name and tag from that image for processes to pick up the image before **your image** has actually be published to the registry.
+
+The pattern module [avm/ptn/app/container-job](https://github.com/Azure/bicep-registry-modules/tree/main/avm/ptn/authorization/policy-assignment) uses this module to create the job initially with an image that is available, which most likely will be updated later and the job will pick up the new image then.
+
 ## Data Collection
 
 The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the [repository](https://aka.ms/avm/telemetry). There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at <https://go.microsoft.com/fwlink/?LinkID=824704>. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

avm/ptn/deployment-script/import-image-to-acr/main.bicep

@@ -32,6 +32,12 @@ param managedIdentityName string?
 })
 param image string
 
+@description('Optional. The new image name in the ACR. You can use this to import a publically available image with a custom name for later updating from e.g., your build pipeline.')
+@metadata({
+  example: 'your-image-name:tag'
+})
+param newImageName string = last(split(image, '/'))
+
 @description('Optional. The image will be overwritten if it already exists in the ACR with the same tag. Default is false.')
 param overwriteExistingImage bool = false
 
@@ -166,6 +172,10 @@ module imageImport 'br/public:avm/res/resources/deployment-script:0.2.3' = {
           name: 'imageName'
           value: image
         }
+        {
+          name: 'newImageName'
+          value: newImageName
+        }
         {
           name: 'overwriteExistingImage'
           value: toLower(string(overwriteExistingImage))
@@ -200,9 +210,9 @@ module imageImport 'br/public:avm/res/resources/deployment-script:0.2.3' = {
     do
       echo "Importing Image ($retryLoopCount): $imageName into ACR: $acrName\n"
       if [ $overwriteExistingImage = 'true' ]; then
-        az acr import -n $acrName --source $imageName --force
+        az acr import -n $acrName --source $imageName --image $newImageName --force
       else
-        az acr import -n $acrName --source $imageName
+        az acr import -n $acrName --source $imageName --image $newImageName
       fi
 
       sleep $retrySleep

avm/ptn/deployment-script/import-image-to-acr/main.json

@@ -6,7 +6,7 @@
     "_generator": {
       "name": "bicep",
       "version": "0.28.1.47646",
-      "templateHash": "723991129039360172"
+      "templateHash": "18410876545978102921"
     },
     "name": "import-image-to-acr",
     "description": "This modules deployes an image to an Azure Container Registry.",
@@ -107,6 +107,14 @@
         "description": "Required. A fully qualified image name to import."
       }
     },
+    "newImageName": {
+      "type": "string",
+      "defaultValue": "[last(split(parameters('image'), '/'))]",
+      "metadata": {
+        "example": "your-image-name:tag",
+        "description": "Optional. The new image name in the ACR. You can use this to import a publically available image with a custom name for later updating from e.g., your build pipeline."
+      }
+    },
     "overwriteExistingImage": {
       "type": "bool",
       "defaultValue": false,
@@ -300,6 +308,10 @@
                   "name": "imageName",
                   "value": "[parameters('image')]"
                 },
+                {
+                  "name": "newImageName",
+                  "value": "[parameters('newImageName')]"
+                },
                 {
                   "name": "overwriteExistingImage",
                   "value": "[toLower(string(parameters('overwriteExistingImage')))]"
@@ -332,7 +344,7 @@
             "value": "[parameters('subnetResourceIds')]"
           },
           "scriptContent": {
-            "value": "#!/bin/bash\n    set -e\n\n    echo \"Waiting on RBAC replication ($initialDelay)\\n\"\n    sleep $initialDelay\n\n    # retry loop to catch errors (usually RBAC delays, but 'Error copying blobs' is also not unheard of)\n    retryLoopCount=0\n    until [ $retryLoopCount -ge $retryMax ]\n    do\n      echo \"Importing Image ($retryLoopCount): $imageName into ACR: $acrName\\n\"\n      if [ $overwriteExistingImage = 'true' ]; then\n        az acr import -n $acrName --source $imageName --force\n      else\n        az acr import -n $acrName --source $imageName\n      fi\n\n      sleep $retrySleep\n      retryLoopCount=$((retryLoopCount+1))\n    done\n\n    echo \"done\\n\""
+            "value": "#!/bin/bash\n    set -e\n\n    echo \"Waiting on RBAC replication ($initialDelay)\\n\"\n    sleep $initialDelay\n\n    # retry loop to catch errors (usually RBAC delays, but 'Error copying blobs' is also not unheard of)\n    retryLoopCount=0\n    until [ $retryLoopCount -ge $retryMax ]\n    do\n      echo \"Importing Image ($retryLoopCount): $imageName into ACR: $acrName\\n\"\n      if [ $overwriteExistingImage = 'true' ]; then\n        az acr import -n $acrName --source $imageName --image $newImageName --force\n      else\n        az acr import -n $acrName --source $imageName --image $newImageName\n      fi\n\n      sleep $retrySleep\n      retryLoopCount=$((retryLoopCount+1))\n    done\n\n    echo \"done\\n\""
           }
         },
         "template": {

avm/ptn/deployment-script/import-image-to-acr/tests/e2e/max/main.test.bicep

@@ -60,6 +60,7 @@ module testDeployment '../../../main.bicep' = [
       acrName: dependencies.outputs.acrName
       location: resourceLocation
       image: 'mcr.microsoft.com/k8se/quickstart-jobs:latest'
+      newImageName: 'your-image-name:tag'
       cleanupPreference: 'OnExpiration'
       assignRbacRole: true
       managedIdentities: { userAssignedResourcesIds: [dependencies.outputs.managedIdentityResourceId] }

avm/ptn/deployment-script/import-image-to-acr/version.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://aka.ms/bicep-registry-module-version-file-schema#",
-  "version": "0.1",
+  "version": "0.2",
   "pathFilters": [
     "./main.json"
   ]