Deployment hooks for service lifecycle operations
Services are on boarded in Service Fabrik by providing the following:
- Service BOSH release
- Service catalog file (erb)
- Service manifest file (ejs)
During Service Fabrik deployment, service release is uploaded (1) into BOSH & its catalog (2) is evaluated & is added in as part of service fabrik configuration, which is later used in generating the catalog of services offerred. During runtime when a service is to be provisioned, service fabrik provides a context and the ejs file (3) is evaluated/executed to generate the service manifest which is provided to bosh for deployment. This is a standard procedure and all the scripting that services need must go in either in the ejs file or they are to be part of the services bosh release itself (i.e. part of some jobs). Any action related to a service can only be executed during the deployment time. However, services may have some requirements which requires some custom actions to be executed prior to the deployment and the result of the same is to be provided for the service. Thus arises the need for Service Fabrik to provide a framework where in such custom actions or hooks can be executed in various phases (pre) of lifecycle (create/delete) of services which could be conditionally enabled.
[Note]: Service fabrik supports only pre lifecycle hooks as of now.
To create a new action which is to be executed as part of pre lifecycles of service, the action script (Which can be defined in either javascript file or an executable) has to be created. The format and input parameters to action scripts that fabrik provides will be discussed in details in later sections.
Action hooks implemented in JS must extend from 'BaseAction'. BaseAction is an empty class with the following empty methods defined in it:
- executePreCreate
- executePreUpdate
- executePreDelete
- executePreBind
- executePreUnbind
Depending on the kind of action to be executed in the required phase, appropriate method from the BaseAction must be overridden. For ex., if an action named 'ReserveIp' must be executed during PreCreate phase, then the implementation details for the same must be provided in the overridden method 'executePreCreate'. The method can be further modularised by adding any number of private methods, but the entry point to the phase, must be via the overridden method of that particular phase.
Action hooks if to be written in shell script should follow the naming convention ${actionName}_${lifecycle_phase}. Ex: if an action named 'Blueprint' must be executed during PreCreate phase, then all the script contents must be put in a file named Blueprint_PreCreate
If broker is running locally, then action scripts can be placed at config/templates/actions
In case broker is deployed on bosh then actions should be written at services/actions directory in service-fabrik-boshrelease.
To demonstrate usage clearly, we will be writing 2 sample hooks, One in each scripting language (ie. js and shell script)
Let's say we want to execute an action as part of PreCreate. We will name it Blueprint.
The PreCreate action script for Blueprint action should be named Blueprint_PreCreate.
And the other hook we will name ReserveIps.
These sample hooks can be found here
Names of the actions that are to be executed during lifecycle of individual services can be configured in the services catalog either at service level or plan level. Actions configured at service level will be executed for all service plans and actions defined at a plan level is just executed during the lifecycle of an instance for the particular plan. More than one hook/action could be executed by specifying the actions as a comma separated list. The result of all the actions is aggregated and a name-value pair (name of action/ response of action) is then provided as context for the service's ejs during manifest creation, which can then use the action response appropriately. https://github.com/cloudfoundry-incubator/service-fabrik-boshrelease/blob/master/services/blueprint.yml.erb#L27 https://github.com/cloudfoundry-incubator/service-fabrik-boshrelease/blob/master/services/blueprint-manifest.yml.ejs#L70
These actions has to be defined in service-fabrik manifest if service-farbik is being deployed through bosh, in case of running broker locally, actions should be defined in settings.yml.
actions node in manifest should have action script name and it's base64 encoded value as name value pair.
The input arguments to the script will be an exhaustive but limited json object context.
Context object will have deployment_name and instance_id for all lifecycle operation.
For specific operations input parameters will include all the parameters that comes as part of cf operation request.
- Only prelifecycle hooks are supported
- PreCreate
- PreUpdate
- PreDelete
- PreBind
- PreUnBind
-
Timeout: Timeout for action scripts to run is configured to 80s ie. script should finish executing within 80s. If actions take more than 80s then sf will throw an exception leading to failure of that lifecycle operation
-
In case of JS hooks, it is assumed that all the dependent modules required by it in the script is already defined as a dependency in Service Fabrik's package.json. However if any dependent JS module as required is missing, then such modules must be added as a dependency in 'package.json' in SF broker repo.
-
With regards to shell script as well, the script must only work with executables / commands that is available on the broker. Any additional software which are required to be invoked from the script is to be packaged as part of an independent bosh release which is to be deployed on to the broker VMs along with SF BOSH release.
-
In current implementation, service fabrik does not restrict resource usage by actions. As the action process will be running on the the same vm as service-fabrik, separation of resources is also not ensured. Hence hook owner has to take care of the usage and leakage of resources.
