Use Packet Inspector 2#

About Packet Inspector 2#

Introduction#

Packet Inspector 2 captures the traffic entering and leaving the application containers in a namespace or set of labeled pods and sends the traffic to a supported analysis service. You can install more than one Packet Inspector 2 filter instance to capture traffic from more than one namespace or set of labeled pods.

Supported protocols#

Packet Inspector 2 supports the following protocols:

Diameter
HTTP (1.1 and 2), including gRPC

Note

Diameter packet captures from ingress and egress gateways are not supported.

Packet Inspector 2 block diagram#

This diagram shows the components of Packet Inspector 2 and how data travels among them:

Packet Inspector 2 components#

Packet Inspector 2 consists of the following components:

Component	Description
Filters	Extensions of Istio proxies (whether used as sidecars or in a gateway) that capture and forward data

Types of analysis services#

You can send captured traffic to either of the following types of analysis services:

Analysis service	Purpose
A third-party network analysis tool	For use in production environments to analyze captured data
The Aspen Mesh analysis emulator	For use in non-production environments to demonstrate or test Packet Inspector 2

About the analysis emulator#

Types of files written by the analysis emulator#

For each sequence in an HTTP transaction, the analysis emulator writes serialized protobuf (.pb) files to the /tmp directory.

Analysis-emulator HTTP filename formats#

HTTP files written by the analysis emulator use one of the following filename formats:

Direction	Filename format	Example
Inbound	`<authorityHeader>-<xTraceId>-<streamDirection>-<sequenceNumber>`	`httpbin-go-httpbin.httpbin-go-httpbin-1-56058.svc:8080-a7020847b1ec89328e3f8d357f373266-res-1.pb`
Outbound	`<clientNS>-<xTraceId>-<streamDirection>-<sequenceNumber>`	`sleep-2-59564-a7020847b1ec89328e3f8d357f373266-req-1.pb`

Analysis-emulator Diameter filename formats#

Diameter files written by the analysis emulator use the following filename format:

<podName>-<endToEndId>-<hopByHopId>-<timestamp>

Example

diameter-client-6464c65b66-4c8jl-1339708294-1857878061-1675782061987009574.pb

Prepare to capture traffic with Packet Inspector 2#

Introduction#

To prepare to capture traffic using Packet Inspector 2, you need to install the network analysis tool or the analysis emulator.

When to follow these instructions#

Follow the instructions below only if you want to start using Packet Inspector 2 to capture traffic and only after you’ve installed Aspen Mesh. Perform the tasks in order.

Install the analysis service#

Do you want to use a network analysis tool (not the analysis emulator) as your analysis service?
- Yes:
  - Install the network analysis tool.
- No:
  - Install the analysis emulator.

Install the network analysis tool#

Note

Perform this task only when other instructions tell you to do so.

Add the automatic-sidecar-injection label to the namespace in which you’ll install the network analysis tool:

$ kubectl label namespace <networkAnalysisToolNamespaceName> \
    istio-injection=enabled --overwrite

Follow the installation instructions provided with the network analysis tool.

Install the analysis emulator#

Note

Perform this task only when other instructions tell you to do so.

Change to the Aspen Mesh release directory.

Create a namespace named analysis-emulator:

$ kubectl create namespace analysis-emulator

Add the automatic-sidecar-injection label to the analysis-emulator namespace:

$ kubectl label namespace analysis-emulator \
    istio-injection=enabled --overwrite

Install the analysis emulator:

$ helm install pi2-analysis-emulator \
    samples/aspenmesh/packet-inspector-2-analysis-emulator \
    --namespace analysis-emulator \
    --wait

Capture traffic using a Packet Inspector 2 filter instance#

Introduction#

Before you can capture traffic using a Packet Inspector 2 filter instance, you need to:

(Optional) Label the set of pods you want to capture traffic from
Create an override values file for the Packet Inspector 2 filter instance
Install the Packet Inspector 2 filter instance

After you capture traffic, you need to uninstall the Packet Inspector 2 filter instance to prevent it from lowering the performance of your cluster.

When to follow these instructions#

Follow the instructions below only if you want to capture traffic using Packet Inspector 2 and only after you’ve prepared to capture traffic with Packet Inspector 2. Perform the tasks in order.

About Packet Inspector 2 filter configuration#

The Helm chart for the Packet Inspector 2 filter includes a values.yaml file that contains fields that Helm uses to generate the manifest files during an installation or an upgrade. You can change the default value of a field by doing both of the following:

Include the field in the override values file for a Packet Inspector 2 filter instance and specify a different value.
Specify the override values file and a namespace when installing the Packet Inspector 2 filter instance.

Configuration overview for a Packet Inspector 2 filter instance#

This table provides an overview of how to configure a Packet Inspector 2 filter instance, depending on what traffic you want to capture.

