How to handle APIM managed certificate suspension in Bicep?

Question

How to handle APIM managed certificate suspension in Bicep?

Westman Carl 25

I have this Bicep code

resource apiManagementService 'Microsoft.ApiManagement/service@2024-05-01' = {
  name: apiManagementServiceName
  location: location
  sku: {
    name: sku
    capacity: skuCount
  }
  properties: {
    hostnameConfigurations: empty(customDomain)
      ? null
      : [
          {
            hostName: customDomain
            type: 'Proxy'
            negotiateClientCertificate: false
            defaultSslBinding: false
            certificateSource: 'Managed'
          }
        ]
    publisherEmail: publisherEmail
    publisherName: publisherName
    apiVersionConstraint: {
      minApiVersion: '2019-12-01'
    }
  }
  identity: identityType == 'None'
    ? null
    : {
        type: identityType
      }
  tags: resourceTags
}

However I cannot deploy this atm because I get

"Update APIM service 'shared-azure-api-management-sf57piwqzokg6' failed. The HostnameConfiguration includes a new Managed Certificate Request, which is temporarily not supported during update from August 15th 2025 to March 15th 2026. All the configured custom domains with Managed Certificate can still be reachable without any impact. Please refer to API Management documentation here: https://learn.microsoft.com/en-us/azure/api-management/breaking-changes/managed-certificates-suspension-august-2025"

How am I supposed to get this to deploy while also keeping my cert and custom domain active?

Rakesh Mishra 255 Reputation points Microsoft External Staff Moderator

2025-08-19T14:23:00.7233333+00:00

Hi @Westman Carl ,

Welcome to the Microsoft Q&A Platform! Thank you for asking your question here. Hope the answer suggested by Sina is helpful. If yes, please accept as Yes so that it can help others in the community. Do let me know if you need any further assistance on this.

Accepted answer

1 additional answer

Your answer

Rakesh Mishra 255 Reputation points Microsoft External Staff Moderator

2025-08-19T14:23:00.7233333+00:00

Hi @Westman Carl ,

Welcome to the Microsoft Q&A Platform! Thank you for asking your question here. Hope the answer suggested by Sina is helpful. If yes, please accept as Yes so that it can help others in the community. Do let me know if you need any further assistance on this.

Answer 1

Problem

The Bicep deployment for an Azure API Management service fails with an error stating that new managed certificate requests are temporarily suspended from August 15, 2025, to March 15, 2026. The goal is to deploy other changes to the API Management service while keeping the existing custom domain and managed certificate active.

Solution

The core issue is that the Bicep code attempts to update the hostnameConfigurations section, which triggers a new managed certificate request, leading to the deployment failure. To work around this, you must temporarily stop sending the hostnameConfigurations section in your Bicep template during the suspension window.

Here are the specific actions to take:

Remove or skip the hostnameConfigurations section: The most direct solution is to conditionally remove the hostnameConfigurations block from your Bicep template. This prevents the deployment from attempting to create or update the managed certificate, allowing other changes (like updates to APIs, products, or policies) to succeed. Your existing managed certificate will remain valid and will be automatically renewed by Azure.

Split your Infrastructure as Code (IaC): For a more robust approach, you can separate your Bicep code into two parts. One template would manage the core service-level settings (like sku, location, publisherEmail, etc.), while a separate, independent template would manage the content (APIs, products, policies, etc.) of the API Management service. This allows you to deploy content updates without touching the service's configuration, including the hostnameConfigurations.

Use a Key Vault certificate (Alternative): If you must add or change a custom domain during the suspension period, you can't use a new managed certificate. Instead, you would need to use a certificate stored in Azure Key Vault. This requires updating the hostnameConfigurations to reference the Key Vault ID and a certificate secret, instead of using the 'Managed' certificate source. This is a more involved change but is necessary if you need to onboard a new custom domain during this specific timeframe.

Answer 2

Sina Salam 23,931 Volunteer Moderator

Hello Westman Carl,

Welcome to the Microsoft Q&A and thank you for posting your questions here.

