Azure / Azure/azure-cli-extensions

az aks pod-identity commands need better documentation

Open
#3,013 3 comments 0 reactions 0 assignees View on GitHub
AKS Service Attention
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.