Options for the Lightweight Kubernetes Agent

FlexNet Manager Suite 2022 R1 (On-Premises)

Alternative modes

These first two flags are not operational flags, but if you require more information, these may be set on the command line for the lightweight Kubernetes agent when run underneath Docker:

--version

Prints the long-form version of the lightweight Kubernetes agent to stdout, and exits.

docker run --rm flexera/lwk:x.y.z --version

--help

Prints the built-in usage information to stdout, and exits.

docker run --rm flexera/lwk:x.y.z --help

For normal operation, the following flags may be set in the deployment.yaml file that modifies the Deployment during installation.

Duration values

Flags that accept a duration of time use the formatting from the Go programming language: a numeric value, followed immediately by a unit suffix: h for hours, m for minutes, or s for seconds. Units larger than a hour are not supported, so days or weeks must be specified by calculating the number of hours. For example:

• 24 hours is 24h
• 15 minutes is 15m
• 30 seconds is 30s
• 2 days is 48h
• 1 week (7 days) is 168h.

Option values

Placeholders for values to supply are shown thus.

Tip: Flags that require a Boolean value (true, false) must have an equals sign (=) linking the flag and value. All other flags may have a space between the flag name and value.

Available flags (listed in alphabetical order) include:

--beacon URL

Type: Valid URL (required — otherwise the lightweight Kubernetes agent will log an error and exit if this is not specified)

Default: Unset

