Skip to main content
Version: 14.x (Next)

Template

A Template is a base repository from which users can build a new Microservice.

Teamplates can be instantiated in Console the same as plugins. The difference is that they provide an archive that is cloned in the Project scope, instead of a Docker image, giving developers direct access to the codebase to evolve it at will.

Templates are meant to be starting points with the bear minimum needed to start a service. Just like plugins, templates may also come with some predefined configurations.

To create or edit a template, you need to provide a manifest, whose resources property should adhere to the following JSON schema.

tip

The JSON schemas of the template resources and of the full template manifest are available on GitHub.

Catalog template resources
type : object
  • services object required
    type : object
    • ^[a-z]([-a-z0-9]*[a-z0-9])?$ object
      type : object
      • archiveUrl uri-reference required
        type : string (uri-reference)
        Length : >= 1 character(s)
      • componentId string
        type : string
      • containerPorts (object,...)[]
        type : array
        • items[x] object
          type : object
          • from integer XOR string required
            oneOf
            type : integer
            Possible values : >= 0 AND <= 65535
          • name string required
            type : string
            Pattern : ^[a-z]([-a-z0-9]*[a-z0-9])?$
          • protocol string
            type : string
            Possible values : 
            • TCP
            • UDP
            Default value : TCP
          • to integer XOR string
            oneOf
            type : integer
            Possible values : >= 0 AND <= 65535
          🚨 No extra propertie(s) are authorized in this object
      • defaultAnnotations (object,...)[]
        type : array
        • items[x] object
          type : object
          • description string
            type : string
          • name string required
            type : string
            Pattern : ^([a-zA-Z0-9][a-zA-Z0-9\.\-]{0,253}[\/])?([a-zA-Z0-9][a-zA-Z0-9\.\-]{0,63}[a-zA-Z0-9]?)$
          • readOnly boolean
            type : boolean
          • value string required
            type : string
          🚨 No extra propertie(s) are authorized in this object
        The service annotations, which can be used to provide additional information about your services for various purposes. Annotations starting with `mia-platform.eu` are reserved
      • defaultArgs (string,...)[]
        type : array
        • items[x] string
          type : string
      • defaultConfigMaps (object,...)[]
        type : array
        • items[x] object
          type : object
          • files (object,...)[] required
            type : array
            • items[x] object
              type : object
              • content string required
                type : string
              • name string required
                type : string
          • mountPath string required
            type : string
            Pattern : ^[a-zA-Z0-9-/_\s.|\\!"£$%&()=?^"{}[\]*+@]+$
          • name string required
            type : string
            Pattern : ^[a-z][a-z0-9]*(-[a-z0-9]+)*$
          • subPaths (string,...)[]
            type : array
            • items[x] string
              type : string
          • usePreserve boolean
            type : boolean
          • viewAsReadOnly boolean
            type : boolean
          🚨 No extra propertie(s) are authorized in this object
        The default ConfigMaps, if any, that will be mounted inside the container of the microservice
      • defaultDocumentationPath string
        type : string
        Pattern : ^$|^(\/$|(\/([\w\-\.]|(:[a-zA-Z]))[\w\-\.]*)+)$
        The APIs documentation path
      • defaultEnvironmentVariables (object XOR object XOR object XOR object XOR object,...)[]
        type : array
        • items[x] object XOR object XOR object XOR object XOR object
          oneOf
          type : object
          • name string required
            type : string
            Length : >= 1 character(s)
            The variable name (generally, a key written in UPPER_SNAKE_CASE)
          • description string
            type : string
            A brief description of the variable
          • managedBy "fast-data" constant
            type : string
            Possible values : 
            • fast-data
            A string that represents the Console section that manages the variable. It only works used in combination with the `readOnly` property set to `true`
          • readOnly boolean
            type : boolean
            A boolean that represents if you can change the value of the variable through the Console
          • value string
            type : string
            The variable default value. It can contain placeholders that will be replaced with the actual values when the service is created
          • valueType "plain" required constant
            type : string
            Constant value : plain
          🚨 No extra propertie(s) are authorized in this object
        The environment variables that will overwrite the default environment variables applied by the Console
      • defaultLabels (object,...)[]
        type : array
        • items[x] object
          type : object
          • description string
            type : string
          • name string required
            type : string
            Pattern : ^([a-zA-Z0-9][a-zA-Z0-9\.\-]{0,253}[\/])?([a-zA-Z0-9][a-zA-Z0-9\.\-]{0,63}[a-zA-Z0-9]?)$
          • readOnly boolean
            type : boolean
          • value string required
            type : string
          🚨 No extra propertie(s) are authorized in this object
        The service labels, which can be used to categorize, group, and select your service. Labels starting with "mia-platform.eu" are reserved
      • defaultLogParser string
        type : string
        Possible values : 
        • mia-plain
        • mia-json
        • mia-nginx
      • defaultMonitoring object
        type : object
        • endpoints (object,...)[]
          type : array
          • items[x] object
            type : object
            • interval string required
              type : string
              Pattern : ^(\d)+[s]$
            • path string required
              type : string
              Pattern : ^\/(([\w-])\/?)*$
            • port string required
              type : string
            🚨 No extra propertie(s) are authorized in this object
        🚨 No extra propertie(s) are authorized in this object
      • defaultProbes object
        type : object
        • liveness object XOR object XOR object
          oneOf
          type : object
          • cmd (string,...)[] required
            type : array
            • items[x] string
              type : string
          • failureThreshold number
            type : number
          • initialDelaySeconds number
            type : number
          • periodSeconds number
            type : number
          • successThreshold number
            type : number
          • timeoutSeconds number
            type : number
          🚨 No extra propertie(s) are authorized in this object
        • readiness object XOR object XOR object
          oneOf
          type : object
          • cmd (string,...)[] required
            type : array
            • items[x] string
              type : string
          • failureThreshold number
            type : number
          • initialDelaySeconds number
            type : number
          • periodSeconds number
            type : number
          • successThreshold number
            type : number
          • timeoutSeconds number
            type : number
          🚨 No extra propertie(s) are authorized in this object
        • startup object XOR object XOR object
          oneOf
          type : object
          • cmd (string,...)[] required
            type : array
            • items[x] string
              type : string
          • failureThreshold number
            type : number
          • initialDelaySeconds number
            type : number
          • periodSeconds number
            type : number
          • successThreshold number
            type : number
          • timeoutSeconds number
            type : number
          🚨 No extra propertie(s) are authorized in this object
        🚨 No extra propertie(s) are authorized in this object
        The readiness, liveness, and startup paths of the service. By modifying the map of the probes, you can overwrite the default paths applied by the Console
      • defaultResources object
        type : object
        • cpuLimits object
          type : object
          • max string
            type : string
            Pattern : (^((\{\{([A-Z])([A-Z0-9_]*)\}\})|(\d+))m$)|^$
          • min string
            type : string
            Pattern : (^((\{\{([A-Z])([A-Z0-9_]*)\}\})|(\d+))m$)|^$
          🚨 No extra propertie(s) are authorized in this object
        • memoryLimits object
          type : object
          • max string
            type : string
            Pattern : (^((\{\{([A-Z])([A-Z0-9_]*)\}\})|(\d+))Mi$)|^$
          • min string
            type : string
            Pattern : (^((\{\{([A-Z])([A-Z0-9_]*)\}\})|(\d+))Mi$)|^$
          🚨 No extra propertie(s) are authorized in this object
        🚨 No extra propertie(s) are authorized in this object
        CPU and memory limitations of the service, which can be used to overwrite the default limitations imposed by the Console for these parameters
      • defaultSecrets (object,...)[]
        type : array
        • items[x] object
          type : object
          • mountPath string required
            type : string
            Pattern : ^[a-zA-Z0-9-/_\s.|\\!"£$%&()=?^"{}[\]*+@]+$
          • name string required
            type : string
            Pattern : ^[a-z][a-z0-9]*(-[a-z0-9]+)*$
          🚨 No extra propertie(s) are authorized in this object
        The default secrets, if any, to be mounted inside the container of the microservice
      • defaultTerminationGracePeriodSeconds number
        type : number
      • description string
        type : string
      • dockerImage string
        type : string
        Pattern : ^(?:[a-z0-9.\-\/:]+\/)?([\w.}{\-\/]+)(:[\w.}{\-]+)?$
      • mapEnvVarToMountPath object
        type : object
        • property name* object
          type : object
          • type string required
            type : string
            Possible values : 
            • file
            • folder
          • envName string required
            type : string
          🚨 No extra propertie(s) are authorized in this object
      • name string required
        type : string
        Length : >= 1 character(s)
        Pattern : ^[a-z]([-a-z0-9]*[a-z0-9])?$
      • pipelines object
        type : object
        • azure-pipelines object
          type : object
          • branch string
            type : string
          • path string
            type : string
          • providerId string
            type : string
        • github-actions object
          type : object
          • branch string
            type : string
          • path string
            type : string
          • providerId string
            type : string
        • gitlab-ci object
          type : object
          • branch string
            type : string
          • path string
            type : string
          • providerId string
            type : string
        • jenkins object
          type : object
          • gitWebhookOptions object
            type : object
          • gitlabWebhookOptions object
            type : object
          • providerId string
            type : string
          • xmlTemplate object
            type : object
            • gitBranch string
              type : string
            • gitPath string
              type : string
            • gitProjectId string
              type : string
            • gitlabBranch string
              type : string
            • gitlabPath string
              type : string
            • gitlabProjectId string
              type : string
        • webhook object
          type : object
          • providerId string
            type : string
          • token string
            type : string
          • url string
            type : string
      • type "template" required constant
        type : string
        Constant value : template
      🚨 No extra propertie(s) are authorized in this object
    Length : >= 1 propertie(s) AND <= 1 propertie(s)
    🚨 No extra propertie(s) are authorized in this object
