Jump to: navigation, search

Group Policy:Architecture/Policy Model

The policy model is built around the idea of placing endpoints into groups that share the same semantics, and then defining what other groups those endpoints need to communicate, and then finally defining how these endpoints need to communicate. In this way, we represent the requirements of the application and then force the infrastructure to figure out how to meet these requirements, rather than defining the policy in terms of the underlying infrastructure.

Policy Concepts

This section describes some of the most important concepts in the policy model. See the next section on Policy Resolution for a description of how these fit together to determine how to apply the policy to the network.

An endpoint is a specific device in the network. It could be a VM interface, a physical interface, or other network device. Endpoints are defined and assigned to endpoint groups through mechanisms that are not specified by the policy model (See Endpoint Registry for more information). Endpoints can have associated conditions that are just labels that represent some potentially-transient status information about an endpoint.
Endpoint Group
Endpoint groups are sets of endpoints that share a common set of policies. Endpoint groups can participate in contracts that determine the kinds of communication that is allowed. They also expose both requirements and capabilities, which are labels that help to determine how contracts will be applied. An endpoint group is allowed to specify a parent endpoint group from which it inherits.
Contracts determine which endpoints can communicate and in what way. Contracts between pairs of endpoint groups are selected by the contract selectors defined by the endpoint group. Contracts expose qualities, which are labels that can help endpoint groups to select contracts. Once the contract is selected, contracts have clauses that can match against requirements and capabilities exposed by endpoint groups, as well as any conditions that may be set on endpoints, in order to activate subjects that can allow specific kinds of communication. A contracts is allowed to specify a parent contract from which it inherits.
Clauses are defined as part of a contract. Clauses determine how a contract should be applied to particular endpoints and endpoint groups. Clauses can match against requirements and capabilities exposed by endpoint groups, as well as any conditions that may be set on endpoints. Matching clauses define some set of subjects which can be applied to the communication between the pairs of endpoints.
Subjects describe some aspect of how two endpoints are allowed to communicate. Subjects define an ordered list of rules that will match against the traffic and perform any necessary actions on that traffic. No communication is allowed unless a subject allows that communication.

Introduction to Policy Resolution

There are a lot of concepts to unpack and it can be difficult to see how this all fits together. Let's imagine that we want to analyze a particular flow of traffic in the network and walk through the policy resolution process for that flow. The key here is that the policy resolution process happens logically in three phases. First, we need to select the contracts that are in scope for the endpoint groups of the endpoints of the flow. Next, we select the set of subjects that apply to the endpoints of the flow. Finally, we apply the rules from the applicable subjects to the actual network traffic in the flow.

Note that this description gives a semantic understanding of how the policy model should be applied. The steps described here may or may not correspond to an actual efficient implementation of this policy model.

Contract Selection

The first step in policy resolution is to select the contracts that are in scope. For a particular flow, we look up the endpoint groups for each of the endpoints involved in the flow.

Endpoint groups participate in contracts either as a provider or as a consumer. Each endpoint group can participate in many contracts at the same time, but for each contract it can be in only one role at a time. In addition, there are two ways for an endpoint group to select a contract: either with a named selector or with a target selector. Named selectors simply select a specific contract by its contract ID. Target selectors allow for additional flexibility by matching against qualities of the contract's target.

Thus, there are a total of 4 kinds of contract selector:

provider named selector
Select a contract by contract ID, and participate as a provider.
provider target selector
Match against a contract's target with a quality matcher, and participate as a provider.
consumer named selector
Select a contract by contract ID, and participate as a consumer.
consumer target selector
Match against a contract's target with a quality matcher, and participate as a consumer.

So to determine which contracts are in scope for our flow, we must find contracts where either the source endpoint group selects a contract as either a provider or consumer, while the destination endpoint group matches against the same contract in the corresponding role. So if endpoint x in endpoint group X is communicating with endpoint y in endpoint group Y, a contract C is in scope if either X selects C as a provider and Y selects C as a consumer, or X selects C as a consumer and Y selects C as a provider.

