Azure / Azure/azure-cli-extensions
az aks pod-identity commands need better documentation
- Dominant language
- Python
- Stars
- 454
- Forks
- 1.7k
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 64
Description
### Extension name (the extension in question)
`az aks`
### Description of issue (in as much detail as possible)
The documentation included in `az aks pod-identity --help` and also located [here](https://docs.microsoft.com/en-us/cli/azure/ext/aks-preview/aks/pod-identity?view=azure-cli-latest) is very bare.
It doesn't refer to existing documentation such as [this](https://docs.microsoft.com/en-us/azure/aks/use-azure-ad-pod-identity).
It doesn't explain `az aks pod-identity`'s relationship to [aad-pod-identity](https://github.com/Azure/aad-pod-identity). I think that creating a pod identity via `az aks pod-identity` is basically equal to creating an `aadpodidentity` and `aadpodidentitybinding` with the same name (and a selector that matches that name), but it's not clear that's the case. Even the documentation [here](https://docs.microsoft.com/en-us/azure/aks/use-azure-ad-pod-identity) talks about `AzureIdentityBinding` in the section on `Run a sample application`, but it's totally unclear (at least to me) where that `AzureIdentityBinding` came from given that you never created one or talked about it prior to its reference in running a sample application. It is unclear from the provided documentation given an identity name how to actually have a pod bind to that identity.
The same comments also apply to `pod-identity exceptions`. Looking at the documents [here](https://docs.microsoft.com/en-us/cli/azure/ext/aks-preview/aks/pod-identity/exception?view=azure-cli-latest#ext_aks_preview_az_aks_pod_identity_exception_add) (and in the `--help`) there is no explanation of what an `exception` is or why I might want one. `az aks pod-identity exception add` just says `Add a pod identity exception to a managed Kubernetes cluster.`
A more helpful document would be something like: `Adds a pod identity exception to a managed Kubernetes cluster. The exception applies only to pods matching the specified labels. For more details about exceptions and their usage see **this link**`
Contributor guide
Assessment
This issue has not been assessed yet.