search

microsoft / azure-container-apps

Roadmap and issues for Azure Container Apps
MIT License
372 stars 29 forks source link

API version inconsistencies bug Portal export functionality - requires clarifications on intent #1288

Closed saarivirtajCGI closed 2 months ago

saarivirtajCGI commented 2 months ago

Please provide us with the following information:

This issue is a: (mark with an x)

Issue description

The Portal allows you to do things that you are unable to export via the Export functionality, because of a mismatch in API version used by the portal to operate the resource vs the API version used to export the resource definition.

That is the tangible bug, but what requires clarification here is also the intent.

The current state of the Microsoft.App/managedEnvironments API leaves me confused. When looking at the changelog (https://learn.microsoft.com/en-us/azure/templates/microsoft.app/change-log/managedenvironments) we can see that a lot of features that were in the last preview have been removed in the last stable API version. I'm not going to quote all of them here as the list is long, but rather focus on the few ones that are of most interest regarding my own user experience:

2024-03-01 Removed:

  • properties.certificateKeyVaultProperties
  • properties.certificateKeyVaultProperties.identity
  • properties.certificateKeyVaultProperties.keyVaultUrl
  • properties.certificateType ...

2024-02-02-preview Added:

  • peerTrafficConfiguration
  • peerTrafficConfiguration.encryption
  • peerTrafficConfiguration.encryption.enabled
  • publicNetworkAccess

2023-11-02-preview Added:

The question is: how are we supposed to interpret this?

I couldn't find real documentation beside the simple added/removed property list on the API version. This leaves me to wonder, that is it either:

  1. The changes were rolled back (it was a preview after all), and are not going to be added. The stable version represents the current state of development upon which next versions will be built on, and those preview version features didn't make it through.
  2. Most changes stay in preview, while some made it to the current stable version. The ones in the preview version will eventually pull through to the stable version.

To further add to the confusion, the Azure Portal clearly mixes both of these versions: you can do things that the preview version provides, such as setting the ACA Environment a Managed Identity and configuring the Custom domain suffix with KeyVault-based SSL certificate. However if you try to export the resources, these things are plainly missing from the resource definition because the version used in the export is the latest stable API version. So the export produces an incomplete output.

How should we interpret the situation? Are the new features here to stay?

Steps to reproduce

  1. Create an ACA environment
  2. Configure Managed Identity with KeyVault access and an SSL cert
  3. Set up a custom domain suffix with the said SSL cert
  4. Export the resource. Notice how the properties are missing and the export is done with the latest stable API version

Expected behavior [What you expected to happen.] Consistency; the portal to operate with a single API version.

Actual behavior [What actually happened.] ACA environment is exported with the 2024-03-01 API version, while clearly Portal is manipulating the resources with a preview API.

simonjj commented 2 months ago

@saarivirtajCGI, thank you for raising this with us. Unfortunately, there is a set of circumstances that lead to this confusion. Let me explain:

In the case of Container Apps this is slightly more impactful because the API is evolving more quickly than with other services. In general we rarely remove capabilities and if we do usually go through a deprecation process. Please share any additional concerns I may not have addressed with the above.

saarivirtajCGI commented 2 months ago

@simonjj Thank you for these clarifications!

So we can use the preview API then to use these new features and we can trust that they will be available there in the future. This was the main concern, as we wouldn't want to build on something that wasn't going to exist in the future.

It's also good to know that the export always uses the stable API version - however the confusion still easily happens as it isn't immediately evident what features are preview features when operating in the portal.

Thanks for your input, case closed.