Improve API documentation for ephemeral containers

pkg/apis/core/types.go

@@ -2591,12 +2591,10 @@ type PodSpec struct {
 	InitContainers []Container
 	// List of containers belonging to the pod.
 	Containers []Container
-	// EphemeralContainers is the list of ephemeral containers that run in this pod. Ephemeral containers
+	// List of ephemeral containers run in this pod. Ephemeral containers may be run in an existing
-	// are added to an existing pod as a result of a user-initiated action such as troubleshooting.
+	// pod to perform user-initiated actions such as debugging. This list cannot be specified when
-	// This list is read-only in the pod spec. It may not be specified in a create or modified in an
+	// creating a pod, and it cannot be modified by updating the pod spec. In order to add an
-	// update of a pod or pod template.
+	// ephemeral container to an existing pod, use the pod's ephemeralcontainers subresource.
-	// To add an ephemeral container use the pod's ephemeralcontainers subresource, which allows update
-	// using the EphemeralContainers kind.
 	// This field is alpha-level and is only honored by servers that enable the EphemeralContainers feature.
 	// +optional
 	EphemeralContainers []EphemeralContainer
@@ -2882,6 +2880,10 @@ type PodIP struct {
 	IP string
 }
 
+// EphemeralContainerCommon is a copy of all fields in Container to be inlined in
+// EphemeralContainer. This separate type allows easy conversion from EphemeralContainer
+// to Container and allows separate documentation for the fields of EphemeralContainer.
+// When a new field is added to Container it must be added here as well.
 type EphemeralContainerCommon struct {
 	// Required: This must be a DNS_LABEL.  Each container in a pod must
 	// have a unique name.
@@ -2962,16 +2964,20 @@ type EphemeralContainerCommon struct {
 // these two types.
 var _ = Container(EphemeralContainerCommon{})
 
-// An EphemeralContainer is a special type of container which doesn't come with any resource
+// An EphemeralContainer is a temporary container that may be added to an existing pod for
-// or scheduling guarantees but can be added to a pod that has already been created. They are
+// user-initiated activities such as debugging. Ephemeral containers have no resource or
-// intended for user-initiated activities such as troubleshooting a running pod.
+// scheduling guarantees, and they will not be restarted when they exit or when a pod is
-// Ephemeral containers will not be restarted when they exit, and they will be killed if the
+// removed or restarted. If an ephemeral container causes a pod to exceed its resource
-// pod is removed or restarted. If an ephemeral container causes a pod to exceed its resource
 // allocation, the pod may be evicted.
-// Ephemeral containers are added via a pod's ephemeralcontainers subresource and will appear
+// Ephemeral containers may not be added by directly updating the pod spec. They must be added
-// in the pod spec once added.
+// via the pod's ephemeralcontainers subresource, and they will appear in the pod spec
+// once added.
 // This is an alpha feature enabled by the EphemeralContainers feature flag.
 type EphemeralContainer struct {
+	// Ephemeral containers have all of the fields of Container, plus additional fields
+	// specific to ephemeral containers. Fields in common with Container are in the
+	// following inlined struct so than an EphemeralContainer may easily be converted
+	// to a Container.
 	EphemeralContainerCommon
 
 	// If set, the name of the container from PodSpec that this ephemeral container targets.
@@ -3030,7 +3036,7 @@ type PodStatus struct {
 	// +optional
 	ContainerStatuses []ContainerStatus
 
-	// Status for any ephemeral containers that running in this pod.
+	// Status for any ephemeral containers that have run in this pod.
 	// This field is alpha-level and is only honored by servers that enable the EphemeralContainers feature.
 	// +optional
 	EphemeralContainerStatuses []ContainerStatus
@@ -4042,13 +4048,15 @@ type Binding struct {
 
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
-// A list of ephemeral containers used in API operations
+// A list of ephemeral containers used with the Pod ephemeralcontainers subresource.
 type EphemeralContainers struct {
 	metav1.TypeMeta
 	// +optional
 	metav1.ObjectMeta
 
-	// The new set of ephemeral containers to use for a pod.
+	// A list of ephemeral containers associated with this pod. New ephemeral containers
+	// may be appended to this list, but existing ephemeral containers may not be removed
+	// or modified.
 	EphemeralContainers []EphemeralContainer
 }
 

staging/src/k8s.io/api/core/v1/types.go

@@ -2843,12 +2843,10 @@ type PodSpec struct {
 	// +patchMergeKey=name
 	// +patchStrategy=merge
 	Containers []Container `json:"containers" patchStrategy:"merge" patchMergeKey:"name" protobuf:"bytes,2,rep,name=containers"`
-	// EphemeralContainers is the list of ephemeral containers that run in this pod. Ephemeral containers
+	// List of ephemeral containers run in this pod. Ephemeral containers may be run in an existing
-	// are added to an existing pod as a result of a user-initiated action such as troubleshooting.
+	// pod to perform user-initiated actions such as debugging. This list cannot be specified when
-	// This list is read-only in the pod spec. It may not be specified in a create or modified in an
+	// creating a pod, and it cannot be modified by updating the pod spec. In order to add an
-	// update of a pod or pod template.
+	// ephemeral container to an existing pod, use the pod's ephemeralcontainers subresource.
-	// To add an ephemeral container use the pod's ephemeralcontainers subresource, which allows update
-	// using the EphemeralContainers kind.
 	// This field is alpha-level and is only honored by servers that enable the EphemeralContainers feature.
 	// +optional
 	// +patchMergeKey=name
@@ -3220,6 +3218,10 @@ type PodIP struct {
 	IP string `json:"ip,omitempty" protobuf:"bytes,1,opt,name=ip"`
 }
 
+// EphemeralContainerCommon is a copy of all fields in Container to be inlined in
+// EphemeralContainer. This separate type allows easy conversion from EphemeralContainer
+// to Container and allows separate documentation for the fields of EphemeralContainer.
+// When a new field is added to Container it must be added here as well.
 type EphemeralContainerCommon struct {
 	// Name of the ephemeral container specified as a DNS_LABEL.
 	// This name must be unique among all containers, init containers and ephemeral containers.
@@ -3350,16 +3352,20 @@ type EphemeralContainerCommon struct {
 // these two types.
 var _ = Container(EphemeralContainerCommon{})
 
-// An EphemeralContainer is a special type of container which doesn't come with any resource
+// An EphemeralContainer is a container that may be added temporarily to an existing pod for
-// or scheduling guarantees but can be added to a pod that has already been created. They are
+// user-initiated activities such as debugging. Ephemeral containers have no resource or
-// intended for user-initiated activities such as troubleshooting a running pod.
+// scheduling guarantees, and they will not be restarted when they exit or when a pod is
-// Ephemeral containers will not be restarted when they exit, and they will be killed if the
+// removed or restarted. If an ephemeral container causes a pod to exceed its resource
-// pod is removed or restarted. If an ephemeral container causes a pod to exceed its resource
 // allocation, the pod may be evicted.
-// Ephemeral containers are added via a pod's ephemeralcontainers subresource and will appear
+// Ephemeral containers may not be added by directly updating the pod spec. They must be added
-// in the pod spec once added. No fields in EphemeralContainer may be changed once added.
+// via the pod's ephemeralcontainers subresource, and they will appear in the pod spec
+// once added.
 // This is an alpha feature enabled by the EphemeralContainers feature flag.
 type EphemeralContainer struct {
+	// Ephemeral containers have all of the fields of Container, plus additional fields
+	// specific to ephemeral containers. Fields in common with Container are in the
+	// following inlined struct so than an EphemeralContainer may easily be converted
+	// to a Container.
 	EphemeralContainerCommon `json:",inline" protobuf:"bytes,1,req"`
 
 	// If set, the name of the container from PodSpec that this ephemeral container targets.
@@ -3454,8 +3460,8 @@ type PodStatus struct {
 	// More info: https://git.k8s.io/community/contributors/design-proposals/node/resource-qos.md
 	// +optional
 	QOSClass PodQOSClass `json:"qosClass,omitempty" protobuf:"bytes,9,rep,name=qosClass"`
-	// Status for any ephemeral containers that running in this pod.
+	// Status for any ephemeral containers that have run in this pod.
-	// This field is alpha-level and is only honored by servers that enable the EphemeralContainers feature.
+	// This field is alpha-level and is only populated by servers that enable the EphemeralContainers feature.
 	// +optional
 	EphemeralContainerStatuses []ContainerStatus `json:"ephemeralContainerStatuses,omitempty" protobuf:"bytes,13,rep,name=ephemeralContainerStatuses"`
 }
@@ -4665,13 +4671,15 @@ type Binding struct {
 
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
-// A list of ephemeral containers used in API operations
+// A list of ephemeral containers used with the Pod ephemeralcontainers subresource.
 type EphemeralContainers struct {
 	metav1.TypeMeta `json:",inline"`
 	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
 
-	// The new set of ephemeral containers to use for a pod.
+	// A list of ephemeral containers associated with this pod. New ephemeral containers
+	// may be appended to this list, but existing ephemeral containers may not be removed
+	// or modified.
 	// +patchMergeKey=name
 	// +patchStrategy=merge
 	EphemeralContainers []EphemeralContainer `json:"ephemeralContainers" patchStrategy:"merge" patchMergeKey:"name" protobuf:"bytes,2,rep,name=ephemeralContainers"`