Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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







Anchor
structure
structure

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 NameData TypeMandatoryDefault ValueDescription
namestringyesN/AUnique template name
descriptionstringyesN/ATemplate description
reusablebooleannofalseWhether 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.
restrictionobjectnoN/ADepicts which infrastructure providers and/or container/vm technologies that can be used with this template.
contentobjectyesN/AThe content of the template which refers to the components that should be imported and/or created & deployed when using this template.
deployobjectyesN/AIf there are any components to be deployed, which stage and in what order should these components be deployed.


Code Block
languagejs
titleRoot Level Template Sample
linenumberstrue
{ 
    "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.

Code Block
languagejs
titleTemplate Restriction Example
linenumberstrue
"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 NameData TypeMandatoryDefault ValueProcessedRestrictionDescription
recipesobjectnoN/AImportNone

Contains 2 types of recipes: catalog deployments - continuous integration.

All Recipes regardless of their type are imported upon importing a template.

endpointsobjectnoN/AImportNone

Contains the list of endpoints that should be created.

All endpoints are created upon importing a template.

custom_registryobjectnoN/ACreate EnvironmentNoneContains the list of custom registry that should be created whenever this template is used to create an environment.
productizationobjectnoN/ACreate EnvironmentNoneContains the list of productized packages that should be created OR updated whenever this template is used to create a new environment.
tenantobjectnoN/ACreate EnvironmentNoneContains the list of tenants, applications and tenant configuration that should be created OR updated whenever this template is used to create a new environment.
secretsobjectnoN/ACreate EnvironmentContainerContains the list of secrets that should be created whenever this template is used to create a new environment
deploymentsobjectnoN/ACreate EnvironmentContainer / VM

Contains the list of source code & resources that should be created whenever this template is used to create a new environment.


Code Block
languagejs
titleRoot Level Template Content
linenumberstrue
{ 
    "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 NameData TypeMandatoryDefault ValueProcessedRestrictionDescription
databaseobjectnoN/ACreate EnvironmentNone

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.

deploymentsobjectnoN/ACreate EnvironmentContainer / 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.


Code Block
languagejs
titleTemplate Deployments Example
linenumberstrue
{ 
    "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:

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





Anchor
managing
managing

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





Anchor
import
import

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


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.

View file
namesample_env_template.zip
height150


Import a new Templated Environment





Anchor
export
export

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





Anchor
template_examples
template_examples

5- Examples


Child pages (Children Display)