Contributing to Model Relationships

Relationships within Model play a crucial role in establishing concrete visualisations of efficient data flow between different components of Meshery. These are used to classify the nature of interaction between one or more interconnected Components.

Identify the relationship and any specific constraints to be enforced between the two specific components, their models or potentially other components, models, or environmental considerations.
Propose a specific visual representation for the relationship.
Visual representation examples:
- Hierarchical
- Sibling
- Binding
- Edge
Prospose the appropriate relationship type, using one of the predefined set of relationship types or suggest a new relationship where an existing type does not fit.
Create a Relationship Definition (yaml).
Create a policy for evaluation of the relationship (rego). See examples.
Add in Documentation.

Existing Relationships, their Definitions and their Subtypes

Hierarchical relationships involve either an ancestral connection of the components i.e. the creation/ deletion of a Component higher up affects the existence of the Components below in the lineage or a connection which involves the inheritence of features from one Component to the other.

Parent: A parent-child relationship implies the requirement of the parent component before the child component can be created. For example, a “Namespace” in Kubernetes can be a parent of “Pods” within that namespace. The namespace must exist before creating pods within it. Here is the source code for the above example.
Inventory: A hierarchical inventory relationship implies the configuration of (parent) component is patched with the configuration of other (child) component. For example, Wasm filters can inherit features and functionalities from Envoy filters. This can be used to build on existing functionalities provided by Envoy filters and further extend them using Wasm filters. It enables a modular and scalable approach to customize the behavior of the proxy while maintaining a clear hierarchy of features. Here is the source code for the above example.

Edge relationships indicate the possibility of traffic flow between two components. They enable communication and interaction between different Components within the system.

Mount: This subtype addresses the storage and access possibility between involved components. For example, a “PersistentVolume” can be mounted to a “Pod” to provide persistent storage for the pod’s data. Here is the source code for the above example.
Network: This deals with IP addresses and DNS names and provides stable endpoints for communication. For example, a “Service” provides a stable endpoint for accessing multiple replicas of a “Deployment”. Here is the source code for the above example.
Firewall: This acts as intermediary for communications which include standard networking protocols like TCP and UDP. It can enforce network policies to control traffic between components. For example, a “NetworkPolicy” can be used to manage the traffic flow between different “Pods” in the cluster. Here is the source code for the above example.
Permission: This defines the permissions for components if they can have a possible relationship with other Components. It ensures that only authorized Components can interact with each other. For example, a “Role” can define permissions for Components to access specific resources. Here is the source code for the above example.

Sibling relationships represent connections between components that are at the same hierarchical level or share a common parent. Siblings can have the same or similar functionalities or may interact with each other in specific ways. These relationships facilitate communication and cooperation between components that are in the same group or category. For example, a Service and a Pod in Kubernetes are siblings as they share a common parent and are at the same hierarchical level. Here is the source code for the above example.

Structure of Selectors

Selectors are structured as an array, wherein each entry comprises a ‘from(self)’ field and a ‘to(other)’ field ([from: [{..}], to: [{..}]]), delineating the components involved in a particular relationship. These entries define the constraints necessary for the existence of said relationship, thus providing scoping within a relationship. Each item in the selector, uniquely defines a relation between the components listed. i.e. from and to fields are evaluated within the context of the selector.

Only the components within the same selector relates to each other via 1:many kind of relation between components listed inside the from and to field. i.e. Each object inside the from relates to each item inside the two field within a particular selector.

When defining relationships that involve a large number of combinations between from and to, selectors provide a mechanism to organize and manage these relationships. This prevents the need for crafting complex deny attributes and facilitates easier maintenance.

This arrangement enhances flexibility and reusability in the definition and configuration of relationships among components.

Selector example

