Skip to main content
logoTetrate Service BridgeVersion: 1.4.x

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

AgentConfiguration

AgentConfiguration specifies configuration of the Workload Onboarding Agent.

FieldDescriptionValidation 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.

FieldDescriptionValidation Rule

auto

tetrateio.api.onboarding.config.agent.v1alpha1.HostEnvironment.Auto oneof _kind
Automatically inferred environment.

This is the default mode.

custom

tetrateio.api.onboarding.config.agent.v1alpha1.HostEnvironment.Custom oneof _kind
Custom environment configured explicitly by the user.

aws

tetrateio.api.onboarding.config.agent.v1alpha1.HostEnvironment.Aws oneof _kind
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.

Aws

AWS environment.

FieldDescriptionValidation Rule

ec2

tetrateio.api.onboarding.config.agent.v1alpha1.HostEnvironment.Aws.Ec2 oneof _kind
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.

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.

FieldDescriptionValidation 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.

FieldDescriptionValidation Rule

plugin

tetrateio.api.onboarding.config.agent.v1alpha1.Plugin oneof _kind
Plugin (an executable binary) as a source of platform-specific information.

IstioSidecar

Sidecar specifies configuration of the pre-installed Istio Sidecar.

Output

Destination for process output.

FieldDescriptionValidation Rule

filename

string oneof _kind
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.

FieldDescriptionValidation 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.

FieldDescriptionValidation 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.

FieldDescriptionValidation Rule

istio

tetrateio.api.onboarding.config.agent.v1alpha1.IstioSidecar oneof _kind
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.