Skip to content

Commit 3847b6e

Browse files
technosophostechnosophos
committed
Add an Application Model object
Signed-off-by: Matt Butcher <matt.butcher@microsoft.com>
1 parent 5b61466 commit 3847b6e

File tree

1 file changed

+207
-0
lines changed

1 file changed

+207
-0
lines changed

‎4.application_model.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# Application Model
2+
3+
The Hydra approach identifies four important roles:
4+
5+
- The developer: Creates and maintains components (microservices)
6+
- The application architect: Defines an application as composed of components
7+
- The application operator: Instantiates an application, providing configuration
8+
- The infrastructure operator: Maintains the underlying platform, making low-level decisions about infrastructure
9+
10+
The previous section of the specification defines the component model. This section defines how components can be composed in an application.
11+
12+
> 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.
13+
14+
## Representation
15+
16+
The `ApplicationModel` object follows the same basic structure as other Hydra manifests.
17+
18+
### Top-Level Attributes
19+
20+
The top-level attributes of a trait define its metadata, version, kind, and spec.
21+
22+
| Attribute | Type | Required | Default Value | Description |
23+
|-----------|------|----------|---------------|-------------|
24+
| `apiVersion` | `string` | Y || The specific version of the specification in use. At present only `core.hydra.io/v1alpha1` is defined. |
25+
| `kind` | `string` | Y || The string `ApplicationModel` |
26+
| `metadata` | [`Metadata`](#metadata) | Y | | ApplicationModel metadata. |
27+
| `spec`| [`Spec`](#spec) | Y || A specification for application models. |
28+
29+
### Metadata
30+
31+
Metadata describes this Application Model. The metadata section is defined in [Section 3](3.component_model.md#metadata).
32+
33+
### Spec
34+
35+
The job of an Application Model is to relate multiple components to a single functional unit. The `spec` section declares the relationship.
36+
37+
| Attribute | Type | Required | Default Value | Description |
38+
|-----------|------|----------|---------------|-------------|
39+
| components | [][ComponentReference](#componentreference) | y | | The list of components in this Application Model |
40+
41+
### ComponentReference
42+
43+
| Attribute | Type | Required | Default Value | Description |
44+
|-----------|------|----------|---------------|-------------|
45+
| metadata | [Metadata](#metadata) | n | | The metadata for a component |
46+
| spec | [ComponentSpec](3.component_model.md#spec) | n | | A component schematic |
47+
| reference | string | n | | The name of an external component |
48+
49+
*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.
50+
51+
The following example shows two components, one inline schematic, and another external reference:
52+
53+
```yaml
54+
components: # This is a list of the components that make up this app.
55+
- metadata:
56+
name: admin-portal
57+
annotations:
58+
version: "1.0.0"
59+
description: Administration portal
60+
spec:
61+
workloadType: core.hydra.io/v1alpha1.ReplicatedService
62+
containers:
63+
- name: server
64+
image: example/admin:v1.2.3
65+
- reference: my-database
66+
```
67+
68+
## Example Application Model
69+
70+
This example shows a three-component application model, where all three components are declared inline.
71+
72+
```yaml
73+
apiVersion: core.hydra.io/v1alpha1
74+
kind: ApplicationModel
75+
metadata:
76+
name: example-app-model
77+
annotations:
78+
version: v1.0.0
79+
description: >
80+
An example app model that is composed of three components
81+
icon: https://example.com/assets/example/icon.png
82+
spec:
83+
components: # This is a list of the components that make up this app.
84+
- metadata:
85+
name: admin-portal
86+
annotations:
87+
version: "1.0.0"
88+
description: Administration portal
89+
spec:
90+
workloadType: core.hydra.io/v1alpha1.ReplicatedService
91+
containers:
92+
- name: server
93+
ports:
94+
- containerPort: 5001
95+
name: http
96+
image: example/admin:v1.2.3
97+
- metadata:
98+
name: database
99+
annotations:
100+
version: "1.0.0"
101+
description: PostgreSQL Database
102+
spec:
103+
workloadType: core.hydra.io/v1alpha1.Singleton
104+
containers:
105+
- name: db
106+
ports:
107+
- containerPort: 5432
108+
name: pgsql
109+
image: example/postgres:9.4
110+
- metadata:
111+
name: frontend
112+
annotations:
113+
version: "1.0.0"
114+
description: Front-end webserver
115+
spec:
116+
workloadType: core.hydra.io/v1alpha1.ReplicatedService
117+
parameters:
118+
- name: username
119+
description: Basic auth username for accessing the administrative interface
120+
type: string
121+
required: true
122+
- name: password
123+
description: Basic auth password for accessing the administrative interface
124+
type: string
125+
required: true
126+
- name: db-host
127+
description: Host name or IP of the backend
128+
type: string
129+
required: true
130+
containers:
131+
- name: server
132+
ports:
133+
- containerPort: 5000
134+
name: http
135+
image: example/front-end:v1.2.3
136+
```
137+
138+
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:
139+
140+
```yaml
141+
apiVersion: core.hydra.io/v1alpha1
142+
kind: ApplicationModel
143+
metadata:
144+
name: example-app-model
145+
annotations:
146+
version: v1.0.0
147+
description: >
148+
An example app model that is composed of three components
149+
spec:
150+
components: # This is a list of the components that make up this app.
151+
- reference: admin-portal
152+
- reference: database
153+
- reference: voting-frontend
154+
```
155+
156+
Of course, an Application Model may freely mix references to components and inline components.
157+
158+
### Limits on Inline Components
159+
160+
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.
161+
162+
## Referencing Application Models from Application Configurations
163+
164+
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.
165+
166+
```yaml
167+
apiVersion: core.hydra.io/v1alpha1
168+
kind: ApplicationConfiguration
169+
metadata:
170+
name: custom-single-app
171+
annotations:
172+
version: v1.0.0
173+
description: "Customized version of single-app"
174+
spec:
175+
# Specify which Application Model is to be instantiated
176+
applicationModel: example-app-model
177+
# Provide configuration specific to the defined components:
178+
components:
179+
- componentName: frontend
180+
instanceName: web-front-end
181+
parameterValues:
182+
- name: db-host
183+
value: my-db.cluster
184+
- name: user
185+
value: db-user
186+
traits:
187+
- name: app-ingress
188+
type: core.hydra.io/v1alpha1.Ingress
189+
properties:
190+
- name: host
191+
fromParam: domainName
192+
- name: path
193+
value: "/"
194+
# For these, we are just declaring the instance names, not setting params or
195+
# traits.
196+
- componentName: database
197+
instanceName: my-db
198+
# This is the default behavior:
199+
# - componentName: admin-portal
200+
# instanceName: admin-portal
201+
```
202+
203+
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.
204+
205+
## Considerations
206+
207+
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.

0 commit comments

Comments
 (0)