🚨 No extra propertie(s) are authorized in this object
Resources of Catalog items of type template

The source repository​

The template content must be hosted on a remote Git repository. Once a new microservice starting from the template is created, the Console clones the content of the repository in a new one under the Git provider of the user's project.

The URL to the repository must be specified in the archiveUrl filed of the item, and must point to the tar.gz version of a specific sha or ref of the Git project (e.g., https://github.com/mia-platform-marketplace/crud-sql-template/archive/0.1.0.tar.gz).

tip

For archives hosted on GitLab, if is better to use API URLs (e.g. https://git.tools.mia-platform.eu/api/v4/projects/MY_PROJECT_ID/repository/archive.tar.gz?sha=main), instead of UI-based URLs, since group tokens work properly with the API format but often fail with the UI path.

Private repositories​

If the repository is public and openly accessible (i.e., open source), no further actions are required for the item to be accessible and usable by any Company.

However, if the item is stored in a private repository, some additional configurations are required to ensure the Console can access it.

Namely, you need to create a provider for the Catalog, where you'll configure the credentials required to access your Git Provider, and link the provider to the item through the providerId field.

tip

To make Software Catalog resources accessible to other Companies, you must enable the "Allow access to all the Companies" option in the Provider settings, as explained here. This ensures the Console can access the item’s resources even when it belongs to a project in a different Company.

Continuous integration​

The service should ensure that Continuous Integration (CI) is set up, to update the service image any time its code is modified.

When creating a template item, you can either ship the CI with the archive itself, or use the pipelines field to reference an existing CI that will be generated alongside the service files.

tip

Mia-Platform provides some ready-to-use pipeline teamplates. Contact your referent to know how to configure them within your Console installation.

Special files and placeholders​

Any of the archive file can contain some special placeholders that will be replaced by the Console at the creation of the new microservice. The available placeholders are:

  • mia_template_image_name_placeholder: name of the docker image entered by the user;
  • %CUSTOM_PLUGIN_PROJECT_NAME%: name (label) of the Console project;
  • mia_template_project_id_placeholder: id of the Console project;
  • mia_template_service_name_placeholder: service name chosen by the user;
  • %CUSTOM_PLUGIN_SERVICE_DESCRIPTION%: description of the service chosen by the user;
  • %CUSTOM_PLUGIN_CREATOR_USERNAME%: username of the user who created the service;
  • %CUSTOM_PLUGIN_PROJECT_GIT_PATH%: full path of the repository of the Git provider;
  • %GIT_PROVIDER_PROJECT%: name of the Git project entered by the user (e.g. GitHub repository or Gitlab project);
  • %GIT_PROVIDER_GROUP%: name of the group of Projects entered by the user (e.g. GitHub organization or Gitlab group);
  • %GIT_PROVIDER_BASE_URL%: URL base of the Git provider;
  • %NEXUS_HOSTNAME%: Docker registry hostname;
  • %CUSTOM_PLUGIN_IMAGE_NAME% (deprecated): name of the Docker image entered by the user;
  • %CUSTOM_PLUGIN_PROJECT_ID% (deprecated): id of the Console project;
  • %CUSTOM_PLUGIN_PROJECT_NAMESPACE% (deprecated): id of the Console project;
  • %CUSTOM_PLUGIN_SERVICE_NAME% (deprecated): service name chosen by the user.

Moreover, in the archive you can make use of the special root-level directory .mia-template/. This folder will not be committed in the created repository: instead, its content will overwrite any file with the same name in the main directory (e.g., you can use it to provide a different README file to developers or to store the images and the marketplace item configuration).