Skip to content

Commit ce17d6a

Browse files
emjburnsrobzienert
emjburns
authored and
robzienert
committed
docs(mpt): updating docs and examples (#18)
1 parent 1b8eb20 commit ce17d6a

16 files changed

+392
-37
lines changed

‎MPTGraphic.png

26.7 KB
Loading

‎PIPELINE_TEMPLATES.md

Lines changed: 45 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -35,9 +35,10 @@ For usage information, please see [ALPHA-GETTING-STARTED.md](ALPHA-GETTING-START
3535

3636
# Taxonomy
3737

38-
* *Pipeline Template*: An abstract, composable definition of a Spinnaker Pipeline
39-
* *Pipeline Configuration*: A variable-binding and user-facing configuration
40-
format that inherits a Pipeline Template.
38+
* *Pipeline Template (template)*: An abstract, composable definition of a Spinnaker Pipeline
39+
* *Pipeline Configuration (configuration)*: A variable-binding and user-facing configuration
40+
format that combines with a Pipeline Template to make it runnable.
41+
* *Spinnaker Pipeline (pipeline)*: (what you see in the UI) a pipeline, represented internally by json, that can be run by orca.
4142

4243
# Key Concepts
4344

@@ -46,42 +47,12 @@ For usage information, please see [ALPHA-GETTING-STARTED.md](ALPHA-GETTING-START
4647
concrete implementations of a Template.
4748
* Composability of Templates are done via Modules. Configurations can configure
4849
a module or entirely replace modules if they don't fit.
49-
* Templates can use Jinja expression syntax for better flow control.
5050
* Configurations can inject new stages into the final pipeline graph and modify
5151
individual objects with JSONPath.
52+
* Templates can use Jinja expression syntax for better flow control.
5253

53-
# Jinja Templating
54-
55-
Templates can use jinjava (Java implementation of Jinja) to offer greater
56-
productivity while creating and using templates. Jinja templating is only
57-
allowed in string values so that the JSON transport can always be valid. The
58-
results of Jinja templates can and often will result in non-string values (even
59-
object graphs).
60-
61-
For more information about what's possible with Jinja, and specifically jinjava:
62-
63-
* https://github.com/HubSpot/jinjava
64-
* http://jinja.pocoo.org/docs/2.9/ (Python implementation; good reference)
65-
66-
Jinja is supported in the following areas:
67-
68-
* Stage & module `when` stanzas
69-
* Module `definition` stanza (or any nested value inside)
70-
* Stage `config` stanza (or any nested value inside)
71-
* Stage `name` stanza
72-
* Template `metadata` values
73-
74-
## Custom Tags & Filters
75-
76-
We're continually extending the Jinja implementation with new Tags and Filters.
77-
78-
* `frigga` filter: Used to parse string values and return Frigga naming
79-
convention substrings. `{{ "orca-main"|frigga('stack') }} == "main" }}`
80-
* `json` filter: Output a value as a JSON object. `{{ myVar|json }}`
81-
* `base64` filter: Output a value as a Base64 encoded string. `{{ myVar|base64 }}`
82-
83-
**IMPORTANT**: If your Jinja template is intended to return a list, map or
84-
object graph, you must ensure the output is *valid YAML or JSON*.
54+
# Explained in Pictures
55+
![mpt-graphic](MPTGraphic.png "Logo Title Text 1")
8556

8657
# Template & Configuration Schemas
8758

@@ -96,7 +67,7 @@ UI. **NOTE:** This stanza, while defined in the spec, is not currently consumed
9667
by Spinnaker itself.
9768

9869
This section primarily gives explanations of Templates & Configurations. For
99-
actual reference schemas, please take a look at [schemas/pipeline-templates-v1](schemas/pipeline-templates-v1).
70+
actual reference schemas, please take a look at [schemas/pipeline-templates-v1](schemas/pipeline-templates-v1). For examples, please take a look at [examples/pipeline-templates-v1](examples/pipeline-templates-v1).
10071

10172
## Templates
10273

@@ -210,6 +181,41 @@ When using the *spinnaker scheme*, it's recommended to namespace your template
210181
IDs, as they are globally unique, regardless of the scope you provide them while
211182
publishing.
212183

184+
# Jinja Templating
185+
186+
Templates can use jinjava (Java implementation of Jinja) to offer greater
187+
productivity while creating and using templates. Jinja templating is only
188+
allowed in string values so that the JSON transport can always be valid. The
189+
results of Jinja templates can and often will result in non-string values (even
190+
object graphs).
191+
192+
For more information about what's possible with Jinja, and specifically jinjava:
193+
194+
* https://github.com/HubSpot/jinjava
195+
* http://jinja.pocoo.org/docs/2.9/ (Python implementation; good reference)
196+
197+
Jinja is supported in the following areas:
198+
199+
* Stage & module `when` stanzas
200+
* Module `definition` stanza (or any nested value inside)
201+
* Stage `config` stanza (or any nested value inside)
202+
* Stage `name` stanza
203+
* Template `metadata` values
204+
205+
## Custom Tags & Filters
206+
207+
We're continually extending the Jinja implementation with new Tags and Filters.
208+
209+
* `frigga` filter: Used to parse string values and return Frigga naming
210+
convention substrings. `{{ "orca-main"|frigga('stack') }} == "main" }}`
211+
* `json` filter: Output a value as a JSON object. `{{ myVar|json }}`
212+
* `base64` filter: Output a value as a Base64 encoded string. `{{ myVar|base64 }}`
213+
214+
**IMPORTANT**: If your Jinja template is intended to return a list, map or
215+
object graph, you must ensure the output is *valid YAML or JSON*.
216+
217+
218+
213219
# Variables
214220

215221
Variables are used during the Jinja template rendering phase to build up stages.
@@ -332,6 +338,8 @@ Conditional stages are supported within Partials as well.
332338

333339
# Modules
334340

341+
Modules are used to represent common functionality within stages, like stage configuration.
342+
335343
Modules can be referenced by each other, the Template they are defined in,
336344
child Templates and Configurations. Furthermore, they can be replaced by child
337345
Templates and Configurations as well.

‎examples/README.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# dcd-examples
2+
3+
Examples of how to use MPT, organized by schema version.
4+
5+
Templates are linked using the `file://myfile.yml` format.
6+
To use templates in a hosted manner, change all the `source:` fields to represent the URL
7+
of the raw file or the `spinnaker://` format.
8+
See [my gists](https://gist.github.com/emjburns/b769578860ecbb84d64ea72b544e205c) for an example.

‎examples/pipeline-templates-v1/bake-deploy/README.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# This example shows a bake and deploy pipeline with the option to override to a find image and deploy pipeline
2+
The UI view for this pipeline is shown in [complex-wait-ui.png](complex-wait-ui.png). Same UI for all three options.
3+
4+
## Option 1: Bake
5+
`template.yml` shows a sample multi region bake and deploy. `bake-deploy-config.yml` shows the config for that pipeline, providing a stage name for the first stage.
6+
7+
8+
## Option 2: Find Image
9+
`template.yml` remains the same. `findImage-deploy-config.yml` shows replacing the bake stage with a findImage stage.

‎examples/pipeline-templates-v1/bake-deploy/bake-deploy-config.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
schema: "1"
3+
pipeline:
4+
application: orca
5+
name: Bake and Deploy
6+
template:
7+
source: file://template.yml
8+
variables:
9+
myCustomFirstStageName: "Bake"
10+
stages: []

‎examples/pipeline-templates-v1/bake-deploy/findImage-deploy-config.yml

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
schema: "1"
3+
pipeline:
4+
application: orca
5+
name: Find Image and Deploy
6+
template:
7+
source: file://template.yml
8+
variables:
9+
myCustomFirstStageName: "Find Image"
10+
stages:
11+
- id: bake1
12+
type: findImageFromTags
13+
name: "{{ myCustomFirstStageName }}"
14+
config:
15+
cloudProvider: aws
16+
cloudProviderType: aws
17+
packageName: "{{ application }}"
18+
regions:
19+
- us-east-1
20+
- us-west-1
21+
- us-west-2
22+
- eu-west-1
23+
tags:
24+
stack: test

‎examples/pipeline-templates-v1/bake-deploy/template.yml

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
schema: "1"
3+
id: bakeDeploy
4+
metadata:
5+
name: Bake and Deploy
6+
description: Example bake and deploy template
7+
variables:
8+
- name: myCustomFirstStageName
9+
stages:
10+
- id: bake1
11+
type: bake
12+
name: "{{ myCustomFirstStageName }}"
13+
config:
14+
baseLabel: release
15+
baseOs: trusty
16+
cloudProviderType: aws
17+
enhancedNetworking: false
18+
extendedAttributes: {}
19+
overrideTimeout: true
20+
package: orca
21+
regions:
22+
- us-east-1
23+
- us-west-1
24+
- us-west-2
25+
- eu-west-1
26+
sendNotifications: true
27+
showAdvancedOptions: true
28+
stageTimeoutMs: 900000
29+
storeType: ebs
30+
user: [email protected]
31+
vmType: hvm
32+
- id: deploy2
33+
type: deploy
34+
dependsOn:
35+
- bake1
36+
name: Deploy
37+
config:
38+
clusters:
39+
- account: test
40+
application: orca
41+
availabilityZones:
42+
us-west-1:
43+
- us-west-1a
44+
- us-west-1c
45+
capacity:
46+
desired: 1
47+
max: 1
48+
min: 1
49+
cloudProvider: aws
50+
cooldown: 10
51+
copySourceCustomBlockDeviceMappings: true
52+
ebsOptimized: false
53+
enabledMetrics: []
54+
freeFormDetails: demo
55+
healthCheckGracePeriod: 600
56+
healthCheckType: EC2
57+
iamRole: myIAMRole
58+
instanceMonitoring: false
59+
instanceType: m3.large
60+
interestingHealthProviderNames:
61+
- Amazon
62+
keyPair: keypair
63+
loadBalancers:
64+
- orca-demo-frontend
65+
maxRemainingAsgs: 2
66+
preferSourceCapacity: true
67+
provider: aws
68+
scaleDown: true
69+
securityGroups: []
70+
stack: test
71+
strategy: redblack
72+
subnetType: mySubnet
73+
suspendedProcesses: []
74+
tags: {}
75+
targetGroups: []
76+
targetHealthyDeployPercentage: 100
77+
terminationPolicies:
78+
- Default
79+
useAmiBlockDeviceMappings: false
80+
useSourceCapacity: true
81+
- account: test
82+
application: orca
83+
availabilityZones:
84+
us-east-1:
85+
- us-east-1c
86+
- us-east-1d
87+
- us-east-1e
88+
capacity:
89+
desired: 0
90+
max: 0
91+
min: 0
92+
cloudProvider: aws
93+
cooldown: 10
94+
ebsOptimized: false
95+
freeFormDetails: demo
96+
healthCheckGracePeriod: 600
97+
healthCheckType: EC2
98+
iamRole: myIAMRole
99+
instanceMonitoring: false
100+
instanceType: m3.large
101+
interestingHealthProviderNames:
102+
- Amazon
103+
keyPair: keypair
104+
provider: aws
105+
securityGroups: []
106+
stack: test
107+
strategy: highlander
108+
subnetType: mySubnet
109+
suspendedProcesses: []
110+
tags: {}
111+
targetHealthyDeployPercentage: 100
112+
terminationPolicies:
113+
- Default
114+
useSourceCapacity: false

‎examples/pipeline-templates-v1/complex-wait/README.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# This example shows a complex wait pipeline.
2+
The UI view for this pipeline is shown in [complex-wait-ui.png](complex-wait-ui.png). Same UI for all three options.
3+
4+
## Option 1: Inheritance
5+
`root-template.yml`, `child-template.yml`, and `child-2-template.yml` show an inheritence structure and the use variable. `mypipeline-config.yml` adds another stage at the configuration level.
6+
7+
8+
## Option 2: One template
9+
`combined-template.yml` shows the same stages represented in one template. `mypipelineCombined-config.yml` shows the config for that template that produces the same pipeline.
10+
11+
## Option 3: All Config
12+
`only-config.yml` shows how you can create the same pipeline with one config file. You might want to do this if you are only using this logic for one pipeline, or you are working to transition to managed pipeline templates and want to first convert each pipeline to code.

‎examples/pipeline-templates-v1/complex-wait/child-2-template.yml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
schema: "1"
2+
id: child-2-template
3+
source: file://child-template.yml
4+
variables:
5+
- name: childWaitTime
6+
description: pause time for another wait
7+
metadata:
8+
name: A Second Child template
9+
description: A second child template
10+
stages:
11+
- id: waitChild2
12+
type: wait
13+
dependsOn:
14+
- wait1
15+
config:
16+
waitTime: "{{ childWaitTime }}"

‎examples/pipeline-templates-v1/complex-wait/child-template.yml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
schema: "1"
2+
id: child-template
3+
source: file://root-template.yml # Indicates that this template inherits from the root-template
4+
metadata:
5+
name: Child template
6+
description: A child template
7+
stages:
8+
- id: waitChild1
9+
type: wait
10+
dependsOn:
11+
- wait1 # Depending on a stage from the root-template
12+
config:
13+
waitTime: "{{ waitTime }}" # Using a variable from the root-template

0 commit comments

Comments
 (0)