Add packetcapture api

[hangyan]

Add packetcapture's API changes.

For the full feature, please ref to:

#5821

[hangyan]

moved API to this MR. Thanks you previous feedback and welcome to help review this again.

@luolanzone @tnqn @jianjuns @antoninbas

Accoding to #5821 (comment) . IPHeader field was removed.

[antoninbas]

I don't know how @jianjuns and @tnqn will feel about this, but since this is a new API, I think we should follow the K8s convention:

Therefore, we ask that pointers always be used with optional fields that do not have a built-in nil value.

It tends to lead to a lot of pointers, but it makes it clearer what is optional and what is not. When creating a resource with YAML, it makes no difference. When creating a resource in Go, we can use ptr.To from the K8s libraries to make initialization less verbose. What do you think?

[hangyan]

Agreed. There maybe a small problem if we upgrade to v1beta1 later to share the same structure with Traceflow though.

[antoninbas]

I'd rather do the best interface possible now for PacketCapture, and worry about unifying later.

If we have to introduce a new v1beta2 version for Traceflow, it should still be possible to define a conversion webhook to convert between v1beta1 and v1beta2, because of the semantics of the field?

[hangyan]

updated. Can you help review this change? I'm not very sure if i have done it right.

[tnqn]

I think @antoninbas means:

type UDPHeader struct {
	// SrcPort is the source port.
	SrcPort *int32 `json:"srcPort,omitempty"`
	// DstPort is the destination port.
	DstPort *int32 `json:"dstPort,omitempty"`
}

because they are optional.

[tnqn]

Just saw newer comments. Please ignore it.

[antoninbas]

I'd rather do the best interface possible now for PacketCapture, and worry about unifying later.

If we have to introduce a new v1beta2 version for Traceflow, it should still be possible to define a conversion webhook to convert between v1beta1 and v1beta2, because of the semantics of the field?

[antoninbas]

it looks like we are missing the srcIP / dstIP properties here?

[hangyan]

it's actually not missed, since we have a Source and Destination field in spec, so the srcIP/dstIP is not used. The golang structure still keep these fields in the PR, but i think we can removed them. The whole Packet structure has changed a lot during the review compared to the original one(==Traceflow's Packet strucuture).

[hangyan]

Updated this part. Currently the package related structure looks like this:

// Packet includes header info.
type Packet struct {
	IPv6Header      *IPv6Header     `json:"ipv6Header,omitempty"`
	TransportHeader TransportHeader `json:"transportHeader"`
}

Note: remove IPv4Header as it's unused and in another thread, we are discussing if a IPFamily field is needed.

Also in the TransportHeader, we have tcp/icmp/udp strcuture to allow user filter based on transport attributes. For icmp, we don't have any filter yet, so the strucutre is mainly used as a type indicator.

type ICMPEchoRequestHeader struct {
}

[hangyan]

cc @jianjuns @tnqn @luolanzone

Can you help review this MR again? Thank you

I will be actively working on this recently.

[antoninbas]

Is this field mutually exclusive with Namespace / Pod?

[hangyan]

not exactly. we don't have this kind of check now. This IP field is used for Pod->IP or IP->Pod filter case.

The only requirement is that at least one pod is specified.

[antoninbas]

