Skip to main content
Version: 1.6.x

Onboarding Policy

Onboarding Policy authorizes matching workloads to join the mesh and become a part of a WorkloadGroup.

By default, none of the workloads are allowed to join the mesh.

A workload is only allowed to join the mesh if there is an OnboardingPolicy resource that explicitly authorizes that.

For the purposes of authorization, a workload is considered to have the identity of the host it is running on.

E.g., workloads that run on VMs in the cloud are considered to have cloud-specific identity of that VM. In case of AWS EC2 instances, VM identity includes AWS Partition, AWS Account number, AWS Region, AWS Zone, EC2 instance id, AWS IAM Role name, etc.

As part of the Workload Onboarding flow, Workload Onboarding Agent (that runs alongside the workload) will interact with cloud-specific metadata APIs to procure a credential (digitally signed data item) that can be passed to a third-party (Workload Onboarding Endpoint) as a proof of identity.

Once Workload Onboarding Endpoint has verified validity of the credential, i.e. audience, expiration time, digital signature, etc, it looks for an OnboardingPolicy resource that allows a workload with that identity to join the mesh.

OnboardingPolicy resource consists of a list of rules.

Each rule describes what workload identities it is applicable to and what WorkloadGroups the workload is allowed to join.

E.g., consider the following example of a very permissive OnboardingPolicy:

apiVersion: authorization.onboarding.tetrate.io/v1alpha1
kind: OnboardingPolicy
metadata:
name: allow-aws-ec2-vms
namespace: bookinfo
spec:
allow:
- workloads:
- aws:
accounts:
- '123456789012'
ec2: {} # any AWS EC2 instance from the above account
onboardTo:
- workloadGroupSelector: {} # any WorkloadGroup from that namespace

The above policy allows any workload running on an AWS EC2 instance of the AWS Account 123456789012 to join any WorkloadGroup in the bookinfo namespace.

The next example adds a constraint on AWS Regions the AWS EC2 instance may belong to:

apiVersion: authorization.onboarding.tetrate.io/v1alpha1
kind: OnboardingPolicy
metadata:
name: allow-aws-ec2-vms
namespace: bookinfo
spec:
allow:
- workloads:
- aws:
regions:
- ca-central-1
accounts:
- '123456789012'
ec2: {} # any AWS EC2 instance from the above account and region
onboardTo:
- workloadGroupSelector: {} # any WorkloadGroup from that namespace

The next example puts a constraint on WorkloadGroups the workload may join:

apiVersion: authorization.onboarding.tetrate.io/v1alpha1
kind: OnboardingPolicy
metadata:
name: allow-aws-ec2-vms
namespace: bookinfo
spec:
allow:
- workloads:
- aws:
accounts:
- '123456789012'
ec2: {} # any AWS EC2 instance from the above account
onboardTo:
- workloadGroupSelector:
matchLabels:
app: ratings # any WorkloadGroup from that namespace that has a label `app=ratings`

The following example puts a constraint on AWS IAM Role an AWS EC2 instance must be associated with to limit the scope of the rule to a narrow subset of AWS EC2 instances in that AWS Account:

apiVersion: authorization.onboarding.tetrate.io/v1alpha1
kind: OnboardingPolicy
metadata:
name: allow-aws-ec2-vms
namespace: bookinfo
spec:
allow:
- workloads:
- aws:
accounts:
- '123456789012'
ec2:
iamRoleNames:
- ratings-role # any AWS EC2 instance from the above account that is
# associated with one of IAM Roles on that list
onboardTo:
- workloadGroupSelector:
matchLabels:
app: ratings # any WorkloadGroup from that namespace that has a label `app=ratings`
- workloads:
- aws:
accounts:
- '123456789012'
ec2:
iamRoleNames:
- reviews-role # any AWS EC2 instance from the above account that is
# associated with one of IAM Roles on that list
onboardTo:
- workloadGroupSelector:
matchLabels:
app: reviews # any WorkloadGroup from that namespace that has a label `app=reviews`

The above policy will allow AWS EC2 instances associated with AWS IAM Role ratings-role to join WorkloadGroups that have label app=ratings, while AWS EC2 instances associated with AWS IAM Role reviews-role to join WorkloadGroups that have label app=reviews.

The final example demonstrates other constraints that can be put on AWS EC2 instances:

apiVersion: authorization.onboarding.tetrate.io/v1alpha1
kind: OnboardingPolicy
metadata:
name: allow-aws-ec2-vms
namespace: bookinfo
spec:
allow:
- workloads:
- aws:
partitions:
- aws
accounts:
- '123456789012'
regions:
- ca-central-1
zones:
- ca-central-1b
ec2: {} # any AWS EC2 instance from the above partitions/accounts/regions/zones
- aws:
partitions:
- aws
accounts:
- '123456789012'
regions:
- us-east-1
zones:
- us-east-1a
ec2:
iamRoleNames:
- example-role # any AWS EC2 instance from the above partitions/accounts/regions/zones
# associated with one of IAM Roles on that list
onboardTo:
- workloadGroupSelector:
matchLabels:
app: ratings

