Catalog Recipes
Overview
Catalog Recipes are JSON configuration entries in catalogs collection in core provision database; each catalog represents a recipe to deploy an nginx - service - daemon - mongo - elasticsearch - nodejs service or any custom type.
Once a catalog recipe is created, you can then use it in the Clouds & Deployments section to deploy your services.
Sections
Generic Schema Explanation
{
"name": "Service Recipe", //catalog recipe name
"type": "soajs", //catalog recipe type
"subtype": "service", //catalog recipe subtype supporting only service or daemon and applicable for soajs only
"description": "This is a sample service catalog recipe", //catalog recipe description
"locked": true, //if catalog recipe is locked, it cannot be modified but you can create copies out of it
"recipe": { //catalog recipe configuration
"deployOptions": { //recipe deployment options
"image": { //recipe image
"prefix": "soajsorg", //image prefix
"name": "soajs", //image name
"tag": "latest", //image tag
"pullPolicy": "Always" //image pull policy (only valid for kubernetes),
"override": false //if set to true, then when using this catalog recipe in the deploy pillar, you can change the values of prefix, name and tag before you submit
},
"specifyGitConfiguration": true, //if set to true, then when deploying a soajs service or daemon, the deployer will ask you to provide the git information of the repo to pull the code from
"readinessProbe": { //readiness probe configuration, any valid kubernetes config is allowed
"httpGet": { //http readinesss probe configuration example
"path": "/heartbeat", //Endpoint to hit when probing
"port": "maintenance" //Target port for probe, can be a string (for labeled ports) or number
},
"initialDelaySeconds": 5, //Number of seconds after the container has started before liveness probes are initiated
"timeoutSeconds": 2, //Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1
"periodSeconds": 5, //How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1
"successThreshold": 1, //Minimum consecutive successes for the probe to be considered successful after having failed.
"failureThreshold": 3 //Minimum consecutive failures for the probe to be considered failed after having succeeded
},
"restartPolicy": { //swarm specific restart policy for containers
"condition": "", //Restart condition: none, on-failure, any
"maxAttempts": 0 //maximum number of restart attempts
},
"container": { //Container related deploy options
"network": "", //Docker network that the container should plug to (only applicable for swarm)
"workingDir": "" //Container working directory
},
"ports": [ //Port mapping
{
"name": "http", //Port name
"target": 80, //Target port at container level
"isPublished": true, //Flag that specifies a published port
"published": 81 //Optional exposed port (for kubernetes, 30000 is automatically added to the port number)
}
]
"voluming": {} //Voluming configuration, content depends on platform (swarm or kubernetes), refer to the samples below for more details
},
"buildOptions": {
"settings": {
"accelerateDeployment": true //if set to true, then the deployer will copy soajs from the soajsorg/soajs image instead of installing it using npm
},
//catalog recipe environment variables that are passed on to the service container(s) to be deployed
//environment variables are explained in detail in the last section of this page
"env": {
"NODE_ENV": {
"type": "static",
"value": "production"
},
"SOAJS_ENV": {
"type": "computed",
"value": "$SOAJS_ENV"
},
"MY_ENV": {
"type": "userInput",
"label": "My Environment Variable",
"default": "something",
"fieldMsg": "Enter the value of this field to use in your deployment"
}
},
"cmd": { //catalog recipe command to execute
"deploy": {
"command": [ //command to execute
"bash",
"-c"
],
"args": [ //command arguments
"node index.js -T service"
]
}
}
}
}
}
Docker Swarm Voluming
"voluming": { //Voluming configuration
"volumes": [ //Volumes array, objects have a free schema, any valid swarm volume can be set
{
"Type": "volume", //Type of volume: can be volume or bind
"Source": "/data/custom/db/", //Volume source: can be a path or a volume name
"Target": "/data/db/" //Volume target where it will be mounted inside a container
}
]
}
Reference : https://docs.docker.com/engine/tutorials/dockervolumes/
Kubernetes Voluming
"voluming": { //Voluming configuration
"volumes": [ //Volumes array, objects have a free schema, any valid kubernetes volume can be set
"name" : "custom-mongo-volume", //Volume name
"hostPath" : { //Example of host volume configuration
"path" : "/data/custom/db/" //Path of volume on the host filesystem
}
],
"volumeMounts": [ //Volume mounts configuration example
{
"mountPath" : "/data/db/", //Path where the volume will be plugged at the pod level
"name" : "custom-mongo-volume" //Name of the volume to be plugged
}
]
}
Reference : https://kubernetes.io/docs/concepts/storage/volumes/
Service Catalog Recipe
The following recipe allows the deployment of SOAJS services and controllers
Daemon Catalog Recipe
The following recipe allows the deployment of SOAJS daemon
Nginx Catalog Recipe
The following recipe allows the deployment of an Nginx Container.
Mongo Catalog Recipe
The following recipe allows the deployment of a Mongo Container.
Elasticsearch Catalog Recipe
The following recipe allows the deployment of an ElasticSearch Container.
NodeJs Catalog Recipe
The following recipe allows the deployment of a NodeJS Container.
Environment Variables
The catalog recipe provide the ability to send environment variables to the service container(s) you are deploying.
These environment variables are classified to 3 categories:
Static
This environment variable provided a static value of type string.
"NODE_ENV": { //variable name in your code
"type": "static", //type is static
"value": "production" //value is the word production
}
Computed
This environment variable is computed by SOAJS then assigned before passing the recipe to the deployer to deploy the service container(s).
The full list of supported computed environment variables is found on this page and detailed in depth, Click here to see the list.
"CONTROLLER_IP": { //variable name in your code
"type": "computed", //type is computed
"value": "$SOAJS_NX_CONTROLLER_IP_N" //the variable that SOAJS should match from its list and replace here
}
When you deploy a service, you pick the catalog recipe. SOAJS will then load the list of its environment variables and match them to all the computed variables of your recipe.
The above will result in creating an environment variable called CONTROLLER_IP whose value is 127.0.0.1 for example.
After your deploy your service, if you click on the inspect operation from maintenance operations, you will find that the value of your computed variable is now:
"CONTROLLER_IP": { //variable name in your code
"type": "computed", //type is computed
"value": "127.0.0.1" //if the value of $SOAJS_NX_CONTROLLER_IP_N is 127.0.0.1 in SOAJS for example, then your env variable will now have that value
}
User Input
This environment variable depicts that the user should provide its value while deploying a service.
This means that when you are deploying a new service, if you pick the catalog recipe, SOAJS Dashboard will create new inputs for each environment variable whose type is userInput.
Provide the value of these variables and click deploy.
"MY_ENV": { //variable name in your code
"type": "userInput", //type is userInput
"label": "My Custom User Input Variable", //label to show above the input when attempting to deploy using this recipe
"default": "something", //default value of the input that shows up when attempting to deploy using this recipe
"fieldMsg": "Enter the value of your custom environment variable." //descriptive message that below the input that shows up when attempting to deploy using this recipe
}