Skip to main content
Version: 12.x (Current)

Orchestrator Generator

One of the main features of Mia-Platform is the automatic generation of the orchestrator files, ready to be deployed; these files are saved in the configuration repository.
For instance, the Console can generate Kubernetes files and deploy them on your runtime based on the Design configuration you provided.

However, in some scenarios, you may want to generate these files differently: in this case, you have to use an Orchestrator Generator.
This enables you to tailor the deployment process to your specific needs and the functionalities offered by your chosen orchestrator, achieving a level of customization not readily available with the default Mia-Platform generation.

When the Orchestrator Generator Extension is enabled, the Console sends a POST request to a configured Provider's API Base URL to generate the files to be deployed. The request body contains some information about the Project and the Configuration, and the Console expects to receive, in response, the files to be saved and deployed.

info

An Orchestrator Generator can only be used when the Enhanced Project Workflow is enabled.

Orchestrator Generator

Setup

To enable the Orchestrator Generator on a Project, follow these steps:

  • check that the Enhanced Project Workflow is enabled for the Project;
  • connect a Provider of type Extension API Provider with the Orchestrator Generator capability to its Company, as described in the Extension API Provider page;
  • navigate to Project Settings and click on the Providers tab;
  • enable the Orchestrator Generator extension in the Extensions section, selecting the Provider previously connected.

Extension Provider banner

The Providers suitable for the Orchestrator Generator Extension are the ones featuring the Orchestrator Generator capability. Every Provider with such capability can be selected to enable the Extension.

If no Provider with the Orchestrator Generator capability is connected to the Company, the Orchestrator Generator Extension will not appear in Project Settings.

Sequence diagram

This is a simplified schema of the Orchestrator Generator's operation.

sequenceDiagram actor client as Client participant console as Console participant orch as Orchestrator Generator Provider participant git as Git Provider client->>console: Trigger deploy console->>orch: POST (extension API URL) Note over console,orch: External configurator payload orch->>console: 200: generated configuration Note over console,orch: {fileName1: fileContent1,<br>fileName2: fileContent2} console->>console: Public variable interpolation console->>git: Commit configurations git->>console: 200: commitId console->>client: 200: commitId, refName

Request format

Authentication

The Console will authenticate using the method specified while connecting the Provider, which can be Bearer Token or Basic Auth.

Body

The payload sent to the Extension is shaped as follows:

{
"project": {
"name": "<Project Name>",
"id": "<MongoId>",
"projectId": "<projectId>",
},
"tenant": {
"name": "<Company Name>",
"id": "<tenantId>"
},
"environment": {
"id": "<envId>",
"name": "<Env name>",
"isProduction": true|false
},
"configuration": {
"services": {
"serviceName": {
"name": "serviceName",
...all services configurations
}
},
"configMaps": {
"config1": {
"name": "config1",
"files": [{
"name": "file1",
"content": "file1 content"
}]
}
}
}
}

Service data model

FieldTypeDescriptionoptional
nameStringName of the service
descriptionStringDescription of the service set in UI
tagsString[]List of tags set in UI
dockerImageStringService docker image
advancedBooleanFlag to distinguish the data model for advanced services (if true check the advanced services data model)✔️
replicasNumberNumber of service static replicas
createdAtStringISOString of the service creation date
environmentEnv SchemaEnvironment variables
annotationsObjectService annotation, fields (name, value, description)
labelsObjectService labels, fields (name, value, description)
resourcesResource SchemaCPU and MEM configuration
probesProbes SchemaK8S probes configuration
containerPortsContainerPort[]List of ports exposed by the container (fields: name, from, to)
configMapsConfigMount[]List of configurations to be mounted
terminationGracePeriodSecondsNumberGrace period time configuration
exclusiveServiceExposureBooleanUse this field to understand which containers should be exposed in the k8s Service✔️
additionalContainersContainer[]Extra containers to be installed in the service✔️

Env Schema

FieldTypeDescription
nameStringEnv var name
valueStringEnv var value
valueTypeplain/secretEnv var value (if secret, use secretName and secretKey)
secretNameStringName of the secret holding the env value
secretKey StringName of the secret key (withint the Secret secretName) holding the value for the env

Resource Schema

The resources field holds two properties cpuLimits and memoryLimits, each of them having the following schema:

FieldTypeDescriptionOptional
maxStringCPU/MEM limit✔️
minStringCPU/MEM request✔️

Probes Schema

