package goldmane

Get desktop application:
View/edit binary Protocol Buffers messages

FlowCollector provides APIs capable of receiving streams of Flow data from cluster nodes.

• rpc Connect (stream FlowUpdate, stream FlowReceipt)

  api.proto:276

  Connect receives a connection that may stream one or more FlowUpdates. A FlowReceipt is returned to the client by the server after each FlowUpdate. Following a connection or reconnection to the server, clients should duplicates of previously transmitted FlowsUpdates in order to allow the server to rebuild its cache, as well as any new FlowUpdates that have not previously been transmitted. The server is responsible for deduplicating where needed.

  message FlowUpdate

  api.proto:283

  FlowUpdate wraps a Flow with additional metadata.

  • optional Flow flow = 1

    Flow contains the actual flow being sent.

  message FlowReceipt

  api.proto:280

  FlowReceipt is a response from the server to a client after publishing a Flow.

  (message has no fields)

Flows provides APIs for querying aggregated Flow data. The returned Flows will be aggregated across cluster nodes, as well as the specified aggregation time interval.

• rpc List (FlowListRequest, FlowListResult)

  api.proto:13

  List is an API call to query for one or more Flows.

  message FlowListRequest

  api.proto:26

  FlowListRequest defines a message to request a particular selection of aggregated Flow objects.

  • int64 start_time_gte = 1

    StartTimeGt specifies the beginning of a time window with which to filter Flows. Flows will be returned only if their start time is greater than or equal to the given value. - A value of zero indicates the oldest start time available by the server. - A value greater than zero indicates an absolute time in seconds since the Unix epoch. - A value less than zero indicates a relative number of seconds from "now", as determined by the server.

  • int64 start_time_lt = 2

    StartTimeLt specifies the end of a time window with which to filter flows. Flows will be returned only if their start time occurs before the requested time. - A value of zero means "now", as determined by the server at the time of request. - A value greater than zero indicates an absolute time in seconds since the Unix epoch. - A value less than zero indicates a relative number of seconds from "now", as determined by the server.

  • int64 page = 3

    Page specifies the page to return. It requires that PageSize is also specified in order to determine page boundaries. Note that pages may change over time as new flow data is collected or expired. Querying the same page at different points in time may return different results.

  • int64 page_size = 4

    PageSize configures the maximum number of results to return as part of this query.

  • repeated SortOption sort_by = 5

    SortBy configures how to sort the results of this query. By default flows are sorted by start time. The returned list is sorted by each sort option, in order, using the next sort option in the list as a tie-breaker. Note: At the moment, only a single sort option is supported.

  • optional Filter filter = 6

    Filter allows specification of one or more criteria on which to filter the returned Flows.

  • int64 aggregation_interval = 7

    AggregationInterval is the width of the time window in seconds across which to aggregate when generating Flows to return. This must be a multiple of 15.

  message FlowListResult

  api.proto:65

  FlowListResult is a message containing a list of FlowResults and ListMetadata.

  • optional ListMetadata meta = 1

    Meta specifies metadata about the returned flows.

  • repeated FlowResult flows = 2

    Flows is a list of FlowResult objects.

• rpc Stream (FlowStreamRequest, stream FlowResult)

  api.proto:16

  Stream is an API call to return a long running stream of new Flows as they are generated.

  message FlowStreamRequest

  api.proto:74

  FlowStreamRequest defines a message to request a stream of aggregated Flows.

  • int64 start_time_gte = 1

    StartTimeGt specifies the beginning of a time window from which to stream Flows. Flows will be streamed only if their start time is greater than or equal to the given value. - A value of zero means "now", as determined by the server at the time of request. - A value greater than zero indicates an absolute time in seconds since the Unix epoch. - A value less than zero indicates a relative number of seconds from "now", as determined by the server.

  • optional Filter filter = 2

    Filter allows specification of one or more criteria on which to filter the returned Flows.

  • int64 aggregation_interval = 3

    AggregationInterval defines both the frequency of streamed updates for each Flow, and the amount of time that FlowResult covers. It must always be 15s. Every AggregationInterval the server must send a FlowResult containing the aggregated data for that Flow from a time interval of width AggregationInterval. For a Flow that has continuous traffic, the server should send updates covering the range [now-2*AggregationInterval, now-AggregationInterval] so that the data is reasonably likely to be complete.

