Clarify "runtime" terminology

[vturecek]

The term "runtime" is used in two contexts in the spec:

1. An implementation of the spec itself
2. The workload runtime that executes a workload type, such as a container runtime

We can quantify these terms when they're used in the spec, or come up with a different term altogether for (1). I'm open to either.

[xiang90]

1 is ideal I think. I will try to come up with a better term :P

[hongchaodeng]

Maybe "workload execution engine" or "engine" for 2 ?

[technosophos]

Here are all of the usages:

2.overview_and_terminology.md
21:> A cloud native application is a collection of interrelated, but discrete _components_ (services, tasks, workers) that, when coupled with configuration and instantiated in a suitable runtime, together accomplish a unified functional purpose.
117:__Component schematics__ permit __developers__ to declare the operational characteristics of the code they deliver _in infrastructure neutral terms_. Apart from not burdening developers with infrastructural concerns, this frees operators and runtimes to meet a component's infrastructural needs in whatever opinionated manner they see fit.
121:- A Workload Type: A declaration about what kind of runtime this component relies upon. (The platform will select a runtime that is capable of running this workload type.)
124:- Parameters: The parameters that can be adjusted for specific runtime configuration
129:A hydra platform supplies a runtime (or runtimes) that can execute components. Each type of objects that can be run by the Hydra runtime is represented by a _workload type_ that describes the following:

