// removed jquery ui css and js

External Service

Overview

You can create an application (see Application Discovery) using multiple tiers where you can stipulate each tier to use a different CloudCenter-supported service or externally-provided service (third-party services). Users can define scripts for the each phase for each type service when you add/edit a service.

What Is an External Service?

An external service is a service that you can define as a CloudCenter administrator. An external service does not have an associated VM – it is just a service that contains custom scripts provided by the administrator.

What Are External Lifecycle Actions?

An External Lifecycle Action are actions that you can define for agent-based services (see Virtual Machines with Agent in the above image) during a Service Definition or during an Application Definition.

The following image provides an example of a service-level definition.

The following image provides an example of an application-level definition.

This section allows you to augment the service by adding additional scripts that can be executed during various VM lifecycle events.

Custom Scripts Sources

A custom script can reside in a Docker container (see next section) or a repository as identified in the Deployment Lifecycle Scripts > Script Source Details section.

The Script from Bundle option is not available for this service type.

External Script Specification

External Service, External Initialization, and External Lifecycle Actions have some common areas like defining how scripts are initialized and executed when using these functions.

The following table identifies External Lifecycle Actions that are specific to an External Service.

External Service 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.

 

The following table identifies the External Initialization scripts that are specific to a VM-based (with agent) service.

VM-Based External Initialization Scripts
The specified script is executed...

Pre-VM Start

Before the VM is launched/provisioned
Pre-VM InitAfter the IP address is returned and the application VM service is initialized

Post-VM Init

After the application VM service is started.

Pre-VM Stop

Before the application VM is terminated

Post-VM Stop

application VM is terminated

 

The following table identifies the External Initialization scripts that are specific to a VM-based service tier at the Application level.

External Initialization Scripts at the Application Level
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

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 of 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:

#!/usr/bin/env python

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:

. /utils.sh

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 Bash example:  

echo "CloudCenter_EXTERNAL_SERVICE_LOG_MSG_START"
echo "log message here" 
echo "CloudCenter_EXTERNAL_SERVICE_LOG_MSG_END"

Use the print_log() utility function in the utils.sh file to wrap your log message with delimiters.

Printing Results

If you want to send results to the CCM UI, you must add delimiters around your result message so CloudCenter can execute it accordingly. The following is a Bash example: 

echo "CloudCenter_EXTERNAL_SERVICE_RESULT_START"
echo "<JSON or YAML string>"
echo "CloudCenter_EXTERNAL_SERVICE_RESULT_END"

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.

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:

echo "CLIQR_EXTERNAL_SERVICE_ERR_MSG_START"
echo "error message here"
echo "CLIQR_EXTERNAL_SERVICE_ERR_MSG_END"

Use the print_error() function in utils.sh to wrap your error message with delimiters.

Passing Information from External Service Scripts

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.

    Sample Script in YAML Format
    #!/bin/bash
    
    . /utils.sh
    
    print_log "This is a basic log message"
    
    result="hostName: testsite      #hostname parameter
    ipAddress: 10.1.1.5	    #ipAddress parameter" 
    
    print_ext_service_result "$result"
    Sample Script in JSON Format
    #!/bin/bash
    
    . /utils.sh
    
    print_log "This is a basic log message"
    
    result="{  
       \"hostName\":\"testsite\",
       \"ipAddress\":\"10.1.1.5\",
    }"
    
    print_ext_service_result "$result" 

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

    Sample userenv File
    #passed parameters and variables
    export CliqrTier_extService_1_IP="10.1.1.5"
    export CliqrTier_extService_1_HOSTNAME="testsite"
    
    #Inherited parameters and variables 
    export CliqrTier_extService_1_Cloud_Setting_networkName="sha-net01"
    export CliqrTier_extService_1_Cloud_Setting_numNICs="1"
    export CliqrTier_extService_1_Cloud_Setting_cloud="OpenstackDev-regionOne"
    export CliqrTier_extService_1_Cloud_Setting_publicIpAllocate="true"
    export CliqrTier_extService_1_Cloud_Setting_privateIPAllocationMode="DHCP"
    export CliqrTier_extService_1_Cloud_Setting_TenantId="c8fe2db7a7cb490ba6dd1913f4e5c9c8"
    export CliqrTier_extService_1_Cloud_Setting_account="3"
    export CliqrTier_extService_1_Cloud_Setting_networkId="efdb81c9-eb02-4199-a97b-27aab5ec58df"
    export CliqrTier_extService_1_Cloud_Setting_attachPublicIP="false"
    export CliqrTier_extService_1_Cloud_Setting_TenantName="sha"
    

    The injected properties are prefixed with:

    CliqrTier_<tier_name>_<property name>

    The ipAddress and hostname (if present in the JSON or YAML string) are propagated to the CCM and displayed in the Job Details page. 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.

Passing Information from External Initialization Scripts (Application Level)

External Initialization scripts may return parameters which in turn can be used by associated tier.

You can pass parameters to an associated tier ONLY from the VM Pre-Initialization Script field.

The Initialization scripts can return variables that are injected as environment variables into the userenv file of the associated tier.

  • The environment parameter is a key-value map that contains custom-defined environment variables. For example, the sample script below ...

    Sample Script in YAML Format
    #!/bin/bash
    
    . /utils.sh
    
    print_log "This is a basic log message"
    
    environment:
       hello: world 	            #key-value environment parameter
       instanceName: test_instance 	#key-value environment parameter
       instanceType: dummy 	        #key-value environment parameter
       serviceType: custom  	    #key-value environment parameter
    
    " 
    print_ext_service_result "$result"
    Sample Script in JSON Format
    #!/bin/bash
    
    . /utils.sh
    
    print_log "This is a basic log message"
    
    result="{  
       \"environment\":{  
          \"hello\":\"world\",
          \"instanceName\":\"test_instance\",
          \"instanceType\":\"dummy\",
          \"serviceType\":\"custom\"
       }
    }"
    
    print_ext_service_result "$result" 

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

    Sample userenv File
    #passed parameters and variables
    
    export hello="world" 
    export instanceType="dummy"
    export instanceName="test_instance"
    export serviceType="custom"
    

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.

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

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 the External Initialization Scripts section above 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 Application Deployments Report includes the usage hours for the External Service. See CloudCenter Cost and Fees for additional context.

  • No labels
© 2017 Cisco Systems