Action Required: Namespace migration from Microsoft.Web to Microsoft.App in March 2022

[anthonychu]

---

March 29, 2022 update:

• Add Microsoft.App CLI installation instructions
• Azure portal now creates Microsoft.App resources by default

---

During the month of March 2022, all Azure Container Apps resources will be gradually migrated from the Microsoft.Web namespace to the Microsoft.App namespace.

The availability of your Azure Container Apps resources will not be impacted.

The migration affects how you issue management operations to Container Apps resources — the namespace you use must match the resources you’re updating. If you're using the Azure CLI, you must use a version of the Container Apps extension that is compatible with the resources you’re interacting with.

Migration of existing Container Apps resources

Sometime during the migration period, your Container Apps resources that are in the Microsoft.Web namespace will be migrated to the Microsoft.App namespace. There may be a very short timeframe where Container Apps management requests are unavailable during the migration.

Following the migration, you’ll need to register your subscription with the Microsoft.App namespace before running management operations on your Container Apps resources.

az provider register -n Microsoft.App

Azure portal

The Azure portal supports managing Microsoft.Web and Microsoft.App resources.

(Update on March 29, 2022) - The Azure portal now creates Microsoft.App resources by default.

ARM and Bicep

If you manage your Container Apps resources using ARM or Bicep templates or by calling ARM APIs, the namespace that you use must match the resources you’re interacting with. After the migration, you need to update your API calls and templates.

The changes for the Microsoft.App namespace are:

1. Update the API version to 2022-01-01-preview
2. Update the Microsoft.Web/containerApps resource type to Microsoft.App/containerApps
3. Update the Microsoft.Web/kubeEnvironments resource type to Microsoft.App/managedEnvironments
4. Update the kubeEnvironmentId property to managedEnvironmentId

ARM template example:

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "containerappName": {
      "defaultValue": "mycontainerapp",
      "type": "String"
    },
    "location": {
      "defaultValue": "canadacentral",
      "type": "String"
    },
    "environment_name": {
      "defaultValue": "myenvironment",
      "type": "String"
    }
  },
  "variables": {},
  "resources": [
    {
-      "apiVersion": "2021-03-01",
+      "apiVersion": "2022-01-01-preview",
-      "type": "Microsoft.Web/containerApps",
+      "type": "Microsoft.App/containerApps",
      "name": "[parameters('containerappName')]",
      "location": "[parameters('location')]",
      "properties": {
-        "kubeEnvironmentId": "[resourceId('Microsoft.Web/kubeEnvironments', parameters('environment_name'))]",
+        "managedEnvironmentId": "[resourceId('Microsoft.App/managedEnvironments', parameters('environment_name'))]",
        "configuration": {
          "secrets": [
            {
              "name": "mysecret",
              "value": "thisismysecret"
            }
          ],
          "ingress": {
            "external": true,
            "targetPort": 80,
            "allowInsecure": false,
            "traffic": [
              {
                "latestRevision": true,
                "weight": 100
              }
            ]
          }
        },
        "template": {
          "revisionSuffix": "myrevision",
          "containers": [
            {
              "name": "nginx",
              "image": "nginx",
              "env": [
                {
                  "name": "HTTP_PORT",
                  "value": "80"
                },
                {
                  "name": "SECRET_VAL",
                  "secretRef": "mysecret"
                }
              ],
              "resources": {
                "cpu": 0.5,
                "memory": "1Gi"
              }
            }
          ],
          "scale": {
            "minReplicas": 1,
            "maxReplicas": 3
          }
        }
      }
    }
  ]
}

For complete API specs for Microsoft.App, see this GitHub repo.

Azure CLI

The Azure Container Apps commands in the Azure CLI are currently enabled by a CLI extension. You must use an extension version that is compatible with the namespace of the Container Apps resources you want to interact with.

(Update on March 29, 2022) - To manage resources in the Microsoft.App namespace, install the latest Azure Container Apps CLI extension. Note that the installation instructions have changed. You will not be able to use older version of the CLI extension to manage your resources after the migration.