• rpc FilterHints (FilterHintsRequest, FilterHintsResult)

  api.proto:22

  FilterHints can be used to discover available filter criteria, such as Namespaces and source / destination names. It allows progressive filtering of criteria based on other filters. i.e., return the flow destinations given a source namespace. Note that this API provides hints to the UI based on past flows and other values may be valid.

  message FilterHintsRequest

  api.proto:97

  • FilterType type = 1

    Type is type of Filter to query.

  • optional Filter filter = 2

    Filter is a set of filter criteria used to narrow down returned results.

  • int64 start_time_gte = 3

    StartTimeGt specifies the beginning of a time window with which to filter (inclusive). - A value of zero indicates the oldest start time available by the server. - A value greater than zero indicates an absolute time in seconds since the Unix epoch. - A value less than zero indicates a relative number of seconds from "now", as determined by the server.

  • int64 start_time_lt = 4

    StartTimeLt specifies the end of a time window with which to filter. - A value of zero means "now", as determined by the server at the time of request. - A value greater than zero indicates an absolute time in seconds since the Unix epoch. - A value less than zero indicates a relative number of seconds from "now", as determined by the server.

  • int64 page = 5

    Page specifies the page number to return. It requires that PageSize is also specified in order to determine page boundaries. Note that pages may change over time as new flow data is collected or expired. Querying the same page at different points in time may return different results.

  • int64 page_size = 6

    PageSize configures the maximum number of results to return as part of this query.

  message FilterHintsResult

  api.proto:127

  • optional ListMetadata meta = 1

    ListMetadata specifies list information about the flows returned.

  • repeated FilterHint hints = 2

    FilterHint contains the values that flows can be filtered on.

Statistics provides APIs for retrieving Flow statistics.

• rpc List (StatisticsRequest, stream StatisticsResult)

  api.proto:467

  List returns statistics data for the given request. One StatisticsResult will be returned for each matching PolicyHit and direction over the timeframe, containing time-series data covering the provided time range.

  message StatisticsRequest

  api.proto:485

  • int64 start_time_gte = 1

    The start time from which to collect statistics (inclusive). - A value of zero indicates the oldest start time available by the server. - A value greater than zero indicates an absolute time in seconds since the Unix epoch. - A value less than zero indicates a relative number of seconds from "now", as determined by the server.

  • int64 start_time_lt = 2

    The end time indicates the end of the windows from which to collect statistics. - A value of zero means "now", as determined by the server at the time of request. - A value greater than zero indicates an absolute time in seconds since the Unix epoch. - A value less than zero indicates a relative number of seconds from "now", as determined by the server.

  • StatisticType type = 3

    Type is the type of statistic to return. e.g., packets, bytes, etc.

  • StatisticsGroupBy group_by = 4

    Configure statistics aggregation. - Policy: each StatisticsResult will contain statistics for a particular policy. - PolicyRule: each StatisticsResult will contain statistics for a particular policy rule. - Any: return both per-Policy and per-PolicyRule results.

  • optional PolicyMatch policy_match = 5

    Optionally configure fields to filter results. If provided, any policies not matching the PolicyMatch will be omitted from the results.

  • bool time_series = 6

    TimeSeries configures whether or not to return time-series data in the response. If true, the response will include multiple datapoints over the given time window. If false, data across the time window will be aggregated into a single data point.

  message StatisticsResult

  api.proto:525

  • optional PolicyHit policy = 1

    Policy identifies the policy / rule for which this data applies. Its meaning is contextualized by the GroupBy field. - StatisticsGroupBy_Policy: this field represents the specific Policy, and statistics are aggregated across all rules within that policy. Rule identifiers (Action, RuleID) will be omitted. - StatisticsGroupBy_PolicyRule: this field identifies a specific rule within a Policy, and statistics are scoped to that particular rule.

  • RuleDirection direction = 2

    For statistics results targeting a specific policy rule, the direction contextualizes the rule ID as either an ingress or egress rule. For statistics results grouped by policy, both ingress and egress statistics will be included.

  • StatisticsGroupBy group_by = 3

    GroupBy indicates whether the statistics in this result are aggregated for a policy, or for a specific rule within that policy.

  • StatisticType type = 4

    Type indicates the type of data carried in this result. e.g., PacketCount vs ByteCount.

  • repeated int64 allowed_in = 5

    AllowedIn contains the count of the requested statistic that was allowed for ingress flows. The semantic meaning (e.g., packets vs bytes) is indicated by the Type field.

  • repeated int64 allowed_out = 6

  • repeated int64 denied_in = 7

  • repeated int64 denied_out = 8

  • repeated int64 passed_in = 9

  • repeated int64 passed_out = 10

  • repeated int64 x = 11

    X is the x axis of the data for time-series data. i.e., the timestamp. For non-timeseries data, this will be nil.

Used in: Filter, FlowKey, PolicyHit, PolicyMatch

• ActionUnspecified = 0

• Allow = 1

• Deny = 2

• Pass = 3

Used in: FlowKey

• EndpointTypeUnspecified = 0

  For queries, unspecified means "do not filter on this field".

• WorkloadEndpoint = 1

  WorkloadEndpoint represents an application endpoint with its own network identity. For example, a Kubernetes Pod.