So it would be valid to provide both a destination Pod and a destination IP (which don't match)?

[hangyan]

As long as there is one pod present(no matter whether it's in the source or destination), it will work(ignore the ip field in the same endpoint). I didn't add strict validation for the IP related case, not sure what's the best approach.

[hangyan]

since it's exclusive , i have added crd validation using oneOf in the yaml. User cannot provide ip and pod both in the source/dest struct in there CR.

[hangyan]

@antoninbas found a little problem with this whole omitempty thing.

4ef7a4b

Since i'm using oneOf to perform some validation in the crd, so the related field need to be set to omitempty wether they are pointer or value or not , or the validation will fail. (using yaml is fine, but golang struct is not, eg in tests code)

For example. If i want to use oneOf for source.ip/pod, means only one can be spcified. the following wont work

type Source struct {
	Namespace string `json:"namespace"`
	Pod string `json:"pod"`
	IP string `json:"ip"`
}

spec: crdv1alpha1.PacketCaptureSpec{
					Source: crdv1alpha1.Source{
						Namespace: "test-namespace",
						Pod:       "test-pod",
					},

since there is no omitempty it's actually:

spec: crdv1alpha1.PacketCaptureSpec{
					Source: crdv1alpha1.Source{
						Namespace: "test-namespace",
						Pod:       "test-pod",
                                                IP:         "",
					},

So the oneOf validation will fail. The solution would be change every affected field (including pod) to pointer + omitempty. or keep as value + omitempty. If not set, it won't show up.

Currently i kept the value format and add some of the omitempty tag back, as change to pointer would require some changes on the current codebase. If you still felt this is needed ( > pointer), i can update this later.

[antoninbas]

I feel like we should have the option to write the pcap to a local file as well, just for ease of use / testing
Not everyone will want to have an ftp server for this

[hangyan]

So do you think keep the files in container is enough? Since this is not a cli, it would be odd to export the files to a location on the host.

If keep it in the container, filepath + container name should be ok?

[antoninbas]

If keep it in the container, filepath + container name should be ok

Just filepath I think, the container will always be antrea-agent? If users want the file to be on the Node, they can provide a path that is mounted from the host, such as /var/log/antrea.

But there would need to be a way for users to figure out which antrea-agent Pod has the capture file, so that would need to be included in the Status. Are packets captured at the source or the destination or both?

[hangyan]

Both could happen, in the source or destination. pod name can be exposed in the status. Just need to think about the value format for the filepath field.

[antoninbas]

I know I suggested pointers for this originally. Given more recent discussions, I don't really feel strongly about it anymore, so given that 0 is not a valid port number typically, I would be ok with removing the pointers. I'll let @tnqn chime in as well.

[hangyan]

temporary reset to int32 type.

[tnqn]

My first impression is this should have a pointer because it's optional. if header.SrcPort != nil is the condition in which we should capture specifc source port only, right?

[hangyan]

yes, it's optional. sounds more reasonable to set it as pointer.

[jianjuns]

Is it possible to share some types/constants with Traceflow?

[hangyan]

also see discussion #6257 (comment)

for the constants part i think it's unnecessary, each CRD may have more different status in the future.

About types, since Traceflow is in vebeta1 now, are you suggesting we define some common types in neutral place?

[jianjuns]

I am not sure if we should define common types across versions. Let us see if @tnqn and @antoninbas have an opinion.

[antoninbas]

I guess in theory we could have common definitions in a neutral directory, it wouldn't need to be under apis/crd/<version>. But if it's not a versioned directory, then we would have to be confident that they are not going to change.

K8s has meta/v1 with comm types, such as Time. I don't know how good of an analogy it is.

[tnqn]

Except those meta types in meta/v1. K8s doesn't define common types across versions. If a constant needs to be used by a version, it will just be replicated in that version. I think it's to keep every version's stability and compatability. Otherwise a change in one version would have an impact on other versions.

[hangyan]

@jianjuns Do you think we can add a ip family and ip protocol field? so we can remove ipv6header and icmpheader.

[jianjuns]

@jianjuns Do you think we can add a ip family and ip protocol field? so we can remove ipv6header and icmpheader.

That works for me, if you do not see a potential requirement to support other IP header fields, esp. v4 or v6 specific fields.
And I meant to use intstr.IntOrString for protocol.

[hangyan]

@jianjuns Do you think we can add a ip family and ip protocol field? so we can remove ipv6header and icmpheader.

That works for me, if you do not see a potential requirement to support other IP header fields, esp. v4 or v6 specific fields. And I meant to use intstr.IntOrString for protocol.

updated.

[jianjuns]

I am not sure if we should define common types across versions. Let us see if @tnqn and @antoninbas have an opinion.

[tnqn]

I think @antoninbas means:

type UDPHeader struct {
	// SrcPort is the source port.
	SrcPort *int32 `json:"srcPort,omitempty"`
	// DstPort is the destination port.
	DstPort *int32 `json:"dstPort,omitempty"`
}

because they are optional.

[tnqn]

Except those meta types in meta/v1. K8s doesn't define common types across versions. If a constant needs to be used by a version, it will just be replicated in that version. I think it's to keep every version's stability and compatability. Otherwise a change in one version would have an impact on other versions.

[hangyan]

@antoninbas @jianjuns @tnqn

Any new comments?