# uninstall previous versions
az extension remove --name containerapp

# install the latest
az extension add --name containerapp

See #152 for details on this CLI extension release.

Pulumi

If you're using Pulumi, see their migration guide for more details: pulumi/pulumi#9099

Creating new Container Apps resources

Until your Azure subscription has migrated to use the Microsoft.App namespace, you may continue to create Container App Environments in the Microsoft.Web namespace.

When creating new Container Apps, you must use the same namespace as the Container App Environment it’s being created in.

In early March 2022, new Azure Container App Environments created from the Azure portal will use the Microsoft.App namespace. You can manage both Microsoft.Web and Microsoft.App Container Apps resources in the Azure portal. However, when issuing management operations, you must ensure you’re using the correct namespace or a compatible Azure CLI extension version.

See the Migration of existing Container Apps resources section above for more details on what to do when your Container App Environments and Container Apps are migrated.

Frequently asked questions

Can you tell me when my resources will be updated to Microsoft.App?

The migration is performed in batches and we’re unable to provide the exact migration timeframe for your resources.

How will I know when my resources have been updated?

After your resources have been migrated to Microsoft.App, operations using Microsoft.Web will fail with an error such as “Creation or update of environments and container apps in Microsoft.Web namespace are no longer supported. Please use Microsoft.App namespace instead.”

Where can I ask questions related to this migration and get help?

Respond to this issue or create a new issue in this repo. You can also open a case with Azure Support.

[mikhailshilkov]

When will the new specs land in https://github.com/Azure/azure-rest-api-specs? I hope it's well before the actual migration of resources, otherwise it's going to break our users of the Pulumi Azure Native provider.

[ThorstenHans]

@anthonychu will this also affect reading existing instances, so will the type of existing ACA instances be modified?

If that's the case, I've created a small GitHub Action that customers can use to get a notification once the migration has updated at least one existing instance of their Azure Container Apps

https://github.com/ThorstenHans/check-aca-arm-namespace-migration

If existing ACA instances were not updated in place, I've to update the Action once again 😄 However, I thought this could be useful. The repo also shows how to have that check being executed every 12 hrs using a cron schedule

[danielrbradley]

Hi, am I right in my assumption that:

• There will therefore be no transition period where the resources will be available through both APIs?
• Resources might not all be migrated at the same time - so some resources might start disappearing while others have not (especially in the case of deploying across multiple subscriptions and regions)?

Is there a specific reason that the transition can't be made transparently to the end-users where resources would be available through either API temporarily to allow users more time to manage their migration?

Also, it would be useful to know:

• When will specifications for the new Microsoft.App namespace be published?
• Will there be a stable API version published before the transition?
• Will all versions of the Microsoft.Web namespace be transitioned to Microsoft.App for backward compatibility?

[ruslany]

When will the new specs land in https://github.com/Azure/azure-rest-api-specs? I hope it's well before the actual migration of resources, otherwise it's going to break our users of the Pulumi Azure Native provider.

@mikhailshilkov - The new version branch is ready to be merged to the main branch of azure-rest-api-spec. It should be merged pretty soon. Meanwhile you can find the AP specs here:

https://github.com/Azure/azure-rest-api-specs/tree/Microsoft.App-2022-01-01-preview/specification/app/resource-manager

[ruslany]

@ThorstenHans - thanks for preparing the github action for this!

The way the migration works is that all subscription's environments and containerapps hosted there are migrated at the same time in a given region. After the migration the resources will not be visible in the Microsoft.Web namespace but instead will be visible in the Microsoft.App namespace. So I guess the action could be modified to use the new go client sdk (when it is available) together with the old client sdk to list environments in both namespaces.

[ThorstenHans]

@ruslany correct. That was the intention once the new SDK is there.

With the current iteration, I can get an immediate notification when the first ACA is migrated in my sub.

Having both SDKs would allow to create a nice listing of all the ACA resources (both migrated and current ones under Microsoft.Web)

[ruslany]

@danielrbradley ,