• HostEndpoint = 2

  HostEndpoint represents a host machine.

• NetworkSet = 3

  NetworkSet represents an address from within a configured projectcalico.org/v3 NetworkSet or GlobalNetworkSet.

• Network = 4

  Network represents an endpoint on a public or private network not known by Calico. For example, traffic from the public internet or private LAN not covered by a NetworkSet.

Filter defines criteria for selecting a set of Flows based on their parameters.

Used in: FilterHintsRequest, FlowListRequest, FlowStreamRequest

• repeated StringMatch source_names = 1

  SourceNames allows filtering on the source name field. Combined using logical OR.

• repeated StringMatch source_namespaces = 2

  SourceNamespaces filters on the source namespace field. Combined using logical OR.

• repeated StringMatch dest_names = 3

  DestNames filters on the destination name field. Combined using logical OR.

• repeated StringMatch dest_namespaces = 4

  DestNamespaces filters on the destination namespace field. Combined using logical OR.

• repeated StringMatch protocols = 5

  Protocols filters on the protocol field. Combined using logical OR.

• repeated PortMatch dest_ports = 6

  DestPorts filters on the port field. Combined using logical OR.

• repeated Action actions = 7

  Actions filters on the action field. Combined using logical OR.

• repeated PolicyMatch policies = 8

  Policies matches on policy fields. Combined using logical OR.

Used in: FilterHintsResult

• string value = 1

FilterType specifies which fields on the underlying Flow data to collect.

Used in: FilterHintsRequest

• FilterTypeUnspecified = 0

• FilterTypeDestName = 1

• FilterTypeSourceName = 2

• FilterTypeDestNamespace = 3

• FilterTypeSourceNamespace = 4

• FilterTypePolicyTier = 5

• FilterTypePolicyName = 6

Flow is a message representing statistics gathered about connections that share common fields, aggregated across either time, nodes, or both.

Used in: FlowResult, FlowUpdate

• optional FlowKey Key = 1

  Key includes the identifying fields for this flow.

• int64 start_time = 2

  StartTime is the start time for this flow. It is represented as the number of seconds since the UNIX epoch.

• int64 end_time = 3

  EndTime is the end time for this flow. It is always at least one aggregation interval after the start time.

• repeated string source_labels = 4

  SourceLabels contains the intersection of labels that appear on all source pods that contributed to this flow.

• repeated string dest_labels = 5

  SourceLabels contains the intersection of labels that appear on all destination pods that contributed to this flow.

• int64 packets_in = 6

  Statistics.

• int64 packets_out = 7

• int64 bytes_in = 8

• int64 bytes_out = 9

• int64 num_connections_started = 10

  NumConnectionsStarted tracks the total number of new connections recorded for this Flow. It counts each connection attempt that matches the FlowKey that was made between this Flow's StartTime and EndTime.

• int64 num_connections_completed = 11

  NumConnectionsCompleted tracks the total number of completed TCP connections recorded for this Flow. It counts each connection that matches the FlowKey that was completed between this Flow's StartTime and EndTime.

• int64 num_connections_live = 12

  NumConnectionsLive tracks the total number of still active connections recorded for this Flow. It counts each connection that matches the FlowKey that was active at this Flow's EndTime.

FlowKey includes the identifying fields for a Flow. - Source: Name, namespace, type, and labels. - Destination: Name, namespace, type, labels and port - Action taken on the connection. - Reporter (i.e., measured at source or destination). - Protocol of the connection (TCP, UDP, etc.).

Used in: Flow

• string source_name = 1

  SourceName is the name of the source for this Flow. The value is contextualized by the source_type field: - For WorkloadEndpoint, this represents a set of pods that share a GenerateName. - For HostEndpoint, this is the host endpoint name. - For NetworkSet, it is the name of the network set. - For Network, this is either "pub" for a public network, or "pvt" for a private network.

• string source_namespace = 2

  SourceNamespace is the namespace of the source pods for this flow.

• EndpointType source_type = 3

  SourceType is the type of the source, used to contextualize the source name and namespace fields.

• string dest_name = 4

  DestName is the name of the destination for this Flow. The value is contextualized by the source_type field: - For WorkloadEndpoint, this represents a set of pods that share a GenerateName. - For HostEndpoint, this is the host endpoint name. - For NetworkSet, it is the name of the network set. - For Network, this is either "pub" for a public network, or "pvt" for a private network.

• string dest_namespace = 5

  DestNamespace is the namespace of the destination pods for this flow.

• EndpointType dest_type = 6

  DestType is the type of the destination, used to contextualize the dest name and namespace fields.

• int64 dest_port = 7

  DestPort is the destination port on the specified protocol accessed by this flow.

• string dest_service_name = 8

  DestServiceName is the name of the destination service, if any.

