Try Kubernetes

Concepts

Detailed explanations of Kubernetes system concepts and abstractions.

Documentation for Kubernetes v1.5 is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.

Edit This Page

Garbage Collection

The role of the Kubernetes garbage collector is to delete certain objects that once had an owner, but no longer have an owner.

Note: Garbage collection is a beta feature and is enabled by default in Kubernetes version 1.4 and later.

Owners and dependents

Some Kubernetes objects are owners of other objects. For example, a ReplicaSet is the owner of a set of Pods. The owned objects are called dependents of the owner object. Every dependent object has a metadata.ownerReferences field that points to the owning object.

Sometimes, Kubernetes sets the value of ownerReference automatically. For example, when you create a ReplicaSet, Kubernetes automatically sets the ownerReference field of each Pod in the ReplicaSet. You can also specify relationships between owners and dependents by manually setting the ownerReference field.

Here’s a configuration file for a ReplicaSet that has three Pods:

my-repset.yaml 
apiVersion: extensions/v1beta1
kind: ReplicaSet
metadata:
  name: my-repset
spec:
  replicas: 3
  selector:
    matchLabels:
      pod-is-for: garbage-collection-example
  template:
    metadata:
      labels:
        pod-is-for: garbage-collection-example
    spec:
      containers:
      - name: nginx
        image: nginx

If you create the ReplicaSet and then view the Pod metadata, you can see OwnerReferences field:

kubectl create -f http://k8s.io/docs/concepts/abstractions/controllers/my-repset.yaml
kubectl get pods --output=yaml

The output shows that the Pod owner is a ReplicaSet named my-repset:

apiVersion: v1
kind: Pod
metadata:
  ...
  ownerReferences:
  - apiVersion: extensions/v1beta1
    controller: true
    kind: ReplicaSet
    name: my-repset
    uid: d9607e19-f88f-11e6-a518-42010a800195
  ...

Controlling whether the garbage collector deletes dependents

When you delete object, you can specify whether the object’s dependents are deleted automatically. Deleting dependents automatically is called cascading deletion. If you delete an object without deleting its dependents automatically, the dependents are said to be orphaned.

To delete dependent objects automatically, set the orphanDependents query parameter to false in your request to delete the owner object.

To orphan the dependents of an owner object, set the orphanDependents query parameter to true in your request to delete the owner object.

The default value for orphanDependents is true. So unless you specify otherwise, dependent objects are orphaned.

Here’s an example that deletes dependents automatically:

kubectl proxy --port=8080
curl -X DELETE localhost:8080/apis/extensions/v1beta1/namespaces/default/replicasets/my-repset?orphanDependents=false

To delete dependents automatically using kubectl, set --cascade to true. To orphan dependents, set --cascade to false. The default value for --cascade is true.

Here’s an example that orphans the dependents of a ReplicaSet:

kubectl delete replicaset my-repset --cascade=false

Ongoing development

In Kubernetes version 1.5, synchronous garbage collection is under active development. See the tracking issue for more details.

What’s next

Design Doc

Known issues

Analytics

Create an Issue Edit this Page