Add an Application Model object

Signed-off-by: Matt Butcher <matt.butcher@microsoft.com>

4.application_model.md

@@ -0,0 +1,207 @@
+# Application Model
+
+The Hydra approach identifies four important roles:
+
+- The developer: Creates and maintains components (microservices)
+- The application architect: Defines an application as composed of components
+- The application operator: Instantiates an application, providing configuration
+- The infrastructure operator: Maintains the underlying platform, making low-level decisions about infrastructure
+
+The previous section of the specification defines the component model. This section defines how components can be composed in an application.
+
+> The term "application" is not intended to provide a one-size-fits-all definition of what an application is. Rather, it is used to describe how a set of related components can be treated as a single functional unit. Our use of the term is not intended to enforce a particular design methodology. Users of the Hydra platform may, for example, use several application models to describe a single large platform.
+
+## Representation
+
+The `ApplicationModel` object follows the same basic structure as other Hydra manifests.
+
+### Top-Level Attributes
+
+The top-level attributes of a trait define its metadata, version, kind, and spec.
+
+| Attribute | Type | Required | Default Value | Description |
+|-----------|------|----------|---------------|-------------|
+| `apiVersion` | `string` | Y || The specific version of the specification in use. At present only `core.hydra.io/v1alpha1` is defined. |
+| `kind` | `string` | Y || The string `ApplicationModel` |
+| `metadata` | [`Metadata`](#metadata) | Y | | ApplicationModel metadata. |
+| `spec`| [`Spec`](#spec) | Y || A specification for application models. |
+
+### Metadata
+
+Metadata describes this Application Model. The metadata section is defined in [Section 3](3.component_model.md#metadata).
+
+### Spec
+
+The job of an Application Model is to relate multiple components to a single functional unit. The `spec` section declares the relationship.
+
+| Attribute | Type | Required | Default Value | Description |
+|-----------|------|----------|---------------|-------------|
+| components | [][ComponentReference](#componentreference) | y | | The list of components in this Application Model | 
+
+### ComponentReference
+
+| Attribute | Type | Required | Default Value | Description |
+|-----------|------|----------|---------------|-------------|
+| metadata  | [Metadata](#metadata) | n | | The metadata for a component |
+| spec | [ComponentSpec](3.component_model.md#spec) | n | | A component schematic |
+| reference | string | n | | The name of an external component |
+
+*IMPORTANT:* If `reference` is not provided, both `spec` and `metadata` are required. If `spec` is provided, `reference` MUST be ignored and MAY produce an error if present.
+
+The following example shows two components, one inline schematic, and another external reference:
+
+```yaml
+components:  # This is a list of the components that make up this app.
+    - metadata:
+        name: admin-portal
+        annotations:
+          version: "1.0.0"
+          description: Administration portal
+      spec:
+        workloadType: core.hydra.io/v1alpha1.ReplicatedService
+        containers:
+            - name: server
+              image: example/admin:v1.2.3
+    - reference: my-database
+```
+
+## Example Application Model
+
+This example shows a three-component application model, where all three components are declared inline.
+
+```yaml
+apiVersion: core.hydra.io/v1alpha1
+kind: ApplicationModel
+metadata:
+  name: example-app-model
+  annotations:
+    version: v1.0.0
+    description: >
+      An example app model that is composed of three components
+    icon: https://example.com/assets/example/icon.png
+spec:
+  components:  # This is a list of the components that make up this app.
+    - metadata:
+        name: admin-portal
+        annotations:
+          version: "1.0.0"
+          description: Administration portal
+      spec:
+        workloadType: core.hydra.io/v1alpha1.ReplicatedService
+        containers:
+            - name: server
+              ports:
+              - containerPort: 5001
+                name: http
+              image: example/admin:v1.2.3
+    - metadata:
+        name: database
+        annotations: 
+          version: "1.0.0"
+          description: PostgreSQL Database
+      spec:
+        workloadType: core.hydra.io/v1alpha1.Singleton
+        containers:
+        - name: db
+          ports:
+            - containerPort: 5432
+              name: pgsql
+          image: example/postgres:9.4
+    - metadata:
+        name: frontend
+        annotations:
+          version: "1.0.0"
+          description: Front-end webserver
+      spec:
+        workloadType: core.hydra.io/v1alpha1.ReplicatedService
+        parameters:
+        - name: username
+          description: Basic auth username for accessing the administrative interface
+          type: string
+          required: true
+        - name: password
+          description: Basic auth password for accessing the administrative interface
+          type: string
+          required: true
+        - name: db-host
+          description: Host name or IP of the backend
+          type: string
+          required: true
+        containers:
+        - name: server
+          ports:
+            - containerPort: 5000
+              name: http
+          image: example/front-end:v1.2.3
+```
+
+In some cases, it is beneficial to declare the components separately (as defined in Part 3), and then merely reference them from an Application Model:
+
+```yaml
+apiVersion: core.hydra.io/v1alpha1
+kind: ApplicationModel
+metadata:
+  name: example-app-model
+  annotations:
+    version: v1.0.0
+    description: >
+      An example app model that is composed of three components
+spec:
+  components:  # This is a list of the components that make up this app.
+    - reference: admin-portal
+    - reference: database
+    - reference: voting-frontend
+```
+
+Of course, an Application Model may freely mix references to components and inline components.
+
+### Limits on Inline Components
+
+When a component is declared _inline_, it is considered _application specific_, and is not made available in the general catalog of components. Conversely, applications that are defined in stand-alone `ComponentSchematic` definitions are made available in the general catalog of components, and may be referenced from any number of `ApplicationModel` definitions.
+
+## Referencing Application Models from Application Configurations
+
+An application model declares _the parts of an application_. An Application Configuration provides _configuration for a particular instance of an application model_. For example, an Application Model may define the parts of a blog platform, while an application configuration defines a particular instance of that blog platform. One model may be instantiated numerous times, with each instance having its own configuration.
+
+```yaml
+apiVersion: core.hydra.io/v1alpha1
+kind: ApplicationConfiguration
+metadata:
+  name: custom-single-app
+  annotations:
+    version: v1.0.0
+    description: "Customized version of single-app"
+spec:
+  # Specify which Application Model is to be instantiated
+  applicationModel: example-app-model
+  # Provide configuration specific to the defined components:
+  components:
+    - componentName: frontend
+      instanceName: web-front-end
+      parameterValues:
+        - name: db-host
+          value: my-db.cluster
+        - name: user
+          value: db-user
+      traits:
+        - name: app-ingress
+          type: core.hydra.io/v1alpha1.Ingress
+          properties:
+            - name: host
+              fromParam: domainName
+            - name: path
+              value: "/"
+    # For these, we are just declaring the instance names, not setting params or
+    # traits.
+    - componentName: database
+      instanceName: my-db
+    # This is the default behavior:
+    # - componentName: admin-portal
+    #   instanceName: admin-portal
+```
+
+In the example above, the Application Configuration declares that it is an instance of `applicationModel: example-app-model` (which was defined earlier in this section). It provides instance-specific settings, like the names, parameter values, scopes, and traits that are to be applied to this application instance.
+
+## Considerations
+
+The ApplicationModel's components declare parameters, but there is currently no facility for declaring a "top level" parameter that would bubble down to individual components. The reason for this omission is that referenced components are assumed to have no knowledge of the Application Model(s) in which they are referenced. Thus, they cannot reference the values defined in an Application Model.