The details of how quality matchers work are described further below in Matchers. For now, we can simply state that quality matchers provide a flexible mechanism for selecting the contract based on labels.

The end result of the contract selection phase can be thought of as a set of tuples representing selected contract scopes. The fields of the tuple are:

  • Contract ID
  • The provider endpoint group ID
  • The name of the selector in the provider endpoint group that was used to select the contract, which we'll call the matching provider selector.
  • The consumer endpoint group ID
  • The name of the selector in the consumer endpoint group that was used to select the contract, which we'll call the matching consumer selector.

Subject Selection

The second phase in policy resolution is to determine which subjects are in scope. The subjects allow us to define what kinds of communication are allowed between endpoints in the endpoint groups. For each of the selected contract scopes from the contract selection phase, we'll need to apply the subject selection procedure.

Before we can discuss how the subjects are matched, we need to first examine what we match against to bring those subjects into scope. We match against labels called, capabilities, requirements and conditions. Endpoint groups have capabilities and requirements, while endpoints have conditions.

Requirements and Capabilities

When acting as a provider, endpoint groups expose capabilities, which are labels representing specific pieces of functionality that can be exposed to other endpoint groups that may meet functional requirements of those endpoint groups. When acting as a consumer, endpoint groups expose requirements, which are labels that represent that fact that the endpoint group requires some specific piece of functionality. As an example, we might create a capability called "user-database" which indicates that an endpoint group contains endpoints that implement a database of users. We might create a requirement also called "user-database" to indicate an endpoint group contains endpoints that will need to communicate with the endpoints that expose this service. Note that in this example the requirement and capability have the same name, but the user need not follow this convention.

We examine the matching provider selector (that was used by the provider endpoint group to select the contract) to determine the capabilities exposed by the provider endpoint group for this contract scope. The provider selector will have a list of capabilities either directly included in the provider selector or inherited from a parent selector or parent endpoint group (See Inheritance below). Similarly, the matching consumer selector will expose a set of requirements.


Endpoints can have conditions, which are labels representing some relevant piece of operational state related to the endpoint. An example of a condition might be "malware-detected," or "authentication-succeeded." We'll be able to use these conditions to affect how that particular endpoint can communicate. To continue with our example, the "malware-detected" condition might cause an endpoint's connectivity to be cut off, while "authentication-succeeded" might open up communication with services that require an endpoint to be first authenticated and then forward its authentication credentials.

Conditions do not actually appear in the policy configuration model other than as a named reference. To determine the set of conditions that apply to a particular endpoint, the endpoint will need to be looked up in the endpoint registry, and it associated condition labels retrieved from there.


Clauses are what will do the actual selection of subjects. A clause has four lists of matchers in two categories. In order for a clause to become active, all four lists of matchers must match. A matching clause will select all the subjects referenced by the clause. Note that an empty list of matchers counts as a match.

The first category is the consumer matchers, which match against the consumer endpoint group and endpoints. The consumer matchers are:

Requirement matchers
matches against requirements in the matching consumer selector.
Consumer condition matchers
matches against conditions on endpoints in the consumer endpoint group

The second category is the provider matchers, which match against the provider endpoint group and endpoints. The provider matchers are:

Capability matchers
matches against capability in the matching provider selector.
Provider condition matchers
matches against conditions on endpoints in the provider endpoint group

Clauses have a list of subjects that apply when all the matchers in the clause match. The output of the subject selection phase logically is a set of subjects that are in scope for any particular pair of endpoints.

Rule Application

Now that we have a list of subjects that apply to the traffic between a particular set of endpoints, we're ready to describe how we actually apply policy to allow those endpoints to communicate. The applicable subjects from the previous step will each contain a set of rules.

Rules consist of a set of classifiers and a set of actions. Classifiers match against traffic between two endpoints. An example of a classifier would be something that matches against all TCP traffic on port 80, or one that matches against HTTP traffic containing a particular cookie. Actions are specific actions that need to be taken on the traffic before it reaches its destination. Actions could include tagging or encapsulating the traffic in some way, redirecting the traffic, or applying some service chain. For more information on how classifiers and actions are defined, see below under Subject Features.

