Agent Configuration

Agent Configuration specifies configuration of the Workload Onboarding Agent.

In most cases, Workload Onboarding Agent can automatically recognize the host environment, e.g. AWS EC2, which makes explicit Agent Configuration optional.

By default, Workload Onboarding Agent comes with the minimal configuration:

apiVersion: config.agent.onboarding.tetrate.io/v1alpha1
kind: AgentConfiguration

which at runtime is interpreted as an equivalent of:

apiVersion: config.agent.onboarding.tetrate.io/v1alpha1
kind: AgentConfiguration
host:
  auto: {}
sidecar:
  istio: {}
  stdout:
    filename: /dev/stdout
  stderr:
    filename: /dev/stderr

The above configuration means that Workload Onboarding Agent should infer host environment automatically, should be in control of the Istio Sidecar pre-installed on that host, should redirect standard output of the Istio Sidecar into its own output.

Most users do not need to change the default configuration.

Users who make use of Istio revisions, need to specify the revision the pre-installed Istio Sidecar corresponds to, e.g.:

apiVersion: config.agent.onboarding.tetrate.io/v1alpha1
kind: AgentConfiguration
sidecar:
  istio:
    revision: canary

Users who want to redirect standard output of the Istio Sidecar into a separate file (instead of mixing together output of the Workload Onboarding Agent and output of the Istio Sidecar), should use the following configuration:

apiVersion: config.agent.onboarding.tetrate.io/v1alpha1
kind: AgentConfiguration
sidecar:
  stdout:
    filename: ./relative/path/to/file
  stderr:
    filename: /absolute/path/to/file

Relative path of a log file is interpreted as relative to the working directory of the Workload Onboarding Agent.

Advanced users who would like to utilize Workload Onboarding Agent in an environment that is not supported out-of-the-box, can develop custom Workload Onboarding Agent Plugins and use them by providing an explicit Agent Configuration, e.g.:

apiVersion: config.agent.onboarding.tetrate.io/v1alpha1
kind: AgentConfiguration
host:
  custom:
    credential:
    - plugin:
        name: custom-credential-provider
        path: /path/to/custom-credential-provider-binary
    hostinfo:
      plugin:
        name: custom-hostinfo-provider
        path: /path/to/custom-hostinfo-provider-binary
        env:
        - name: CONFIG
          value: /path/to/config
        args:
        - --name=value
settings:
  connection:
    timeout: 60s
    retryPolicy:
      exponentialBackoff:
        initialInterval: 10s
        maxInterval: 120s

Workload Onboarding Agent Plugin is an auxiliary executable (e.g. binary, shell script, Python script, etc) installed in addition to the Workload Onboarding Agent.

Workload Onboarding Agent executes a Workload Onboarding Agent Plugin to procure platform-specific information.

+--------------------------------------------------------+
| Host (e.g., VM or container)                           |
|                                                        |
|  +------------------+            +------------------+  |
|  |                  |            |                  |  |
|  |     Workload     | ---------> |     Workload     |  |
|  | Onboarding Agent | (executes) | Onboarding Agent |  |
|  |                  |            |      Plugin      |  |
|  +------------------+            +------------------+  |
|                                                        |
+--------------------------------------------------------+

Workload Onboarding Agent Plugin is modeled as a gRPC service with unary call method(s). However, Workload Onboarding Agent Plugin does not run a network server. Instead, semantics of an unary RPC call is mapped onto execution of a process.

To make a call to the plugin, Workload Onboarding Agent:

• runs executable of the Workload Onboarding Agent Plugin
• passes parameters in via environment variables with the following names:
  • PLUGIN_NAME - mandatory - e.g., aws-ec2-credential
  • RPC_SERVICE_NAME - mandatory - e.g. tetrateio.api.onboarding.private.component.agent.plugin.credential.v1alpha1.CredentialPlugin
  • RPC_METHOD_NAME - mandatory - e.g. GetCredential
• writes request message serialized into JSON to the stdin of the plugin process
• if plugin process exists with a 0 code, reads from stdout response message serialized into JSON
• if plugin process exists with a non-0 code, reads from stdout RPC status message serialized into JSON
• in a corner case where plugin process starts writing to stdout a response message, then encounters a failure and continues by writing to stdout an RPC status message, Workload Onboarding Agent should look at the exit code of the plugin process to decide how to interpret contents of stdout
• plugin process must only print to stdout either a response message or an RPC status message
• plugin process may print to stderr any data, e.g. diagnostic messages

In some cases instead of developing a custom plugin it is possible to reuse a built-in behavior.

E.g., instead of developing a custom HostInfo plugin you can reuse built-in behavior that simply lists available network interfaces instead of interacting with the platform-specific metadata API.

apiVersion: config.agent.onboarding.tetrate.io/v1alpha1
kind: AgentConfiguration
host:
  custom:
    credential:
    - plugin:
        name: custom-credential-provider
        path: /path/to/custom-credential-provider-binary
    hostinfo:
      basic:
        networkInterfaces:
          include:
          - ^eth[0-9]*$

AgentConfiguration

AgentConfiguration specifies configuration of the Workload Onboarding Agent.

BasicHostInfo

BasicHostInfo specifies how to collect basic information about the host in a cross-platform way.

NetworkInterfaces

NetworkInterfaces specifies a filter on network interfaces that should be taken into account to determine IP addresses of the host.

For a network interface to be taken into account its name must be matched by one of the regular expressions on the include list and none of the regular expressions on the exclude list.

ConnectionSettings

ConnectionSettings specifies settings that control execution of agent plugins, e.g. a timeout for a single plugin call, a retry policy for failed plugin calls, etc. The same settings apply to agent plugins of all kinds, e.g. credential plugins, host info plugins, etc.

CredentialSource

CredentialSource specifies a source of a platform-specific credential.

Workload Onboarding Agent uses CredentialSource to procure a platform-specific credential.

ExponentialBackoff

ExponentialBackoff specifies exponential backoff strategy.

HostEnvironment

HostEnvironment specifies information about the host environment.

Aws

AWS environment.

Custom

Custom environment configured explicitly by the user.

In this mode a user has to explicitly configure a list of Workload Onboarding Agent Plugins that procure information about the host using platform-specific APIs, e.g. plugin(s) to procure platform-specific credential of the host, a plugin to procure IP address(es) of the host, etc.

HostInfoSource

HostInfoSource specifies a source of platform-specific information about the host.

Workload Onboarding Agent uses HostInfoSource to procure platform-specific information about the host.

IstioSidecar

Sidecar specifies configuration of the pre-installed Istio Sidecar.

Output

Destination for process output.

Plugin

Plugin specifies a Workload Onboarding Agent Plugin as a source of platform-specific information.

EnvVar

EnvVar specifies a single environment variable.

RetryPolicy

RetryPolicy specifies a retry policy for failed plugin calls.

Settings

Settings specifies in-depth runtime configuration.

Sidecar

Sidecar specifies configuration of the pre-installed sidecar.