# Kubernetes Discovery

## Kubernetes

### Description

`gm-control kubernetes` is used to discover services instances in Kubernetes from pod tags and selectors.

### Usage

`gm-control [GLOBAL OPTIONS] kubernetes [OPTIONS]`

### Help

To list available commands run with the global help flag, `gm-control kubernetes --help`:

```bash
$ gm-control kubernetes --help
NAME
    kubernetes - kubernetes collector

USAGE
    gm-control [GLOBAL OPTIONS] kubernetes [OPTIONS]

VERSION
    1.0.3-dev

DESCRIPTION
    Connects to a Kubernetes cluster API server and updates Clusters stored in the Greymatter API at startup and periodically thereafter. By default, the tool assumes that it is being run within the Kubernetes cluster and will automatically find the API server.

    Pod labels are used to determine to which API cluster a particular pod belongs. The default label name is "gm_cluster", but it may be overridden by command line flags (see -cluster-label). By default all pods in the configured namespace(s) are watched, but you
    may also provide a label selector (using the same format at the kubectl command) to specify a subset of pods to watch.

    In each pod, all containers must be running before the pod is considered live and ready for inclusion in the API cluster's instance list. Each container is examined for ports. The first TCP port found is used as the API instance's port unless a port name is
    specified (see -port-name), in which case the first port with that name becomes the API instance's port. Pods with no container port are ignored. All pod labels (except for the cluster label) are attached as instance metadata.

GLOBAL OPTIONS
    --api.header=header
            Specifies a custom header to send with every gm-control request. Headers are given as name:value pairs. Leading and trailing whitespace will be stripped from the name and value. For multiple headers, this flag may be repeated or multiple headers can be
            delimited with commas.

    --api.host=host:port
            (default: localhost:80)
            The address (host:port) for gm-control requests. If no port is given, it defaults to port 443 if --api.ssl is true and port 80 otherwise.

    --api.insecure
            (default: false)
            If true, don't validate server cert when using SSL for gm-control requests

    --api.key=string
            (default: "none")
            [SENSITIVE] The auth key for gm-control requests

    --api.prefix=value
            The url prefix for gm-control requests. Forms the path part of <host>:<port><path>

    --api.ssl
            (default: true)
            If true, use SSL for gm-control requests

    --api.sslCert=value
            Specifies the SSL cert to use for every gm-control request.

    --api.sslKey=value
            Specifies the SSL key to use for every gm-control request.

    --api.zone-name=string
            The name of the API Zone for gm-control requests.

    --console.level=level
            (default: "info")
            (valid values: "debug", "info", "error", or "none")
            Selects the log level for console logs messages.

    --delay=duration
            (default: 30s)
            Sets the minimum time between API updates. If the discovery data changes more frequently than this duration, updates are delayed to maintain the minimum time.

    --diff.dry-run
            (default: false)
            Log changes at the info level rather than submitting them to the API

    --diff.ignore-create
            (default: false)
            If true, do not create new Clusters in the API

    --diff.include-delete
            (default: false)
            If true, delete missing Clusters from the API

    --help  (default: false)
            Show a list of commands or help for one command

    --stats.api.header=header
            Specifies a custom header to send with every stats API request. Headers are given as name:value pairs. Leading and trailing whitespace will be stripped from the name and value. For multiple headers, this flag may be repeated or multiple headers can be
            delimited with commas.

    --stats.api.host=host:port
            (default: localhost:80)
            The address (host:port) for stats API requests. If no port is given, it defaults to port 443 if --stats.api.ssl is true and port 80 otherwise.

    --stats.api.insecure
            (default: false)
            If true, don't validate server cert when using SSL for stats API requests

    --stats.api.prefix=value
            The url prefix for stats API requests. Forms the path part of <host>:<port><path>

    --stats.api.ssl
            (default: true)
            If true, use SSL for stats API requests

    --stats.api.sslCert=value
            Specifies the SSL cert to use for every stats API request.

    --stats.api.sslKey=value
            Specifies the SSL key to use for every stats API request.

    --stats.backends=value
            (valid values: "dogstatsd", "prometheus", "statsd", or "wavefront")
            Selects which stats backend(s) to use.

    --stats.batch
            (default: true)
            If true, stats requests are batched together for performance.

    --stats.dogstatsd.debug
            (default: false)
            If enabled, logs the stats data on stdout.

    --stats.dogstatsd.flush-interval=duration
            (default: 5s)
            Specifies the duration between stats flushes.

    --stats.dogstatsd.host=string
            (default: "127.0.0.1")
            Specifies the destination host for stats.

    --stats.dogstatsd.latch
            (default: false)
            Specifies whether stats are accumulated over a window before being sent to the backend.

    --stats.dogstatsd.latch.base-value=float
            (default: 0.001)
            Specifies the upper bound of the first bucket used for accumulating histograms. Each subsequent bucket's upper bound is double the previous bucket's. For timings this value is taken to be in units of seconds. Must be greater than 0.

    --stats.dogstatsd.latch.buckets=int
            (default: 20)
            Specifies the number of buckets used for accumulating histograms. Must be greater than 1.

    --stats.dogstatsd.latch.window=duration
            (default: 1m0s)
            Specifies the period of time over which stats are latched. Must be greater than 0.

    --stats.dogstatsd.max-packet-len=bytes
            (default: 8192)
            Specifies the maximum number of payload bytes sent per flush. If necessary, flushes will occur before the flush interval to prevent payloads from exceeding this size. The size does not include IP and UDP header bytes. Stats may not be delivered if the
            total size of the headers and payload exceeds the network's MTU.

    --stats.dogstatsd.port=int
            (default: 8125)
            Specifies the destination port for stats.

    --stats.dogstatsd.scope=string
            If specified, prepends the given scope to metric names.

    --stats.dogstatsd.transform-tags=string
            Defines one or more transformations for tags. A tag with a specific name whose value matches a regular expression can be transformed into one or more tags with values extracted from subexpressions of the regular expression. Transformations are specified
            as follows:

                tag=/regex/,n1,n2...

            where tag is the name of the tag to be transformed, regex is a regular expression with 1 or more subexpressions, and n1,n2... is a sequence of names for the tags formed from the regular expression's subexpressions (matching groups). Any character may be
            used in place of the slashes (/) to delimit the regular expression. There must be at least one subexpression in the regular expression. There must be exactly as many names as subexpressions. If one of the names is the original tag name, the original tag
            is replaced with the transformed value. Otherwise, the original tag is passed through unchanged. Multiple transformations may be separated by semicolons (;). Any character may be escaped with a backslash (\).

            Examples:

                foo=/^(.+):.*x=([0-9]+)/,foo,bar
                foo=@.*y=([A-Za-z_]+)@,yval

    --stats.event-backends=value
            (valid values: "console" or "honeycomb")
            Selects which stats backend(s) to use for structured events.

    --stats.exec.attempt-timeout=duration
            (default: 1s)
            Specifies the default timeout for individual action attempts. A timeout of 0 means no timeout.

    --stats.exec.delay=duration
            (default: 100ms)
            Specifies the initial delay for the exponential delay type. Specifies the delay for constant delay type.

    --stats.exec.delay-type=value
            (default: "exponential")
            (valid values: "constant" or "exponential")
            Specifies the retry delay type.

    --stats.exec.max-attempts=int
            (default: 8)
            Specifies the maximum number of attempts made, inclusive of the original attempt.

    --stats.exec.max-delay=duration
            (default: 30s)
            Specifies the maximum delay for the exponential delay type. Ignored for the constant delay type.

    --stats.exec.parallelism=int
            (default: 8)
            Specifies the maximum number of concurrent attempts running.

    --stats.exec.timeout=duration
            (default: 10s)
            Specifies the default timeout for actions. A timeout of 0 means no timeout.

    --stats.honeycomb.api-host=string
            (default: "https://api.honeycomb.io")
            The Honeycomb API host to send messages to

    --stats.honeycomb.batchSize=uint
            (default: 50)
            The Honeycomb batch size to use

    --stats.honeycomb.dataset=string
            They Honeycomb dataset to send messages to.

    --stats.honeycomb.sample-rate=uint
            (default: 1)
            The Honeycomb sample rate to use. Specified as 1 event sent per Sample Rate

    --stats.honeycomb.write-key=string
            They Honeycomb write key used to send messages.

    --stats.max-batch-delay=duration
            (default: 1s)
            If batching is enabled, the maximum amount of time requests are held before transmission

    --stats.max-batch-size=int
            (default: 100)
            If batching is enabled, the maximum number of requests that will be combined.

    --stats.node=string
            If set, specifies the node to use when submitting stats to backends. Equivalent to adding "--stats.tags=node=value" to the command line.

    --stats.prometheus.addr=value
            (default: 0.0.0.0:9102)
            Specifies the listener address for Prometheus scraping.

    --stats.prometheus.scope=string
            If specified, prepends the given scope to metric names.

    --stats.source=string
            If set, specifies the source to use when submitting stats to backends. Equivalent to adding "--stats.tags=source=value" to the command line. In either case, a UUID is appended to the value to insure that it is unique across proxies. Cannot be combined
            with --stats.unique-source.

    --stats.statsd.debug
            (default: false)
            If enabled, logs the stats data on stdout.

    --stats.statsd.flush-interval=duration
            (default: 5s)
            Specifies the duration between stats flushes.

    --stats.statsd.host=string
            (default: "127.0.0.1")
            Specifies the destination host for stats.

    --stats.statsd.latch
            (default: false)
            Specifies whether stats are accumulated over a window before being sent to the backend.

    --stats.statsd.latch.base-value=float
            (default: 0.001)
            Specifies the upper bound of the first bucket used for accumulating histograms. Each subsequent bucket's upper bound is double the previous bucket's. For timings this value is taken to be in units of seconds. Must be greater than 0.

    --stats.statsd.latch.buckets=int
            (default: 20)
            Specifies the number of buckets used for accumulating histograms. Must be greater than 1.

    --stats.statsd.latch.window=duration
            (default: 1m0s)
            Specifies the period of time over which stats are latched. Must be greater than 0.

    --stats.statsd.max-packet-len=bytes
            (default: 8192)
            Specifies the maximum number of payload bytes sent per flush. If necessary, flushes will occur before the flush interval to prevent payloads from exceeding this size. The size does not include IP and UDP header bytes. Stats may not be delivered if the
            total size of the headers and payload exceeds the network's MTU.

    --stats.statsd.port=int
            (default: 8125)
            Specifies the destination port for stats.

    --stats.statsd.scope=string
            If specified, prepends the given scope to metric names.

    --stats.statsd.transform-tags=string
            Defines one or more transformations for tags. A tag with a specific name whose value matches a regular expression can be transformed into one or more tags with values extracted from subexpressions of the regular expression. Transformations are specified
            as follows:

                tag=/regex/,n1,n2...

            where tag is the name of the tag to be transformed, regex is a regular expression with 1 or more subexpressions, and n1,n2... is a sequence of names for the tags formed from the regular expression's subexpressions (matching groups). Any character may be
            used in place of the slashes (/) to delimit the regular expression. There must be at least one subexpression in the regular expression. There must be exactly as many names as subexpressions. If one of the names is the original tag name, the original tag
            is replaced with the transformed value. Otherwise, the original tag is passed through unchanged. Multiple transformations may be separated by semicolons (;). Any character may be escaped with a backslash (\).

            Examples:

                foo=/^(.+):.*x=([0-9]+)/,foo,bar
                foo=@.*y=([A-Za-z_]+)@,yval

    --stats.tags=value
            Tags to be included with every stat. May be comma-delimited or specified more than once. Should be of the form "<key>=<value>" or "tag"

    --stats.unique-source=string
            If set, specifies the source to use when submitting stats to backends. Equivalent to adding "--stats.tags=source=value" to the command line. Unlike --stats.source, failing to specify a unique value may prevent stats from being recorded correctly. Cannot
            be combined with --stats.source.

    --stats.wavefront.debug
            (default: false)
            If enabled, logs the stats data on stdout.

    --stats.wavefront.flush-interval=duration
            (default: 5s)
            Specifies the duration between stats flushes.

    --stats.wavefront.host=string
            (default: "127.0.0.1")
            Specifies the destination host for stats.

    --stats.wavefront.latch
            (default: false)
            Specifies whether stats are accumulated over a window before being sent to the backend.

    --stats.wavefront.latch.base-value=float
            (default: 0.001)
            Specifies the upper bound of the first bucket used for accumulating histograms. Each subsequent bucket's upper bound is double the previous bucket's. For timings this value is taken to be in units of seconds. Must be greater than 0.

    --stats.wavefront.latch.buckets=int
            (default: 20)
            Specifies the number of buckets used for accumulating histograms. Must be greater than 1.

    --stats.wavefront.latch.window=duration
            (default: 1m0s)
            Specifies the period of time over which stats are latched. Must be greater than 0.

    --stats.wavefront.max-packet-len=bytes
            (default: 8192)
            Specifies the maximum number of payload bytes sent per flush. If necessary, flushes will occur before the flush interval to prevent payloads from exceeding this size. The size does not include IP and UDP header bytes. Stats may not be delivered if the
            total size of the headers and payload exceeds the network's MTU.

    --stats.wavefront.port=int
            (default: 8125)
            Specifies the destination port for stats.

    --stats.wavefront.scope=string
            If specified, prepends the given scope to metric names.

    --stats.wavefront.transform-tags=string
            Defines one or more transformations for tags. A tag with a specific name whose value matches a regular expression can be transformed into one or more tags with values extracted from subexpressions of the regular expression. Transformations are specified
            as follows:

                tag=/regex/,n1,n2...

            where tag is the name of the tag to be transformed, regex is a regular expression with 1 or more subexpressions, and n1,n2... is a sequence of names for the tags formed from the regular expression's subexpressions (matching groups). Any character may be
            used in place of the slashes (/) to delimit the regular expression. There must be at least one subexpression in the regular expression. There must be exactly as many names as subexpressions. If one of the names is the original tag name, the original tag
            is replaced with the transformed value. Otherwise, the original tag is passed through unchanged. Multiple transformations may be separated by semicolons (;). Any character may be escaped with a backslash (\).

            Examples:

                foo=/^(.+):.*x=([0-9]+)/,foo,bar
                foo=@.*y=([A-Za-z_]+)@,yval

    --version
            (default: false)
            Print the version and exit

    --xds.addr=value
            (default: :50000)
            The address on which to serve the envoy API server.

    --xds.ads-enabled
            (default: true)
            If false, turn off ads discovery mode

    --xds.ca-file=string
            Path to a file (on the Envoy host's file system) containing CA certificates for TLS.

    --xds.default-timeout=duration
            (default: 1m0s)
            The default request timeout, if none is specified in the RetryPolicy for a Route

    --xds.disabled
            (default: false)
            Disables the xDS listener.

    --xds.enable-tls
            (default: false)
            Enable grpc xDS TLS

    --xds.grpc-log-top=int
            (default: 0)
            When gRPC logging is enabled and this value is greater than 1, logs of non-success Envoy responses are tracked and periodically reported. This flag controls how many unique response code & request path combinations are tracked. When the number of
            tracked combinations in the reporting period is exceeded, uncommon paths are evicted.

    --xds.grpc-log-top-interval=duration
            (default: 5m0s)
            See the grpc-log-top flag. Controls the interval at which top logs are generated.

    --xds.interval=duration
            (default: 1s)
            The interval for polling the Greymatter API. Minimium value is 500ms

    --xds.resolve-dns
            (default: true)
            If true, resolve EDS hostnames to IP addresses.

    --xds.server-auth-type=string
            TLS client authentication type

    --xds.server-cert=string
            URL containing the server certificate for the grpc ADS server

    --xds.server-key=string
            URL containing the server certificate key for the grpc ADS server

    --xds.server-trusts=string
            Comma-delimited URLs containing truststores for the grpc ADS server

    --xds.standalone-cluster=string
            (default: "default-cluster")
            The name of the cluster for the Envoys consuming the standalone xDS server. Should match the --service-cluster flag for the envoy binary, or the ENVOY_NODE_CLUSTER value for the envoy-simple Docker image.

    --xds.standalone-port=int
            (default: 80)
            The port on which Envoys consuming the standalone xDS server should listen. Ignored if --api.key is specified.

    --xds.standalone-zone=string
            (default: "default-zone")
            The name of the zone for the Envoys consuming the standalone xDS server. Should match the --service-zone flag for the envoy binary, or the ENVOY_NODE_ZONE value for the envoy-simple Docker image.

    --xds.static-resources.conflict-behavior=value
            (default: "merge")
            (valid values: "overwrite" or "merge")
            How to handle conflicts between configuration types. If "overwrite" configuration types overwrite defaults. For example, if one were to include "listeners" in the static resources configuration file, all existing listeners would be overwritten. If the
            value is "merge", listeners would be merged together, with collisions favoring the statically configured listener. Clusters are differentiated by name, while listeners are differentiated by IP/port. Listeners on 0.0.0.0 (or ::) on a given port will
            collide with any other IP with the same port. Specifying colliding static resources will produce a startup error.

    --xds.static-resources.filename=string
            Path to a file containing static resources. The contents of the file should be either a JSON or YAML fragment (as configured by the corresponding --format flag) containing any combination of "clusters" (an array of
            https://www.envoyproxy.io/docs/envoy/v1.13.1/api-v2/api/v2/cluster.proto), "cluster_template" (a single cluster, which will be used as the prototype for all clusters not specified statically), and/or listeners" (an array of
            https://www.envoyproxy.io/docs/envoy/v1.13.1/api-v2/api/v2/listener.proto). The file is read once at startup. Only the v2 API is parsed. Enum strings such as "ROUND_ROBIN" must be capitalized.

    --xds.static-resources.format=value
            (default: "yaml")
            (valid values: "json" or "yaml")
            The format of the static resources file

    Global options can also be configured via upper-case, underscore-delimited environment variables prefixed with "GM_CONTROL_". For example, "--some-flag" becomes "GM_CONTROL_SOME_FLAG". Command-line flags take precedence over environment variables.

OPTIONS
    --ca-cert=path
            The path to a trusted root certificate file for the Kubernetes API server. Only used if -kubernetes-host is set.

    --client-cert=path
            The path to a certificate file which the client will use to authenticate itself to the Kubernetes API server. Only used if -kubernetes-host is set.

    --client-key=path
            The path to a certificate key file which the client will use to authenticate itself to the Kubernetes API server. Only used if -kubernetes-host is set.

    --cluster-label=name
            (default: "gm_cluster")
            The name of Kubernetes label that specifies to which cluster a pod belongs.

    --help  (default: false)
            Show a list of commands or help for one command

    --kubernetes-host=host
            The host name for the kubernetes API server. Required if the collector is to run outside of the Kubernetes cluster.

    --log-level=string
            (default: "error")
            The log level used for this discovery plugin

    --namespaces=namespace
            (default: "default")
            A comma-delimited Kubernetes cluster namespace list to watch for pods.

    --port-name=string
            (default: "http")
            The named container port assigned to cluster instances.

    --selector=string
            A Kubernetes label selector that selects which pods are polled.

    --timeout=duration
            (default: 2m0s)
            The timeout used for Kubernetes API requests (converted to seconds).

    --version
            (default: false)
            Print the version and exit

    Options can also be configured via upper-case, underscore-delimited environment variables prefixed with "GM_CONTROL_KUBERNETES_". For example, "--some-flag" becomes "GM_CONTROL_KUBERNETES_SOME_FLAG". Command-line flags take precedence over environment
    variables.
```
