Add hubble observe flags reference docs

[kimstacy]

Hello! 👋

Hubble CLI produces a beautifully documented output. I was wondering if it'd be useful to document the hubble observe commands and/or flags at the surface level? This could be in cilium/hubble or the reference area of docs.cilium.io.

We could either manually create the documentation or automate its generation. I'd be willing to maintain the documentation if it'd be helpful. I'm less familiar with doc-generating scripts so I'm biased towards manually transferring the information since it'd be easier to customize. I'm open to anyone's thoughts.

❯ hubble observe --help
Observe flows and events of a Hubble server

Usage:
  hubble observe [flags]
  hubble observe [command]

Available Commands:
  agent-events Observe Cilium agent events
  debug-events Observe Cilium debug events
  flows        Observe flows of a Hubble server

Selectors Flags:
      --all            Get all flows stored in Hubble's buffer. Note: this option may cause Hubble to return a lot of data. It is recommended to only use it along filters to limit the amount of data returned.
      --first uint     Get first N flows stored in Hubble's buffer. When querying against Hubble Relay, this gets N flows per instance of Hubble connected to that Relay.
  -f, --follow         Follow flows output
      --last uint      Get last N flows stored in Hubble's buffer (default 20). When querying against Hubble Relay, this gets N flows per instance of Hubble connected to that Relay.
      --since string   Filter flows since a specific date. The format is relative (e.g. 3s, 4m, 1h43,, ...) or one of:
                         StampMilli:             Jan _2 15:04:05.000
                         YearMonthDay:           2006-01-02
                         YearMonthDayHour:       2006-01-02T15-07:00
                         YearMonthDayHourMinute: 2006-01-02T15:04-07:00
                         RFC3339:                2006-01-02T15:04:05-07:00
                         RFC3339Milli:           2006-01-02T15:04:05.999-07:00
                         RFC3339Micro:           2006-01-02T15:04:05.999999-07:00
                         RFC3339Nano:            2006-01-02T15:04:05.999999999-07:00
                         RFC1123Z:               Mon, 02 Jan 2006 15:04:05 -0700

      --until string   Filter flows until a specific date. The format is relative (e.g. 3s, 4m, 1h43,, ...) or one of:
                         StampMilli:             Jan _2 15:04:05.000
                         YearMonthDay:           2006-01-02
                         YearMonthDayHour:       2006-01-02T15-07:00
                         YearMonthDayHourMinute: 2006-01-02T15:04-07:00
                         RFC3339:                2006-01-02T15:04:05-07:00
                         RFC3339Milli:           2006-01-02T15:04:05.999-07:00
                         RFC3339Micro:           2006-01-02T15:04:05.999999-07:00
                         RFC3339Nano:            2006-01-02T15:04:05.999999999-07:00
                         RFC1123Z:               Mon, 02 Jan 2006 15:04:05 -0700


