Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve "authenticating to k8s api from a pod" docs #6259

Merged
merged 2 commits into from
Nov 14, 2017
Merged

Improve "authenticating to k8s api from a pod" docs #6259

merged 2 commits into from
Nov 14, 2017

Conversation

ahmetb
Copy link
Member

@ahmetb ahmetb commented Nov 9, 2017

Helps with kubernetes/kubernetes#22121.
Also removing the link to kubectl-container example which is staged for removal.


This change is Reviewable

@k8s-ci-robot k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Nov 9, 2017
@k8sio-netlify-preview-bot
Copy link
Collaborator

k8sio-netlify-preview-bot commented Nov 9, 2017

Deploy preview ready!

Built with commit 5fc5733

https://deploy-preview-6259--kubernetes-io-master-staging.netlify.com

Copy link

@clhodapp clhodapp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This definitely clarifies that client libraries are preferred much better.

I personally still strongly believe that the release process should be amended to produce a kubectl container image if kubectl proxy is going to remain as the recommended way to talk to the API from pods for languages without an official client, but I don't think that should get in the way of making this change.

@ahmetb
Copy link
Member Author

ahmetb commented Nov 9, 2017

@clhodapp I have a discussion about it at https://groups.google.com/d/msg/kubernetes-sig-cli/yUkt_ZkAAY0/WQ3NVRLyCwAJ feel free to participate if you support the idea we should have a kubectl-only image.

@chenopis
Copy link
Contributor

chenopis commented Nov 9, 2017

@ahmetb FYI, the Travis CI error has been fixed. Please rebase or update your branch. Thx!

@ahmetb
Copy link
Member Author

ahmetb commented Nov 10, 2017

Rebased.

- use the Go client library, and create a client using the `rest.InClusterConfig()` and `kubernetes.NewForConfig()` functions.
They handle locating and authenticating to the apiserver. [example](https://git.k8s.io/client-go/examples/in-cluster-client-configuration/main.go)
- if you would like to query the API without an official client library, you can run `kubectl proxy`
as one of the containers in the pod (i.e. sidecar container), or as a background process within a container.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

as one

in one

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or:

 as the [command](/docs/tasks/inject-data-application/define-command-argument-container/) for a container
``

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

actually rephrasing this to remove "background process" recommendation and just saying sidecar proxy with kubectl proxy as the command.

Helps with kubernetes/kubernetes#22121.

Also removing kubectl-container example as it's staged for removal and not
very useful.

Signed-off-by: Ahmet Alp Balkan <ahmetb@google.com>
will be routed to an apiserver.
The easiest way to use the Kubernetes API from a Pod is to use
one of the official [client libraries](/docs/reference/client-libraries/). These
libraries can automatically discover the apiserver and authenticate automatically.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think you need the second "automatically".
... can automatically discover the API server and authenticate.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

The recommended way to authenticate to the apiserver is with a
[service account](/docs/user-guide/service-accounts) credential. By kube-system, a pod
While running in a Pod, the Kubernetes apiserver is accessible via a Service named
`kubernetes` in the `default` namespace. Therefore, Pods can use the
Copy link
Contributor

@steveperry-53 steveperry-53 Nov 14, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the apiserver -> the API server (several instances)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We currently don't have guidance on what it should be, hence my confusion.
https://www.google.com/search?q=site%3Akubernetes.io+"apiserver"&oq=site%3Akubernetes.io+"apiserver"
apiserver is indeed a Kubernetes term and it refers to the kube-apiserver component, but in this case I think we're trying to say "the API server"

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

as the [command](/docs/tasks/inject-data-application/define-command-argument-container/)
of a new sidecar container in the Pod. This way, `kubectl proxy` will authenticate
to the API and expose it on the `localhost` interface of the Pod, so that other containers
in the Pod can use it directly.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Start bullet items with caps.

  • Use one ...
  • If you would like ...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done


- use one of the official [client libraries](/docs/reference/client-libraries/)
as they handle API host discovery and authentication out of the box.
For Go client, the `rest.InClusterConfig()` function assists with this.
Copy link
Contributor

@steveperry-53 steveperry-53 Nov 14, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

out of the box -> automatically
For Go client -> For the Go client

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Signed-off-by: Ahmet Alp Balkan <ahmetb@google.com>
@steveperry-53
Copy link
Contributor

@ahmetb Are you ready for me to merge this?

@ahmetb ahmetb merged commit 30ea773 into kubernetes:master Nov 14, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/M Denotes a PR that changes 30-99 lines, ignoring generated files.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants