API-initiated Eviction

    You can request eviction by calling the Eviction API directly, or programmatically using a client of the API server, like the kubectl drain command. This creates an Eviction object, which causes the API server to terminate the Pod.

    API-initiated evictions respect your configured and terminationGracePeriodSeconds.

    Using the API to create an Eviction object for a Pod is like performing a policy-controlled on the Pod.

    Note: policy/v1 Eviction is available in v1.22+. Use policy/v1beta1 with prior releases.

    Note: Deprecated in v1.22 in favor of policy/v1

    Alternatively, you can attempt an eviction operation by accessing the API using curl or , similar to the following example:

    • 429 Too Many Requests: the eviction is not currently allowed because of the configured PodDisruptionBudget. You may be able to attempt the eviction again later. You might also see this response because of API rate limiting.
    • 500 Internal Server Error: the eviction is not allowed because there is a misconfiguration, like if multiple PodDisruptionBudgets reference the same Pod.

    If the Pod you want to evict isn’t part of a workload that has a PodDisruptionBudget, the API server always returns 200 OK and allows the eviction.

    If the API server allows the eviction, the Pod is deleted as follows:

    1. The Pod resource in the API server is updated with a deletion timestamp, after which the API server considers the resource to be terminated. The Pod resource is also marked with the configured grace period.
    2. The on the node where the local Pod is running notices that the Pod resource is marked for termination and starts to gracefully shut down the local Pod.
    3. While the kubelet is shutting the Pod down, the control plane removes the Pod from Endpoint and objects. As a result, controllers no longer consider the Pod as a valid object.
    4. After the grace period for the Pod expires, the kubelet forcefully terminates the local Pod.
    5. The API server deletes the Pod resource.

    In some cases, your applications may enter a broken state, where the Eviction API will only return 429 or 500 responses until you intervene. This can happen if, for example, a ReplicaSet creates pods for your application but new pods do not enter a Ready state. You may also notice this behavior in cases where the last evicted Pod had a long termination grace period.

    • Abort or pause the automated operation causing the issue. Investigate the stuck application before you restart the operation.
    • Wait a while, then directly delete the Pod from your cluster control plane instead of using the Eviction API.