3.component_model.md
25:The exact meaning of this unit varies from platform to platform.  Implementors should consider that logical cpu is equivalent to one AWS vCPU or one Azure vCore or one GCP Core or one IBM vCPU. Fractional values are allowed. If a runtime does not support fractional units, it MUST round up (ceiling function) to the next integer value.
110:| `workloadType` | `string` | Y | | A succinct, semantically meaningful descriptor of the component's runtime profile. See ["Workload Types"](#workload-types). |
111:| `osType` | `string` | N | `linux` | The OS required to host (all of) the component's containers (since containers share a kernel with the underlying host). Possible values include:<ul><li>linux</li><li>windows</li></ul> For extended runtimes, this is passed in unaltered. |
114:| `workloadSettings` | [`[]WorkloadSetting`](#workloadsetting) | N | | Declaration of non-container settings that should be passed to the workload runtime|
132:A _workload type_ is an indicator to the runtime as to how it should execute the given workload. In other words, it provides a single field by which the developer can indicate to the runtime how the developer intends for this component to be executed.
138:- `core.hydra.io/v1alpha1.Singleton`: The group is `core.hydra`, meaning it is built-in. The version indicates that this is still an alpha version (`v1alpha1`). The kind is `Singleton`. This means the core singleton runtime must be used for this component.
139:- `azure.com/v1.Function`: The group is `azure.com` (which is a vendor-specific implementation, and may not be present on all runtimes). The version is `v1`, which marks this as stable. The kind is `Function`, whose runtime implementation is the Azure Functions offering.
154:The core workload types MUST all be supported according to the definitions in this section by any runtime implementation of this specification.
179: - Defines a container runtime where zero or more replicas of the same container may be run simultaneously. 
181: - A service is daemonized. A runtime MUST attempt to restart replicas that exit regardless of error code.
188: - Defines a container runtime where at most one replica of the same container may be run at a time.  
189: - A singleton service is daemonized. A runtime MUST attempt to restart the singleton replica if it exits regardless of error code.
196: - Defines a container runtime where zero or more replicas of the same container may be run simultaneously. 
198: - A worker is daemonized. A runtime MUST attempt to restart replicas that exit regardless of error code.
204: - Defines a container runtime where at most one replica of the same container may be run at a time.  
205: - A singleton worker is daemonized. A runtime MUST attempt to restart the singleton replica if it exits regardless of error code.
212: - Defines a container runtime where zero or more replicas of the same container may be run simultaneously.
214:  - A task is non-daemonized. A runtime MUST NOT attempt to restart replicas that exit without an error code.
220: - Defines a container runtime where at most one replica of the same container may be run at a time.  
221:  - A singleton task is non-daemonized. A runtime MUST NOT attempt to restart replicas that exit without an error code.
228:Extended workload types are _per runtime_, meaning that each runtime may define its own extended workload types beyond this specification. In the present version of the spec, allowing user-defined extended workload types is _not supported_.
230:Some workload types are specific to containers, a primary runtime target for the model. Other workload types may allow (or even require) non-component runtimes. For example, a workload type of `azure.com/v1.ContainerInstance` may _require_ that the containerized workload be run using the Azure Container Instances tool, while `azure.com/v1.Functions` may require that a particular non-containerized workload be executed using Azure Functions.
255:This section describes the runtime configuration necessary to run a containerized workload for this component.
272:This section describes additional configuration for a workload (settings that are not about a container runtime).
285:Workload settings are passed as name/value pairs, where the type of value may be anything supported by JSON/YAML. The runtim environment MAY choose to treat `workloadSettings` values as opaque, merely passing them directly to an implementing service. A runtime MAY return an error if certain constraints are not met, including:
294:Resources describe compute resources attached to a runtime.
303:For any resource that cannot be satisfied by the underlying platform, the platform MUST return an error and cease deployment. A resource is considered a requirement, and failure to meet that requirement means the runtime MUST NOT deploy the application. For example, if an application requests `1P` of memory, and that amount of memory is not available, the application deployment must fail. Likewise, if an application requires `1` gpu, and the runtime does not provide gpus, the application deployment MUST fail.
389:If both `fromParam` and `value` are specified, `fromParam` MUST take precedence, even if the parameter value is an empty value. If neither is specified, the runtime MUST produce an error.
592:Imagine a service runtime that checks out code from a Git repository and executes it as an Azure function. This service might be used as follows:

5.traits.md
3:A _trait_ is a discretionary runtime overlay that augments a component workload type (`workloadType`) with additional features. It is an opportunity for those in the _application operator_ role to make specific decisions about the configuration of components, but without involving the developer. A trait can be any operational configuration of a distributed application that applies to an individual component, such as traffic routing rules (e.g., load balancing policy, network ingress routing, circuit breaking, rate limiting), auto-scaling policies, upgrade strategies, and more.
5:The _traits system_ is defined in this specification as the way a runtime applies and manages operational behaviors to instances of components through traits.
7:Runtime implementations of the specification MUST provide the traits system for attaching operational behaviors to instances of components. 
13:Traits should be applied into the runtime at installation/upgrade time. Traits should not be checked "lazily", but should be checked when the trait-holding components are created.
26:Components can specify multiple traits, therefore a runtime MUST support the application of zero or more traits to a component. A runtime MUST produce an error and stop deployment if the requested traits cannot be fulfilled by the underlying runtime.
30:Any trait that is made available in a runtime MUST be implemented for that runtime. For example, there cannot be a trait for `autoscaling` in a runtime with no implementation of that trait.
34:The  traits system is designed to serve as an extension point for runtime operational capability while also providing common, and in some cases, necessary operational functionality for components.
36:The implementation details of a trait is beyond the scope of this document. However, to allow runtimes to implement arbitrary traits while maintaining a degree commonality for application portability across runtimes, traits are categorized in the following way:
38: - **Core traits.** This specification defines a set of trait definitions with type names in the `core.hydra.io` group. These traits provide operational functionality that is necessary for the operation of certain workload types and component features. Runtimes are REQUIRED to implement these traits as defined in this specification.
40: - **Standard traits.** The specification defines a set of trait definitions with type names in the `standard.hydra.io` group. These traits provide operational functionality that is commonly used by application operators and implemented by most runtimes. Runtimes are RECOMMENDED to use the standard trait definitions as defined in this specification when providing equivalent operational functionality to those listed in the standard trait definitions. In other words, if a runtime is implementing trait with behavior `foo` and a standard trait definition for behavior `foo` exists, the runtime SHOULD use the standard `foo` trait definition. Application operators that intend to maximize portability of their applications should use these trait definitions when available. Although this does not _guarantee_ portability of an application, it is designed to increase portability across runtimes.
42: - **Extension traits.** The specification allows a runtime to define its own set of trait definitions that are unique to that runtime in addition to those defined by core and standard traits. A runtime can choose to implement any set of traits in this category with any definition. Extension trait type names MUST NOT be in the `core.hydra.io` or `standard.hydra.io` groups.
50:Implementations of the Hydra runtime SHOULD make all supported traits discoverable in the format explained below.
159:This example illustrates using the manual scaler trait to manually scale a component by specifying the number of replicas the runtime should create. This trait has only one attribute in its properties: `replicaCount`. This takes an integer, and a value is required for this trait to be successfully applied. If, for example, an operational configuration used this trait but did not provide the `replicaCount`, the system would reject the operational configuration.

6.operational_configuration.md
5:A component schematic can be deployed into any number of runtimes, any number of times. We call each deployment of a component an _instance_. Each time a component is deployed, it must be deployed _with a configuration_. This section of the specification describes configurations.
7:An _operational configuration_ (sometimes abbreviated to _configuration_) is managed by the _app operator_ role, and provides information specific to the current instance of a component. The following information is considered specific to the runtime instance of a component:
46:## Runtime and Operational Configuration
48:The [Component Model](3.component_model.md) chapter of the specification defines how schematics are constructed. The resulting schematics may then be used to instantiate a component on a Hydra-compliant runtime.
50:Component schematics can be deployed into numerous different runtimes. But at runtime, there is a one-to-one correspondence between an _instance of an configuration_ and an _operational configuration_.
137:If no schema is supplied, a property will be passed to the trait runtime without structural validation. As long as it parses as YAML or JSON, it will be considered valid.

1.purpose_and_goals.md
15:- __Workload types and configurations__, which describe the underlying runtime for a particular workload, as well as exposing per-application configuration.
20:- Promote the genesis of multiple, _differentiated_ implementations of both tooling and runtimes which can operate on a common class of components and applications.
30:- Describing or defining the runtimes themselves

README.md
3:This repository holds the specifications for Hydra-compliant runtimes.

schema/component.schema.json
61:                "description": "A succinct, semantically meaningful descriptor of the component's runtime profile.",
85:                "description": "Declaration of non-container settings that should be passed to the workload runtime.",
125:            "description": "Additional configuration for a workload (settings that are not about a container runtime)",
150:            "description": "The runtime configuration necessary to run a containerized workload for this component.",

4.application_scopes.md
27:Core application scope types define grouping constructs for basic runtime behavior. They have the following characteristics:
32: - Runtimes MUST provide a default "root" application scope instance for each core application scope type.
33: - Runtimes MUST deploy each component instances into default "root" application scope instances when an operational configuration does not otherwise specify an application scope for a component instance.
39:|Network|`core.hydra.io/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.
44: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.
73:| `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. |

7.workload_types.md
24:The specification describes how to declare that a component is bound to a workload type. In addition, it exposes which settings are configurable on the underlying workload runtime.

Which ones do you find confusing?

[negz]

This overloaded term has certainly hindered discussions around OAM and Crossplane; it's been unclear whether "a Kubernetes OAM runtime" means "an OAM runtime built using Kubernetes" or "an OAM runtime that deploys applications to Kubernetes". i.e. It's quite possible to implement OAM as a Kubernetes controller that orchestrates a cloud provider's serverless functions API, and it's also possible to implement OAM as a Python cronjob that orchestrates Kubernetes APIs. :)