Clarify behaviour of kubernetes_users role field in docs

[strideynet]

Applies To

https://goteleport.com/docs/kubernetes-access/getting-started/#kubernetes-authentication

Kubernetes docs in general.

Details

The behaviour of the allow.kubernetes_users role field is quite complex, and we don't do a good job of describing its behaviour anywhere in the documentation.

From my brief exploration:

• When it is unset or empty, the username of the user is used for impersonation when making requests to the kube apiserver.
• When it is set with one entry, that value is impersonated when making requests to the kube apiserver.
• When it is set with multiple entries, the client MUST specify which value it wishes to impersonate. The value they wish to impersonate must be included within the kubernetes_user set. Specifying this is done with the --as when using kubectl. Failure of the client to specify a user it wishes to impersonate will lead to an error rather than a successful request.

Suggested fixes

Remove mention of kubernetes_users from Getting Started

As far as I can tell, this value in the getting started documentation not necessary. If nothing is configured here, then the user's username will be used for impersonation, which is a sane default.

I would go as far as to suggest that the current value we suggest users set is actually harmful. In my case:

➜  teleport-actions git:(strideynet/k8s-auth-helper) ✗ kubectl config view \        
-o jsonpath="{.contexts[?(@.name==\"$(kubectl config current-context)\")].context.user}"
root.tele.ottr.sh-docker-desktop%  

The docs would have me set the user to "root.tele.ottr.sh-docker-desktop" - which is certainly far less descriptive and useful than "noahstride".

Include an explicit section in the FAQs of Kubernetes Access on kubernetes_users

I think we need to not only capture the behaviour of this field, but also why it is useful and in what circumstances you should want to use it.

[strideynet]

It appears this PR introduced this field and provides some additional context: #3404

[ptgott]

Hi @strideynet, since this issue was opened, we added some more explanation of how the Kubernetes Service processes Teleport roles: https://goteleport.com/docs/kubernetes-access/controls/

Does this take care of this issue? Thanks!

[strideynet]

@ptgott

https://goteleport.com/docs/kubernetes-access/controls/

This explanation is a significant improvement, it captures my understanding of the topic well.

---

I think my concerns re: https://goteleport.com/docs/kubernetes-access/getting-started/#kubernetes-authentication are still valid.

We instruct users to run the following command:

kubectl config view \
-o jsonpath="{.contexts[?(@.name==\"$(kubectl config current-context)\")].context.user}"

The output of this command returns the Teleport cluster name and the name of the Kubernetes cluster in Teleport concatenated:

noah.teleport.sh-example-cluster

We then instruct the user to insert this value into the spec.allow.kubernetes_users field of the Role they need to create.

This doesn't make any sense to me at all. It's causing all Kubernetes requests made by that user to be impersonated as noah.teleport.sh-example-cluster - which completes obscures which user is running an action in Kubernetes internal logs (as opposed to Teleport's logs).

Unless someone more familiar with this chimes in to correct me, I recommend dropping the kubectl config view... step from the docs and dropping the spec.allow.kubernetes_users from the example Role we instruct the user to create. If this field is not provided, then Teleport acts in a sane way by default and uses the Teleport user's username.