Introduction

Environment Templates allow you to extend creating a blank environment and associate creating and deploying several components along with the environment itself.

In addition, environment templates also assist you in importing and exporting configuration to your core database such as: Catalog Deployment Recipes, Continuous Integration Recipes, endpoints ... etc

Objectives

Template Structure
Managing Templates
Importing Templates
Exporting Templates
Examples
Creating Environment from Templates

1- Template Structure

Templates are defined by a JSON Schema, and contains instructions about what to import to the database and what to create and deploy while creating an environment.

Basic Information:

Property Name	Data Type	Mandatory	Default Value	Description
name	string	yes	N/A	Unique template name
description	string	yes	N/A	Template description
reusable	boolean	no	false	Whether the template can be used to create multiple environments from it or it should be disabled if there is at least 1 environment created from it.
restriction	object	no	N/A	Depicts which infrastructure providers and/or container/vm technologies that can be used with this template.
content	object	yes	N/A	The content of the template which refers to the components that should be imported and/or created & deployed when using this template.
deploy	object	yes	N/A	If there are any components to be deployed, which stage and in what order should these components be deployed.

Root Level Template Sample

{ 
    "name" : "My Template", 
    "description" : "Template Description", 
    "reusable" : true, 
    "restriction" : { /* ... */ }, 
    "content" : { /* ... */ }, 
    "deploy" : { /* ... */ }
}

Template Restriction:

This part of the template defines if the template has a certain restriction meaning it can only be used with the following infra cloud provider or the following technology.

The below snippet states that this template is restricted to use container technology and support both docker and kubernetes drivers as well as AWS and Google Cloud as Infra Cloud Providers.

Template Restriction Example

"restriction": {
    "deployment": [
      "container"
    ],
    "driver": [
      "container.docker",
      "container.kubernetes"
    ],
    "infra": [
      "aws",
      "google"
    ]
}

Template Content:

This part of the template contains the content which gets imported upon importing the template or created & deployed while creating a new environment from this template.

Property Name	Data Type	Mandatory	Default Value	Processed	Restriction	Description
recipes	object	no	N/A	Import	None	Contains 2 types of recipes: catalog deployments - continuous integration. All Recipes regardless of their type are imported upon importing a template.
endpoints	object	no	N/A	Import	None	Contains the list of endpoints that should be created. All endpoints are created upon importing a template.
custom_registry	object	no	N/A	Create Environment	None	Contains the list of custom registry that should be created whenever this template is used to create an environment.
productization	object	no	N/A	Create Environment	None	Contains the list of productized packages that should be created OR updated whenever this template is used to create a new environment.
tenant	object	no	N/A	Create Environment	None	Contains the list of tenants, applications and tenant configuration that should be created OR updated whenever this template is used to create a new environment.
secrets	object	no	N/A	Create Environment	Container	Contains the list of secrets that should be created whenever this template is used to create a new environment
deployments	object	no	N/A	Create Environment	Container / VM	Contains the list of source code & resources that should be created whenever this template is used to create a new environment.

Root Level Template Content

{ 
    "recipes" : {
		"ci": [], 			//array of continuous integration recipes
		"deployment": [],	//array of catalog deployment recipes
	}, 
    "endpoints" : {
		"data": []			//array of endpoint entries 
	},		
    "custom_registry" : {
		"data": []			//array of custom registry entries 
	}, 
    "productization" : {
		"data": []			//array of productized packages entries 
	}, 
    "tenant" : {
		"data": []			//array of tenant entries 
	}, 
    "secrets" : {
		"data": []			//array of secrets entries 
	},
	"deployments": {
		"repo": {},			//object where each entry represents one source code deployment configuration
		"resources": {}		//object where each entry represents one resource deployment configuration
	}
}

Template Deploy:

This part of the template depicts the stages and the order of deployment for all template components.

Property Name

Data Type

Mandatory

Default Value

Processed

Restriction

Description

database

object

no

N/A

Create Environment

None

Contains the list of template content entries that should be created OR update in the database.

This stage runs before the deployments stage and only handles database execution operations.

deployments

object

no

N/A

Create Environment

Container / VM

Contains the list of template content entries that should be deployed in containers, virtual machines or even infra setup.

This stage runs after the database stage and does not handle any database execution operations.

Template Deployments Example

{ 
    "database" : {
		"pre": {
			"custom_registry": {} //example
		},
		"steps": {
			"productization": {} //example
		},
		"post": {
			"tenant": {} //example
		}
	}, 
    "deployments" : {
		"pre": {
			"secrets.[%name%]": {} //example
		},
		"steps": {
			"deployments.repo.[%name%]": {} //example
		},
		"post": {
			"deployments.resources.[%name%]": {} //example
		}
	}
}

Each entry under the deployment stage is noted by specifying the relative path under template content to the configuration that dictates how it should be created or deployed.

Ex:

If the template contains a secret that should be created upon creating an environment, you will see something like this:

{ 
    "content": {
		"secrets": {
     		 "data": [
        		{
		          "name": "mysecret"
       			}
      		]
    	}
	},
	"deployments" : {
		"steps": {
			"secrets.mysecret": {} //specify the path to where mysecret is located under content
		}
	}
}

2- Managing Templates

Manage templates via the UI module Environment Templates which provides a list of all available templates where you can browse the content of each template and see what are the components that will be created & deployed when you use this template and create an environment from it. You can also download copies of templates, import new templates you created, delete templates that were imported and also export content from the core database and generate a template out of them.

List Environment Templates

Browse One Template

3- Importing Templates

You can import custom templates using the Environment Template Import Wizard. The wizard assist you in detecting any issues or discrepancy in your templates and also checks if your templates includes content that already exists in the database.

Some of the issues can be rectified by the wizard but require minor modification from your end and some require you fix the template manually then re-import it again. The wizard will read your template and inform you of such events as well as what to do to fix them.

Every template is represented by a JSON object, the wizard requires you zip the template and then upload it. As mentioned in the above section, a template might contain several components which might cause the JSON object to be enormous and unmanageable if you use only 1 file.

Therefore, the best approach when creating templates is:

Create a directory that holds all your template files
Create a main file in the directory and name it index.js
Create a file for each type of content you want to include in your template: catalog deployment recipes - continuous integration recipes - endpoints - custom registries - productization - tenants - secrets
Update your index.js file to require all these subsidiary files
ZIP your directory and import it using the wizard

The following attachment contains an example of how a templated environment should look like as well as a full list of all possible combinations that can be placed in a templated environment.

Import a new Templated Environment

4- Exporting Templates

Similar to importing templates, you can also export content from your database and generate templates out of them. Simply click on export and follow the wizard steps.

SOAJS provides the ability to export Continuous Integration Recipes, Catalog Deployment Recipes and Endpoints.

Follow the wizard steps and when done, the wizard will download a zip file for you that contains the template and in it, all the recipes and endpoints you have selected.

The downloaded file has the same schema as the one in the sample above under Import.

Export Content as a Templated Environment

5- Examples

Browser not supported