I understand that you are in need of how you can handle APIM managed certificate suspension in Bicep, and keeping your certificate + custom domain active.

Your Bicep deployment fails because it's attempting to add or modify the managed certificate configuration within this suspension window. You already have a working custom domain with a managed cert and you just need deployments to succeed (no domain change) by keeping the domain and cert untouched; deploy other changes by:

Stop sending hostnameConfigurations during the suspension window so ARM doesn’t attempt a new managed-cert request. Existing managed certs remain valid and auto-renewed - https://learn.microsoft.com/en-us/azure/api-management/breaking-changes/managed-certificates-suspension-august-2025
Split your IaC: manage service-level settings separately from “content” (APIs, products, policies). Use an existing APIM resource to deploy APIs/products without updating the service body. - https://learn.microsoft.com/en-us/azure/api-management/configure-custom-domain
To keep your current cert + domain active and unblock deployments now: remove/skip the hostnameConfigurations section during this window. That avoids triggering a new managed-cert request while preserving your live config. - https://learn.microsoft.com/en-us/azure/api-management/breaking-changes/managed-certificates-suspension-august-2025
If you must add/change a domain now: switch that hostname to Key Vault. Docs for Key Vault option & required permissions could be found here. - https://learn.microsoft.com/en-us/azure/api-management/configure-custom-domain and Property names/shape (certificateSource, keyVaultId, etc.). - https://learn.microsoft.com/en-us/azure/templates/microsoft.apimanagement/service

I hope this is helpful! Do not hesitate to let me know if you have any other questions or clarifications.

Please don't forget to close up the thread here by upvoting and accept it as an answer if it is helpful.

Westman Carl 25 Reputation points

2025-08-20T06:03:42.42+00:00

The problem with removing it is that we run weekly Complete deployments to clean stuff up, then my custom domain and cert will be removed right?
Brian Nielsen (Denmark) 0 Reputation points

2025-08-20T12:08:13.2033333+00:00

Hi @Sina Salam

Thank you for this response. I'm in the same situation, and would like to further get clarification on how I can handle this in my Bicep.
Does this imply that I can safely remove the 'hostnameConfigurations' property from 'Microsoft.ApiManagement/service' and the custom domain/managed certificate will continue to work after I re-deploy? - or am I forced to transition to Key Vault stored Certificates if I need to continue re-deploying 'Microsoft.ApiManagement/service'?

Right now I can't try this out without possibly ruining my currently deployed infrastructure (with Bicep for IaC).

Brgds
Sina Salam 23,931 Reputation points Volunteer Moderator

2025-08-20T13:14:23.79+00:00
Hello All,

@Westman Carl

Will my cert/domain be removed?

If you omit hostnameConfigurations during full redeploy. Yes, if your Bicep template defines the full APIM resource and omits hostnameConfigurations, Azure interprets that as a removal. To avoid this:

Split your deployment.

Use existing resource references.

Avoid overwriting the APIM service definition.

@Brian Nielsen

Can I safely remove hostnameConfigurations and still keep my cert/domain?

Yes, as long as you don’t overwrite the APIM resource with a new definition that lacks the domain config. Use a split deployment or existing resource pattern to avoid touching the domain settings.

Success
Westman Carl 25 Reputation points

2025-08-20T13:24:02.8633333+00:00

I ended up removing the certificate by accident when trying to get this to work... And as Brian said, I had to test it on my live resource...

So a little downtime later I now have a cert in my keyvault instead...

It was a couple off stressful hours, next time it would be nice to get a heads up and a recommendation to change from Managed before it's inactivated...
I don't understand why it would try to create a cert even though there already exist a cert, if that just would have worked when deploying from Bicep, nothing of this would be a problem.

But well, it seems to work now.
Sina Salam 23,931 Reputation points Volunteer Moderator

2025-08-20T15:47:43.3666667+00:00

Hello Westman Carl,

Thank you for your feedback. It's so good to read yours is now working.

Brian too will learn and make it work.

However, let's close the thread and forget not to thump up and accept as an answer.

Thank you.

Share via

How to handle APIM managed certificate suspension in Bicep?

1 additional answer

Your answer