Back to blog

Tutorial: automating Kubernetes worker node retirement

This guide shows you how to manually decommission Kubernetes worker nodes and replace them with a new host and then shows you how to automate that process with a Shoreline Op Pack.
Narendra Nath Challa


As powerful as Kubernetes is, it doesn't know what is relevant to your bespoke application software. Kubernetes will do its thing and schedule pods, which are abstract, rather than specific to your company and this can cause problems. One of the jobs operational and platform teams have is to encode rules that handle the nuance of their organization's applications in order to prevent orchestration logic from causing an outage. Shoreline is designed to bridge the automation gap between your application software and your orchestration layer.

This guide shows you how to manually decommission Kubernetes worker nodes and replace them with a new host and then shows you how to automate that process with a Shoreline Op Pack. The Op Pack will automatically and cleanly remove a node scheduled for retirement and allow the autoscaling groups to replace it with a new host on the latest configurations.

This is a relatively common process, but automating it can help you avoid several pitfalls; primarily that Kubernetes will do exactly what it’s told when it’s told to do it, and sometimes that involves behaviors that aren’t what you would otherwise expect.

For example, a few common pitfalls when retiring Kubernetes worker nodes include:

  • Forgetting to drain nodes before deleting them
  • Not waiting for pods to fully migrate before removing cluster capacity
  • Not adding capacity before retiring multiple nodes, leaving the cluster without enough capacity to run its software
  • Forgetting about custom labeling or pod workloads with specific node affinity, leading to difficulty rescheduling pods

Let's dive in. We'll start with at an example architecture, manually reprovision a node, and then see how much easier (and safer) it is to do this using Shoreline.

Our Infrastructure

We have a simple architecture today with worker nodes in an EKS provisioned cluster with our application running distributed across each node. Because our apps could be running on any node at any time, it’s important to be mindful of our processes to prevent disruption to the business.

Within this infrastructure, we’ll need to make some changes to our AutoScaling Group and reprovision a node with the updated configuration.

The Manual Steps

First, see what pods are running and where in order to find our blast radius for this maintenance.

<code-embed>kubectl get pods -o wide

NAME                                  READY   STATUS    RESTARTS   AGE   IP               NODE                                            NOMINATED NODE   READINESS GATES
shoreline-demo-app-84c58c758d-9pft7   1/1     Running   0          11m
shoreline-demo-app-84c58c758d-wjpph   1/1     Running   0          28s
shoreline-demo-app-84c58c758d-zc4hl   1/1     Running   0          11m<code-embed>

Ensure that no other pods will be added to this blast radius while we work.

<code-embed>kubectl cordon

node/ cordoned<code-embed>

Remove any pods running on this node.

<code-embed>kubectl drain --ignore-daemonsets --delete-local-data

node/ already cordoned
WARNING: ignoring DaemonSet-managed Pods: kube-system/aws-node-4nsmj, kube-system/kube-proxy-fj8x7
evicting pod default/shoreline-demo-app-84c58c758d-wjpph
pod/shoreline-demo-app-84c58c758d-wjpph evicted
node/ evicted<code-embed>

Verify that our applications are running on other nodes now. If we skip this step, we risk progressing too quickly and impacting the application by removing too many applications from service leading to resource contention.

<code-embed>kubectl get pods -o wide

NAME                                  READY   STATUS    RESTARTS   AGE   IP               NODE                                            NOMINATED NODE   READINESS GATES
shoreline-demo-app-84c58c758d-9pft7   1/1     Running   0          12m
shoreline-demo-app-84c58c758d-bdnjn   1/1     Running   0          16s
shoreline-demo-app-84c58c758d-zc4hl   1/1     Running   0          12m<code-embed>

Safely delete the node from the cluster to remove it from any other management/automation.

<code-embed>kubectl delete node

node "" deleted<code-embed>

Verify the work has completed.

<code-embed>kubectl get nodes

NAME                                            STATUS   ROLES    AGE   VERSION     Ready       22m   v1.19.6-eks-49a6c0   Ready       22m   v1.19.6-eks-49a6c0<code-embed>

Permanently delete the instance to ensure the AutoScaling Group brings in a new, fresh node.

Verify that the cluster now sees the node.

<code-embed>kubectl get nodes

NAME                                            STATUS   ROLES    AGE    VERSION   Ready       3m9s   v1.19.6-eks-49a6c0     Ready       35m    v1.19.6-eks-49a6c0   Ready       34m    v1.19.6-eks-49a6c0<code-embed>

While conceptually, the process of setting up the cluster and reprovisioning nodes is a simple matter, there’s a lot of manual steps for it to be a safe practice. Here we had to take several Kubernetes specific steps, and several EKS specific steps including hopping out of our CLI to find and delete the appropriate node in the console.

Automating this with Shoreline

Now, we'll show you how to automate this work using Shoreline and Shoreline's operations language, Op. Shoreline Op is a purpose-built operations oriented language designed to allow operators and admins to rapidly understand, debug, and fix systems during an operational event, and automate the tasks performed during mitigation in order to reduce or eliminate future manual intervention.

There are two scripts that we will use to automate this work.

Script 1

<code-block><code-block> Identifies the EC2 scheduled events using EC2 metadata IMDS v1. The container where the script is executed should have access to the EC2 metadata to retrieve information about EC2 events.

<code-block>EVENT_TYPE<code-block> is passed as an environment variable through a Shoreline Op command.

<code-embed># validate EVENT_TYPE
if [ $EVENT_TYPE == "instance-retirement" ] || [ $EVENT_TYPE == "instance-stop" ] || [ $EVENT_TYPE == "instance-reboot" ] || [ $EVENT_TYPE == "system-reboot" ];
       printf -- "Event type selected: ${EVENT_TYPE}\n"
       printf -- 'Invalid event type passed expected one of "instance-stop"|"instance-retirement"|"instance-reboot"|"system-reboot"'
       exit 127

function check_command() {
_=$(command -v $1);
if [ "$?" != "0" ]; then
 printf -- "You don't seem to have $1 installed.\n";
 printf -- "Exiting with code 127...\n";
 exit 127;

#check for curl binary
check_command "curl"

#check for jq binary
check_command "jq"
status_code=$(curl -LI ${url} -o /dev/null -w '%{http_code}\n' -s)

if [ $status_code == "200" ];
       maintenance_codes=("$(curl -s ${url}/events/maintenance/scheduled | jq -r '.[] | .Code' )")
       printf -- "http status code: ${status_code}"
       printf "Make sure the container/instance has access to ec2 metadata"
       exit 127

for i in ${!maintenance_codes[@]}; do
       if [ "${maintenance_codes[$i]}" == "${EVENT_TYPE}" ]; then
         maintenance_state=$(curl -s ${url}/events/maintenance/scheduled | jq -r  ".[$i][\"State\"]")
         if [ $maintenance_state == "active" ]; then
               printf -- "Instance is scheduled for event ${EVENT_TYPE} and is in state active\n"
               exit 1

exit 0<code-embed>

Script 2

<code-block><code-block> This script also uses AWS EC2 metadata to get region and instance-id ..etc. It uses kubectl command to drain a node and then uses aws cli binary to terminate EC2 instances.

<code-embed>function check_command() {
_=$(command -v $1);
if [ "$?" != "0" ]; then
 printf -- "You don't seem to have $1 installed.\n";
 printf -- "Exiting with code 127...\n";
 exit 127;

#check for kubectl binary
check_command "kubectl"

#check for aws binary
check_command "aws"

#check for curl binary
check_command "curl"

#override default pod grace period

#override default kubectl drain timeout

Both the scripts use curl and jq to get EC2 metadata and parse it. These two scripts can be combined into one, but I choose to have two scripts to mix and match actions with some of my other alarms. The scripts are written in bash but can also be modified to use any other shell installed in your environment.

<code-block>${ACTION_NODE_NAME},${grace_period},${timeout}<code-block> environment variables are set as part of action execution.

Op commands to automate execution using a bot

The Op commands below assume the two scripts are loaded in the container at /scripts path in a Shoreline pod. Each Shoreline pod has a single container with AWS cli, kubectl, curl and jq installed on an Ubuntu base image.

I can select these containers running on Shoreline pods using op with Kubernetes' selector <code-block>app="shoreline"<code-block> on the pods and piping the output to container. I will create a resource called shoreline to make it easier to select the Shoreline container for subsequent Op statements.

<code-embed>resource shoreline = host | .pod | app=”shoreline” | .container
action check_instance_event(EVENT_TYPE) = `cd /scripts && ./`
action retire_node(grace_period, timeout) = `cd /scripts && ./`

alarm retirement_alarm = check_instance_event("instance-retirement") == 1
retirement_alarm.clear_query = check_instance_event("instance-retirement") != 1
retirement_alarm.check_interval_sec = 600
retirement_alarm.resource_query = shoreline
enable retirement_alarm

bot retirement_bot = if retirement_alarm then retire_node(300, 300) fi<code-embed>

The first action check_instance_event executes takes one input EVENT_TYPE that the script 1 expects. In the example, I am looking for “instance-retirement” type of Ec2 event.

If the EVENT_TYPE matches the “instance-retirement” when the script is executed then the script exits with exit status 1 which in turn triggers an alarm retirement_alarm.

The second action, retire_node, drains a node and then terminates the node using the AWS binary. This action takes two input parameters grace_period (grace period for pods to be evicted) and timeout (timeout for the kubectl command).

The alarm and action are attached together using a bot called retirement_bot. Whenever the retirement_alarm is triggered, then retire_node is triggered to drain the node.

Permission prerequisites:

The pod where the actions are run should have a service account with the following api permissions attached using role binding.

<code-embed># Needed to evict pods
- apiGroups: [""]
 resources: ["pods/eviction"]
 verbs: ["create"]
# Needed to determine Pod owners
- apiGroups: ["apps"]
 resources: ["statefulsets", "daemonsets"]
 verbs: ["get", "list"]
# Needed to determine Pod owners
- apiGroups: ["extensions"]
 resources: ["daemonsets", "replicasets"]
 verbs: ["get", "list"]<code-embed>

Permission required to run the AWS command

<code-block>EC2:TerminateInstances<code-block> This can be attached to the worker node role or can be attached to the pod where the action is being executed using IAM roles for Service accounts.


We can use this automation when an EC2 instance is running on degraded hardware. AWS will schedule maintenance of these nodes and will change the underlying host. Downtime is often involved in this process, but we can automate this process using Shoreline to prevent downtime and eliminate the need for manual intervention.

Find more Shoreline resources

Looking for more information? Visit our other resource sections