Merge pull request oam-dev#433 from resouer/dev

Fix app scope model

5.application_scopes.md

@@ -30,24 +30,24 @@ There are three kinds of application scope types:
     - 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.
 
- - **Standard application scope types**: Standard application scope types MUST be defined in `standard.oam.dev` group. These application scopes provide operational functionality that is commonly used by application operators and implemented by most runtimes. Runtimes are RECOMMENDED to use the standard application scope definitions as defined in this specification when providing equivalent operational functionality to those listed in the standard application scope definitions. In other words, if a runtime is implementing application scope with behavior `foo` and a standard application scope definition for behavior `foo` exists, the runtime SHOULD use the standard `foo` application scope definition. Application operators that intend to maximize portability of their applications should use these application scope definitions when available. Although this does not _guarantee_ portability of an application, it is designed to increase portability across runtimes.
+ - **Standard application scope types**: Standard application scope types MUST be defined in `standard.oam.dev` group. These application scopes provide operational functionality that is commonly used by application operators and implemented by most runtimes. If a runtime is implementing a behavior `foo` and a standard application scope for behavior `foo` exists, the runtime SHOULD use the standard `foo` application scope. Application operators that intend to maximize portability of their applications should use these application scopes when available. Although this does not _guarantee_ portability of an application, it is designed to increase portability across runtimes.
 
  - **Extended application scope types**:  Each runtime MAY choose to implement any number of extended application scopes.
 
 ## Defining an application scope
 
-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.
+This section is normative because application scope instances 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.
+> Note that application scope doesn't provide abstraction for now, i.e. no template and parameters could be defined for application scope by a scope definition. We may define abstraction for scopes similar to traits in the future if it's required. 
 
 ### Top-Level Attributes
 
-These attributes provide top-level information about the scope definition.
+These attributes provide top-level information about the application scope.
 
 | Attribute | Type | Required | Default Value | Description |
 |-----------|------|----------|---------------|-------------|
 | `apiVersion` | `string` | Y || A string that identifies the version of the schema the object should have. The core types uses `core.oam.dev/v1alpha2` in this version of specification. |
-| `kind` | `string` | Y || Must be `ScopeDefinition`. |
+| `kind` | `string` | Y || Must end with `Scope`. |
 | `metadata` | [`Metadata`](2.overview_and_terminology.md#metadata) | Y | | Information about the scope. |
 | `spec`| [`Spec`](#spec) | Y || A specification for scope attributes. |
 
@@ -57,16 +57,12 @@ The spec defines the constituent parts of a scope.
 
 | Attribute | Type | Required | Default Value | Description |
 |-----------|------|----------|---------------|-------------|
-| `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. |
-| `definitionRef` | [`DefinitionRef`](#definitionRef) | Y | | Index of the scope definition. |
+| `allowComponentOverlap` | `bool` | N | true | 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. |
 
-#### DefinitionRef
 
-See [*DefinitionRef*](4.workload_types.md#DefinitionRef).
+## Examples
 
-## Standard application scopes
-
-The following standard scopes are defined in the OAM specification.
+The following scopes are defined in the OAM specification.
 
 ### Network Scope
 

standard/scopes/health_scope.md

@@ -7,20 +7,16 @@ The health scope on its own does not take any action based on health status. It
 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.
 
-## Schematic
+## Properties
 
 | Attribute | Type | Required | Default Value | Description |
 |-----------|------|----------|---------------|-------------|
 | `probe-timeout` | `int32` | Y | | ProbeTimeout is the amount of time in seconds to wait when receiving a response before marked failure.|
 | `probe-interval` | `int32` | Y | | ProbeInterval is the amount of time in seconds between probing tries. |
 
-## Spec
-
-As a core scope, the spec of network scope has already defined. So we don't need any scope definition for this.
-
 ## Instance Example
 
-For example, a network scope instance can be like below:
+For example, a health scope instance can be like below:
 
 ```yaml
 apiVersion: core.oam.dev/v1alpha2
@@ -31,3 +27,24 @@ spec:
   probe-timeout: 5
   probe-interval: 5
 ```
+
+## Usage Example
+
+An application could reference above scope instance as below:
+
+```yaml
+apiVersion: core.oam.dev/v1alpha2
+kind: ApplicationConfiguration
+metadata:
+  name: example-appconfig
+spec:
+  components:
+    - componentName: example-component
+      traits:
+        ...
+      scopes:
+        - scopeRef:
+            apiVersion: core.oam.dev/v1alpha2
+            kind: HealthScope
+            name: example-health-scope
+```

standard/scopes/network_scope.md

@@ -6,18 +6,14 @@ The network scope may also be queried by traffic management traits to determine
 
 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.
 
-## Schematic
+## Properties
 
 | Attribute | Type | Required | Default Value | Description |
 |-----------|------|----------|---------------|-------------|
 | `networkId` | `string` | Y | | The id of the network, e.g. vpc-id, VNet name. |
 | `subnetIds` | `array` | Y | | 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. |
 | `internetGatewayType` | `string` | Y | | The type of the gateway, options are 'public', 'nat'. Empty string means no gateway. |
 
-## Spec
-
-As a core scope, the spec of network scope has already defined. So we don't need any scope definition for this.
-
 ## Instance Example
 
 For example, a network scope instance can be like below:
@@ -31,10 +27,32 @@ metadata:
     region: us-west
     environment: production
 spec:
+  allowComponentOverlap: true # can be skipped
   networkId: cool-vpc-network
   subnetIds:
-  - cool-subnetwork
-  - cooler-subnetwork
-  - coolest-subnetwork
+    - cool-subnetwork
+    - cooler-subnetwork
+    - coolest-subnetwork
   internetGatewayType: nat
 ```
+
+## Usage Example
+
+An application could reference above scope instance as below:
+
+```yaml
+apiVersion: core.oam.dev/v1alpha2
+kind: ApplicationConfiguration
+metadata:
+  name: example-appconfig
+spec:
+  components:
+    - componentName: example-component
+      traits:
+        ...
+      scopes:
+        - scopeRef:
+            apiVersion: standard.oam.dev/v1alpha2
+            kind: NetworkScope
+            name: example-vpc-network
+```