From ae1fa536d09156ecfe814e5127cc7cce01586a49 Mon Sep 17 00:00:00 2001 From: Oliver Gould Date: Thu, 8 Sep 2022 08:41:22 -0700 Subject: [PATCH 1/3] Fix in-cluster API discovery documentation The documentation incorrectly describes the way that client libraries discover the Kubernetes API server. While the `kubernetes.default.svc` DNS is provided as a convenience, **all** of the officially supported API clients use environment variables to discover the address of the API server. This change updates the documentation to reflect this. Signed-off-by: Oliver Gould --- .../en/docs/tasks/run-application/access-api-from-pod.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/content/en/docs/tasks/run-application/access-api-from-pod.md b/content/en/docs/tasks/run-application/access-api-from-pod.md index d56f624cd561b..3ea855afe4df2 100644 --- a/content/en/docs/tasks/run-application/access-api-from-pod.md +++ b/content/en/docs/tasks/run-application/access-api-from-pod.md @@ -42,10 +42,11 @@ securely with the API server. ### Directly accessing the REST API -While running in a Pod, the Kubernetes apiserver is accessible via a Service named -`kubernetes` in the `default` namespace. Therefore, Pods can use the -`kubernetes.default.svc` hostname to query the API server. Official client libraries -do this automatically. +While running in a Pod, the Kubernetes API server is referenced by the environment +variables `KUBERNETES_SERVICE_HOST` and `KUBERNETES_SERVICE_PORT`. As a convenience, +the API server may also be referenced via a Service named `kubernetes` in the `default` +namespace. Therefore, Pods can use the `kubernetes.default.svc` hostname to query the +API server. The recommended way to authenticate to the API server is with a [service account](/docs/tasks/configure-pod-container/configure-service-account/) From ee12363239568b97ef13766a6e39b6c6b4374cf2 Mon Sep 17 00:00:00 2001 From: Oliver Gould Date: Tue, 20 Sep 2022 13:30:19 -0700 Subject: [PATCH 2/3] Review feedback --- .../tasks/run-application/access-api-from-pod.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/content/en/docs/tasks/run-application/access-api-from-pod.md b/content/en/docs/tasks/run-application/access-api-from-pod.md index 3ea855afe4df2..0467e4aea8a95 100644 --- a/content/en/docs/tasks/run-application/access-api-from-pod.md +++ b/content/en/docs/tasks/run-application/access-api-from-pod.md @@ -42,12 +42,24 @@ securely with the API server. ### Directly accessing the REST API -While running in a Pod, the Kubernetes API server is referenced by the environment -variables `KUBERNETES_SERVICE_HOST` and `KUBERNETES_SERVICE_PORT`. As a convenience, +While running in a Pod, your container can create an HTTPS URL for the Kubernetes API +server by fetching the `KUBERNETES_SERVICE_HOST` and `KUBERNETES_SERVICE_PORT_HTTPS` +environment variables. As a convenience, the API server may also be referenced via a Service named `kubernetes` in the `default` namespace. Therefore, Pods can use the `kubernetes.default.svc` hostname to query the API server. +The API server's in-cluster address is published to a Service named `kubernetes` in +the `default` namespace. This means that pods may reference `kubernetes.default.svc` +as a DNS name for the local API server. + +{{< note >}} +Kubernetes does not guarantee that the API server has a valid certificate for +the hostname `kubernetes.default.svc`; +however, the control plane **is** expected to present a valid certificate for the +hostname or IP address that `$KUBERNETES_SERVICE_HOST` represents. +{{< /note >}} + The recommended way to authenticate to the API server is with a [service account](/docs/tasks/configure-pod-container/configure-service-account/) credential. By default, a Pod From e4c29016bd29516b2babf9c565d01df1262f0415 Mon Sep 17 00:00:00 2001 From: Oliver Gould Date: Tue, 20 Sep 2022 13:32:01 -0700 Subject: [PATCH 3/3] Fixup --- .../docs/tasks/run-application/access-api-from-pod.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/content/en/docs/tasks/run-application/access-api-from-pod.md b/content/en/docs/tasks/run-application/access-api-from-pod.md index 0467e4aea8a95..41d6ea478e579 100644 --- a/content/en/docs/tasks/run-application/access-api-from-pod.md +++ b/content/en/docs/tasks/run-application/access-api-from-pod.md @@ -44,14 +44,9 @@ securely with the API server. While running in a Pod, your container can create an HTTPS URL for the Kubernetes API server by fetching the `KUBERNETES_SERVICE_HOST` and `KUBERNETES_SERVICE_PORT_HTTPS` -environment variables. As a convenience, -the API server may also be referenced via a Service named `kubernetes` in the `default` -namespace. Therefore, Pods can use the `kubernetes.default.svc` hostname to query the -API server. - -The API server's in-cluster address is published to a Service named `kubernetes` in -the `default` namespace. This means that pods may reference `kubernetes.default.svc` -as a DNS name for the local API server. +environment variables. The API server's in-cluster address is also published to a +Service named `kubernetes` in the `default` namespace so that pods may reference +`kubernetes.default.svc` as a DNS name for the local API server. {{< note >}} Kubernetes does not guarantee that the API server has a valid certificate for