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, GCP Compute, Azure Compute, etc, 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 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

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 stdoutRPC 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

AgentConfiguration

AgentConfiguration specifies configuration of the Workload Onboarding Agent.

Field	Description	Validation Rule
host	tetrateio.api.onboarding.config.agent.v1alpha1.HostEnvironment Configuration of the host environment. Defaults to automatically inferred configuration that will work out-of-the-box if Workload Onboarding Agent is deployed into one of the most commonly used cloud environments, e.g. AWS EC2, GCP Compute, Azure Compute, etc.	–
sidecar	tetrateio.api.onboarding.config.agent.v1alpha1.Sidecar Configuration of the pre-installed sidecar. Defaults to Istio Sidecar installed at a well-known location (i.e., /usr/local/bin/pilot-agent, /usr/local/bin/envoy, etc).	–

HostEnvironment

HostEnvironment specifies information about the host environment.

Field	Description	Validation Rule
auto	tetrateio.api.onboarding.config.agent.v1alpha1.HostEnvironment.Auto Automatically inferred environment. This is the default mode.	–
custom	tetrateio.api.onboarding.config.agent.v1alpha1.HostEnvironment.Custom Custom environment configured explicitly by the user.	–
aws	tetrateio.api.onboarding.config.agent.v1alpha1.HostEnvironment.Aws AWS environment.	–

Auto

Automatically inferred environment.

In this mode Workload Onboarding Agent checks whether the host environment is one of the environments supported out-of-the-box, e.g. AWS EC2, GCP Compute, Azure Compute, etc.

If Workload Onboarding Agent recognizes the environment, it will use builtin capabilities to interact with the respective platform-specific APIs to procure information about the host.

Name	Number	Description

Aws

AWS environment.

Field	Description	Validation Rule
ec2	tetrateio.api.onboarding.config.agent.v1alpha1.HostEnvironment.Aws.Ec2 AWS EC2 environment.	–

Ec2

AWS EC2 environment. In this mode Workload Onboarding Agent will use EC2 instance metadata service to procure information about the host, i.e. Private IP (aka VPC IP), Public IP (aka Internet IP), AWS IAM Role credentials, etc.

Name	Number	Description

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.

Field	Description	Validation Rule
credential	List of tetrateio.api.onboarding.config.agent.v1alpha1.InfoSource REQUIRED Source(s) of an environment-specific credential.	repeated = {   min_items: 1   items: {message:{required:true}} }
hostinfo	tetrateio.api.onboarding.config.agent.v1alpha1.InfoSource REQUIRED Source of an environment-specific host information.	message = {   required: true }

InfoSource

InfoSource specifies a source of platform-specific information.

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

Field	Description	Validation Rule
plugin	tetrateio.api.onboarding.config.agent.v1alpha1.Plugin Plugin (an executable binary) as a source of platform-specific information.	–

IstioSidecar

Sidecar specifies configuration of the pre-installed Istio Sidecar.

Name	Number	Description

Output

Destination for process output.

Field	Description	Validation Rule
filename	string Path to a file with standard output of the process.	–

Plugin

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

Field	Description	Validation Rule
name	string REQUIRED Plugin reference name. E.g., my-platform-credential.	string = {   min_len: 1 }
path	string Path to the plugin executable. Defaults to onboarding-agent-{{ plugin name }}-plugin that will be looked up on the PATH.	–
env	List of tetrateio.api.onboarding.config.agent.v1alpha1.Plugin.EnvVar Environment variables of the plugin.	–
args	List of string Arguments of the plugin.	repeated = {   items: {string:{min_len:1}} }

EnvVar

EnvVar specifies a single environment variable.

Field	Description	Validation Rule
name	string REQUIRED Name of the environment variable.	string = {   min_len: 1 }
value	string Value of the environment variable.	–

Sidecar

Sidecar specifies configuration of the pre-installed sidecar.

Field	Description	Validation Rule
istio	tetrateio.api.onboarding.config.agent.v1alpha1.IstioSidecar Configuration of the pre-installed Istio Sidecar.	–
stdout	tetrateio.api.onboarding.config.agent.v1alpha1.Output Destination for the standard output of the sidecar. Relative path is interpreted as relative to the working directory of the Workload Onboarding Agent. Defaults to /dev/stdout.	–
stderr	tetrateio.api.onboarding.config.agent.v1alpha1.Output Destination for the standard error output of the sidecar. Relative path is interpreted as relative to the working directory of the Workload Onboarding Agent. Defaults to /dev/stderr.	–