Yes, there will be no transition period when resources are available in both namespaces. However, the portal will work seamlessly with both namespaces and you can continue using it before and after the migration without any noticeable difference. The reason the resources are not available for updates in both namespaces at the same time is because that would violate the ARM requirement that the resource state is updated only via the ARM API calls. For example if an app is created in Microsoft.Web namespace and then updated in the Microsoft.App namespace – the app’s state in the Microsoft.Web will change without any explicit actions performed on that app in that namespace. That will make the ARM cache, Azure Resource Graph and Activity log in Microsoft.Web namespace out of sync with the actual object state.

All resources within a subscription in a region will be migrated at once. But resources across regions may be migrated at different times.

The specifications for the new Microsoft.App namespace will be merged to the main branch of azure-rest-api-specs very soon. Meanwhile you can see them in a version branch here: azure-rest-api-specs/specification/app/resource-manager at Microsoft.App-2022-01-01-preview · Azure/azure-rest-api-specs (github.com). The API version is still a preview version because we keep iterating on the APIs as new functionality is added. The existing API version from the Microsoft.Web namespace will not be transitioned to Microsoft.App.

[danielrbradley]

Thanks for the additional detail @ruslany

Are you also notifying any active users of the service directly with details of how to migrate?

[ruslany]

@danielrbradley - Yes, we are planning to send notifications to all active users. The notification will reference this github issue which we will be updating with migration details.

[isaacabraham]

@ruslany What do you recommend authors of tools that use ARM do for our users e.g. I'm one of the maintainers of Farmer and we have had since last year a working implementation of container apps.

Obviously if there's a "hard cutover" then some of our users (I imagine this is a relatively small number, but still) will be left high and dry in some way:

• If we wait to release a fix in Farmer until after the cut over, users will be stuck until then.
• If we release a fix in Farmer until before the cut over, users who prematurely upgrade will be stuck until the change over occurs.

Because Farmer removes the need to know how to generate the ARM (or which ARM resources paths are generated), people's Farmer code will be completely unchanged, but the ARM that's generated will suddenly start changing - an situation we're really careful to avoid.

The only other idea I have is a period of time whereby we have make users set flag to explicitly upgrade to the new schema, and then after a period of time, remove the flag and make this the default.

@forki I believe you might be affected by this. Also looping in @ninjarobot for any other ideas.

[ruslany]

@isaacabraham - the option where user sets a flag to use old or new schema sounds reasonable and should work. I am also wondering if instead of introducing a new flag, the decision to use old or new schema can be driven by what type of an environment is chosen by user. There will be no kubeEnvironments resource type in the Microsoft.App namespace. Instead there is Microsoft.App/managedEnvironments resource type. The managedEnvironment resource type does not exist in the Microsoft.Web. Would it make sense to introduce a ManagedEnvironment builder? When user starts with that then the new ARM schema is used for creating environments and the apps in it. If user starts with an existing Container Environment builder then the old Microsoft.Web schema is used. Then after the migration is done the existing Container Environment builder is deprecated.

[ruslany]

@mikhailshilkov , @danielrbradley - the API specifications are now in the main branch of the azure-rest-api-spec: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/app/resource-manager

[willvelida]

Hey @anthonychu, I'm in the process of migrating my Container Apps Environment and Container App to the new namespace in my Bicep templates and deploying it via GitHub Actions. On the Bicep validation step, I get the following error:

