search

Azure / kubernetes-keyvault-flexvol

Azure keyvault integration with Kubernetes via a Flex Volume
MIT License
253 stars 83 forks source link

Proposed documentation updates #148

Open lee0c opened 4 years ago

lee0c commented 4 years ago

Describe the request

Current documentation (primarily the main README file) is unclear in places and uses poor examples. Proposed changes (I am happy to make these if y'all OK any/all of them) in solution field.

Explain why Key Vault FlexVolume needs it

Current docs are confusing and misleading to users, especially users who are less familiar with YAML & Kubernetes ecosystem cooncepts.

Describe the solution you'd like

  1. In the Contents, split "Getting started" into "Installing" and "Using" (and, optionally, "YAML Specification") - otherwise users jump immediately to "Detailed use cases" which are very specific.
  2. Pull out specification details (YAML fields, the table nested under this use case) into a separate section on specifications rather than nested under individual setup options. Keep spec details specific to each implementation option listed as steps in that implementation option as well.
  3. Provide more descriptive examples. The current example in the main README lacks clarity, especially around the keyvaultobjectaliases field - "secrets.json" can lead users to think that the aliases are stored in a file called "secrets.json".
  4. Fix broken links for VMSS MSI implementations in first line of Using KeyVault FlexVol section.
  5. Generally update language to align with all options offered - some language is still indicative of SPN versus Pod Identity being the only available implementation options.

Happy to make these updates if y'all want, will add in other tweaks if there are suggestions.

Describe alternatives you've considered

N/a as it is a docs change

Additional context

None.

stewartadam commented 4 years ago

It should also be noted in the docs that spaces must not be present after semicolon-separated values in the config values or else parsing errors occur (I would add that the errors are extremely unclear/unrelated to the root cause when this happens - for example it will complain that a config key like 'tenantid' or 'resourcegroup' provided is empty, when it is not)

namoshizun commented 4 years ago

+1. This is a very useful add-on but unfortunately the documentation is just not so comprehensible...