Move Guide topic: Garbage Collection. (#2488)
This commit is contained in:
Steve Perry
@@ -20,6 +20,7 @@ toc:
|
||||
- title: Controllers
|
||||
section:
|
||||
- docs/concepts/abstractions/controllers/statefulsets.md
|
||||
- docs/concepts/abstractions/controllers/garbage-collection.md
|
||||
|
||||
- title: Object Metadata
|
||||
section:
|
||||
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: Garbage Collection
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
|
||||
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.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
|
||||
{% capture body %}
|
||||
|
||||
## 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:
|
||||
|
||||
{% include code.html language="yaml" file="my-repset.yaml" ghlink="/docs/concepts/abstractions/controllers/my-repset.yaml" %}
|
||||
|
||||
If you create the ReplicaSet and then view the Pod metadata, you can see
|
||||
OwnerReferences field:
|
||||
|
||||
```shell
|
||||
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:
|
||||
|
||||
```shell
|
||||
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:
|
||||
|
||||
```shell
|
||||
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:
|
||||
|
||||
```shell
|
||||
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](https://github.com/kubernetes/kubernetes/issues/29891) for more details.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
|
||||
{% capture whatsnext %}
|
||||
|
||||
[Design Doc](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/garbage-collection.md)
|
||||
|
||||
[Known issues](https://github.com/kubernetes/kubernetes/issues/26120)
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
|
||||
{% include templates/concept.md %}
|
||||
@@ -0,0 +1,17 @@
|
||||
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
|
||||
@@ -4,35 +4,6 @@ assignees:
|
||||
title: Garbage Collection (Beta)
|
||||
---
|
||||
|
||||
* TOC
|
||||
{:toc}
|
||||
{% include user-guide-content-moved.md %}
|
||||
|
||||
## Garbage Collection
|
||||
|
||||
Note: the Garbage Collection is a beta feature and is enabled by default in Kubernetes version 1.4.
|
||||
|
||||
### What does Garbage Collector do
|
||||
|
||||
When you delete, for example, a ReplicaSet, it is often desirable for the server to automatically garbage collect all the Pods that the ReplicaSet creates. The Garbage Collector (GC) implements this. In general, when you delete an owner object, GC deletes that owner's dependent objects.
|
||||
|
||||
### How to establish an owner-dependent relationship between objects
|
||||
|
||||
Kubernetes 1.3 added a metadata.ownerReferences field to every Kubernetes API object. If an API object is a dependent of another object, ownerReference should point to the owning API object.
|
||||
|
||||
When you create a ReplicationController or a ReplicaSet in Kubernetes 1.4, the Kubernetes control plane automatically sets the ownerReference field in each created pod to point to the owning ReplicationController or ReplicaSet.
|
||||
|
||||
You can set up owner-dependent relationships among other objects by manually setting the ownerReference field on dependent objects.
|
||||
|
||||
### Controlling whether Garbage Collector deletes dependents
|
||||
|
||||
When deleting an object, you can request the GC to ***asynchronously*** delete its dependents by ***explicitly*** specifying `deleteOptions.orphanDependents=false` in the deletion request that you send to the API server. A 200 OK response from the API server indicates the owner is deleted.
|
||||
|
||||
In Kubernetes version 1.5, synchronous garbage collection is under active development. See the tracking [issue](https://github.com/kubernetes/kubernetes/issues/29891) for more details.
|
||||
|
||||
If you specify `deleteOptions.orphanDependents=true`, or leave it blank, then the GC will first reset the `ownerReferences` in the dependents, then delete the owner. Note that the deletion of the owner object is asynchronous, that is, a 200 OK response will be sent by the API server before the owner object gets deleted.
|
||||
|
||||
### Other references
|
||||
|
||||
[Design Doc](https://github.com/kubernetes/kubernetes/blob/master/docs/proposals/garbage-collection.md)
|
||||
|
||||
[Known issues](https://github.com/kubernetes/kubernetes/issues/26120)
|
||||
[Garbage Collection](/docs/concepts/abstractions/controllers/garbage-collection/)
|
||||
|
||||
Reference in New Issue
Block a user