Filters Flags:
      --fqdn filter                Show all flows related to the given fully qualified domain name (e.g. "*.cilium.io").
      --from-fqdn filter           Show all flows originating at the given fully qualified domain name (e.g. "*.cilium.io").
      --from-identity filter       Show all flows originating at an endpoint with the given security identity
      --from-ip filter             Show all flows originating at the given IP address. Each of the source IPs can be specified as an exact match (e.g. '1.1.1.1') or as a CIDR range (e.g.'1.1.1.0/24').
      --from-label filter          Show only flows originating in an endpoint with the given labels (e.g. "key1=value1", "reserved:world")
      --from-namespace filter      Show all flows originating in the given Kubernetes namespace.
      --from-pod filter            Show all flows originating in the given pod name prefix([namespace/]<pod-name>). If namespace is not provided, 'default' is used
      --from-port filter           Show only flows with the given source port (e.g. 8080)
      --from-service filter        Shows flows where the source IP address matches the ClusterIP address of the given service name prefix([namespace/]<svc-name>). If namespace is not provided, 'default' is used
      --from-workload filter       Show all flows originating at an endpoint with the given workload
      --http-method filter         Show only flows which match this HTTP method (e.g. "get", "post")
      --http-path filter           Show only flows which match this HTTP path regular expressions (e.g. "/page/\\d+")
      --http-status filter         Show only flows which match this HTTP status code prefix (e.g. "404", "5+")
      --identity filter            Show all flows related to an endpoint with the given security identity
      --ip filter                  Show all flows related to the given IP address. Each of the IPs can be specified as an exact match (e.g. '1.1.1.1') or as a CIDR range (e.g.'1.1.1.0/24').
      --ip-version filter          Show only IPv4, IPv6 flows or non IP flows (e.g. ARP packets) (ie: "none", "v4", "v6")
  -4, --ipv4 filter[=v4]           Show only IPv4 flows
  -6, --ipv6 filter[=v6]           Show only IPv6 flows
  -l, --label filter               Show only flows related to an endpoint with the given labels (e.g. "key1=value1", "reserved:world")
  -n, --namespace filter           Show all flows related to the given Kubernetes namespace.
      --node-name filter           Show all flows which match the given node names (e.g. "k8s*", "test-cluster/*.company.com")
      --not filter[=true]          Reverses the next filter to be blacklist i.e. --not --from-ip 2.2.2.2
      --pod filter                 Show all flows related to the given pod name prefix ([namespace/]<pod-name>). If namespace is not provided, 'default' is used.
      --port filter                Show only flows with given port in either source or destination (e.g. 8080)
      --protocol filter            Show only flows which match the given L4/L7 flow protocol (e.g. "udp", "http")
      --service filter             Shows flows where either the source or destination IP address matches the ClusterIP address of the given service name prefix ([namespace/]<svc-name>). If namespace is not provided, 'default' is used.
      --tcp-flags filter           Show only flows which match the given TCP flags (e.g. "syn", "ack", "fin")
      --to-fqdn filter             Show all flows terminating at the given fully qualified domain name (e.g. "*.cilium.io").
      --to-identity filter         Show all flows terminating at an endpoint with the given security identity
      --to-ip filter               Show all flows terminating at the given IP address. Each of the destination IPs can be specified as an exact match (e.g. '1.1.1.1') or as a CIDR range (e.g.'1.1.1.0/24').
      --to-label filter            Show only flows terminating in an endpoint with given labels (e.g. "key1=value1", "reserved:world")
      --to-namespace filter        Show all flows terminating in the given Kubernetes namespace.
      --to-pod filter              Show all flows terminating in the given pod name prefix([namespace/]<pod-name>). If namespace is not provided, 'default' is used
      --to-port filter             Show only flows with the given destination port (e.g. 8080)
      --to-service filter          Shows flows where the destination IP address matches the ClusterIP address of the given service name prefix ([namespace/]<svc-name>). If namespace is not provided, 'default' is used
      --to-workload filter         Show all flows terminating at an endpoint with the given workload
      --trace-id filter            Show only flows which match this trace ID
      --traffic-direction filter   Show all flows in the given traffic direction (either ingress or egress)
  -t, --type filter                Filter by event types TYPE[:SUBTYPE]. Available types and subtypes:
                                   TYPE             SUBTYPE
                                   capture          n/a
                                   drop             n/a
                                   l7               n/a
                                   policy-verdict   n/a
                                   trace            from-endpoint
                                                    from-host
                                                    from-network
                                                    from-overlay
                                                    from-proxy
                                                    from-stack
                                                    to-endpoint
                                                    to-host
                                                    to-network
                                                    to-overlay
                                                    to-proxy
                                                    to-stack
                                   trace-sock       n/a
      --uuid filter                Show the only flow matching this unique flow identifier, if any
      --verdict filter             Show only flows with this verdict [FORWARDED, DROPPED, AUDIT, REDIRECTED, ERROR, TRACED, TRANSLATED]
      --workload filter            Show all flows related to an endpoint with the given workload

Raw-Filters Flags:
      --allowlist stringArray   Specify allowlist as JSON encoded FlowFilters
      --denylist stringArray    Specify denylist as JSON encoded FlowFilters