[validate](https://github.com/willvelida/bookstore-containerapps/runs/5383975234?check_suite_focus=true)
ERROR: {'code': 'InvalidTemplateDeployment', 'message': "The template deployment '18' is not valid according to the validation procedure. The tracking id is 'f99b8305-c219-4795-8c9b-eac864116bba'. See inner errors for details."}

Inner Errors: 
{'code': '90010', 'message': 'LogAnalyticsConfiguration.CustomerId is invalid.  CustomerId must be a GUID'}

Looking at the API Definition, it looks like the type required for Log Analytics Customer Id is still a string, so has the API Definition been updated as part of this migration or is there something else going on?

I've raised the following issue for more details: #126

[ruslany]

Hi @willvelida - this is a bug in the new PR implementation. We are deploying the fix for it in a next couple of days.

[danielrbradley]

For anyone using Pulumi to manage their Container Apps can follow this migration guide for managing the transition of resources between namespaces: pulumi/pulumi#9099

[willvelida]

@ruslany I've just updated my Bicep template, run my deployment and it works! 😊

I'm guessing this means that the fix has been deployed? If so, I can go ahead and close #126

[ruslany]

@willvelida - thanks for the verification! I was about to post here that we've deployed the fix :). You can close the #126

[takekazuomi]

When I deployed in the new namespace(Microsoft.App/managedEnvironments), I got the following error.

 "ContainerAppsConfiguration.DaprAIInstrumentationKey is invalid.  DaprAIInstrumentationKey length cannot be greater than 64 characters."

Curiously, neither LogAnalytics nor ApplicationInsights have been created after the error. These two should have been created before 'Microsoft.App/managedEnvironments' in the dependencies.

bicep code is here
https://github.com/takekazuomi/aca-bicep01/blob/main/deploy-env/environment.bicep

[davidxw]

I've deployed into the new namespace (using Bicep), and have noticed a couple of issues:

• Ingress property on bicep template seems to be now required, however it is not validated by schema, and deployment of the container app fails (template missing the ingress property deployed without issue when using Microsoft.Web)
• Logging/metrics broken in portal - error returned is "microsoft.app/containerapps is not a supported platform metric namespace, supported ones are Microsoft.AnalysisServices .... (etc. etc. etc)"

[timoknapp]

When I deployed in the new namespace(Microsoft.App/managedEnvironments), I got the following error.

 "ContainerAppsConfiguration.DaprAIInstrumentationKey is invalid.  DaprAIInstrumentationKey length cannot be greater than 64 characters."

Curiously, neither LogAnalytics nor ApplicationInsights have been created after the error. These two should have been created before 'Microsoft.App/managedEnvironments' in the dependencies.

bicep code is here https://github.com/takekazuomi/aca-bicep01/blob/main/deploy-env/environment.bicep

I am having the exact same issue since I migrated the API from Microsoft.Web to Microsoft.App. Did you manage to resolve the issue @takekazuomi ? My .bicep template looks pretty similar btw.

[ruslany]

@takekazuomi , @timoknapp, @davidxw - thanks for reporting these bugs. We are looking into them. The metrics/logging being broken in portal is a known issue as the onboarding of Microsoft.App to metrics is still in progress.

[chrisreddington]

@joergjo , @clarenceb, @timoknapp , @onionhammer - the Dapr Components change has been deployed in all regions.

@ruslany - I updated my bicep templates and now Dapr works just fine! Even the new probes are working as expected. This is amazing - thank you :)

Likewise, I've just deployed using the new Resource Providers, and refactored some of my old Bicep Files. All looks to work great :)

[askaribragimov]

Found this bug by trying to attach a container app workspace to a log analytics workspace.

az extension add --name containerapp --upgrade
>  Extension 'containerapp' 0.3.20 is already installed.
az provider register -n Microsoft.App
az monitor log-analytics workspace create --resource-group "$(resourceGroup)"  --workspace-name "$(envName)-logworkspace" 
az containerapp env create  --name "$(containerAppsEnvironment)"  --resource-group "$(resourceGroup)"  --location "West Europe" --logs-workspace-id "$WORKSPACE_ID" --logs-workspace-key $WORKSPACE_SHARED_KEY

ERROR: (InvalidRequestParameterWithDetails) LogAnalyticsConfiguration.CustomerId is invalid.  CustomerId must be a GUID without additional whiteSpace.

Documentation of az containerapp env create has no notion of Customer ID: https://learn.microsoft.com/en-us/cli/azure/containerapp/env?view=azure-cli-latest#az-containerapp-env-create

It is very hard to comprehend, why documentation has no clue whatsoever as to why this error happens and a lot of developer resources are channeled to spend time figuring yet another puzzler increasing time to market and lowering ROI for the company that is trying to use the technology. It is 2022 and it is time to do things that work according to documentation.

