From ede985dccd861299494a95e15049b467eef3e2d1 Mon Sep 17 00:00:00 2001 From: Lee Verberne Date: Fri, 14 May 2021 14:49:41 +0200 Subject: [PATCH] Update website for 1.22 ephemeral containers API This removes the description of the ephemeral containers API from the concepts section of the website. Most (all?) concepts don't have a detailed description of their API in concepts. We added it for the initial release of ephemeral containers because using the raw API was the only way to add an ephemeral container. This description of the API is no longer correct. Since it's now easy to add an ephemeral container using `kubectl debug`, and this is too much detail for a concepts section, we should remove the API description entirely. --- .../workloads/pods/ephemeral-containers.md | 120 +----------------- .../debug-running-pod.md | 11 +- 2 files changed, 9 insertions(+), 122 deletions(-) diff --git a/content/en/docs/concepts/workloads/pods/ephemeral-containers.md b/content/en/docs/concepts/workloads/pods/ephemeral-containers.md index 011fa4adf4..c26a63b183 100644 --- a/content/en/docs/concepts/workloads/pods/ephemeral-containers.md +++ b/content/en/docs/concepts/workloads/pods/ephemeral-containers.md @@ -9,7 +9,7 @@ weight: 80 -{{< feature-state state="alpha" for_k8s_version="v1.16" >}} +{{< feature-state state="alpha" for_k8s_version="v1.22" >}} This page provides an overview of ephemeral containers: a special type of container that runs temporarily in an existing {{< glossary_tooltip term_id="pod" >}} to @@ -17,7 +17,7 @@ accomplish user-initiated actions such as troubleshooting. You use ephemeral containers to inspect services rather than to build applications. {{< warning >}} -Ephemeral containers are in early alpha state and are not suitable for production +Ephemeral containers are in alpha state and are not suitable for production clusters. In accordance with the [Kubernetes Deprecation Policy]( /docs/reference/using-api/deprecation-policy/), this alpha feature could change significantly in the future or be removed entirely. @@ -77,119 +77,7 @@ When using ephemeral containers, it's helpful to enable [process namespace sharing](/docs/tasks/configure-pod-container/share-process-namespace/) so you can view processes in other containers. -See [Debugging with Ephemeral Debug Container]( -/docs/tasks/debug-application-cluster/debug-running-pod/#ephemeral-container) -for examples of troubleshooting using ephemeral containers. - -## Ephemeral containers API - -{{< note >}} -The examples in this section require the `EphemeralContainers` [feature -gate](/docs/reference/command-line-tools-reference/feature-gates/) to be -enabled, and Kubernetes client and server version v1.16 or later. -{{< /note >}} - -The examples in this section demonstrate how ephemeral containers appear in -the API. You would normally use `kubectl debug` or another `kubectl` -[plugin](/docs/tasks/extend-kubectl/kubectl-plugins/) to automate these steps -rather than invoking the API directly. - -Ephemeral containers are created using the `ephemeralcontainers` subresource -of Pod, which can be demonstrated using `kubectl --raw`. First describe -the ephemeral container to add as an `EphemeralContainers` list: - -```json -{ - "apiVersion": "v1", - "kind": "EphemeralContainers", - "metadata": { - "name": "example-pod" - }, - "ephemeralContainers": [{ - "command": [ - "sh" - ], - "image": "busybox", - "imagePullPolicy": "IfNotPresent", - "name": "debugger", - "stdin": true, - "tty": true, - "terminationMessagePolicy": "File" - }] -} -``` - -To update the ephemeral containers of the already running `example-pod`: - -```shell -kubectl replace --raw /api/v1/namespaces/default/pods/example-pod/ephemeralcontainers -f ec.json -``` - -This will return the new list of ephemeral containers: - -```json -{ - "kind":"EphemeralContainers", - "apiVersion":"v1", - "metadata":{ - "name":"example-pod", - "namespace":"default", - "selfLink":"/api/v1/namespaces/default/pods/example-pod/ephemeralcontainers", - "uid":"a14a6d9b-62f2-4119-9d8e-e2ed6bc3a47c", - "resourceVersion":"15886", - "creationTimestamp":"2019-08-29T06:41:42Z" - }, - "ephemeralContainers":[ - { - "name":"debugger", - "image":"busybox", - "command":[ - "sh" - ], - "resources":{ - - }, - "terminationMessagePolicy":"File", - "imagePullPolicy":"IfNotPresent", - "stdin":true, - "tty":true - } - ] -} -``` - -You can view the state of the newly created ephemeral container using `kubectl describe`: - -```shell -kubectl describe pod example-pod -``` - -``` -... -Ephemeral Containers: - debugger: - Container ID: docker://cf81908f149e7e9213d3c3644eda55c72efaff67652a2685c1146f0ce151e80f - Image: busybox - Image ID: docker-pullable://busybox@sha256:9f1003c480699be56815db0f8146ad2e22efea85129b5b5983d0e0fb52d9ab70 - Port: - Host Port: - Command: - sh - State: Running - Started: Thu, 29 Aug 2019 06:42:21 +0000 - Ready: False - Restart Count: 0 - Environment: - Mounts: -... -``` - -You can interact with the new ephemeral container in the same way as other -containers using `kubectl attach`, `kubectl exec`, and `kubectl logs`, for -example: - -```shell -kubectl attach -it example-pod -c debugger -``` +## {{% heading "whatsnext" %}} +* Learn how to [debug pods using ephemeral containers](/docs/tasks/debug-application-cluster/debug-running-pod/#ephemeral-container). diff --git a/content/en/docs/tasks/debug-application-cluster/debug-running-pod.md b/content/en/docs/tasks/debug-application-cluster/debug-running-pod.md index 59a83e87c7..6009a76341 100644 --- a/content/en/docs/tasks/debug-application-cluster/debug-running-pod.md +++ b/content/en/docs/tasks/debug-application-cluster/debug-running-pod.md @@ -73,22 +73,20 @@ For more details, see [Get a Shell to a Running Container]( ## Debugging with an ephemeral debug container {#ephemeral-container} -{{< feature-state state="alpha" for_k8s_version="v1.18" >}} +{{< feature-state state="alpha" for_k8s_version="v1.22" >}} {{< glossary_tooltip text="Ephemeral containers" term_id="ephemeral-container" >}} are useful for interactive troubleshooting when `kubectl exec` is insufficient because a container has crashed or a container image doesn't include debugging utilities, such as with [distroless images]( -https://github.com/GoogleContainerTools/distroless). `kubectl` has an alpha -command that can create ephemeral containers for debugging beginning with version -`v1.18`. +https://github.com/GoogleContainerTools/distroless). ### Example debugging using ephemeral containers {#ephemeral-container-example} {{< note >}} The examples in this section require the `EphemeralContainers` [feature gate]( /docs/reference/command-line-tools-reference/feature-gates/) enabled in your -cluster and `kubectl` version v1.18 or later. +cluster and `kubectl` version v1.22 or later. {{< /note >}} You can use the `kubectl debug` command to add ephemeral containers to a @@ -137,7 +135,8 @@ creates. The `--target` parameter must be supported by the {{< glossary_tooltip text="Container Runtime" term_id="container-runtime" >}}. When not supported, the Ephemeral Container may not be started, or it may be started with an -isolated process namespace. +isolated process namespace so that `ps` does not reveal processes in other +containers. {{< /note >}} You can view the state of the newly created ephemeral container using `kubectl describe`: