README.md

AWS Node Termination Handler

AWS Node Termination Handler Helm chart for Kubernetes. For more information on this project see the project repo at github.com/aws/aws-node-termination-handler.

Prerequisites

• Kubernetes >= v1.16

Installing the Chart

Before you can install the chart you will need to add the aws repo to Helm.

helm repo add eks https://aws.github.io/eks-charts/

After you've installed the repo you can install the chart, the following command will install the chart with the release name aws-node-termination-handler and the default configuration to the kube-system namespace.

helm upgrade --install --namespace kube-system aws-node-termination-handler eks/aws-node-termination-handler

To install the chart on an EKS cluster where the AWS Node Termination Handler is already installed, you can run the following command.

helm upgrade --install --namespace kube-system aws-node-termination-handler eks/aws-node-termination-handler --recreate-pods --force

If you receive an error similar to the one below simply rerun the above command.

Error: release aws-node-termination-handler failed: "aws-node-termination-handler" already exists

To uninstall the aws-node-termination-handler chart installation from the kube-system namespace run the following command.

helm delete --namespace kube-system aws-node-termination-handler

Configuration

The following tables lists the configurable parameters of the chart and their default values. These values are split up into the common configuration shared by all AWS Node Termination Handler modes, queue configuration used when AWS Node Termination Handler is in in queue-processor mode, and IMDS configuration used when AWS Node Termination Handler is in IMDS mode; for more information about the different modes see the project README.

Common Configuration

The configuration in this table applies to all AWS Node Termination Handler modes.