If and only if all classifiers on a rule matches, all the actions on that rule are applied (in order) to the traffic. Only the first matching rule will apply.

Rules, subjects, and actions have an order parameter, where a lower order value means that a particular item will be applied first. All rules from a particular subject will be applied before the rules of any other subject, and all actions from a particular rule will be applied before the actions from another rule. If more than item has the same order parameter, ties are broken with a lexicographic ordering of their names, with earlier names having logically lower order.

We've now reached final phase in the three-phases policy resolution process. First, we found the set of contract scopes to apply. Second, we found the set of subjects to apply. Finally, we saw how we apply the subjects to traffic between pairs of endpoints in order to realize the policy. The remaining sections of this document will fill in additional detail for the policy resolution process.


Matchers have been mentioned a few times now without really explaining what they are. Matchers specify a set of labels (which include requirements, capabilities, conditions, and qualities) to match against. There are several kinds of matchers that operate similarly:

  • Quality matchers are used in target selectors during the contract selection phase. Quality matchers provide a more advanced and flexible way to select contracts compared to a named selector.
  • Requirement matchers and capability matchers are used in clauses during the subject selection phase to match against requirements and capabilities on endpoint groups
  • Condition matchers are used in clauses during the subject selection phase to match against conditions on endpoints

A matcher is, at its heart, fairly simple. It will contain a list of label names, along with a match type. The match type can be either "all," which means the matcher matches when all of its labels match, "any," which means the matcher matches when any of its labels match, or "none," which means the matcher matches when none of its labels match. Note that a matcher which always matches can be made by matching against an empty set of labels with a match type of "all."

Additionally each label to match can optionally include a relevant "name" field. For quality matchers, this is a target name. For capability and requirement matchers, this is a selector name. If the name field is specified, then the matcher will only match against targets or selectors with that name, rather than any targets or selectors.

There are some additional semantics related to inheritance. Please see the section for Inheritance for more details.

Quality Matchers

A contract contains targets that are just a set of quality labels. A target selector on an endpoint group matches against these targets using quality matchers. A quality matcher is a matcher where the label it matches is a quality, and the name field is a target name.

Requirement and Capability Matchers

The matching selector from the contract selection phase will define either requirements or capabilities for the consumer and provider endpoint groups, respectively. Clauses can match against these labels using requirement and capability matchers. Requirements matchers match against requirements while capability matchers match against capabilities. In both cases, the name field is a selector.

Condition Matcher

Endpoints can have condition labels. The condition matcher can be used in a clause to match against endpoints with particular combinations of conditions.


The system allows multiple tenants that are designed to allow separate domains of administration. Contracts and endpoint groups are defined within the context of a particular tenant. Endpoints that belong to endpoint groups in separate tenants cannot communicate with each other except through a special mechanism to allow cross-tenant contracts called contract references.

While it would be be possible to define semantics for tenant inheritance, as currently defined there is no way for tenants to inherit from each other. There is, however, a limited mechanism through the special common tenant (see below). All references to names are within the scope of that particular tenant, with the limited exceptions of the common tenant and contract references.

Contract References

Contract references are the mechanism by which endpoints in different tenants can communicate. This is especially useful for such common use cases as gateway routers or other shared services. In order to for an endpoint group to select a contract in a different tenant, there must first exist a contract reference defined in the endpoint group's local tenant. The contract reference is just a tenant ID and a contract ID; this will bring that remote contract into the scope of the local contract. Note that this reference may be subject to additional access control mechanisms.

Endpoint groups can participate in such remotely-defined contracts only as consumers, not as providers.

Once the contract reference exists, endpoint groups can now select that contract using either named or target selectors. By defining a contract reference, the qualities and targets in that contract are imported into the namespace of the local tenant for the contract selection phase. Similarly, the requirements and conditions from the local tenant will be used when performing the consumer matches in the subject selection phase.