The probes field holds three properties: readiness, liveness and startup, each of them having the following schema:

FieldTypeDescriptionOptional
pathStringPath to configure the httpGet probe✔️
portStringName of the container port exposing the probe✔️
initialDelaySecondsNumberValue for the initialDelaySeconds k8s configuration✔️
periodSecondsNumberValue for the periodSeconds k8s configuration✔️
timeoutSecondsNumberValue for the timeoutSeconds k8s configuration✔️
successThresholdNumberValue for the successThreshold k8s configuration✔️
failureThresholdNumberValue for the failureThreshold k8s configuration✔️

ConfigMount Schema

Each configMaps item holds information about how to mount a specific ConfigMap found in the top-level configMaps field.

Mount information is the following:

FieldTypeDescriptionOptional
nameStringName of the ConfigMap to be mounted
mountPathStringPath where the configuration files should be mounted
subPathsString[]List of specific files that needs to be picked from the ConfigMap and mounted✔️

Container schema

Each additional container has a similar shape of the main service, holding the following properties subset: name, dockerImage, exclusiveServiceExposure, containerPorts, probes, environment, resources, and configMaps.

Service data model example

JSON request body
{
"name": "my-service",
"description": "Some description",
"tags": ["custom"],
"dockerImage": "ghcr.io/mia-platform/crud-service",
"swaggerPath": "/documentation/json",
"advanced": false,
"replicas": 1,
"createdAt": "2022-10-18T13:51:49.959Z",
"environment": [
{
"name": "SOME_VAR",
"value": "VALUE",
"valueType": "plain"
}
],
"annotations": [
{
"name": "mia-platform.eu/version",
"value": "v11.5.0",
"description": "Version of Mia-Platform used by the project"
}
],
"labels": [
{
"name": "app",
"value": "crud-service",
"description": "Name of the microservice, in the service selector",
}
],
"resources": {
"cpuLimits": { "max": "300m", "min": "150m" },
"memoryLimits": { "max": "300Mi", "min": "150Mi" }
},
"probes": {
"liveness": {
"path": "/-/healthz",
"port": "http",
"initialDelaySeconds": 15,
"periodSeconds": 20,
"timeoutSeconds": 1,
"failureThreshold": 3
},
"readiness": {
"path": "/-/ready",
"port": "http",
"initialDelaySeconds": 5,
"periodSeconds": 10,
"timeoutSeconds": 1,
"successThreshold": 1,
"failureThreshold": 3
}
},
"configMaps": [{
"name": "crud-service-collections",
"mountPath": "/home/node/app/collections"
}],
"containerPorts": [{
"name": "http",
"from": 80,
"to": 3000
}],
"terminationGracePeriodSeconds": 30,
"additionalContainers": [
{
"name": "rbac-service",
"dockerImage": "ghcr.io/rond-authz/rond:main",
"exclusiveServiceExposure": true,
"containerPorts": [{"name": "rbac-service","from": 80,"to": 9876}],
"probes": {
"liveness": { "path": "/-/rbac-healthz", "port": "rbac-service" },
"readiness": { "path": "/-/rbac-ready", "port": "rbac-service" }
},
"environment": [
{
"name": "HTTP_PORT",
"value": "9876",
"valueType": "plain"
}
],
"resources": {
"cpuLimits": { "min": "100m", "max": "100m" },
"memoryLimits": { "min": "60Mi", "max": "430Mi" }
},
"configMaps": [{
"name": "rbac-sidecar-svc-opa-policies-config",
"mountPath": "/configurations/opa",
}, {
"name": "rbac-sidecar-svc-oas-permissions-config",
"mountPath": "/configurations/oas",
"subPaths": ["crud-service-permissions.json"]
}]
}
]
}

Response format

The response, coming from the Extension and received by the Console, must be an object holding a key/value pair for each file that needs to be saved to the configuration repository. The key will be threated as the file name while the value as the file content. The file content must be a string.

Example

{
"values.yaml": "the content of the values file...",
"my-service.deployment.yml": "the content of the deployment file for my-service..."
}

If something goes wrong and an error must be produced by the Orchestrator Generator, you can send a 500 status code and a payload that looks like this

{
"error": "some technical error to be traced in service logs",
"message": "some user facing error message that is propagated to the final user"
}
tip

Use the message field to provide useful insights to the final user and help them resolve what have gone wrong with the configuration.

The user will receive your message in the failed deploy feedback modal

failed deploy custom message in modal