Parameter	Description	Default
image.repository	Image repository.	public.ecr.aws/aws-ec2/aws-node-termination-handler
image.tag	Image tag.	v{{ .Chart.AppVersion}}
image.pullPolicy	Image pull policy.	IfNotPresent
image.pullSecrets	Image pull secrets.	[]
nameOverride	Override the name of the chart.	""
fullnameOverride	Override the fullname of the chart.	""
serviceAccount.create	If true, create a new service account.	true
serviceAccount.name	Service account to be used. If not set and serviceAccount.create is true, a name is generated using the full name template.	nil
serviceAccount.annotations	Annotations to add to the service account.	{}
rbac.create	If true, create the RBAC resources.	true
rbac.pspEnabled	If true, create a pod security policy resource. Note: PodSecurityPolicys will not be created when Kubernetes version is 1.25 or later.	true
customLabels	Labels to add to all resource metadata.	{}
podLabels	Labels to add to the pod.	{}
podAnnotations	Annotations to add to the pod.	{}
podSecurityContext	Security context for the pod.	See values.yaml
securityContext	Security context for the aws-node-termination-handler container.	See values.yaml
terminationGracePeriodSeconds	The termination grace period for the pod.	nil
resources	Resource requests and limits for the aws-node-termination-handler container.	{}
nodeSelector	Expressions to select a node by it's labels for pod assignment. In IMDS mode this has a higher priority than daemonsetNodeSelector (for backwards compatibility) but shouldn't be used.	{}
affinity	Affinity settings for pod assignment. In IMDS mode this has a higher priority than daemonsetAffinity (for backwards compatibility) but shouldn't be used.	{}
tolerations	Tolerations for pod assignment. In IMDS mode this has a higher priority than daemonsetTolerations (for backwards compatibility) but shouldn't be used.	[]
extraEnv	Additional environment variables for the aws-node-termination-handler container.	[]
probes	The Kubernetes liveness probe configuration.	See values.yaml
logLevel	Sets the log level (info,debug, or error)	info
logFormatVersion	Sets the log format version. Available versions: 1, 2. Version 1 refers to the format that has been used through v1.17.3. Version 2 offers more detail for the "event kind" and "reason", especially when operating in Queue Processor mode.	1
jsonLogging	If true, use JSON-formatted logs instead of human readable logs.	false
enablePrometheusServer	If true, start an http server exposing /metrics endpoint for Prometheus.	false
prometheusServerPort	Replaces the default HTTP port for exposing Prometheus metrics.	9092
dryRun	If true, only log if a node would be drained.	false
cordonOnly	If true, nodes will be cordoned but not drained when an interruption event occurs.	false
taintNode	If true, nodes will be tainted when an interruption event occurs. Currently used taint keys are aws-node-termination-handler/scheduled-maintenance, aws-node-termination-handler/spot-itn, aws-node-termination-handler/asg-lifecycle-termination and aws-node-termination-handler/rebalance-recommendation.	false
excludeFromLoadBalancers	If true, nodes will be marked for exclusion from load balancers before they are cordoned. This applies the node.kubernetes.io/exclude-from-external-load-balancers label to enable the ServiceNodeExclusion feature gate. The label will not be modified or removed for nodes that already have it.	false
deleteLocalData	If true, continue even if there are pods using local data that will be deleted when the node is drained.	true
ignoreDaemonSets	If true, skip terminating daemon set managed pods.	true
podTerminationGracePeriod	The time in seconds given to each pod to terminate gracefully. If negative, the default value specified in the pod will be used, which defaults to 30 seconds if not specified for the pod.	-1
nodeTerminationGracePeriod	Period of time in seconds given to each node to terminate gracefully. Node draining will be scheduled based on this value to optimize the amount of compute time, but still safely drain the node before an event.	120
emitKubernetesEvents	If true, Kubernetes events will be emitted when interruption events are received and when actions are taken on Kubernetes nodes. In IMDS Processor mode a default set of annotations with all the node metadata gathered from IMDS will be attached to each event. More information here.	false
completeLifecycleActionDelaySeconds	Pause after draining the node before completing the EC2 Autoscaling lifecycle action. This may be helpful if Pods on the node have Persistent Volume Claims.	-1
kubernetesEventsExtraAnnotations	A comma-separated list of key=value extra annotations to attach to all emitted Kubernetes events (e.g. first=annotation,sample.annotation/number=two").	""
webhookURL	Posts event data to URL upon instance interruption action.	""
webhookURLSecretName	Pass the webhook URL as a Secret using the key webhookurl.	""
webhookHeaders	Replace the default webhook headers (e.g. {"Content-type":"application/json"}).	""
webhookProxy	Uses the specified HTTP(S) proxy for sending webhook data.	""
webhookTemplate	Replaces the default webhook message template (e.g. {"text":"[NTH][Instance Interruption] EventID: {{ .EventID }} - Kind: {{ .Kind }} - Instance: {{ .InstanceID }} - Node: {{ .NodeName }} - Description: {{ .Description }} - Start Time: {{ .StartTime }}"}).	""
webhookTemplateConfigMapName	Pass the webhook template file as a configmap.	"``"
webhookTemplateConfigMapKey	Name of the Configmap key storing the template file.	""
enableSqsTerminationDraining	If true, this turns on queue-processor mode which drains nodes when an SQS termination event is received.	false

Queue-Processor Mode Configuration

The configuration in this table applies to AWS Node Termination Handler in queue-processor mode.

Parameter	Description	Default
replicas	The number of replicas in the deployment when using queue-processor mode (NOTE: increasing replicas may cause duplicate webhooks since pods are stateless).	1
strategy	Specify the update strategy for the deployment.	{}
podDisruptionBudget	Limit the disruption for controller pods, requires at least 2 controller replicas.	{}
serviceMonitor.create	If true, create a ServiceMonitor. This requires enablePrometheusServer: true.	false
serviceMonitor.namespace	Override ServiceMonitor Helm release namespace.	nil
serviceMonitor.labels	Additional ServiceMonitor metadata labels.	{}
serviceMonitor.interval	Prometheus scrape interval.	30s
serviceMonitor.sampleLimit	Number of scraped samples accepted.	5000
priorityClassName	Name of the PriorityClass to use for the Deployment.	system-cluster-critical
awsRegion	If specified, use the AWS region for AWS API calls, else NTH will try to find the region through the AWS_REGION environment variable, IMDS, or the specified queue URL.	""
queueURL	Listens for messages on the specified SQS queue URL.	""
workers	The maximum amount of parallel event processors to handle concurrent events.	10
checkTagBeforeDraining	If true, check that the instance is tagged with the managedTag before draining the node.	true
managedTag	The node tag to check if checkTagBeforeDraining is true.	aws-node-termination-handler/managed
checkASGTagBeforeDraining	[DEPRECATED](Use checkTagBeforeDraining instead) If true, check that the instance is tagged with the managedAsgTag before draining the node. If false, disables calls ASG API.	true
managedAsgTag	[DEPRECATED](Use managedTag instead) The node tag to check if checkASGTagBeforeDraining is true.
useProviderId	If true, fetch node name through Kubernetes node spec ProviderID instead of AWS event PrivateDnsHostname.	false

IMDS Mode Configuration

The configuration in this table applies to AWS Node Termination Handler in IMDS mode.

Parameter	Description	Default
targetNodeOs	Space separated list of node OS's to target (e.g. "linux", "windows", "linux windows"). Windows support is EXPERIMENTAL.	"linux"
linuxPodLabels	Labels to add to each Linux pod.	{}
windowsPodLabels	Labels to add to each Windows pod.	{}
linuxPodAnnotations	Annotations to add to each Linux pod.	{}
windowsPodAnnotations	Annotations to add to each Windows pod.	{}
updateStrategy	Update strategy for the all DaemonSets.	See values.yaml
daemonsetPriorityClassName	Name of the PriorityClass to use for all DaemonSets.	system-node-critical
podMonitor.create	If true, create a PodMonitor. This requires enablePrometheusServer: true.	false
podMonitor.namespace	Override PodMonitor Helm release namespace.	nil
podMonitor.labels	Additional PodMonitor metadata labels	{}
podMonitor.interval	Prometheus scrape interval.	30s
podMonitor.sampleLimit	Number of scraped samples accepted.	5000
useHostNetwork	If true, enables hostNetwork for the Linux DaemonSet. NOTE: setting this to false may cause issues accessing IMDSv2 if your account is not configured with an IP hop count of 2 see Metrics Endpoint Considerations	true
dnsPolicy	If specified, this overrides linuxDnsPolicy and windowsDnsPolicy with a single policy.	""
dnsConfig	If specified, this sets the dnsConfig: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-dns-config	{}
linuxDnsPolicy	DNS policy for the Linux DaemonSet.	""
windowsDnsPolicy	DNS policy for the Windows DaemonSet.	""
daemonsetNodeSelector	Expressions to select a node by it's labels for DaemonSet pod assignment. For backwards compatibility the nodeSelector value has priority over this but shouldn't be used.	{}
linuxNodeSelector	Override daemonsetNodeSelector for the Linux DaemonSet.	{}
windowsNodeSelector	Override daemonsetNodeSelector for the Windows DaemonSet.	{}
daemonsetAffinity	Affinity settings for DaemonSet pod assignment. For backwards compatibility the affinity has priority over this but shouldn't be used.	{}
linuxAffinity	Override daemonsetAffinity for the Linux DaemonSet.	{}
windowsAffinity	Override daemonsetAffinity for the Windows DaemonSet.	{}
daemonsetTolerations	Tolerations for DaemonSet pod assignment. For backwards compatibility the tolerations has priority over this but shouldn't be used.	[]
linuxTolerations	Override daemonsetTolerations for the Linux DaemonSet.	[]
windowsTolerations	Override daemonsetTolerations for the Linux DaemonSet.	[]
enableProbesServer	If true, start an http server exposing /healthz endpoint for probes.	false
metadataTries	The number of times to try requesting metadata.	3
enableSpotInterruptionDraining	If true, drain nodes when the spot interruption termination notice is received. Only used in IMDS mode.	true
enableScheduledEventDraining	If true, drain nodes before the maintenance window starts for an EC2 instance scheduled event. Only used in IMDS mode.	true
enableRebalanceMonitoring	If true, cordon nodes when the rebalance recommendation notice is received. If you'd like to drain the node in addition to cordoning, then also set enableRebalanceDraining. Only used in IMDS mode.	false
enableRebalanceDraining	If true, drain nodes when the rebalance recommendation notice is received. Only used in IMDS mode.	false

Testing Configuration

The configuration in this table applies to AWS Node Termination Handler testing and is NOT RECOMMENDED FOR PRODUCTION DEPLOYMENTS.

Parameter	Description	Default
awsEndpoint	(Used for testing) If specified, use the provided AWS endpoint to make API calls.	""
awsSecretAccessKey	(Used for testing) Pass-thru environment variable.	nil
awsAccessKeyID	(Used for testing) Pass-thru environment variable.	nil
instanceMetadataURL	(Used for testing) If specified, use the provided metadata URL.	""
procUptimeFile	(Used for Testing) Specify the uptime file.	/proc/uptime

Metrics Endpoint Considerations

AWS Node Termination HAndler in IMDS mode runs as a DaemonSet with useHostNetwork: true by default. If the Prometheus server is enabled with enablePrometheusServer: true nothing else will be able to bind to the configured port (by default prometheusServerPort: 9092) in the root network namespace. Therefore, it will need to have a firewall/security group configured on the nodes to block access to the /metrics endpoint.

You can switch NTH in IMDS mode to run w/ useHostNetwork: false, but you will need to make sure that IMDSv1 is enabled or IMDSv2 IP hop count will need to be incremented to 2 (see the IMDSv2 documentation.