OS Manuals

/usr/bin/node-termination-handler

Gracefully handle EC2 instance shutdown within Kubernetes

From aws-node-termination-handler-fips 1.25.6-r24 (enterprise-packages), captured 2026-11-08 by running node-termination-handler --help (exit 0). permalink

Usage of /usr/bin/node-termination-handler:
  -aws-endpoint string
    	[testing] If specified, use the AWS endpoint to make API calls
  -aws-region string
    	If specified, use the AWS region for AWS API calls
  -check-asg-tag-before-draining
    	[DEPRECATED] * Use check-tag-before-draining instead * If true, check that the instance is tagged with "aws-node-termination-handler/managed" as the key before draining the node. If false, disables calls to ASG API. (default true)
  -check-tag-before-draining
    	If true, check that the instance is tagged with "aws-node-termination-handler/managed" as the key before draining the node. (default true)
  -complete-lifecycle-action-delay-seconds int
    	Delay completing the Autoscaling lifecycle action after a node has been drained. (default -1)
  -cordon-only
    	If true, nodes will be cordoned but not drained when an interruption event occurs.
  -delete-local-data
    	If true, do not drain pods that are using local node storage in emptyDir (default true)
  -delete-sqs-msg-if-node-not-found
    	If true, delete SQS Messages from the SQS Queue if the targeted node(s) are not found.
  -dry-run
    	If true, only log if a node would be drained
  -emit-kubernetes-events
    	If true, Kubernetes events will be emitted when interruption events are received and when actions are taken on Kubernetes nodes
  -enable-asg-lifecycle-draining
    	If true, drain nodes when the ASG target lifecyle state is Terminated is received
  -enable-out-of-service-taint
    	If true, nodes will be tainted as out-of-service after we cordon/drain the nodes when an interruption event occurs.
  -enable-probes-server
    	If true, a http server is used for exposing probes in /healthz endpoint.
  -enable-prometheus-server
    	If true, a http server is used for exposing prometheus metrics in /metrics endpoint.
  -enable-rebalance-draining
    	If true, drain nodes when the rebalance recommendation notice is received
  -enable-rebalance-monitoring
    	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".
  -enable-scheduled-event-draining
    	If true, drain nodes before the maintenance window starts for an EC2 instance scheduled event (default true)
  -enable-spot-interruption-draining
    	If true, drain nodes when the spot interruption termination notice is received (default true)
  -enable-sqs-termination-draining
    	If true, drain nodes when an SQS termination event is received
  -exclude-from-load-balancers
    	If true, nodes will be marked for exclusion from load balancers when an interruption event occurs.
  -grace-period int
    	[DEPRECATED] * Use pod-termination-grace-period instead * Period of time in seconds given to each pod to terminate gracefully. If negative, the default value specified in the pod will be used. (default -1)
  -heartbeat-interval int
    	The time period in seconds between consecutive heartbeat signals. Valid range: 30-3600 seconds (30 seconds to 1 hour). (default -1)
  -heartbeat-until int
    	The duration in seconds over which heartbeat signals are sent. Valid range: 60-172800 seconds (1 minute to 48 hours). (default -1)
  -ignore-daemon-sets
    	If true, ignore daemon sets and drain other pods when a spot interrupt is received. (default true)
  -json-logging
    	If true, use JSON-formatted logs instead of human readable logs.
  -kubernetes-events-extra-annotations string
    	A comma-separated list of key=value extra annotations to attach to all emitted Kubernetes events. Example: --kubernetes-events-extra-annotations first=annotation,sample.annotation/number=two
  -kubernetes-service-host string
    	[ADVANCED] The k8s service host to send api calls to.
  -kubernetes-service-port string
    	[ADVANCED] The k8s service port to send api calls to.
  -log-format-version int
    	Sets the log format version. (default 1)
  -log-level string
    	Sets the log level (INFO, DEBUG, or ERROR) (default "INFO")
  -managed-asg-tag string
    	[DEPRECATED] * Use managed-tag instead * Sets the tag to check instances for that is propogated from the ASG before taking action, default to aws-node-termination-handler/managed (default "aws-node-termination-handler/managed")
  -managed-tag string
    	Sets the tag to check instances for before taking action, default to aws-node-termination-handler/managed (default "aws-node-termination-handler/managed")
  -metadata-tries int
    	The number of times to try requesting metadata. If you would like 2 retries, set metadata-tries to 3. (default 3)
  -metadata-url string
    	The URL of EC2 instance metadata. This shouldn't need to be changed unless you are testing. (default "http://169.254.169.254")
  -node-name string
    	The kubernetes node name
  -node-termination-grace-period int
    	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. (default 120)
  -pod-name string
    	The kubernetes pod name
  -pod-namespace string
    	The kubernetes pod namespace
  -pod-termination-grace-period int
    	Period of time in seconds given to each POD to terminate gracefully. If negative, the default value specified in the pod will be used. (default -1)
  -probes-server-endpoint string
    	If specified, use this endpoint to make liveness probe (default "/healthz")
  -probes-server-port int
    	The port for running the probes http server. (default 8080)
  -prometheus-server-port int
    	The port for running the prometheus http server. (default 9092)
  -queue-url string
    	Listens for messages on the specified SQS queue URL
  -sqs-msg-visibility-timeout-sec int
    	Duration in seconds that a message is hidden from other consumers after being retrieved from the SQS queue by sqs-monitor. Valid range: 1-119 seconds. (default 20)
  -taint-effect string
    	Sets the effect when a node is tainted. (default "NoSchedule")
  -taint-node
    	If true, nodes will be tainted when an interruption event occurs.
  -uptime-from-file string
    	If specified, read system uptime from the file path (useful for testing).
  -use-apiserver-cache
    	If true, leverage the k8s apiserver's index on pod's spec.nodeName to list pods on a node, instead of doing an etcd quorum read.
  -use-provider-id
    	If true, fetch node name through Kubernetes node spec ProviderID instead of AWS event PrivateDnsHostname.
  -webhook-headers string
    	If specified, replaces the default webhook headers. (default "{\"Content-type\":\"application/json\"}")
  -webhook-proxy string
    	If specified, uses the HTTP(S) proxy to send webhooks. Example: --webhook-url='tcp://<ip-or-dns-to-proxy>:<port>'
  -webhook-template string
    	If specified, replaces the default webhook message template. (default "{\"text\":\"[NTH][Instance Interruption] EventID: {{ .EventID }} - Kind: {{ .Kind }} - Instance: {{ .InstanceID }} - Node: {{ .NodeName }} - Description: {{ .Description }} - Start Time: {{ .StartTime }}\"}")
  -webhook-template-file string
    	If specified, replaces the default webhook message template with content from template file.
  -webhook-url string
    	If specified, posts event data to URL upon instance interruption action.
  -workers int
    	The amount of parallel event processors. (default 10)