The URL of an inventory beacon to which collected inventories are uploaded every 24 hours (by default, or see --inventory-interval). Must include the protocol (either http:// or https://), the host name, an optional port number (if used, separated from the host name by a colon), and any necessary path elements to reliably reach the inventory beacon. The value may include any or none of the /ManageSoftRL/Inventory path components used within the inventory beacon — these will be automatically appended by the lightweight Kubernetes agent if omitted from the flag (as in the example below).

Tip: Uptime on the inventory beacon, and network reliability on the path from the lightweight Kubernetes agent to the inventory beacon, are critical to inventory gathering. Because the lightweight Kubernetes agent does not install any components of the FlexNet inventory agent, it does not include the inventory beacon failover, or overnight catch-up uploads to recover from temporary network outages. The inventory beacon specified with this flag is the only one used by the lightweight Kubernetes agent. Also note that if you are using the https protocol, the lightweight Kubernetes agent supports only standard TLS to authenticate those communications.

Example:

--beacon https://mybeacn.example.com:443/leaveK8s

--exclude-namespace name --exclude-namespaces name,name,...

Type: Kubernetes text (lower-case alphanumeric characters and dashes), with list comma-separated without whitespace characters or quotation marks

Default: Unset

Add one or more namespaces to the exclusion list in the namespace filter used by the lightweight Kubernetes agent:

• The --exclude-namespace flag accepts only a single name, but may be specified any number of times. All of the occurrences of the flag are combined into a list.
• The --exclude-namespaces flag accepts a comma-separated list of namespaces, and can only be specified once.

The two flags are additive. All of the instances of --exclude-namespace are combined with the value of --exclude-namespaces, and the resulting list of namespaces is deduplicated.

Examples:

--exclude-namespace private

--exclude-namespaces private,testing

--ibm-licensing

Type: Boolean

Default: false (when unspecified, this default is provided in the code of the lightweight Kubernetes agent)

A Boolean option that, when true, enables integration with the IBM License Service. This is means that, by default, the lightweight Kubernetes agent cannot gather licensing data for IBM Cloud Paks running in Kubernetes containers (recall that using the IBM License Service is mandatory to meet IBM's license terms in this environment). You must explicitly enable this integration.

The examples below show the two ways of enabling the integration, either by:

• Specifying the flag with no assigned value
• Specify the flag with an explicit Boolean value.

Important: When this flag is set to true by either method, the other flags pertaining to integration with the IBM License Service integration are mandatory. These flags all begin with ibm-licensing… If this flag is set and either of --ibm-licensing-url or --ibm-licensing-token is missing, the lightweight Kubernetes agent aborts with an error.

Examples:

--ibm-licensing=true
--ibm-licensing

--ibm-licensing-tls-verify

Type: Boolean string

Default: True

By default, the lightweight Kubernetes agent properly verifies the server certificate for TLS certification of HTTPS communications with the IBM Licensing Service. However, if the IBM License Service is using an untrusted certificate, this option can be set to false to allow the lightweight Kubernetes agent to ignore certificate verification errors.

Tip: Unless you supplied the IBM License Server with a certificate and key certified by a Certificate Authority, its default behavior is to use a self-signed certificate, and in that case you should turn off the formal verification process that looks for a root certificate from a Certificate Authority — as in the following example.

Example:

--ibm-licensing-tls-verify=false

--ibm-licensing-token string

Type: String

Default: Unset (required when --ibm-licensing true)

The authentication token the lightweight Kubernetes agent can use to authenticate with the IBM License Service. This is typically stored in a ConfigMap in the cluster. If the token is changed, the value of this flag must also be changed to match, and the lightweight Kubernetes agent must then be restarted.

Example:

--ibm-licensing-token jNsshfn6scWre4unzCWlO7xs

--ibm-licensing-url url

Type: Valid URL

Default: Unset (required when --ibm-licensing true)

The complete URL, including the protocol, the host name, an optional port number (if used, separated from the host name by a colon), and any necessary path elements to reliably reach the IBM License Service.

Example:

--ibm-licensing-url 
   https://ibm-licensing-service-instance.ibm-common-services.svc:8080

--include-namespace name --include-namespaces name,name,...

Type: Kubernetes text (lower-case alphanumeric characters and hyphens), with list comma-separated without whitespace characters or quotation marks

Default: Unset

Add one or more namespaces to the inclusion list in the namespace filter used by the lightweight Kubernetes agent:

• The --include-namespace flag accepts only a single name, but may be specified any number of times. All of the occurrences of the flag are combined into a list.
• The --include-namespaces flag accepts a comma-separated list of namespaces, and can only be specified once.

The two flags are additive. All of the instances of --include-namespace are combined with the value of --include-namespaces, and the resulting list of namespaces is deduplicated.

Examples:

--include-namespace production

--include-namespaces production,testing

--inventory-backoff duration

Type: Duration value (see details above)

Default: 5m

Set the duration of time for which the lightweight Kubernetes agent gathers data before uploading the first inventory.

Unlike the standard FlexNet inventory agent, the lightweight Kubernetes agent does not use a polling strategy to gather inventory. Instead, it continuously monitors the state of the cluster by consuming event streams. In theory, it can upload an inventory file at any point after it connects to Kubernetes and begins receiving data. However, if the lightweight Kubernetes agentuploads too soon, it may not have received the initial state of each resource in the cluster, leaving the first inventory incomplete (and by default, this would only be corrected a day later). The default value is 5 minutes, which is sufficient to receive all of the data for nearly all clusters. For very small clusters or for testing purposes, this value can be shortened to mere seconds.

Example:

--inventory-backoff 10m

--inventory-interval duration

Type: Duration value (see details above)

Default: Unset (in which case the lightweight Kubernetes agent uses a value of 24h)

Set the time interval on which the lightweight Kubernetes agent collects and uploads inventories. General best practice is to omit this flag, accepting the default of 24 hours, as a shorter interval requires uploading and processing a larger number of smaller inventories. However, you may adjust this interval to meet the needs of your enterprise for frequency of inventory gathering.

Example:

--inventory-interval 48h

--label-selector selector --namespace-label-selector selector --node-label-selector selector --pod-label-selector selector

Type: Kubernetes label selector (using either equality-based requirement or [within single quotes] set-based requirement, see https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)

Default: Unset

Set the label selectors that are used when subscribing to the event streams in the Kubernetes API. A distinct selector, as indicated by the names, can be applied to the subscription to each of the Namespace, Node, and Pod resources. The general --label-selector flag, if specified, is used for whichever of the three distinct subscriptions have not been specified. Only events that match all of the specified selectors are used to add to the inventory for upload.

In the following example, inventory is calculated from events coming from pods where the environment label is set to one of the following:

environment: qa
environment: production

and the namespace and node both have a label set:

app: store

Example:

--pod-label-selector 'environment in (production, qa)'
--label-selector app=store

--log-level level

Type: String option list

Default: info

Set the logging verbosity level to one of:

• info — Provides all of the information that is typically useful
• debug — Available for additional information or troubleshooting, and produces a high volume of information
• trace — Provides even more information than debug, and typically should not be needed
• warn — Only produce messages logged at warning level or higher (not recommended because, should an issue arise, this can mask valuable troubleshooting information)
• error — Only produce messages logged at error level or higher (not recommended because, should an issue arise, this can mask valuable troubleshooting information)
• fatal — Suppress all messages except fatal errors resulting in immediate termination of the application (not recommended because, should an issue arise, this can mask valuable troubleshooting information).

Other string values not in this list are ignored.

Example:

--log-level debug

--metrics

Type: Boolean string

Default: False

When true, this option enables an HTTP endpoint on the lightweight Kubernetes agent to serve Prometheus metrics. By default, the metrics endpoint is not enabled. As in the following examples, it can be enabled using the option flag by itself, or with an explicit boolean value,

Examples:

--metrics
--metrics=true

--metrics-address host:port

Type: String

Default: :9090 (matching the Prometheus default port)

When Prometheus metrics are enabled using --metrics, this flag sets the host and port to which the HTTP server is bound. Using the default value where the host is not set (and the colon is mandatory to precede the port number), the default is to listen on the Pod's internal, automatically-assigned IP address, on the nominated port.

Example:

--metrics-address :80

--metrics-endpoint path

Type: String giving valid path with the metrics server

Default: /metrics (supplied by internal code when flag is unset)

When Prometheus metrics are enabled using --metrics, this flag sets the path on which the metrics service is mounted. This value can be appended to the value of metrics-address to complete the HTTP path.

Tip: If you change this value, the lightweight Kubernetes agent must be restarted.

Example:

--metrics-endpoint /prometheus

-v

Type: No value required

Default: Unset

An alias for

--log-level debug

that provides a shorthand way to increase the logging verbosity level to debug.

Example:

-v

--volume path

Type: A valid path within the container's file system.

Default: Unset

By default, the lightweight Kubernetes agent assumes that the container is immutable at run-time and therefore does not have any persistent storage volumes mounted. As a result, by default:

• All collected inventory data is cached in memory
• Inventory is never written to a file on the agent end of the process
• Run-time state is lost on restarts.

Note: Some of the Kubernetes libraries that are utilized by the lightweight Kubernetes agent (notably the Kubernetes client) may attempt to interact with the file system, such as reading random data from the random device node, or reading the service account token that is mounted into the container. With these exceptions, the lightweight Kubernetes agent behaves by default as if there were no file system.

However, you may change that default behavior by providing a path in this ‑‑volume flag. A value here instructs the lightweight Kubernetes agent that there is a persistent, mutable volume mounted at the specified directory. It then uses the volume to cache its inventory data in that directory on disk. This reduces the memory overhead of the lightweight Kubernetes agent by allowing it to cache to disk instead of in memory.

The most common pattern for providing the agent with persistent storage, and the method supported by the lightweight Kubernetes agent, is to first create a PersistentVolumeClaim (for example, see https://kubernetes.io/docs/tasks/configure-pod-container/configure-persistent-volume-storage/). When the ‑‑volume flag exists in the deployment.yaml file, the agent's Deployment is modified to mount the volume provided by the PersistentVolumeClaim to a path in the container's file system. Finally, the ‑‑volume flag is added to the command line for the lightweight Kubernetes agent in the Deployment, along with the path in the container file system where the volume was mounted.

Example:

--volume /data

Advanced options

These options rarely require modification, have a significant impact on the behavior of the lightweight Kubernetes agent, or are present to support future expansion.

--cluster-interval duration

Type: Duration value (see details above)

Default: 24h

Sets the duration of time after which the lightweight Kubernetes agent will issue requests to update the basic metadata about the cluster. For clusters whose version rarely changes, the interval can be much wider to (slightly) reduce the number of requests to the Kubernetes API.

Example:

--cluster-interval 96h

--connect-profile name

Type: String

Sets the algorithm used to provision and configure the Kubernetes API client. Currently, this value must not be modified.

--restore-mode mode

Type: String option list

Default: clean

In the scenario where:

• File storage has been enabled using the --volume flag, and
• Collected data has been persisted to storage, and
• The lightweight Kubernetes agent is restarted

the agent must resolve changes that have occurred in the cluster since the data was written. This flag sets the behavior of the lightweight Kubernetes agent when an unrecoverable discrepancy has been detected, such as data referencing a different cluster. The options are:

• clean — The lightweight Kubernetes agent deletes the persisted data, and proceeds with normal operation using the current environment
• refuse — The lightweight Kubernetes agent leaves the persisted data unchanged, and exits with a failure.

Example:

----restore-mode refuse