To capture traffic from	Do this
All pods with sidecars in a namespace	- In the override values file for the Packet Inspector 2 filter instance, do not add a key/value pair under `.workloadSelector.labels`. - Install the Packet Inspector 2 filter instance in the namespace. Important: - Do not deploy the analysis service to the same namespace. - The namespace can be any namespace other than the `istio-system` namespace.
A set of labeled pods with sidecars, regardless of namespace	- Label each pod in the set with a unique key/value pair for the set. - In the override values file for the Packet Inspector 2 filter instance, add the key/value pair under `.workloadSelector.labels`. - Install the Packet Inspector 2 filter instance in the `istio-system` namespace. Important: Do not install a Packet Inspector 2 filter instance in the `istio-system` namespace without specifying a key/value pair in the override values file. Doing so will cause traffic to be captured from all pods in the service mesh, including the analysis service.
A set of labeled pods with sidecars in a namespace	- Label each pod in the set with a unique key/value pair for the set. - In the override values file for the Packet Inspector 2 filter instance, add the key/value pair under `.workloadSelector.labels`. - Install the Packet Inspector 2 filter instance in the namespace that contains the labeled pods.

Label the set of pods you want to capture traffic from#

Important

Perform this task only if you want to capture traffic from a set of labeled pods.

Label each pod in the set with a unique key/value pair (for example, pi2-bookinfo-app-reviews2 = true).

Create an override values file for the Packet Inspector 2 filter instance#

Change to the Aspen Mesh release directory.
Change to the directory for the Packet Inspector 2 filter chart:
```
$ cd manifests/charts/packet-inspector-2-filter
```
Create an override values file for the Packet Inspector 2 filter instance by copying the Packet Inspector 2 filter values.yaml file to a new file (for example, pi2-override-values-bookinfo-app-reviews2.yaml):
```
$ cp values.yaml <instanceOverrideValuesFilename>
```
Open the override values file for the Packet Inspector 2 filter instance in a text editor.

Do you want to send captured traffic to a network analysis tool (not the analysis emulator)?

Yes:

Set the value of serviceFqdn to:

<networkAnalysisToolServiceName>.<networkAnalysisToolNamespaceName>.svc.cluster.local

Replace the placeholders:

Replace this placeholder	With
`<networkAnalysisToolServiceName>`	The network analysis tool’s Kubernetes service name
`<networkAnalysisToolServiceName>`	The namespace in which the network analysis tool is installed

Set the value of servicePort to the port on which the network analysis tool is listening.
Go to step 6.

No:
- Set the value of serviceFqdn to:
  
  packet-inspector-2-analysis-emulator.analysis-emulator.svc.cluster.local
- Set the value of servicePort to 9000.
- Go to step 6.

Do you want to capture HTTP traffic?
- Yes:
  - Make sure the value of .httpCapture.enabled is true.
  - Go to step 7.
- No:
  - Make sure the value of .httpCapture.enabled is false.
  - Go to step 7.
Do you want to capture Diameter traffic?
- Yes:
  - Make sure the value of .diameterCapture.enabled is true.
  - Make sure .diameterCapture.port specifies the port being used for Diameter traffic (typically 3868).
  - Go to step 8.
- No:
  - Make sure the value of .diameterCapture.enabled is false.
  - Go to step 8.
Read the comments for each remaining field and comment out or remove any unrequired fields that you don’t want to override.

Remember, if you want the Packet Inspector 2 filter instance to capture traffic from a set of labeled pods, you must add the key/value pair for the set under .workloadSelector.labels, as mentioned in Configuration overview for a Packet Inspector 2 filter instance.
Change the values of the remaining fields.
Save and close the file.
Move the override values file for the Packet Inspector 2 filter instance to a permanent location.

You’ll need access to this file when installing the Packet Inspector 2 filter instance, and you should keep the file under version control.

Install the Packet Inspector 2 filter instance#

Change to the Aspen Mesh release directory.

Install the Packet Inspector 2 filter instance:

$ helm install <packetInspector2FilterInstanceName> \
    manifests/charts/packet-inspector-2-filter \
    --namespace <instanceNamespaceName> \
    --values <instanceOverrideValuesFilename> \
    --wait

Capture traffic using the Packet Inspector 2 filter instance#

Use the analysis service (either the network analysis tool or the analysis emulator) to capture traffic using the Packet Inspector 2 filter instance.

Uninstall the Packet Inspector 2 filter instance#

Important

Perform this task after you’re finished capturing traffic.

Uninstall the Packet Inspector 2 filter instance:

$ helm uninstall <packetInspector2FilterInstanceName> \
    --namespace <instanceNamespaceName> \
    --wait

Troubleshooting#

Troubleshooting guide#

There are no packets being captured.

Verify that sidecar proxies are injected in workloads that should be capturing packets.

Uninstall Packet Inspector 2#

When to follow these instructions#

Follow the instructions below in the following cases:

When you no longer plan to use Packet Inspector 2
Before you upgrade Aspen Mesh

Perform the tasks in order.

Uninstall all Packet Inspector 2 filter instances#

Are any Packet Inspector 2 filter instances installed?

You can use the following command to determine whether any Packet Inspector 2 filter instances are installed:
```
$ kubectl get envoyfilters --all-namespaces | grep f5-tap-
```
- Yes: Uninstall each Packet Inspector 2 filter instance.
- No: Stop. All Packet Inspector 2 filter instances are uninstalled.

Uninstall the analysis emulator#

Uninstall the analysis emulator if you previously installed it:

$ helm uninstall pi2-analysis-emulator --namespace analysis-emulator --wait