CliQr is now part of Cisco Learn More About Cisco

External Service

Overview

Docker for External Callouts

You can launch an isolated Docker container in the following scenarios:

Docker is installed by default on CentOS 7 and RHEL 7 installers and appliances for the CloudCenter platform (included in the core_installer.bin file, see Installer Packages or Virtual Appliances). For other operating systems, you can set up your own Docker environment and configure the CCO server to point to the external Docker appliance – contact CloudCenter Support for additional information.

Icon

If you install Docker after you install CCO, you must update the CCO properties file with a corresponding value, you cannot leave this field blank.

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 various events for existing or new services using sourcing methods explained in the Deployment Lifecycle Scripts page.

Icon

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 Initialization Scripts
The specified script is executed...

VM Pre-Provision Script

Before the VM is launched/provisioned
VM Pre-Initialization ScriptAfter 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 ActionsThe specified script is executed...
UpdateWhen an updated IP address or a scaling operation dependency is specified when scaling up or scaling down.
StartWhen a service initializes for a specific cluster or tier.
StopWhen the application terminates.
SuspendWhen the application is powered off or shut down (not terminated).
ResumeWhen a suspended deployment resumes.

Script Timer

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

For example:

docker.container.scriptTimeoutDuration=10m will be overridden by:

cliqrContainerExecuteScriptTimeout=10m

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.

  1. Access the CCM UI > Admin > Services > Add Service page.

  2. Click External Service to select this service type.
  3. Proceed as you would to Define a Custom Service.
  4. Configure the scripts for each Service-Based External Initialization described in the table above.

  5. Click Save

Writing an External Service Script

Icon

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.

Script Language

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:

Log Messages

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:  

Icon

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.

     

Icon

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.

Error Handling

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:

Icon

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:

    Sample Script in YAML Format
    Sample Script in JSON Format

    ... returns the parameters to the dependent tier as displayed in the following Sample userenv File (available at /usr/local/osmosix/etc):

    Sample userenv File

    The injected properties are prefixed with:

    The injected properties are visible in the UI as highlighted in the following image:

     

Icon

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.

  1. Define input parameters in a script and save the script in an accessible location as explained in the Passing Information from External Services section

  2. 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.
  3. Save the external service.
  4. Model an application using this external service.
  5. Launch the application. At this point, the CloudCenter platform add the injected properties to the dependent tier(s).

Cost and Reports

The VM-Hours column in the Usage Details Report includes the usage hours for the External Service. See CloudCenter Cost and Fees for additional context.

 

 

  • No labels