Capture network traffic on an EKS Auto Mode node using kubectl and Amazon S3 - Amazon EKS
PrerequisitesStep 1: Create S3 bucket destination (optional)Step 2: Start packet captureStep 3: Monitor capture progressStep 4: Download capture files from S3Step 5: Clean upConfiguration options and behavior
Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Help improve this page

To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.

Capture network traffic on an EKS Auto Mode node using kubectl and Amazon S3

Learn how to capture network traffic on an Amazon EKS Auto Mode node. The EKS node monitoring agent runs tcpdump on the node, compresses capture files, and uploads them to your S3 bucket.

Important

Packet capture requires the tcpdump binary to be present in the environment that the EKS node monitoring agent runs in. This is currently the case only on EKS Auto Mode nodes, where the agent runs as part of the node image.

When you install the agent as an EKS add-on or with Helm on other compute types, such as EKS managed node groups or self-managed nodes, the agent runs in a container that doesn’t include tcpdump. The capture fails immediately, and the capture status reports a reason of Failure with the message failed to start tcpdump: exec: "tcpdump": executable file not found in $PATH.

Prerequisites

Make sure you have the following:

  • An existing Amazon EKS Auto Mode cluster. EKS Auto Mode includes the EKS node monitoring agent. For more information, see Detect node health issues and enable automatic node repair.

  • The kubectl command-line tool installed and configured to communicate with your cluster.

  • The AWS CLI installed and logged in with sufficient permissions to create S3 buckets and objects.

  • A recent version of Python 3 installed.

  • The AWS SDK for Python 3, Boto 3, installed.

  • The PyYAML library installed (pip install pyyaml).

Step 1: Create S3 bucket destination (optional)

If you don’t already have an S3 bucket to store the capture files, create one. Replace bucket-name and region with your values.

aws s3api create-bucket --bucket <bucket-name> \
    --region <region> \
    --create-bucket-configuration LocationConstraint=<region>
Note

The --create-bucket-configuration parameter is required for all regions except us-east-1.

Step 2: Start packet capture

Use the start-capture.py script from the node monitoring agent repository (tools/start-capture.py) to generate pre-signed S3 credentials, create the NodeDiagnostic resource, and apply it to your cluster.

  1. Identify the node you want to capture traffic from.

    kubectl get nodes

  2. Save the start-capture.py script from the node monitoring agent repository to your local machine, then run it. Replace <bucket-name> and <node-name> with your values.

    python3 start-capture.py --bucket <bucket-name> --node <node-name>

    Common options:

    # Capture for 5 minutes on eth0 with a filter
python3 start-capture.py --bucket <bucket-name> --node <node-name> \
    --duration 5m --interface eth0 --filter "tcp port 443"

# Preview the YAML without applying
python3 start-capture.py --bucket <bucket-name> --node <node-name> --dry-run

    The script requires Python 3 with boto3 and pyyaml installed, and kubectl configured for your cluster. The script applies the resource to your current kubectl context, so if you work with more than one cluster, confirm your context first with kubectl config current-context.

    The script generates a NodeDiagnostic resource like the following. This example is provided for reference; note that the upload fields require pre-signed S3 POST credentials that are generated programmatically by the script.

    apiVersion: eks.amazonaws.com/v1alpha1
kind: NodeDiagnostic
metadata:
  name: <node-name>                    # Required: node name as shown by kubectl get nodes
spec:
  packetCapture:
    duration: "30s"                       # Required: capture duration (max 1h)
    # interface: "eth0"                   # Optional: default is primary ENI. Use "any" for all interfaces
    # filter: "tcp port 443"             # Optional: tcpdump filter expression
    # chunkSizeMB: 10                    # Optional: file rotation size in MB (1-100, default: 10)
    upload:                               # Required: pre-signed S3 POST credentials
      url: "https://<bucket>.s3.amazonaws.com/"
      fields:
        key: "captures/<node-name>/${filename}"
        # ... other pre-signed POST fields (generated by the script)

Step 3: Monitor capture progress

Check the status of the capture.

kubectl describe nodediagnostic <node-name>

The status will show:

  • Running while the capture is in progress.

  • Completed with reason Success when the capture finishes and all files are uploaded.

  • Completed with reason Failure if the capture encountered errors.

To see the full status including captureID (used for S3 path identification):

kubectl get nodediagnostic <node-name> -o jsonpath='{.status.captureStatuses}'

Step 4: Download capture files from S3

Once the status shows Success, download the capture files from S3.

aws s3 cp s3://<bucket-name>/captures/ ./captures/ --recursive

The EKS node monitoring agent uploads each capture under a prefix that includes the captureID, so the downloaded files are nested rather than sitting directly in ./captures/. The resulting layout is as follows.

captures/<node-name>/<captureID>/capture.pcap0000.gz

The files are gzip-compressed pcap format. Decompress and analyze them with tcpdump or Wireshark. Because of the nesting, use a recursive pattern rather than a flat one.

# Decompress every capture file that was downloaded
find captures -name '*.gz' -exec gunzip {} +

# Read one capture file
tcpdump -r captures/<node-name>/<captureID>/capture.pcap0000 -n

Step 5: Clean up

NodeDiagnostic resources are not automatically deleted. Clean up after you have obtained your capture files. Deleting the resource while a capture is running will stop the capture immediately.

kubectl delete nodediagnostic <node-name>

Configuration options and behavior

For the full packetCapture spec reference, configuration options, and behavior details, see the packet capture documentation in the node monitoring agent repository.