Describe graceful deletion in more detail

pkg/api/types.go

@@ -114,15 +114,23 @@ type ObjectMeta struct {
 	// +optional
 	CreationTimestamp unversioned.Time `json:"creationTimestamp,omitempty"`
 
-	// DeletionTimestamp is the time after which this resource will be deleted. This
+	// DeletionTimestamp is RFC 3339 date and time at which this resource will be deleted. This
 	// field is set by the server when a graceful deletion is requested by the user, and is not
-	// directly settable by a client. The resource will be deleted (no longer visible from
+	// directly settable by a client. The resource is expected to be deleted (no longer visible
-	// resource lists, and not reachable by name) after the time in this field. Once set, this
+	// from resource lists, and not reachable by name) after the time in this field. Once set,
-	// value may not be unset or be set further into the future, although it may be shortened
+	// this value may not be unset or be set further into the future, although it may be shortened
 	// or the resource may be deleted prior to this time. For example, a user may request that
 	// a pod is deleted in 30 seconds. The Kubelet will react by sending a graceful termination
-	// signal to the containers in the pod. Once the resource is deleted in the API, the Kubelet
+	// signal to the containers in the pod. After that 30 seconds, the Kubelet will send a hard
-	// will send a hard termination signal to the container.
+	// termination signal (SIGKILL) to the container and after cleanup, remove the pod from the
+	// API. In the presence of network partitions, this object may still exist after this
+	// timestamp, until an administrator or automated process can determine the resource is
+	// fully terminated.
+	// If not set, graceful deletion of the object has not been requested.
+	//
+	// Populated by the system when a graceful deletion is requested.
+	// Read-only.
+	// More info: http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#metadata
 	// +optional
 	DeletionTimestamp *unversioned.Time `json:"deletionTimestamp,omitempty"`
 

pkg/api/v1/types.go

@@ -151,13 +151,16 @@ type ObjectMeta struct {
 
 	// DeletionTimestamp is RFC 3339 date and time at which this resource will be deleted. This
 	// field is set by the server when a graceful deletion is requested by the user, and is not
-	// directly settable by a client. The resource will be deleted (no longer visible from
+	// directly settable by a client. The resource is expected to be deleted (no longer visible
-	// resource lists, and not reachable by name) after the time in this field. Once set, this
+	// from resource lists, and not reachable by name) after the time in this field. Once set,
-	// value may not be unset or be set further into the future, although it may be shortened
+	// this value may not be unset or be set further into the future, although it may be shortened
 	// or the resource may be deleted prior to this time. For example, a user may request that
 	// a pod is deleted in 30 seconds. The Kubelet will react by sending a graceful termination
-	// signal to the containers in the pod. Once the resource is deleted in the API, the Kubelet
+	// signal to the containers in the pod. After that 30 seconds, the Kubelet will send a hard
-	// will send a hard termination signal to the container.
+	// termination signal (SIGKILL) to the container and after cleanup, remove the pod from the
+	// API. In the presence of network partitions, this object may still exist after this
+	// timestamp, until an administrator or automated process can determine the resource is
+	// fully terminated.
 	// If not set, graceful deletion of the object has not been requested.
 	//
 	// Populated by the system when a graceful deletion is requested.