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

1. Template Structure
2. Managing Templates
3. Importing Templates
4. Exporting Templates
5. Examples
6. 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:

{ 
    "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.

"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.

{ 
    "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.

{ 
    "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.

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:

1. Create a directory that holds all your template files
2. Create a main file in the directory and name it index.js
3. 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
4. Update your index.js file to require all these subsidiary files
5. ZIP your directory and import it using the wizard

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.

5- Examples