Application scopes are used to group components together into logical applications by providing different forms of application boundaries with common group behaviors.
Application scopes have the following general characteristics:
- Application scopes SHOULD be used when defining behavior or metadata that is common to a group of component instances.
- A component MAY be deployed into multiple application scopes of different types simultaneously.
- Application scope types MAY determine whether or not components can be deployed into multiple instances of the same application scope type simultaneously.
- Application scopes MAY be used as a connecting mechanism between groups of components and capabilities provided by infrastructure, such as networking, or external capabilities, such as identity providers.
The following diagram illustrates how components can be grouped into overlapping application scopes to create different application boundaries:
This example shows two scope types with four components distributed among them.
Components A, B, and C are deployed to the same health scope. The health scope will collect aggregate health information on its constituent components that is evaluated during component upgrade operations. Query information provided by the health scope can be further used by traits or components that need to evaluate and/or perform actions based on the aggregate health of a set of components. This is a basic grouping construct for applications that provides a loose definition of dependencies between components.
Component A is isolated in its own network scope from components B, C, and D. This allows the infrastructure operator to supply different SDN settings for different groups of components, such as more restricted inbound/outbound rules on back-end components.
There are two kinds of application scope types:
- Core application scope types
- Extended application scope types
Core application scope types define grouping constructs for basic runtime behavior. They have the following characteristics:
- Core application scope types MUST be in the
core.oam.devnamespace. - Core application scope types MUST all be supported by any implementation of the specification. They may be implemented by any available feature in the platform, but they MUST be implemented according to the specification of each core application scope type.
- Instances of core workload types MUST be deployed into an instance of each core application scope type.
- Runtimes MUST provide a default "root" application scope instance for each core application scope type.
- Runtimes MUST deploy each component instances into default "root" application scope instances when an application configuration does not otherwise specify an application scope for a component instance.
The following core application scope types are defined by this specification:
| Name | Type | Description |
|---|---|---|
| Network | core.oam.dev/v1alpha1.Network |
This scope groups components into a network subnet boundaries and defines the general runtime networking model. Network definitions, rules, and policies are described by the infrastructure's network or SDN. |
| Health | core.oam.dev/v1alpha1.Health |
This scope groups components into an aggregate health group. The aggregate health of the constituent components within the group supplies information to upgrade and rollback mechanisms. |
Extended application scopes are optional per runtime, meaning that each runtime may choose which extended scopes are supported. In this version of the spec, allowing user-defined extended application scope types is not supported.
This section is normative because application scopes are an inspectable (and possibly shareable) part of the system. All scopes MUST be representable in the following format.
Application scopes are defined with schematics like components and traits.
The following attributes are common across all schemata defined in this document. This structure is designed to allow object type to be determined by scanning two fields (apiVersion and kind), and provide access to common fields in the metadata section. The spec section is where type-specific information is located, and in this section the spec section defines a Scope.
| Attribute | Type | Required | Default Value | Description |
|---|---|---|---|---|
apiVersion |
string |
Y | The specific version of the OAM specification in use. This version of the specification covers apiVersions in core.oam.dev/v1alpha1. |
|
kind |
string |
Y | For a scope schematic, must be ApplicationScope. |
|
metadata |
Metadata |
Y | Scope metadata. | |
spec |
Spec |
Y | A container for all remaining attributes. |
The spec defines the constituent parts of a scope.
| Attribute | Type | Required | Default Value | Description |
|---|---|---|---|---|
type |
string |
Y | Determines type of the application scope. The core types are defined above | |
allowComponentOverlap |
bool |
Y | Determines whether a component is allowed to be in multiple instances of this scope type simultaneously. When false, the runtime implementation MUST produce an error and stop deployment if an attempt is made to place a component into more than one instance of this scope type simultaneously. | |
parameters |
[]Parameter |
N | The scope's configuration options. |
The type field defines the type name for this type. Examples may be found in the Core Application Scope Types above. Extended scope types MUST NOT be in the core.oam.dev namespace. However, they must follow the group, version, kind notation. For example: scopes.example.com/v1.ExtendedNetworkScope
The parameters that a scope exposes to operators.
| Attribute | Type | Required | Default Value | Description |
|---|---|---|---|---|
name |
string |
Y | The parameter's name. Must be unique per scope. | |
description |
string |
N | A description of the parameter. | |
type |
string |
Y | The parameter's type (One of string, boolean, number). |
|
required |
boolean |
N | false |
Whether a value must be provided for the parameter. |
default |
type indicated by type field |
N | The parameter's default value. |
The name field allows Unicode letters, numbers and _ and -. The description field allows those characters plus whitespace and punctuation characters.
Application scope instances are defined and deployed in an application configuration. See Application Configuration for more information on deploying scopes.
The following core scope types are available:
- network scope
- health scope
The network scope groups components together and links them to a network or SDN. The network itself must be defined and operated by the infrastructure.
The network scope may also be queried by traffic management traits to determine discoverability boundaries for a service mesh or API boundaries for API gateways.
If no network scope is assigned, the platform MUST join the application to a default network. Within that default network, all components in the application configuration MUST be able to communicate to each other, and health probes MUST be able to contact any components who define health checking rules. The network joined, however, is platform-dependent. For example, cluster-based environments (such as Kubernetes) declare cluster-wide networks. Conversely, a truly serverless implementation may join the components to a network that only includes the components and the health checking probes.
The network scope is defined by the following spec:
apiVersion: core.oam.dev/v1alpha1
kind: ApplicationScope
metadata:
name: network
annotations:
version: v1.0.0
description: "network boundary that a group components reside in"
spec:
type: core.oam.dev/v1.NetworkScope
allowComponentOverlap: false
parameters:
- name: network-id
description: The id of the network, e.g. vpc-id, VNet name.
type: string
required: Y
- name: subnet-ids
description: >
A comma separated list of IDs of the subnets within the network. For example, "vsw-123" or ""vsw-123,vsw-456".
There could be more than one subnet because there is a limit in the number of IPs in a subnet.
If IPs are taken up, operators need to add another subnet into this network.
type: string
required: Y
- name: internet-gateway-type
description: The type of the gateway, options are 'public', 'nat'. Empty string means no gateway.
type: string
required: NThe health scope aggregates health states for components. Parameters of the health scope can be set to determine the percentage of components that must be unhealthy to consider the entire scope unhealthy.
The health scope on its own does not take any action based on health status. It is only a group health aggregator that can be queried and used by other processes and parts of an application, such as:
- Application upgrade traits can monitor the aggregate health of a health scope and decide when to initiate an automatic rollback.
- Monitoring applications can monitor the aggregate health of a health scope to issue alerts.
The health scope is defined by the following spec:
apiVersion: core.oam.dev/v1alpha1
kind: ApplicationScope
metadata:
name: health
annotations:
version: v1.0.0
description: "aggregated health state for a group of components."
spec:
type: core.oam.dev/v1alpha1.HealthScope
allowComponentOverlap: true
parameters:
- name: probe-method
description: The method to probe the components, e.g. 'httpGet'.
type: string
required: true
- name: probe-endpoint
description: The endpoint to probe from the components, e.g. '/v1/health'.
type: string
required: true
- name: probe-timeout
description: The amount of time in seconds to wait when receiving a response before marked failure.
type: integer
required: false
- name: probe-interval
description: The amount of time in seconds between probing tries.
type: integer
required: false
- name: failure-rate-threshold
description: If the rate of failure of total probe results is above this threshold, declared 'failed'.
type: double
required: false
- name: healthy-rate-threshold
description: If the rate of healthy of total probe results is above this threshold, declared 'healthy'.
type: double
required: false
- name: health-threshold-percentage
description: The % of healthy components required to upgrade scope
type: double
required: false
- name: required-healthy-components
description: Comma-separated list of names of the components required to be healthy for the scope to be health.
type: []string
required: falseThe following extended scope types are available:
- resource quota scope
- identity scope
The resource quota scope sets resource quotas on a group of components. Resources include CPU, memory, storage, etc. Setting resource quotas for a scope applies across all components within the scope; in other words, the total resource consumption for all components within a scope cannot exceed a certain value.
This is an example of a resource quota scope definition.
apiVersion: core.oam.dev/v1alpha1
kind: ApplicationScope
metadata:
name: myResourceQuotas
annotations:
version: v1.0.0
description: "The production configuration for Corp CMS"
spec:
type: resources.oam.dev/v1.ResourceQuotaScope
allowComponentOverlap: false
parameters:
- name: CPU
description: maximum CPU to be consumed by this scope
type: double
required: Y
- name: Memory
description: maximum memory to be consumed by this scope
type: double
required: YThe identity scope provides identities in components when authenticating to any service. The identities and its credentials are supplied and managed by an external identity provider.
This is an example of a identity scope definition.
apiVersion: core.oam.dev/v1alpha1
kind: ApplicationScope
metadata:
name: myIdentityScope
annotations:
version: v1.0.0
description: "The production configuration for Corp CMS"
spec:
type: identity.oam.dev/v1.IdentityScope
allowComponentOverlap: true
parameters:
- name: IdentityProvider
description: the provider of identity for the scope
type: string
required: Y| Previous Part | Next Part |
|---|---|
| 3. The Component Model | 5. Traits |