azure-cli
azure-cli copied to clipboard
Azure
Extremely poor documentation for `az cosmosdb create`
None of the parameters are documented on a sufficient level. For example:
--capabilities
Set custom capabilities on the Cosmos DB database account.
Not even a link where I can read further what are these mysterious capabilities.
--kind
The type of Cosmos DB database account to create.
accepted values: GlobalDocumentDB, MongoDB, Parse
default value: GlobalDocumentDB
What is Parse in this context?
--locations
Add a location to the Cosmos DB database account.
Luckily the actual help text (--help) explains how to set a location.
Document Details
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
- ID: abc8d652-2eda-296f-28ea-8d5f1ea855b3
- Version Independent ID: 80b87995-d339-61e9-1cac-b5c9ad6efe5e
- Content: az cosmosdb
- Content Source: latest/docs-ref-autogen/cosmosdb.yml
- Service: cosmos-db
- GitHub Login: @rloutlaw
- Microsoft Alias: routlaw
Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @Wmengmsft, @MehaKaushik, @shurd, @anfeldma-ms
Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @Wmengmsft, @MehaKaushik, @shurd, @anfeldma-ms.
Issue Details
None of the parameters are documented on a sufficient level. For example:
--capabilities
Set custom capabilities on the Cosmos DB database account.
Not even a link where I can read further what are these mysterious capabilities.
--kind
The type of Cosmos DB database account to create.
accepted values: GlobalDocumentDB, MongoDB, Parse
default value: GlobalDocumentDB
What is Parse in this context?
--locations
Add a location to the Cosmos DB database account.
Luckily the actual help text (--help) explains how to set a location.
Document Details
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
- ID: abc8d652-2eda-296f-28ea-8d5f1ea855b3
- Version Independent ID: 80b87995-d339-61e9-1cac-b5c9ad6efe5e
- Content: az cosmosdb
- Content Source: latest/docs-ref-autogen/cosmosdb.yml
- Service: cosmos-db
- GitHub Login: @rloutlaw
- Microsoft Alias: routlaw
| Author: | Tattoo |
|---|---|
| Assignees: | - |
| Labels: |
|
| Milestone: | - |
Where are you looking? Can you please post a link to the documentation you are referring to?
Those are api reference docs autogenerated from swagger.
Our docs and samples for az cli are in our docs here. This is what most people use.
https://docs.microsoft.com/en-us/azure/cosmos-db/manage-with-cli
And include az cli samples for all 5 database api's.
https://docs.microsoft.com/en-us/azure/cosmos-db/cli-samples https://docs.microsoft.com/en-us/azure/cosmos-db/cli-samples-cassandra https://docs.microsoft.com/en-us/azure/cosmos-db/cli-samples-mongodb https://docs.microsoft.com/en-us/azure/cosmos-db/cli-samples-gremlin https://docs.microsoft.com/en-us/azure/cosmos-db/cli-samples-table
Well, Google finds the pages I linked first. Why is it published if it's not good?
Also, the link you provided doesn't explain the parameters I listed either.
All service in Azure that provide az cli functionality publish api reference docs. Same goes for PS, REST, and other management SDK clients. I can't speak to why they showed up first in your Google search. Most customers find our regular docs and use those.
These values and usage for locations and kind parameters are referenced throughout our documentation including quite a number in the links I sent you before. Capabilities parameter meanings are found throughout our documentation that describes the features they enable and are self-explanatory to users who are using those features.
I don't understand the reasoning why the published documentation can't be good. If this is not a documentation that should be looked at, why publish it in the first place? As a user, comment like "you should have found our other documentation" is kind of unhelpful one — I can't know what I should and should not find.
I also looked again your links and I still fail to find the answers I iterated in my original comment: what are valid options for --capabilities? What do the options in --kind do? They all seem to link back to the API documentation.
I would argue that API documentation, first and foremost, ought to be in tip top shape as it is generally with other tools.
It's published because it is an api reference. It has value for people who know the service and want to use az cli to manage it. It's not intended for people who are new to the service and need help understanding concepts or features.
Not sure how the links do not explain the parameters you are asking about. Please see this example for what --kind is used for as well as --locations https://docs.microsoft.com/en-us/azure/cosmos-db/scripts/cli/mongodb/create
As explained earlier, --capabilities are for features that are explained in the area of docs for the features they are for.
Our docs for az cli is not where customers tend to learn about a new service. az cli is a management client. As you seem to be new to the service, please read our conceptual and how-to documentation to learn about the service. This is not unique to Cosmos but is how this works across every service in Azure.
API references are documentation as well and this is subpar. You can always link to proper other, existing resources.
#please-dont-close
As explained earlier these docs are auto generated. There is very little control we have over these.
Your comments seem to indicate you may be new to Azure. I appreciate your feedback but I do suggest you get more familiar with things first before disparaging our docs because it was your first hit on Google.
Our api reference docs for az cli is not where people learn about a new service.
I'm not new to Azure and can concur with the original poster that these flags are poorly documented, or at least it is not clear where to find the more complete documentation.
Within the Azure Portal it is clear that the choice of API is mutually exclusive, you choose from a drop down where SQL core and Table appear separately.
Via the Azure CLI this choice not so clear as SQL core is the default , to get an account supporting the table API then --capabilities must be used.
The plural capabilities in the flag suggests being able to support multiple APIs but is that possible (I don't think so for SQL and Table APIs) ? It is this that could be improved in the Azure CLI documentation.
Just ran into a similar issue, trying to figure out how to specify that the created DB should be serverless. I understand that the documentation is auto-generated. That doesn't make it any easier to use though and I hope the team will review how to make it better. Would it be an option to list all the capabilities available? Or have a pointer on how one can find out what those capability values are?
As explained earlier these docs are auto generated. There is very little control we have over these.
They might be autogenerated but they're generated from somewhere. They don't just spring forth into existence. If there's a better place to direct this issue, the place where these strings actually live, then that would be helpful. But it is not helpful to just say there's nothing that can be done about it.
To put this into perspective, this is like there's a C# method named SetCapabilities(string[] capabilityNames). If the IntelliSense for that was "Set custom capabilities on the Cosmos DB database account" too, and there was no mention of the magic strings necessary to make it actually do anything, I would be annoyed with that too.
Sean please see our conceptual docs on this. Emphasis mine
https://docs.microsoft.com/en-us/azure/cosmos-db/serverless#using-serverless-resources
Serverless is a new Azure Cosmos account type, which means that you have to choose between provisioned throughput and serverless when creating a new account. You must create a new serverless account to get started with serverless. During the preview release, the only supported way to create a new serverless account is by using the Azure portal. Migrating existing accounts to/from serverless mode is not currently supported.
#please-close
@petenorth Running multiple API's in a single account is not supported for Cosmos DB. But that is why it's important to read the conceptual docs. https://docs.microsoft.com/azure/cosmos-db/.
@DavidBoike they are generated from the source code in this repo. Some are in help.py. Capabilities help is specifically here https://github.com/Azure/azure-cli/blob/dev/src/azure-cli/azure/cli/command_modules/cosmosdb/_params.py#L71
There are reasons why we do not fully bake elaborate help on this property into these autogenerated docs and instead guide users to refer to the conceptual docs and samples instead.
The first reason is because values for capabilities can change and can also go away. We sometimes use this property to light up a feature while it is in preview before making it a property of the databaseAccount resource because if we hard code it as an account property, even in preview, it is nearly impossible to change it in our RP if we are forced to use a different name, datatype, etc. Because the accepted values for this property change, sometimes frequently we do not include elaborate documentation on all possible values (kind of defeats the purpose of autogen docs too which all az cli docs are).
Additionally capabilities sometimes require other properties to be set when used. For example "EnableAggPipeline" capability can only be used on an account where kind="MongoDB". A full explanation of what each of these values do and when they must be used in combination with other properties is simply beyond the scope of the help that ships within the az cli or is rendered via the autogenerated docs.
Hopefully this explains why we do not fully document this property in az cli help and why the conceptual docs (and the samples I have written too that I pointed out above) are the best source for help in usage.
(kind of defeats the purpose of autogen docs too which all az cli docs are).
Sorry, but the whole point of having auto-generated docs is that it is easy during development to change the documentation, which is then automatically made available during release. This is pretty standard development practice that various APIs, CLIs and others already do. This way, the documentation that is shipped with the CLI is actually useful.
Usually the documentation is even provided for all versions of a CLI so an end user could see how such values as capacity have changed depending on what version they happen to have.
Please see my other point.
Get Outlook for Androidhttps://aka.ms/AAb9ysg
From: Tatu Kairi @.>
Sent: Monday, May 10, 2021 9:37:57 PM
To: Azure/azure-cli @.>
Cc: Mark Brown @.>; Comment @.>
Subject: Re: [Azure/azure-cli] Extremely poor documentation for az cosmosdb create (#16583)
(kind of defeats the purpose of autogen docs too which all az cli docs are).
Sorry, but the whole point of having auto-generated docs is that it is easy during development to change the documentation, which is then automatically made available during release. This is pretty standard development practice that various APIs, CLIs and others already do. This way, the documentation that is shipped with the CLI is actually useful.
Usually the documentation is even provided for all versions of a CLI so an end user could see how such values as capacity have changed depending on what version they happen to have.
— You are receiving this because you commented. Reply to this email directly, view it on GitHubhttps://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FAzure%2Fazure-cli%2Fissues%2F16583%23issuecomment-837792085&data=04%7C01%7Cmjbrown%40microsoft.com%7Cf5ecc40f5b7945ef450208d914368d3e%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637563046799330730%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=tz3xKmseS1Z9o8JaTwirZPnLX%2Bywh19muHvOd5OBYuI%3D&reserved=0, or unsubscribehttps://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAAGDLJT7SJCFZRRUEQONVOLTNCYCLANCNFSM4WIY2ZJQ&data=04%7C01%7Cmjbrown%40microsoft.com%7Cf5ecc40f5b7945ef450208d914368d3e%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637563046799330730%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=kj4BoKUGSoH8vyZAmbsc8mTDrRiZ1FBx0ap9CZrguVY%3D&reserved=0.
As I have detailed before, you can link to more extensive documentation from the auto-generated if needed. In fact, this is one of the prime ways to make sure your end users actually find the relevant, comprehensive documentation.
Again, these are not good reasons to dismiss this ticket. Others are widely doing it.
I will review your suggestion with my team.
Thank you for your feedback.
Get Outlook for Androidhttps://aka.ms/AAb9ysg
From: Tatu Kairi @.>
Sent: Monday, May 10, 2021 9:59:17 PM
To: Azure/azure-cli @.>
Cc: Mark Brown @.>; Comment @.>
Subject: Re: [Azure/azure-cli] Extremely poor documentation for az cosmosdb create (#16583)
As I have detailed before, you can link to more extensive documentation from the auto-generated if needed. In fact, this is one of the prime ways to make sure your end users actually find the relevant, comprehensive documentation.
Again, these are not good reasons to dismiss this ticket. Others are widely doing it.
— You are receiving this because you commented. Reply to this email directly, view it on GitHubhttps://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FAzure%2Fazure-cli%2Fissues%2F16583%23issuecomment-837814362&data=04%7C01%7Cmjbrown%40microsoft.com%7C701fd7f12f434b01aee208d91439887f%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637563059600340164%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=FVNGmTYEvD3i00n9k8zfI2UYEzFlizgKT%2FGfUy5z4xw%3D&reserved=0, or unsubscribehttps://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAAGDLJS77UDX4VMSQXQGLYDTNC2SLANCNFSM4WIY2ZJQ&data=04%7C01%7Cmjbrown%40microsoft.com%7C701fd7f12f434b01aee208d91439887f%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637563059600340164%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=5fEcK9eo%2FcBpKXFC53M%2BLUjAgxer2ZR%2FRF3dMJkrdps%3D&reserved=0.
It's funny, I was looking for documentation on how to declare serverless and I did not find any mention of it in Microsoft documentation when searching (with Google or Bing) but both brought me to this issue page instead. Until then I had never seen the manage-with-cli page that was linked above. Also this page https://docs.microsoft.com/en-us/azure/cosmos-db/serverless#using-serverless-resources no longer has the word "Portal" in it anywhere but the CLI still does not support serverless configurations.
This is GA now, so there should have been samples written for this as well as PS, templates, bicep, etc.
Will check on this and get these written and published ASAP.
Thanks.
We now have cli samples published in our docs for each database API showing how to provision a serverless account. Example here. https://docs.microsoft.com/en-us/azure/cosmos-db/sql/cli-samples
We have added to our backlog an example which we will publish into our auto-generated docs. I don't have a precise ETA on this but it will go out in our next push.
Thanks.
I'm with OP in that I'd like to see Azure CLI docs with full detail. But I'm one of those crazy Linux people who's used to man pages that tell me everything about the command and it's config files, so what do I know. ¯\(ツ)/¯ (Simply listing all the parameter values would be helpful, but not sure what your autodoc process can do on that front.)
Meanwhile, for those of us struggling to figure out the Azure CLI options (because PowerShell makes my teeth hurt) it might help to recognize that many of the Azure CLI (and PowerShell, etc.) parameters are based on ARM templates. Searching for the Cosmos DB ARM template docs and searching that page for "capabilities" gets me here where one more link gets me here, which lists options for --capabilities, the meaning of which I can guess given the list.
This post is open for a while but it seems things haven't changed yet.
While going through this tutorial I found --capabilities EnableMongoRoleBasedAccessControl but when going further into the docs there is no additional information found.
A full list of valid options would be highly appreciated.
I got here after googling what the allowed values for "kind" mean (I'm working on Bicep code, but azCLI ends up working against the same API in the end, no?)
As per the docs, the allowed values are GlobalDocumentDB, MongoDB, and Parse. What does Parse do?
I have to agree with the other commenters, the documentation here is insufficient. I'm an infrastructure person, I just need to know how to deploy resources, not the full life story of each resource, and having to dig through the tutorials (not resource API docs) for each resource in order to understand how to deploy things just wastes my time.
Thanks for the continued feedback.
Parse is an old (and deprecated for new users) database API. We would remove this completely however there are some very old customers still using it that we cannot break. I will take an action here to make this more obvious in our swagger spec and az cli and PS clients.
We are keenly aware of the issues with the Capabilities string array. It is very poorly documented. We know we need to do a better job documenting this. This is on our radar to improve soon.
My intention late last year to add more/better examples into these docs fell off my radar. I will take this continued feedback as motivation to make these and other changes suggested here.
I am always open for input on how to make our RP easier to use. If you have ideas on things you'd like to see better documented, ideas for sample, feel free to submit issues (be sure to tag with "Cosmos"). Totally open to contributions too!
It's not lost on me that you are all customers trying to use our service. I do really appreciate your feedback. Thank you!
Those are api reference docs autogenerated from swagger.
Our docs and samples for az cli are in our docs here. This is what most people use.
https://docs.microsoft.com/en-us/azure/cosmos-db/manage-with-cli
And include az cli samples for all 5 database api's.
https://docs.microsoft.com/en-us/azure/cosmos-db/cli-samples https://docs.microsoft.com/en-us/azure/cosmos-db/cli-samples-cassandra https://docs.microsoft.com/en-us/azure/cosmos-db/cli-samples-mongodb https://docs.microsoft.com/en-us/azure/cosmos-db/cli-samples-gremlin https://docs.microsoft.com/en-us/azure/cosmos-db/cli-samples-table
What about Postgres API? It's still missing. I don't see docs for how to create a free tier cosmos for postgres api as enxample.
