Docker for External Callouts
External Initialization Scripts
The External Initialization section is now available when you Define a Custom Service to specify external initialization scripts.
This section allows you to augment the service by adding additional scripts to be executed during variousDeployment Lifecycle Scripts page.for existing or new services using sourcing methods explained in the
The Script from Bundle option is not available for this service type.
Users can define scripts for the each phase for each type service when you add/edit the service.
The following table identifies when a External Lifecycle Actions specific to a VM-based service type.
|VM-Based External||The specified script is executed...|
VM Pre-Provision Script
|Before the VM is launched/provisioned|
|VM Pre-Initialization Script||After the IP address is returned and the application VM service is initialized|
VM Post-Start Script
|After the application VM service is started.|
VM Pre-Terminate Script
|Before the application VM is terminated|
VM Post-Terminate Script
|application VM is terminated|
The following table identifies when an External Lifecycle Action script is specified for an External Service type.
|External Lifecycle Actions||The specified script is executed...|
|Update||When an updated IP address or a scaling operation dependency is specified when scaling up or scaling down.|
|Start||When a service initializes for a specific cluster or tier.|
|Stop||When the application terminates.|
|Suspend||When the application is powered off or shut down (not terminated).|
|Resume||When a suspended deployment resumes.|
It is possible for an external service to fall into an infinite loop if using the stop/start external initialization scripts. This situation may cause the Docker container to run forever. In these cases, use the CloudCenter platform's cliqrContainerExecuteScriptTimeout property as a global parameter when modelling applications.
When you model an application in the topology builder, you can add a global parameter called cliqrContainerExecuteScriptTimeout.
You can specify this parameter as a floating point number that accepts the following options:
- s = seconds (default)
- m = minutes
- h = hours
- d = days
docker.container.scriptTimeoutDuration=10m will be overridden by:
This global parameter overrides the docker.container.scriptTimeoutDuration property in the gateway.properties and restricts the Docker container from running beyond 10 minutes in case the external service falls into an infinite loop.
Add an External Service
To add an External Service, follow this process.
- Access the CCM UI > Admin > Services > Add Service page.
- Click External Service to select this service type.
- Proceed as you would to Define a Custom Service.
Configure the scripts for each Service-Based Externaldescribed in the table above.
Writing an External Service Script
All service scripts are executed under its parent directory. To execute another script inside the current script, use the relative path to the working directory.
The external service script is executed as a Linux bash script inside a Docker container. If you write the script in other languages, for example, Python, add the following line to the first line of your script:
Utility Bash Functions
Right before your script is executed, CloudCenter supplies all the application-specific parameters as environment variables. Some environment variables ($CloudFamily and $region) allow you to maintain the same script (that may be used for multiple cloud configurations) in a Docker container.
A utils.sh script in the root directory provides the utility bash functions. To include these functions, add the following:
All output is logged at the DEBUG level. Any output using stdout in the Docker container is caught by the CCO.
If you want to send log messages to the CCM UI (task message list in the Job Details page), you must add delimiters around your log message so CloudCenter can execute it accordingly. The following is a Python example:
Use the print_log() utility function in the utils.sh file to wrap your log message with delimiters.
Result Data Format
The ipAddress and hostname (if present in the JSON or YAML string) are propagated to the CCM and displayed in the Job Details page.
Be aware of the following CloudCenter requirements when writing your service scripts:
- The result data is case sensitive.
- The result data must use either JSON or YAML format.
The result data must be wrapped with delimiters.
Use the print_ext_service_result() function in utils.sh to wrap your result with delimiters. See the Passing Information from External Services section for an example.
If your external service script encounters errors, be sure to provide a meaningful error message and exit the script with status code > 0.
To show the error message in the UI, add delimiters around your error message:
Use the print_error() function in utils.sh to wrap your error message with delimiters.
Passing Information from External Services
External services may return parameters which in turn can be used by dependent tiers (any tier above the current tier).
The CloudCenter external service can return the following parameters. These variables are injected as environment variables into dependent tiers.
- The ipAddress parameter is the IP address of the external service. For example, the IP address of an Amazon RDS instance.
- The hostname parameter is the DNS name of the external service. For example, the DNS name of an Amazon RDS instance.
The environment parameter is a key-value map that contains custom-defined environment variables. For example, the following sample script:
... returns the parameters to the dependent tier as displayed in the following Sample userenv File (available at /usr/local/osmosix/etc):
The injected properties are prefixed with:
The injected properties are visible in the UI as highlighted in the following image:
The CloudCenter external service adds on the script details to any other information that already existed in the userenv file as displayed in the example above.
Deploying an External Service
To deploy an external service and ensure that it passes information from an external service to any dependent tier (any tier above the current tier), follow this procedure.
Define input parameters in a script and save the script in an accessible location as explained in the Passing Information from External Services section
- Add an External Service and provide the script location in one of the External Lifecycle Actions (for example, Start or Update). See External Initialization Scripts for additional context.
- Save the external service.
- Model an application using this external service.
- Launch the application. At this point, the CloudCenter platform add the injected properties to the dependent tier(s).
Cost and Reports
- No labels