Common Tenant

The common tenant is an area where definitions that are useful for all tenants can be created. Everything defined in the common tenant behaves exactly as though it were defined individually in every tenant. This applies to resolution of labels for the purposes of contract selection, as well as subject feature instances (see below).

If a name exists in both the common tenant and another tenant, then when resolving names within the context of that tenant the definition in the common tenant will be masked. One special case to consider is if a definition in a tenant defines the common tenant definition as its parent and uses the same name as the parent object. This works as you might expect: the name reference from the child definition will extend the behavior of the definition in the common tenant, but then mask the common tenant definition so that references to the name within the tenant will refer to the extended object.

Subject Features

Subject features are objects that can be used as a part of a subject to affect the communication between pairs of endpoints. This is where the policy model meets the underlying infrastructure. Because different networks will have different sets of features, we need some way to represent to the users of the policy what is possible. Subject features are the answer to this.

There are two kinds of subject features: classifiers and actions. Classifiers match on traffic between endpoints, and actions perform some operation on that traffic (See above for more information on how they are used).

Subject features are defined with a subject feature definition. The definition defines a name and description for the feature, along with a set of parameters that the item can take. This is the most general description for the subject feature, and this definition is global and applies across all tenants. As an example, a classifier definition might be called "tcp_port", and would take an integer parameter "port".

Next, there are subject feature instances. Subject feature instances are scoped to a particular tenant, and reference a subject feature definition, but fill in all required parameters. To continue our example, we might define a classifier instance called "http" that references the "tcp_port" classifier and species the parameter "port" as 80.

Finally, there are subject feature references, which are references to subject feature instances. Subjects contain these subject feature references in order to apply the feature. These references also contain, as appropriate an order field to determine order of operations and fields for matching the direction of the traffic.

If the underlying network infrastructure is unable to to implement a particular subject, then it must raise an exception related to that subject. It may then attempt to relax the constraints in a way that allows it to implement the policy. However, when doing this it must attempt to avoid allowing traffic that should not be allowed. That is, it should "fail closed" when relaxing constraints.

Forwarding Model

Communication between endpoint groups can happen at layer 2 or layer 3, depending on the policy configuration. We define our model of the forwarding behavior in a way that supports very flexible semantics including overlapping layer 2 and layer 3 addresses.

We define several kinds of network domains, which represent some logical grouping or namespace of network addresses:

L3 Context
A layer 3 context represents a namespace for layer 3 addresses. It represents a domain inside which endpoints can communicate without requiring any address translation. A subtype of a forwarding context, which is a subtype of a network domain.
L2 Bridge Domain
A layer 2 bridge domain represents a domain in which layer 2 communication is possible when allowed by policy. Bridge domains each have a single parent L3 context. A subtype of an L2 domain, which is a subtype of a forwarding context.
L2 Flood Domain
A layer 2 flood domain represents a domain in which layer 2 broadcast and multicast is allowed. L2 flood domains each have a single parent L2 bridge domain. A subtype of an L2 domain.
An IP subnet associated with a layer 2 or layer 3 context. Each subnet has a single parent forwarding context. A subtype of a network domain

Every endpoint group references a single network domain.


This section contains information on how inheritance works for various objects in the system. This is covered here to avoid cluttering the main sections with a lot of details that would make it harder to see the big picture.

Some objects in the system include references to parents, from which they will inherit definitions. The graph of parent references must be loop free. When resolving names, the resolution system must detect loops and raise an exception. Objects that are part of these loops may be considered as though they are not defined at all.

Generally, inheritance works by simply importing the objects in the parent into the child object. When there are objects with the same name in the child object, then the child object will override the parent object according to rules which are specific to the type of object. We'll next explore the detailed rules for inheritance for each type of object

Endpoint Groups

Endpoint groups will inherit all their selectors from their parent endpoint groups. Selectors with the same names as selectors in the parent endpoint groups will inherit their behavior as defined below.


