-
Notifications
You must be signed in to change notification settings - Fork 1
Speedrun Configuration
Speedrun uses json called srConfig
to set the context for a page. The configuration contains any templates, services, variables and functions for the page. It supports composition, so you can define variables at one level, and override them at a more specific level.
#copy.raw {"stripComments": true}
```
#srConfig
{
"role" : "ReadOnly", //this is a global variable, it is available to all templates, services and speedrun blocks.
//"role" must be defined at some level to use federate or copy.withCredentials
"templates" : {
"AnnotatedCopy" : { //the template name
"type" : "copy", //one of copy, federate, link, download
"value" : "${header}${content}", //value of the template, here it will append the header with block content.
"header" : "What follows was copied by ${user}:\n" //template variable, it is defined whenever using the AnnotatedCopy template
}
//additional templates go here
},
services : {
SweetMonkeyService : { //will add a service to the dropdown called Sweet Monkey Service
account : "123456789012", //default aws account for all regions in the Sweet Monkey Service
//"account" must be defined at some level to use federate or copy.withCredentials
serviceShortName : "SMS", //service variable, it is defined whenever you are using the Sweet Monkey Service
logGroup: "/lambda/sweetmonkeyservice-${region}",
regions: { //shows up in the region dropdown, if there are no regions, there is no region dropdown
"us-east-1" : { //aws region or partition this config is for, shows up in the region dropdown
account : "234567890123", //region specific aws account for the Sweet Monkey Service in us-east-1
"logGroup": "/lambda/sweetmonkeyservice" //override the service variable to not include -${region}
},
"us-west-2" : {} //this adds us-west-2 to the region dropdown and uses the service defaults for account, serviceShortName and logGroup
}
}
}
}
```
This will helper will create a new wiki for hosting your shared Speedrun Configuration.
#NewGitHubWiki {"title":"Speedrun Configuration"}
~~~org=GitHub Organization {"default":"${user}", "suppress":true, "transform":"slugify(value)"}~~~
~~~repo=GitHub Repository {"default":"${user}", "suppress":true, "transform":"slugify(value)"}~~~
```
#srConfig
{
"role" : "~~~Role Name {"default":"ReadOnly"}~~~",
"templates" : {
},
"services" : {
"~~~Service Name~~~" : {
"regions": {
"~~~Region {"type":"select","options":["us-east-1","us-west-2","us-east-2","us-west-1"]}~~~" : {
"account" : "~~~Service Account Id~~~"
}
}
}
}
}
```
This will edit an existing Speedrun Configuration wiki
#EditGitHubWiki {"title":"Speedrun Configuration"}
~~~org=GitHub Organization {"default":"${user}", "suppress":true, "transform":"slugify(value)"}~~~
~~~repo=GitHub Repository {"default":"${user}", "suppress":true, "transform":"slugify(value)"}~~~
💡 Note If you include multiple
srConfig
configurations on the same page, they are overlaid in the order they appear on the page.
You can add inline configuration to a page by adding a #srConfig
code block.
#copy {"stripComments":false}
```
#srConfig
{
//configuration goes here
}
```
You can transclude configuration from another page by setting the transclude
variable.
#copy {"stripComments":false}
```
#srConfig {"transclude" : "PageName"}
```
It supports transcluding multiple pages if you use array syntax
#copy {"stripComments":false}
```
#srConfig {"transclude" : ["S3Templates", "TeamConfiguration"]}
```
It supports transcluding pages and inline configuration too
#copy {"stripComments":false}
```
#srConfig {"transclude" : "TeamConfiguration"}
{
//optional page specific configuration
}
```
Finally it supports absolute paths so if you need to transclude config into repository markdown or vice versa, you can do that.
#copy {"stripComments":false}
```
#srConfig {"transclude" : "https://github.com/No-Backspace-Crew/Speedrun/wiki/Configuration"}
{
//optional page specific configuration
}
```
💡 Note: you can have multiple
srConfig
configurations on a page. They are applied and overlaid in the order they appear on the page.
The context for a particular block is generated by overlaying the configuration from least to most granular. The value of a variable is determined by overlaying the configurations in this sequence:
- Global
- Page
- Service
- Partition
- Region
- Entry
If you have the same variable defined at the Global level and the Entry level, the Entry level overrides it.
Your variables can use javascript to dynamically set variables using other variables or functions. In this example it uses the value of region
to configure the logGroup
: logGroup: "/lambda/sweetmonkeyservice-${region}"
It may be easier to reference CloudFormation stack outputs than to hardcode variables in your configuration. Use the cfn
function to get the value of a CloudFormation stack output. The syntax is as follows:
${(await cfn('stackname')).outputs.OutputName}
If your stack name isn't fixed, you can dynamically build it use backticks.
${(await cfn('speedrun-federation-`${stage}`')).outputs.OutputName}
There is a helper called acfn
that makes the syntax easier and handles the await and parenthesis for you.
${acfn('stackname','outputs.OutputName')}
The cfn
function makes a service call to CloudFormation to retrieve the value using the current account and role. The role needs DescribeStack permissions on the stack you are attempting to retrieve outputs from. In addition to outputs, you have access to tags and a few other attributes of the CloudFormation stack. To see what's available to use, invoke cfn
or acfn
for the and look in the developer tools console, it will display the output.
To extend the service Speedrun
to add an additional service called Speedrun Admin
to the dropdown that uses the role speedrun-Administrator
, use the .
syntax.
#copy
"services" : {
"Speedrun" {
"account" : "012349587938"
},
"Speedrun.SpeedrunAdmin" {
"role" : "Administrator"
}
}
It works for multiple levels, so if you define services Speedrun
, Speedrun.SpeedrunFederate
and Speedrun.SpeedrunFederate.SpeedrunFederateAdmin
, Speedrun
, Speedrun Federate
and Speedrun Federate Admin
will show up in the service dropdown. Speedrun
will display as Speedrun
in the dropdown and have config for Speedrun
. Speedrun.SpeedrunFederate
will display as Speedrun Federate
in the dropdown and have config for Speedrun
overlayed with Speedrun.SpeedrunFederate
. Speedrun.SpeedrunFederate.SpeedrunFederateAdmin
will display as Speedrun Federate Admin
in the dropdown and have config for Speedrun
overlayed with Speedrun.SpeedrunFederate
overlayed with SpeedrunFederateAdmin
Naming a template copy.raw.withCreds
will result in a template that overlays the copy
template with the raw
template and then overlays the withCreds
template, resulting in the ordered overlay of the variables from all 3.