View a markdown version of this page

Capture network traffic on a managed node using kubectl and 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

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 a managed node using kubectl and S3

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

Prerequisites

Make sure you have the following:

  • An existing Amazon EKS Auto Mode cluster with the 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 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 instance ID
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 files are gzip-compressed pcap format. Decompress and analyze with tcpdump or Wireshark:

gunzip captures/*.gz
tcpdump -r captures/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.