To onboard workloads from custom on-premise environments, you can leverage support for OIDC ID Tokens.

If workloads in your custom environment can authenticate themselves by means of an OIDC ID Token, you can define policies corresponding to those tokens.

For example,

apiVersion: authorization.onboarding.tetrate.io/v1alpha1
kind: OnboardingPolicy
metadata:
name: allow-onpremise-jwt-vms
namespace: bookinfo
spec:
allow:
- workloads:
- jwt:
issuer: "https://mycompany.corp"
subjects:
- "us-east-datacenter1-vm007"
- "us-west-datacenter2-vm008"
onboardTo:
- workloadGroupSelector:
matchLabels:
app: ratings

The above policy applies to those workloads that can authenticate themselves by means of an OIDC ID Token issued by https://mycompany.corp with a subject us-east-datacenter1-vm007 or us-west-datacenter2-vm008.

In those cases where OIDC ID Tokens from a given issuer include a map of fine-grained attributes associated with a workload, it is possible to define rules that match those attributes.

E.g.,

apiVersion: authorization.onboarding.tetrate.io/v1alpha1
kind: OnboardingPolicy
metadata:
name: allow-onpremise-jwt-vms
namespace: bookinfo
spec:
allow:
- workloads:
- jwt:
issuer: "https://mycompany.corp"
attributes:
- name: "region"
values:
- "us-east"
- "us-west"
- name: "instance_role"
values:
- "app-ratings"
onboardTo:
- workloadGroupSelector:
matchLabels:
app: ratings

The above policy applies the workloads that can authenticate themselves by means of an OIDC ID Token issued by https://mycompany.corp that includes 1) attribute region with one of the values us-east or us-west and 2) attribute instance_role with the value app-ratings.

OnboardingPolicyRule

OnboardingPolicyRule authorizes matching workloads to join the mesh and become a part of a WorkloadGroup.

FieldDescriptionValidation Rule

workloads

List of tetrateio.api.onboarding.authorization.v1alpha1.WorkloadIdentityMatcher
REQUIRED
Select the workloads to which this rule applies.

repeated = {
  min_items: 1
  items: {message:{required:true}}
}

onboardTo

List of tetrateio.api.onboarding.authorization.v1alpha1.WorkloadGroupMatcher
REQUIRED
List of WorkloadGroups these workloads are allowed to join.

repeated = {
  min_items: 1
  items: {message:{required:true}}
}

OnboardingPolicySpec

OnboardingPolicySpec is the specification of a policy that authorizes matching workloads to join the mesh and become a part of a WorkloadGroup.

FieldDescriptionValidation Rule

allow

List of tetrateio.api.onboarding.authorization.v1alpha1.OnboardingPolicyRule
REQUIRED
List of authorization rules.

repeated = {
  min_items: 1
  items: {message:{required:true}}
}

OnboardingPolicyStatus

OnboardingPolicyStatus represents the current status of the onboarding policy.

NameNumberDescription

WorkloadGroupMatcher

WorkloadGroupMatcher specifies matching WorkloadGroups.

FieldDescriptionValidation Rule

workloadGroupSelector

k8s.io.apimachinery.pkg.apis.meta.v1.LabelSelector
Selector of WorkloadGroups.

This field follows standard label selector semantics; if present but empty, it selects all WorkloadGroups.

message = {
  required: true
}

WorkloadIdentityMatcher

WorkloadIdentityMatcher specifies matching workloads according to their platform-specific identities.

FieldDescriptionValidation Rule

aws

tetrateio.api.onboarding.authorization.aws.v1alpha1.AwsIdentityMatcher
Match workloads with AWS-specific identities.

jwt

tetrateio.api.onboarding.authorization.jwt.v1alpha1.JwtIdentityMatcher
Match workloads with JWT identities.

k8s.io.apimachinery.pkg.apis.meta.v1.LabelSelector

A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects.

FieldDescriptionValidation Rule

matchLabels

map<string, string>
matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed.

matchExpressions

List of k8s.io.apimachinery.pkg.apis.meta.v1.LabelSelectorRequirement
matchExpressions is a list of label selector requirements. The requirements are ANDed. +optional

k8s.io.apimachinery.pkg.apis.meta.v1.LabelSelectorRequirement

A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values.

FieldDescriptionValidation Rule

key

string
key is the label key that the selector applies to. +patchMergeKey=key +patchStrategy=merge

operator

string
operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist.

values

List of string
values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. +optional