selector: [
{
"allow": {
"from": [
{
"kind": "WASMFilter",
"model": "istio-base",
"patch": {
"patchStrategy": "replace",
"mutatorRef": [
[
"settings",
"config"
],
[
"settings",
"wasm-filter"
]
],
"description": "WASM filter configuration to be applied to Envoy Filter."
}
},
{
"kind": "EBPFFilter",
.....
}
],
"to": [
{
"kind": "EnvoyFilter",
"model": "istio-base",
"patch": {
"patchStrategy": "replace",
"mutatedRef": [
[
"settings",
"configPatches",
"_",
"patch",
"value"
]
],
"description": "Receive the WASM filter configuration."
}
},
{
"kind" : "WASMPlugin",
....
}
...
]
},
"deny": {
...
}
},
{
"allow": {
"from": [
{
"kind": "ConfigMap",
"model": "kubernetes",
"patch": {
"patchStrategy": "replace",
"mutatorRef": [
[
"name"
]
],
"description": "In Kubernetes, ConfigMaps are a versatile resource that can be referenced by various other resources to provide configuration data to applications or other Kubnernetes resources.\n\nBy referencing ConfigMaps in these various contexts, you can centralize and manage configuration data more efficiently, allowing for easier updates, versioning, and maintenance of configurations in a Kubernetes environment."
}
}
],
"to": [
{
"kind": "Deployment",
"model": "kubernetes",
"patch": {
"patchStrategy": "replace",
"mutatedRef": [
[
"spec",
"containers",
"_",
"envFrom",
"configMapRef",
"name"
]
],
"description": "Deployments can reference ConfigMaps to inject configuration data into the Pods they manage. This is useful for maintaining consistent configuration across replica sets.\n\nThe keys from the ConfigMap will be exposed as environment variables to the containers within the pods managed by the Deployment."
}
},
{
"kind": "StatefulSets",
"model": "kubernetes",
"patch": {
....
}
}
...
]
},
"deny": {
...
}
}
]

The `selector` defined for the relationship between `WasmFilter` and `EnvoyFilter` (the first item in the array) is entirely independent from the `selector` defined for the relationship between `ConfigMap` and `Deployment`. This ensures independence in how these components relate to each other while still permitting similar types of relationships. The above relation shows `WASMFilter` and `EBPFFilter` defined inside `from` relates to each component defined inside `to` `(EnvoyFilter, WASMPlugin...)`. Similarly, `ConfigMap` defined inside `from` relates to each component defined inside `to` `(Deployment, StatefulSet,...)`

What is `evaluationQuery` attribute and how to determine value for `evaluationQuery` inside relationship definition?

As all relationship definitions are backed by OPA policies and the relationships depending upon their Kind and Subtype needs to be evaluated with respective policies, the policy to invoke for evaluation is determined by the property evaluationQuery, which follows the convention as kind_subtype_relationship.

Eg: If you are defining/updating a relationship definition with kind: Edge and subType: Network, the value for the attribute `evaluationQuery` should be edge_network_relationship.

Each policy has set of rules defined and the evaluationQuery attribute corresponds to the main rule defined inside the policy, during the policy eval the results are collected from this rule.

Configuring the scopes of the relationship definitions

The extent to which a relationship affects components within a model or beyond a model is defined and controlled using scopes. Scopes are defined using the model and version attributes within the relationship schema.

Global Scope

Relationships can be confined to specific model, a specific model version, or can be allowed affects all models. The relationship schema has a model and version attribute which facilitates this control. For example, if the model is specified as aws-ec2-controller, the relationship will work for those components which belongs to the aws-ec2-controller model.

Local Scope

Scope is defined and controlled via the selectors Selectors attribute in the relationships.

Best practices for defining new relationships

Ensure that the deny selectors and allow selectors do not conflict each other i.e. relations are not getting overlapped for allow and deny selectors.
To configure a relationship to be applied across models, ensure model property for those relationships are set to *, to limit the relationships to specific model, specify correct model(case sensitive).
To configure a relationship to be applied across all versions of a particular model, ensure version property for those relationships are set to *, to limit the relationships to specific version of a model, specify correct model version.
Support for specifying version property as a regex to ensure relationships are applied to a subset of versions of a model is coming soon.
The evaluationQuery property determines the OPA policy to invoke for relationship evaluation, specify correct rego query. To understand what query to specify refer.
If a path mutatedRef/mutatorRef contains more than one array path then only first array positin can be sprciifced as _ for others explicity meniton them as 0
Currently mutatedRef doesn’t supoort having an aaray

Things to keep in mind while defining relationships

Targets of a Relationship can be specific Components or entire Models.
The values for Kind, Version and Model are case-sensitive.
The convention is to use camel-casing for Kind and SubType values.
Absence of a field means in the selector means “*” (or wildcard).
- If we have a selector with {Kind: Pod, Model: Kubernetes}, the absence of the Version field here means that all the versions of the Kubernetes Pod resource (e.g. k8s.io/v1/betav2) will match.
In the event of conflicting Relationship Definitions, union between them is taken.
- If we have two Relationships, one from (Component A) to (Component B and Component F), and another from (Component A) to (Component B and Component C), then it is similar to having a Relationship from Component A to Component B, C and F
In the event of an overlapping set of complementary Relationship Definitions, Union.
In the event of an overlapping set of conflicting Relationship Definitions:
- No relationship type (Kind) is inherently more important than the next one, so will not be any case of conflict