Selectors include provider named selectors, provider target selectors, consumer named selectors, and consumer target selectors. Selectors cannot themselves have parent selectors, but when selectors have the same name as a selector of the same type in the parent endpoint group, then they will inherit from and override the behavior of the selector in the parent endpoint group.

Named Selectors

Named selectors will add to the set of contract IDs that are selected by the parent named selector.

Target Selectors

A target selector in the child endpoint group with the same name as a target selector in the parent endpoint group will inherit quality matchers from the parent. If a quality matcher in the child has the same name as a quality matcher in the parent, then it will inherit as described below under Matchers.


Contracts will inherit all their targets, clauses and subjects from their parent contracts. When any of these objects have the same name as in the parent contract, then the behavior will be as defined below.


Targets cannot themselves have a parent target, but it may inherit from targets with the same name as the target in a parent contract. Qualities in the target will be inherited from the parent. If a quality with the same name is defined in the child, then this does not have any semantic effect except if the quality has its inclusion-rule parameter set to "exclude." In this case, then the label should be ignored for the purpose of matching against this target.


Subjects cannot themselves have a parent subject, but it may inherit from a subject with the same name as the subject in a parent contract.

The order parameter in the child subject, if present, will override the order parameter in the parent subject.

The rules in the parent subject will be added to the rules in the child subject. However, the rules will not override rules of the same name. Instead, all rules in the parent subject will be considered to run with a higher order than all rules in the child; that is all rules in the child will run before any rules in the parent. This has the effect of overriding any rules in the parent without the potentially-problematic semantics of merging the ordering.


Clauses cannot themselves have a parent clause, but it may inherit from a clause with the same name as the clause in a parent contract.

The list of subject references in the parent clause will be added to the list of subject references in the child clause. There is no meaningful overriding possible here; it's just a union operation. Note of course though that a subject reference that refers to a subject name in the parent contract might have that name overridden in the child contract.

Each of the matchers in the clause are also inherited by the child clause. Matchers in the child of the same name and type as a matcher from the parent will inherit from and override the parent matcher. See below under Matchers for more information.


Matchers include quality matchers, condition matchers, requirement matchers, and capability matchers. Matchers cannot themselves have parent matchers, but when there is a matcher of the same name and type in the parent object, then the matcher in the child object will inherit and override the behavior of the matcher in the parent object.

The match type, if specified in the child, overrides the value specified in the parent.

Labels are also inherited from the parent object. If there is a label with the same name in the child object, this does not have any semantic effect except if the label has its inclusion-rule parameter set to "exclude." In this case, then the label should be ignored for the purpose of matching. Otherwise, the label with the same name will completely override the label from the parent.

Subject Feature Definitions

Subject features definitions, including classifier definitions and subject definitions can also inherit from each other by specifying a parent object. These are a bit different from the other forms of override because they do not merely affect the policy resolution process, but rather affect how the policy is applied in the underlying infrastructure.

For the purposes of policy resolution, a subject feature will inherit from its parent any named parameters. However, unlike in other cases, if a named parameter with the same name exists in the child as in the parent, this is an invalid parameter and will be ignored in the child. That is, the child cannot override the type of a named parameter in a child subject feature.

For the purposes of applying the subject in the underlying infrastructure, the child subject feature is assumed to add some additional functionality to the parent subject feature such that the child feature is a specialization of that parent feature. For example, there might be a classifier definition for matching against a TCP port, and a child classifier definition that allowed for deep packet inspection for a particular protocol that extended the base classifier definition. In this case, the child classifier would be expected to match the TCP port as well as apply its additional deep packet inspection semantics.

If the underlying infrastructure is unable to apply a particular subject feature, it can attempt to fall back to implementing instead the parent subject feature. The parameter fallback-behavior determines how this should apply. If this is set to 'strict' then a failure to apply the child is a fatal error and the entire subject must be ignored. If the fallback behavior is 'allow-fallback' then the error is nonfatal and it is allowed to apply instead only the parent subject feature.


Policy _within_ an endpoint group