ARM CognitiveServices accounts documentation is not clear enough to create a Speech Services Resouce (InvalidTemplateDeployment)

[slaterb1]

Bicep version Bicep CLI version 0.4.1008 (223b8d227a)

Describe the bug Running the following main.bicep template fails to create Speech Services Resource and documentation for bicep resource for latest version is not clear enough to satisfy the template.

resource intelligentSpeechService 'Microsoft.CognitiveServices/accounts@2021-04-30' = {
    name: 'TestSpeechModels'
    location: 'eastus'
    kind: 'Speech'
    sku: {
        name: 'S0'
    }
}

Error Message:

{"error":{"code":"InvalidTemplateDeployment","message":"The template deployment 'main' is not valid according to the validation procedure. The tracking id is '5d786a00-252f-4cfa-9f9e-1bbdedd9abc7'. See inner errors for details.","details":[{"code":"UpdateKindNotAllowed","message":"It's not allowed to update kind of API account."}]}}

Documentation: https://docs.microsoft.com/en-ca/azure/templates/microsoft.cognitiveservices/accounts?tabs=bicep

To Reproduce

1. Create the above main.bicep template file
2. az login
3. az set subscription 'your-sub'
4. az configure --defaults group='your-resource-group'
5. az deployment group create --template-file main.bicep

Additional context From the error message is sounds like "kind" field is incorrect. 'Speech' value was taken from docs on 2016-preview version

[anthony-c-martin]

@slaterb1 I'm not familiar with this particular resource type, but my interpretation of the error message is that the resource already exists in your Azure account, but with a different value of the kind field, and the resource provider doesn't allow updating this field to a different value for an account that already exists. Do you know if that's the case here?

If it does already exist, and you're able to delete the account, something to test would be manually removing the account from your subscription, and then using your Bicep deployment to recreate it.

[slaterb1]

A Speech Service does exist in the instance. I tried supplying a new name to generate a "new" instance but that didn't work and produced the same error. What are the acceptable "kinds" for Api Speech Services. Azure Portal just has "Speech Service" as the type you create manually.

[anthony-c-martin]

A Speech Service does exist in the instance. I tried supplying a new name to generate a "new" instance but that didn't work and produced the same error. What are the acceptable "kinds" for Api Speech Services. Azure Portal just has "Speech Service" as the type you create manually.

One good option if you've already got an existing resource and want to find out the current property values is to export and decompile - see docs here: https://docs.microsoft.com/en-us/azure/azure-resource-manager/bicep/decompile?tabs=azure-cli#export-template-and-convert. That should give you a basic starting point Bicep file for your resource group.

Let me know if that doesn't help, and I'll see if we can find someone on the Speech Services team to take a look.

[slaterb1]

I'll give that a shot today and report back. Thanks for the help @anthony-c-martin

[slaterb1]

@anthony-c-martin I took a look at the decompile doc that you sent me and it did not help me out because I do not have any ARM templates composed for a Cognitive Service.

I solved the issue that I had for deployment by referencing the Azure portal again. The kind value that I needed was "SpeechServices" which is not in the list of described kinds in the 2016-preview template for bicep CognitiveServices.account.

My above template, had some other issues in that I needed to supply some properties for it to understand the networking, which I did not have to do in the Azure Portal when I created the service manually. I was able to sort out the "missing required fields" by the Error messages that I received from the CLI.

I would recommend that the docs for the bicep template for CognitiveServices.account either includes a default example template with values such as this (this is the base use case for someone setting up a resource in Azure Portal) or has the default required fields explained AND a list of all valid kind options:

resource intelligentSpeechService 'Microsoft.CognitiveServices/accounts@2021-04-30' = {
    name: 'TestSpeechModels'
    location: 'eastus'
    kind: 'SpeechServices'
    sku: {
        name: 'S0'
    }
    properties: {
        customSubDomainName: 'testspeechmodels' // not required if creating a totally new model, I needed it to match existing model
        publicNetworkAccess: 'Enabled'
        networkAcls: {
            defaultAction: 'Allow'
        }
    }
}

[anthony-c-martin]

@slaterb1 - glad you were able to sort it out! The place in the docs I was trying to link you to was the "Export template and convert" section - which allows you to leverage the az group export command that generates a template on the fly based on your currently deployed resources, and then the decompiler to generate a Bicep file:

Thanks for the detailed info - I've raised https://github.com/Azure/azure-rest-api-specs/issues/16504 for the lack of intellisense on the kind field.

@tfitzmac - w.r.t documenting example templates, is the best place for this still the quickstarts repo?

[alex-frankel]

w.r.t documenting example templates, is the best place for this still the quickstarts repo?

That is my understanding. And then we can link to the quickstart in template reference.

[tfitzmac]

Yes, the quickstart repo is the best place for example templates. Right now, the reference docs are linking to only ARM templates. I will add Bicep examples soon.

[tfitzmac]

"Soon" means November