• string dest_service_namespace = 9

  DestServiceNamespace is the namespace of the destination service, if any.

• string dest_service_port_name = 10

  DestServicePortName is the name of the port on the destination service, if any.

• int64 dest_service_port = 11

  DestServicePort is the port number on the destination service.

• string proto = 12

  Proto is the L4 protocol for this flow. For example, TCP, UDP, SCTP, ICMP.

• Reporter reporter = 13

  Reporter is either "src" or "dst", depending on whether this flow was generated at the initiating or terminating end of the connection attempt.

• Action action = 14

  Action is the ultimate action taken on the flow.

• optional PolicyTrace policies = 15

  Policies includes an entry for each policy rule that took an action on the connections aggregated into this flow.

FlowResult wraps a Flow object with additional metadata.

Used as response type in: Flows.Stream

Used as field type in: FlowListResult

• int64 id = 1

  ID is an opaque integer value ID that can be used to identify a Flow, and is 1:1 with the FlowKey. Note that this ID is not valid across server restarts. Its primary use-case is for correlating FlowResult updates from a Stream request.

• optional Flow flow = 2

  The Flow object itself.

ListMetadata contains information about a returned list of items, such as pagination information (total number of pages and total number of results).

Used in: FilterHintsResult, FlowListResult

• int64 totalPages = 1

  totalPages is the total number of pages that exist given that a pageSize was specified.

• int64 totalResults = 2

  TotalResults are the total number of results that would have been returned if no pagination was specified.

Used in: StringMatch

• Exact = 0

  Match the value exactly.

• Fuzzy = 1

  Use fuzzy matching on the value.

PolicyHit represents a policy rule that was traversed by this flow. It can be either an enforced policy hit from the dataplane, or a staged policy hit that is not yet active.

Used in: PolicyTrace, StatisticsResult

• PolicyKind kind = 1

  Kind corresponds to the resource Kind for the policy.

• string namespace = 2

  Namespace is the Kubernetes namespace of the Policy, if namespaced. It is empty for global / cluster-scoped policy kinds.

• string name = 3

  Name is the Name of the policy object.

• string tier = 4

  Tier is the Tier of the policy object.

• Action action = 5

  Action is the action taken by this policy rule.

• int64 policy_index = 6

  PolicyIndex is the order of the Policy among all policies traversed.

• int64 rule_index = 7

  RuleIndex is the order of the Rule within the Policy rules.

• optional PolicyHit trigger = 8

  Trigger indicates the first policy that selected this Flow and thus triggered the tier's end-of-tier action. This is only valid for kind=EndOfTier, and is nil otherwise.

Used in: PolicyHit, PolicyMatch

• KindUnspecified = 0

  Unspecified

• CalicoNetworkPolicy = 1

  Calico policy types.

• GlobalNetworkPolicy = 2

• StagedNetworkPolicy = 3

• StagedGlobalNetworkPolicy = 4

• StagedKubernetesNetworkPolicy = 5

• NetworkPolicy = 6

  Native Kubernetes types.

• AdminNetworkPolicy = 7

• BaselineAdminNetworkPolicy = 8

• Profile = 9

  Calico Profiles.

• EndOfTier = 10

PolicyMatch defines criteria for matching one or more policy rules within a Flow's policy trace.

Used in: Filter, StatisticsRequest

• PolicyKind kind = 1

• string tier = 2

• string namespace = 3

• string name = 4

• Action action = 5

Used in: FlowKey

• repeated PolicyHit enforced_policies = 1

  EnforcedPolicies shows the active dataplane policy rules traversed by this Flow.

• repeated PolicyHit pending_policies = 2

  PendingPolicies shows the expected policy rules traversed by this Flow when including staged policies.

Used in: Filter

• int64 port = 1

Used in: FlowKey

• ReporterUnspecified = 0

  For queries, unspecified means "do not filter on this field".

• Src = 1

• Dst = 2

Used in: StatisticsResult

• Any = 0

• Ingress = 1

• Egress = 2

Used in: SortOption

• Time = 0

• DestName = 1

• DestNamespace = 2

• DestType = 3

• SourceName = 4

• SourceNamespace = 5

• SourceType = 6

Used in: FlowListRequest

• SortBy sort_by = 1

  SortBy declares the field by which to sort.

StatisticType represents the types of data available over the Statistics API endpoint.

Used in: StatisticsRequest, StatisticsResult

• PacketCount = 0

• ByteCount = 1

• LiveConnectionCount = 2

Used in: StatisticsRequest, StatisticsResult

• Policy = 0

  Policy configures statistics groupings on a per-policy basis.

• PolicyRule = 1

  PolicyRule configures statistics groupings on a per-policy-rule basis.

Used in: Filter

• string value = 1

• MatchType type = 2