Azure-docs: Misplaced NOTE

[Jungers42]

There's a great note on this page about "Not all settings are available in the portal. In case a setting listed below is not available via the portal customize it using an Azure Resource Manager template." Firstly, this is very frustrating and totally unclear why there are only a handful of settings available for control through the portal. Secondly, this note is on the wrong page. It seems like it is supposed to be on the page which actually lists the settings: https://docs.microsoft.com/en-us/azure/service-fabric/service-fabric-cluster-fabric-settings

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 8aac72f9-bdf3-c656-ae5c-1475c413de13
• Version Independent ID: dd937997-96cb-16c3-8cdf-6d6977ad4b92
• Content: Upgrade the configuration of an Azure Service Fabric cluster
• Content Source: articles/service-fabric/service-fabric-cluster-config-upgrade-azure.md
• Service: service-fabric
• GitHub Login: @dkkapur
• Microsoft Alias: dekapur

[mimckitt]

Thanks for the feedback! We are currently investigating and will update you shortly.

[mimckitt]

@Jungers42 for production workloads it is best practice to use ARM templates to manage just about every aspect of your cluster. I can see how it can be annoying when something cannot be managed via the portal.

As per the note, I believe it is in the right place.

@dkkapur @aljo-microsoft could either of you confirm?

[dkkapur]

@Jungers42 - the second spot you linked has an Upgrade policy column on each of the settings specifying whether or not they can be tweaked. The expectation should be that they are tweaked via the ARM template rather than through Portal. We should do a better job making that part clearer (@aljo-microsoft or @peterpogorski do you want to add a note stating this on the page itself?), so appreciate the feedback on that front!

@MicahMcKittrick-MSFT - yes, you are right!

[aljo-microsoft]

@Jungers42 @peterpogorski @dkkapur
Updated the following:

Not all settings are available in the portal, and it is a best practice to customize it using an Azure Resource Manager template; Portal is for Service Fabric Dev\Test scenario's only.

https://github.com/MicrosoftDocs/azure-docs-pr/pull/65600

@MicahMcKittrick-MSFT

please-close

[Jungers42]

@aljo-microsoft @dkkapur @MicahMcKittrick-MSFT
My concern about the note which was on the page is that it said "In case a setting below ..." ... however there is only one setting listed on that page at all and it's just an example. I spent a while on the other page I linked looking at all of the settings and trying to figure out why I couldn't see them in Azure before clicking through and noticing the note on this page. It felt like maybe they used to be one page or the settings were listed on both pages or something like that.

So the page which does actually list all of the settings deserves the same note which is present on this page and the note as it is written on this page is strange since it references settings which are NOT listed on this page. So I believe this page's note should be updated (if it still contains that sentence). And I believe that this note as it was written as well as the updated text about best practices should be placed on the other page.

Furthermore, as for the Upgrade policy column on the other page, that actually has nothing to do with the Azure portal behaviors. Only a small subset of all dynamic properties are available for management through the Azure portal. Stranger still, once you do update the ARM template, you can now see your new settings in the Azure portal even though you can't create or edit them there. Seems like such a trivial feature to support since some of the dynamic properties appear to work just fine through the portal. But that's a feature request and not a documentation issue. Point is, that column does NOT address which settings are manage-able through Azure so more information on that page would be very helpful to those using the portal.

On that point, whether it's a best practice or not, many use cases even of Service Fabrics may well not benefit much at all from full ARM template control. So it seems awfully limiting to force folks down that path when it may be far heavier than they need and simply introduce substantial overhead in their processes for choosing to use Service Fabric. In other words, mandating that choice (using ARM templates) may simply have the effect of pushing folks away from a great technical solution because the overhead is not worth the benefits.

[dkkapur]

@Jungers42 fair points, thanks for the feedback. Part of the reason why this is the way it is, is because we are focusing the product on larger critical workloads where we feel operating without an ARM template would potentially create issues in the future. For smaller deployments, we are evolving Service Fabric Mesh and that will likely become the better path. This will ideally allow for a much easier management experience while providing the benefits of running on a great tech like SF.