module-hooks-b9245ba.md

Module Hooks

Define and execute hooks at specific phases of module deployment.

Note:

The module hooks are supported from major schema version 3 onwards. If they are specified but schema version is below 3, they are ignored.

You can use hooks to change the typical deployment process, in this case to enable tasks to be executed during a specific moment of the application deployment. For example, you can set hooks to be executed before or after the actual deployment steps for a module, depending on the applications' need.

Note:

Currently, module hooks are only Cloud Foundry app tasks. Therefore, the timeout of a hook is the task execution timeout defined for the respective module. For more information, see Application-Specific Timeouts.

When added to the deployment descriptor, module hooks are modeled as follows:

Sample Code:

_schema-version: "3.3"
ID: foo
version: 3.0.0
modules:
  - name: foo
    type: javascript.nodejs
    hooks:
      - name: hook
        type: task
        phases:
          - blue-green.application.before-stop.live
          - blue-green.application.before-stop.idle
        parameters:
          name: foo-task
          command: 'sleep 5m'        

In the example above, the hook attributes are:

• name – defines the name of the hook.

• type – defines the type of the hook. Currently, the only supported type is task.

• phases – defines the specific moment when a hook is executed. The phases element denotes that the hook is executed before the application is stopped. The suffixes live and idle are used during blue-green deployments and indicate when the before-stop phase is executed.

  Example:

  In the example above, the blue-green.application.before-stop.idle phase executes the hook when the new idle applications are redirected to the new live routes, and the blue-green.application.before-stop.live is used just before the deletion of the live application.

• parameters – defines the parameters of the hook. For the hooks of type task, the parameters must define a one-off task.

Depending on the deployment strategy you use, the phases values are:

• For regular deployment

  Phase	Supported for types	Description
  deploy.application.before-stop	task	Executed before the application corresponding to the module is stopped.
  deploy.application.after-stop	task	Executed after the application corresponding to the module is stopped.
  deploy.application.before-start	task	Executed before the application corresponding to the module is started.

• For blue-green deployment

  Phase	Supported for types	Description
  blue-green.application.before-stop.idle	task	Executed before the idle application corresponding to the module is stopped. Idle applications are created as part of blue-green deployments and are restarted (stopped and started again) after the deployment validation phase of their productization. That is after the live routes are mapped to them and their environments are rebuilt to contain only live routes.
  blue-green.application.before-stop.live	task	Executed before the live application corresponding to the module is stopped. Live applications are the ones that are already up and running before the deployment starts.
  blue-green.application.after-stop.idle	task	Executed after the idle application corresponding to the module is stopped.
  blue-green.application.after-stop.live	task	Executed after the live application corresponding to the module is stopped.
  blue-green.application.before-unmap-routes.live	task	Executed before unmapping the route of the live application that corresponds to the module.
  blue-green.application.before-start.idle	task	Executed before the idle application corresponding to the module is started.
  blue-green.application.before-start.live	task	Executed before the live application corresponding to the module is started.

Module Hooks - Specific Parameters

The table below contains the parameters of the supported module hook types:

Module-Hooks-Specific Parameters

Parameter	Scope	Read-Only / Write	Description	Default Value	Example
name	Module Hook	Write	Defines the name of the Cloud Foundry task that should be executed	The name of the hook	name: db_migration
command Note: This is a mandatory parameter.	Module Hook	Write	Defines the actual command that is executed as a Cloud Foundry task		command: "bin/rails db:migrate"
memory	Module Hook	Write	Defines the memory that is available to the Cloud Foundry task	Landscape-specific value that is equal to the default application memory Remember: Do not rely on the default value, as it will probably be much higher than you need and may not fit into the limitations of your quota.	memory: 256M memory: 1G
disk-quota	Module Hook	Write	Defines the disk space that is available to the Cloud Foundry task	Landscape-specific value that is equal to the default application disk quota Remember: Do not rely on the default value, as it will probably be much higher than you need and may not fit into the limitations of your quota.	disk-quota: 256M disk-quota: 1G

Extending Module Hooks Through an Extension Descriptor

You can also extend module hooks through the extension descriptor. To do so, add the code with your specific parameters, similarly to the following example:

Sample Code:

_schema-version: "3.3"
ID: foo-change-command
extends: foo

modules:
  - name: foo
    hooks:
      - name: hook
        parameters:
          command: 'sleep 1m'

Related Information

MTA Deployment Descriptor Examples

Defining Multitarget Application Deployment Descriptors for Cloud Foundry

Defining MTA Extension Descriptors

Legacy Blue-Green Deployment