A project template is a repository which contains some project specific information and a default structure to have after the project creation. The template allows you to pre-fill resources in your project and start all similar projects with the same configuration. In short, it constitutes a base on which to create your project.
The fields set by the template can be changed after the project creation.
Create a template
You can create a project template by setting up a specific document through the
Project Templates page of the Console CMS.
The fields to customize inside CMS are:
name(required): the name of the template;
templateId(required): the human-readable ID of the template (e.g. "mia-platform-multitenant-template"). It must adhere to this regex:
company: the company which owns the project template. If set, the project templates will be visible only to the specific company. If not set, the project template is public and anyone can use it;
description: the description of the template;
archiveUrl: URL to a gzip of the base project configuration folder. All contents of this folder will be copied into the target configuration, and correctly interpolated. If you want to create a custom template, click here to see how to do it;
dashboards: a list of dashboard configured by default in every environments of the project, when created. Dashboards values can be interpolated with:
%projectId%: the projectId of the new project
%envId%: for each environment, the envId
%namespace%: for each environment,the namespace
"label": "My Default dashboard",
id(required): a unique id of the dashboard;
label(required): the labels shown by the monitoring section of the Console;
url(required): the url to the dashboard;
type: can be
newTab. Default to iframe.
deploy: object which identifies some deploy related configurations. For example:
- runnerTool: Set it to
mlpif the project uses it as command line deployment tool. It is required to have the Smart Deploy feature enabled;
- useMiaPrefixEnvs: Set it to false if you want the Public Variables to be saved without
MIA_prefix. That depends on the command line deployment tool. If the project uses
mlpyou don't need to use the
- projectStructure: Set it to
kustomizeif you want to use Kustomize to manage your microservices configurations. More info in this section, otherwise use
defaultor leave it blank to keep the usual configuration setup.
- runnerTool: Set it to
If you set
kustomize, your project configuration structure needs to be changed accordingly.
If you switch
false, you have to remove the
MIA_ prefix by hand. This operation is not performed automatically by the Console.
enabledServices: object which contains as key the service handled by the Console and as value a boolean. If the value is true, the service is enabled and the Console will generate the configuration for that service, otherwise it will be skipped by the Console. For example:
staticSecret: some templates could use the same static secret for a set of projects (especially used with architecture with multiple
api-gatewayentry points). Keys are optional. This is an example of object:
How to create a Project Archive
The project archive is interpolated using mustache.js as template system, using
% as tag symbol instead of the default
In order to use the
% character inside your project archive you can escape it by prefixing the character with an additional
%. For example, the string
%%something will be rendered as
%something when the project archive will be interpolated.
mustache.js is a web template system, which allows you to generate custom templates by replacing all the general information in the web template with your product or organization information.
You could create a project template to avoid copy/paste in every new project having the same base configuration.
At Mia-Platform, for example, we create one template to configure a project exposed through Traefik configuration and one to configure it without expose it. Therefore, for a company that uses this template, creating this type of project will be a very simple process.
You can interpolate the template with some project data. With mustache.js, you could iterate through an array, in order to have some configuration iterated for every environment. The values you can use during template interpolation are:
For the project (accessible using
Inside environments, you can access to:
cluster(an object containing
kubeContextVariablesobject). Here you can find the variable names for the specified environment where to set the cluster variable;
hosts(an array of objects, with
An example of template for the
# job template
- project: 'platform/pipelines-templates'
- $ENVIRONMENT_TO_DEPLOY == "%envId%"
All sections between
%/project.environments% will be written for
n times, where
n is the number of environments. So, inside the environment, you can use the environment specific fields.
For other possibilities, please check mustache.js documentation.
You may want to write a file or a folder for every environment. To enable that, you can write the file name (or folder) in the template as
%envId%, which will be interpolated for every environment.
The interpolation data in those files include the environments fields at the first level (as in
mustache.js sections), with the project as a key for every environment.
To see an example of Jenkins pipelines definition, take a look at this page of our doc.
Create default services
There are two ways to add services to a template:
- Using an
api-console-config, which specifies the services that will be included in the projects created with that template, together with other details (e.g. environment variables). This requires you to add an
api-console-config.jsonfile in the root directory of the project, provided via the
- Deprecated: Using
enabledServices, which only specifies whether a certain service is enabled or not, without the possibility to define any other detail.
enabledServices can only be used for core services (i.e.
oauth-login-site), while it does not work for services used from the Console that have been migrated to custom services (migrated services are now plugins, you can find them in the marketplace).
The base structure of the
api-console-config.json is the following:
If you create the new
api-console-config.json from an existing one, please remember to delete all fields that do not match the structure above, since they will be automatically generated by the Console after save and deploy actions (one of those, depending on the field).