search

Azure / azure-cli

Azure Command-Line Interface
MIT License
4.03k stars 3.01k forks source link

Extremely poor documentation for `az cosmosdb create` #16583

Open Tattoo opened 3 years ago

Tattoo commented 3 years ago

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.

ghost commented 3 years ago

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @Wmengmsft, @MehaKaushik, @shurd, @anfeldma-ms

ghost commented 3 years ago

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](https://docs.microsoft.com/en-us/cli/azure/cosmosdb?view=azure-cli-latest#az_cosmosdb_create) * Content Source: [latest/docs-ref-autogen/cosmosdb.yml](https://github.com/MicrosoftDocs/azure-docs-cli/blob/master/latest/docs-ref-autogen/cosmosdb.yml) * Service: **cosmos-db** * GitHub Login: @rloutlaw * Microsoft Alias: **routlaw**
Author: Tattoo
Assignees: -
Labels: `Cosmos`, `Service Attention`, `needs-triage`
Milestone: -
yonzhan commented 3 years ago

cosmosdb

markjbrown commented 3 years ago

Where are you looking? Can you please post a link to the documentation you are referring to?

Tattoo commented 3 years ago

As linked in my original message

markjbrown commented 3 years ago

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

Tattoo commented 3 years ago

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.

markjbrown commented 3 years ago

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.

Tattoo commented 3 years ago

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.

markjbrown commented 3 years ago

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.

Tattoo commented 3 years ago

API references are documentation as well and this is subpar. You can always link to proper other, existing resources.

please-dont-close

markjbrown commented 3 years ago

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.

petenorth commented 3 years ago

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.

SeanFeldman commented 3 years ago

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?

DavidBoike commented 3 years ago

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.

markjbrown commented 3 years ago

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

markjbrown commented 3 years ago

@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/.

markjbrown commented 3 years ago

@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.

Tattoo commented 3 years ago

(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.

markjbrown commented 3 years ago

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.

Tattoo commented 3 years ago

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.

markjbrown commented 3 years ago

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.

jgentil commented 3 years ago

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.

markjbrown commented 3 years ago

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.

markjbrown commented 3 years ago

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.

jmjf commented 2 years ago

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.

eeepmb commented 2 years ago

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.

asdkant-bf commented 2 years ago

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.

markjbrown commented 2 years ago

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!

GustavoOS commented 7 months ago

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.

niklarin commented 7 months ago

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.

@GustavoOS You're right, there's no way to provision a free trial of Azure Cosmos DB for PostgreSQL programmatically. Pardon possible confusion. The Azure Cosmos DB for PostgreSQL free trial can be started only via this page: https://cosmos.azure.com/try/

Once provisioned you can do all management operations using Azure Cosmos DB for PostgreSQL REST APIs. See docs here: https://learn.microsoft.com/en-us/rest/api/postgresqlhsc/ Just in case: The above REST APIs page is linked in the main Azure Cosmos DB for PostgreSQL documentation. If you open 'Reference' section on the left-hand side, you'd see it there.

REST APIs in the docs
GustavoOS commented 7 months ago

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.

@GustavoOS You're right, there's no way to provision a free trial of Azure Cosmos DB for PostgreSQL programmatically. Pardon possible confusion. The Azure Cosmos DB for PostgreSQL free trial can be started only via this page: https://cosmos.azure.com/try/

Once provisioned you can do all management operations using Azure Cosmos DB for PostgreSQL REST APIs. See docs here: https://learn.microsoft.com/en-us/rest/api/postgresqlhsc/ Just in case: The above REST APIs page is linked in the main Azure Cosmos DB for PostgreSQL documentation. If you open 'Reference' section on the left-hand side, you'd see it there.

REST APIs in the docs

Thanks for the reply The link you sent is a 30 day offer, not the permanent free tier offer that is shown on the free tier page image

So is this lack of free tier creation intetional? if it is, I think it should be better described in the docs.

niklarin commented 7 months ago

@GustavoOS Azure Cosmos DB for PostgreSQL is not part of the Azure Free Tier offering.