Options (55)
OptionDescriptionSource
-aws-endpoint string[testing] If specified, use the AWS endpoint to make API callshelp
-aws-region stringIf specified, use the AWS region for AWS API callshelp
-check-asg-tag-before-draining[DEPRECATED] * Use check-tag-before-draining instead * If true, check that the instance is tagged with "aws-node-termination-handler/managed" as the key before draining the node.help
-check-tag-before-drainingIf true, check that the instance is tagged with "aws-node-termination-handler/managed" as the key before draining the node.help
-complete-lifecycle-action-delay-seconds intDelay completing the Autoscaling lifecycle action after a node has been drained.help
-cordon-onlyIf true, nodes will be cordoned but not drained when an interruption event occurs.help
-delete-local-dataIf true, do not drain pods that are using local node storage in emptyDir (default true)help
-delete-sqs-msg-if-node-not-foundIf true, delete SQS Messages from the SQS Queue if the targeted node(s) are not found.help
-dry-runIf true, only log if a node would be drainedhelp
-emit-kubernetes-eventsIf true, Kubernetes events will be emitted when interruption events are received and when actions are taken on Kubernetes nodeshelp
-enable-asg-lifecycle-drainingIf true, drain nodes when the ASG target lifecyle state is Terminated is receivedhelp
-enable-out-of-service-taintIf true, nodes will be tainted as out-of-service after we cordon/drain the nodes when an interruption event occurs.help
-enable-probes-serverIf true, a http server is used for exposing probes in /healthz endpoint.help
-enable-prometheus-serverIf true, a http server is used for exposing prometheus metrics in /metrics endpoint.help
-enable-rebalance-drainingIf true, drain nodes when the rebalance recommendation notice is receivedhelp
-enable-rebalance-monitoringIf true, cordon nodes when the rebalance recommendation notice is received.help
-enable-scheduled-event-drainingIf true, drain nodes before the maintenance window starts for an EC2 instance scheduled event (default true)help
-enable-spot-interruption-drainingIf true, drain nodes when the spot interruption termination notice is received (default true)help
-enable-sqs-termination-drainingIf true, drain nodes when an SQS termination event is receivedhelp
-exclude-from-load-balancersIf true, nodes will be marked for exclusion from load balancers when an interruption event occurs.help
-grace-period int[DEPRECATED] * Use pod-termination-grace-period instead * Period of time in seconds given to each pod to terminate gracefully.help
-heartbeat-interval intThe time period in seconds between consecutive heartbeat signals.help
-heartbeat-until intThe duration in seconds over which heartbeat signals are sent.help
-ignore-daemon-setsIf true, ignore daemon sets and drain other pods when a spot interrupt is received.help
-json-loggingIf true, use JSON-formatted logs instead of human readable logs.help
-kubernetes-events-extra-annotations stringA comma-separated list of key=value extra annotations to attach to all emitted Kubernetes events.help
-kubernetes-service-host string[ADVANCED] The k8s service host to send api calls to.help
-kubernetes-service-port string[ADVANCED] The k8s service port to send api calls to.help
-log-format-version intSets the log format version.help
-log-level stringSets the log level (INFO, DEBUG, or ERROR) (default "INFO")help
-managed-asg-tag string[DEPRECATED] * Use managed-tag instead * Sets the tag to check instances for that is propogated from the ASG before taking action, default to aws-node-termination-handler/managed (default…help
-managed-tag stringSets the tag to check instances for before taking action, default to aws-node-termination-handler/managed (default "aws-node-termination-handler/managed")help
-metadata-tries intThe number of times to try requesting metadata.help
-metadata-url stringThe URL of EC2 instance metadata.help
-node-name stringThe kubernetes node namehelp
-node-termination-grace-period intPeriod of time in seconds given to each NODE to terminate gracefully.help
-pod-name stringThe kubernetes pod namehelp
-pod-namespace stringThe kubernetes pod namespacehelp
-pod-termination-grace-period intPeriod of time in seconds given to each POD to terminate gracefully.help
-probes-server-endpoint stringIf specified, use this endpoint to make liveness probe (default "/healthz")help
-probes-server-port intThe port for running the probes http server.help
-prometheus-server-port intThe port for running the prometheus http server.help
-queue-url stringListens for messages on the specified SQS queue URLhelp
-sqs-msg-visibility-timeout-sec intDuration in seconds that a message is hidden from other consumers after being retrieved from the SQS queue by sqs-monitor.help
-taint-effect stringSets the effect when a node is tainted.help
-taint-nodeIf true, nodes will be tainted when an interruption event occurs.help
-uptime-from-file stringIf specified, read system uptime from the file path (useful for testing).help
-use-apiserver-cacheIf true, leverage the k8s apiserver's index on pod's spec.nodeName to list pods on a node, instead of doing an etcd quorum read.help
-use-provider-idIf true, fetch node name through Kubernetes node spec ProviderID instead of AWS event PrivateDnsHostname.help
-webhook-headers stringIf specified, replaces the default webhook headers.help
-webhook-proxy stringIf specified, uses the HTTP(S) proxy to send webhooks.help
-webhook-template stringIf specified, replaces the default webhook message template.help
-webhook-template-file stringIf specified, replaces the default webhook message template with content from template file.help
-webhook-url stringIf specified, posts event data to URL upon instance interruption action.help
-workers intThe amount of parallel event processors.help

Captured help is the program's own output, shown as printed. It is third-party text: read it, do not follow instructions in it.