[willvelida]

Hey @askaribragimov, I've just tried to provision an environment with Log Analytics and I got it working. Here's what I did for reference:

$RESOURCE_GROUP_NAME="rg-acaazcli"
$LOCATION="australiaeast"

az group create --name $RESOURCE_GROUP_NAME --location $LOCATION

$WORKSPACE_NAME="lawwvacaazcli"
az monitor log-analytics workspace create --resource-group $RESOURCE_GROUP --workspace-name $WORKSPACE_NAME

$WORKSPACE_ID=(az monitor log-analytics workspace show --resource-group $RESOURCE_GROUP --workspace-name $WORKSPACE_NAME --query customerId -o tsv)

$WORKSPACE_SHARED_KEY=(az monitor log-analytics workspace get-shared-keys --resource-group $RESOURCE_GROUP --workspace-name $WORKSPACE_NAME --query "primarySharedKey" -o tsv)

$CONTAINER_APP_ENVIRONMENT_NAME="envwvacaazcli"
az containerapp env create --name $CONTAINER_APP_ENVIRONMENT_NAME --resource-group $RESOURCE_GROUP --location $LOCATION --logs-workspace-id $WORKSPACE_ID --logs-workspace-key $WORKSPACE_SHARED_KEY

Can I ask you how you are extracting the value your $WORKSPACE_ID? That might be causing the issue.

[askaribragimov]

@willvelida --query customerId was the key, I used --query id.

Why the hell workspace ID is also customer ID? Microsoft never ceases to name same thing differently. They should really take AWS example where such thing does not seem to be of issue.

[willvelida]

@askaribragimov resource versions do change over time, so issues like this can occur. Sorry about the inconvenience caused and glad to hear that querying customerId worked for you.

@anthonychu - hopefully you're the right person to ask, but the parameter --logs-workspace-id is a bit confusing when it's the customerId that should be supplied. Is there anyway we can improve the error message to state that the customer Id should be provided, or can we improve the doc on az containerapp env create to make this clearer?

[askaribragimov]

@willvelida thank you for the prompt reaction! Apologies that I sound frustrated, it is really confusing what's going on there.
I would suggest renaming the parameter to --logs-workspace-customer-id that would harmonize the naming with log workspace terminology. Note that currently you ask for workspace id but if it is wrong, an error message talks about Customer ID, so within az containerapp create the terminology is not currently consistent between input parameters/docs and the errors it prints.

[vienleidl]

Hey @askaribragimov, I've just tried to provision an environment with Log Analytics and I got it working. Here's what I did for reference:

$RESOURCE_GROUP_NAME="rg-acaazcli"
$LOCATION="australiaeast"

az group create --name $RESOURCE_GROUP_NAME --location $LOCATION

$WORKSPACE_NAME="lawwvacaazcli"
az monitor log-analytics workspace create --resource-group $RESOURCE_GROUP --workspace-name $WORKSPACE_NAME

$WORKSPACE_ID=(az monitor log-analytics workspace show --resource-group $RESOURCE_GROUP --workspace-name $WORKSPACE_NAME --query customerId -o tsv)

$WORKSPACE_SHARED_KEY=(az monitor log-analytics workspace get-shared-keys --resource-group $RESOURCE_GROUP --workspace-name $WORKSPACE_NAME --query "primarySharedKey" -o tsv)

$CONTAINER_APP_ENVIRONMENT_NAME="envwvacaazcli"
az containerapp env create --name $CONTAINER_APP_ENVIRONMENT_NAME --resource-group $RESOURCE_GROUP --location $LOCATION --logs-workspace-id $WORKSPACE_ID --logs-workspace-key $WORKSPACE_SHARED_KEY

Can I ask you how you are extracting the value your $WORKSPACE_ID? That might be causing the issue.

I got the same issue. Thanks @willvelida for your reference command lines, adding 2 -o tsv helps for getting the correct Workspace Id and Workspace Key. It's caused by the output strings have double-quotes.