Formatting Flags:
  -o, --output string        Specify the output format, one of:
                               compact:  Compact output
                               dict:     Each flow is shown as KEY:VALUE pair
                               jsonpb:   JSON encoded GetFlowResponse according to proto3's JSON mapping
                               json:     Alias for jsonpb
                               table:    Tab-aligned columns
                              (default "compact")
      --print-node-name      Print node name in output
      --time-format string   Specify the time format for printing. This option does not apply to the json and jsonpb output type. One of:
                               StampMilli:             Jan _2 15:04:05.000
                               YearMonthDay:           2006-01-02
                               YearMonthDayHour:       2006-01-02T15Z07:00
                               YearMonthDayHourMinute: 2006-01-02T15:04Z07:00
                               RFC3339:                2006-01-02T15:04:05Z07:00
                               RFC3339Milli:           2006-01-02T15:04:05.999Z07:00
                               RFC3339Micro:           2006-01-02T15:04:05.999999Z07:00
                               RFC3339Nano:            2006-01-02T15:04:05.999999999Z07:00
                               RFC1123Z:               Mon, 02 Jan 2006 15:04:05 -0700
                               (default "StampMilli")

Flow Format Flags:
      --color string     Colorize the output when the output format is one of 'compact' or 'dict'. The value is one of 'auto' (default), 'always' or 'never' (default "auto")
      --ip-translation   Translate IP addresses to logical names such as pod name, FQDN, ... (default true)
      --numeric          Display all information in numeric form

Server Flags:
      --basic-auth-password string    Specify a password for basic auth
      --basic-auth-username string    Specify a username for basic auth
      --server string                 Address of a Hubble server. Ignored when --input-file is provided. (default "localhost:4245")
      --timeout duration              Hubble server dialing timeout (default 5s)
      --tls                           Specify that TLS must be used when establishing a connection to a Hubble server.
                                      By default, TLS is only enabled if the server address starts with 'tls://'.
      --tls-allow-insecure            Allows the client to skip verifying the server's certificate chain and host name.
                                      This option is NOT recommended as, in this mode, TLS is susceptible to machine-in-the-middle attacks.
                                      See also the 'tls-server-name' option which allows setting the server name.
      --tls-ca-cert-files strings     Paths to custom Certificate Authority (CA) certificate files.The files must contain PEM encoded data.
      --tls-client-cert-file string   Path to the public key file for the client certificate to connect to a Hubble server (implies TLS).
                                      The file must contain PEM encoded data.
      --tls-client-key-file string    Path to the private key file for the client certificate to connect a Hubble server (implies TLS).
                                      The file must contain PEM encoded data.
      --tls-server-name string        Specify a server name to verify the hostname on the returned certificate (eg: 'instance.hubble-relay.cilium.io').

Other Flags:
      --experimental-field-mask strings        Experimental: Comma-separated list of fields for mask. Fields not in the mask will be removed from server response.
      --experimental-use-default-field-masks   Experimental: request only visible fields when the output format is compact, tab, or dict.
      --input-file string                      Query flows from this file instead of the server. Use '-' to read from stdin.
      --print-raw-filters                      Print allowlist/denylist filters and exit without sending the request to Hubble server
  -s, --silent-errors                          Silently ignores errors and warnings

OIDC Flags:
      --issuer-ca string    CA to validate OIDC issuer against.
      --token-file string   Path to a file that contains an authentication token to pass along when doing requests.
      --token-type string   Define the type of token that is expected in specified token file. (default "Bearer")

Aggregation Flags:
      --aggregate strings                  Apply aggregation logic before returning list of flows. Valid options: identity and connection.
      --aggregate-ignore-source-port       Ignore source port when aggregating.
      --aggregation-state-filter strings   The state changes to include while aggregating (default [new,first_error,error,closed])
      --aggregation-ttl duration           TTL to use when aggregating. Set to 0 to only see a flow once for each state change, or non-zero to see non-state changes periodically.

Global Flags:
      --config string   Optional config file (default "/Users/stacy/Library/Application Support/hubble/config.yaml")
  -D, --debug           Enable debug messages

Get help:
  -h, --help	Help for any command or subcommand

Use "hubble observe [command] --help" for more information about a command.