Onboarding Configuration

The differences between TSB and TSE API

Tetrate Service Express (TSE) utilizes many of the same components as the Tetrate Service Bridge(TSB) product but has the several distinctions. Go to Comparing TSE and TSB for more details.

Onboarding Configuration specifies where to onboard the workload to.

To be able to onboard a workload into a service mesh, a user must configure Workload Onboarding Agent with the location of the Workload Onboarding Endpoint and a name of the WorkloadGroup to join.

By default, Workload Onboarding Agent will read Onboarding Configuration from a file /etc/onboarding-agent/onboarding.config.yaml, which must be created by the user.

If Onboarding Configuration file is missing or its contents is not valid, Workload Onboarding Agent will not be able to start.

Consider the following example of the minimal valid configuration:

apiVersion: config.agent.onboarding.tetrate.io/v1alpha1
kind: OnboardingConfiguration
onboardingEndpoint:
  host: onboarding.example.org  # (1)
workloadGroup:
  namespace: bookinfo           # (2)
  name: ratings                 # (2)

The above configuration instructs Workload Onboarding Agent to connect to the Workload Onboarding Endpoint reachable at the address onboarding.example.org:15443 (1) and automatically register the workload as a member of the WorkloadGroup "bookinfo/ratings" (2).

Workload Onboarding Endpoint might decline the workload from being registered in the mesh in case there is no WorkloadGroup with that name or there is no OnboardingPolicy that authorizes this particular workload to join this particular WorkloadGroup.

If a registration attempt fails, Workload Onboarding Agent will continue trying indefinitely until both the WorkloadGroup and allowing OnboardingPolicy exist in the mesh.

Onboarding Configuration can also be used to customize workload's appearance in the mesh, e.g. a set of labels associated with the workload, IP address of the workload that other mesh members should use to make requests to it, etc.

E.g., consider the following example:

apiVersion: config.agent.onboarding.tetrate.io/v1alpha1
kind: OnboardingConfiguration
onboardingEndpoint:
  host: onboarding.example.org
workloadGroup:
  namespace: bookinfo
  name: ratings
workload:
  labels:
    version: v1  # (1)

The above configuration instructs Workload Onboarding Agent to register the workload in the mesh and customize the set of labels associated with it.

By default, a workload is associated only with labels configured in the respective WorkloadGroup resource.

By means of the above configuration, the workload will receive one extra label version=v1 (1).

Notice that Onboarding Configuration gives users an option to specify additional labels for the workload, but it does not allow to override labels specified in the WorkloadGroup. E.g., if a WorkloadGroup specifies label app=ratings, Onboarding Configuration can not be used to override it with app=details.

As a rule of thumb, users should specify labels common to all workloads in the group using the WorkloadGroup resource, e.g. app label. Labels that can be unique to every individual workload in the group, e.g. version label, should be specified using Onboarding Configuration.

Next, Onboarding Configuration can be used to fine-tune workload registration in the mesh on a feature-by-feature basis.

E.g., consider the following example:

apiVersion: config.agent.onboarding.tetrate.io/v1alpha1
kind: OnboardingConfiguration
onboardingEndpoint:
  host: onboarding.example.org
workloadGroup:
  namespace: bookinfo
  name: ratings
settings:
  connectedOver: INTERNET  # (1)

The above configuration instructs Workload Onboarding Agent to register the workload in the mesh by its Public IP address (aka Internet IP) rather than Private IP (aka VPC IP) (1).

Normally, workloads should be connected to the rest of the mesh over a private network, which improves security and therefore is the default behavior.

However, in those cases where private network connectivity between the workload and the rest of the mesh is not possible or not practical, users can use Onboarding Configuration to opt for connectivity over Internet instead.

In the above example, the workload will be registered in the mesh by its Public IP address (aka Internet IP). In practice, it means that other workloads in the mesh will use that Public IP to connect to this workload.

Lastly, Onboarding Configuration provides support for non-production scenarios, such as getting started try-outs and disposable environments for demos and trials.

In those cases where users find it acceptable to disable certain security safeguards in favour of simplicity of the setup, they can utilize the following configuration options.

If a user has no means to create a DNS record for the Workload Onboarding Endpoint, he/she can workaround this constraint by fine-tuning Onboarding Configuration the following way:

apiVersion: config.agent.onboarding.tetrate.io/v1alpha1
kind: OnboardingConfiguration
onboardingEndpoint:
  host: 1.2.3.4                    # (1)
  transportSecurity:
    tls:
      sni: onboarding.example.org  # (2)
workloadGroup:
  namespace: bookinfo
  name: ratings

The above configuration instructs Workload Onboarding Agent to connect to 1.2.3.4 (1), yet validate server certificate as if the connection was made to onboarding.example.org (2), removing the need to register DNS record for onboarding.example.org or to modify /etc/hosts file on the Agent's host.

Furthermore, if a user has no means to issue a certificate for the Workload Onboarding Endpoint signed by a trusted CA, he/she can workaround this constraint by using a self-signed certificate and fine-tuning Onboarding Configuration the following way:

apiVersion: config.agent.onboarding.tetrate.io/v1alpha1
kind: OnboardingConfiguration
onboardingEndpoint:
  host: onboarding.example.org
  transportSecurity:
    tls:
      insecureSkipVerify: true  # (1)
workloadGroup:
  namespace: bookinfo
  name: ratings

The above configuration instructs Workload Onboarding Agent not to verify certificate of the Workload Onboarding Endpoint at all (which is insecure!), tolerating this way self-signed certificates.

⚠️ WARNING: NEVER use insecureSkipVerify setting in production scenarios!

OnboardingConfiguration

OnboardingConfiguration specifies where to onboard the workload to.

Field	Description	Validation Rule
onboardingEndpoint	tetrateio.api.onboarding.config.agent.v1alpha1.OnboardingConfiguration.OnboardingEndpoint REQUIRED Location of the Workload Onboarding Plane.	message = {   required: true }
workloadGroup	tetrateio.api.onboarding.config.types.core.v1alpha1.NamespacedName REQUIRED WorkloadGroup to join.	message = {   required: true }
workload	tetrateio.api.onboarding.config.types.registration.v1alpha1.WorkloadInfo Information about the workload to present to the Workload Onboarding Plane.	–
settings	tetrateio.api.onboarding.config.types.registration.v1alpha1.Settings Registration settings to present to the Workload Onboarding Plane.	–

OnboardingEndpoint

OnboardingEndpoint specifies where to find the Workload Onboarding Plane.

Field	Description	Validation Rule
host	string REQUIRED Address of the onboarding endpoint (can be hostname or IP address).	string = {   address: true }
port	int32 REQUIRED Port of the onboarding endpoint. Defaults to 15443.	int32 = {   lte: 65535   gte: 1 }
transportSecurity	tetrateio.api.onboarding.config.types.config.v1alpha1.ClientTransportSecurity Transport layer security configuration. Defaults to secure TLS client.	–