Board Review: Configuration for Azure SDK track-2 clients

[lmolkova]

Contacts and Timeline

• Responsible service team: ADP
• Main contacts: @lmolkova
• Expected code complete and release date: March 2022

About the client library

• Name of the client library: general configuration story for track 2 clients
• Languages for this review: Java

We want to discuss design principles for non-code configuration, specifically:

• APIs to populate configuration
• property naming principles and structure
• configuration sources
• global vs per-client configuration

More details are outlined in this gist - https://gist.github.com/lmolkova/bf1be28bcd0d08b99d6edd8ea4d740b6

API view: https://apiview.dev/Assemblies/Review/2a7d94c92389414da9448d6aa4c31b4f?diffRevisionId=bb3ed257c464403bba88ce61e40bf068&doc=False&diffOnly=True

Example and context:

Azure Spring Cloud team #3743 has a proposal for a configuration story, which is a general concern across different frameworks and user applications.
We already have limited support for Azure Core and transport configuration through environment variables and other means depending on the language. This proposal suggests covering important value-based client configuration options.

Azure Spring Cloud proposal: https://microsoft.github.io/spring-cloud-azure/4.0.0-beta.3/4.0.0-beta.3/reference/html/appendix.html

[lilyjma]

scheduled for 1/13 2-4pm pst

[tg-msft]

Previous related discussions:

• Connection Strings: Change Request: Connection String Support for all languages #535
• No synthetic connection strings: Change Request: Support components of connection string not present in the portal #1701
• Auth Scope config: Change Request: Add note on how to use package in other Azure clouds in the readme #3353
• Secretless connection strings: Change Request: Support Identity-Based Connection Strings for all languages #3288
• (Draft) Cloud Config: Add cloud configuration support for azure client libraries #1550

 

Questions I'd love to chat about more:

1. Will every settable property get its own env var?
   • Will all languages need to support these env vars per the General Guidelines?
   • How do new properties/env vars get added?
   • What's the plan for language/stack specific values?
   • How far does the set of configurable properties go? Will I be able to change the credential type (in .NET that could mean different dependencies, catching different exceptions, etc.)?
2. How do settings merge between global config and local/per-client config?
   • Can I take global retry settings with a local retry timeout?
   • Can I clear a global value without redefining everything?
   • Can I ignore any external config and only use what's defined in code?
3. How are string values of these properties parsed?
   • Are the conventions the same across languages? I noticed the 8601 duration PT1S syntax as an example where this has problems.
   • How does the proposed collection syntax work? Does it replace the collection wholesale? Can I just add/remove values from an existing allow list? How does this relate to the global/local merging question above?
4. Troubleshooting
   • How would I debug this? Does this mean we should adopt a guideline that everything configurable has a public property (i.e., not all clients have a Uri Endpoint property today with the value passed into their .ctor)?
   • Should we log all the settings used for config? Is it possible to include provenance (i.e., this property came from a file at C:\temp\settings.json and this property came from env var AZURE_FOO)? Do we never log secrets or do we create another allow-list to make it configurable?
5. Documentation
   • How will you document the set of proposed values?
   • How will we document the different supported formats without overwhelming customers?
   • What's the workflow for a customer to go from "I want to configure this property" to finding out how to do so in our docs?
6. Across languages
   • In the linked gist we say Defined environment variables must be consistent across languages but also say it's a non-goal to Make explicit configuration fully-consistent across languages and Define all configuration properties in every language. Defining properties can be done for options/clients gradually as a next steps. Those seem in conflict with the way I understand it.
   • If we don't have a consistent config, doesn't that get us back in the same boat of "why doesn't this Java connection string not work with a C# client" that we were trying to avoid with the "connection strings only allowed to support what's in the portal" guidance we have now?
   • If we wait to light up some config values over time, can't that cause breaks for customers when a previously ignored setting is suddenly respected in a future release?
7. Release plan
   • I would love to see this documented as env vars, JSON, XML, etc., for all the supported providers before we ship
   • Ideally we'd have a long beta where we help customers debug through config issues to make sure we've got the right end to end story in place

[tg-msft]

Recording[MS INTERNAL ONLY]