Service profile reference

The service profile is an XML file that defines system service behavior. It provides the information to run services managed by the EGO service controller (EGOSC). For IBM® Spectrum Conductor, the service profile is needed only if you want to modify a service after creating an instance group. For application containers, you need the service profile only to modify a service after it is defined in an application template and created from registering an application instance.

Environment variables

When modifying a service profile, you can configure the following environment variables with values for your system:
  • EGO_TOP
  • EGO_BINDIR
  • EGO_CLIENT_ADDR
  • EGO_CONFDIR
  • EGO_ESRVDIR
  • EGOSC_INSTANCE_CGROUP_PATH
  • EGO_LIBDIR
  • EGO_LOCAL_CONFDIR
  • EGO_SERVERDIR
  • EGO_MASTER_LIST
  • EGO_MACHINE_TYPE
  • EGO_SHARED_TOP
  • EGO_ESRVIR

ServiceInstanceStateChange > InstanceSequenceId

Description: For internal system use only.

ServiceInfo > NumServiceInstances

Description: The number of active service instances for a service.

Required or optional: Optional

Default value: 1

ServiceAllocationInfo

Description: For internal system use only.

ServiceControlOperation

ServiceDefinition

Configures a service to be managed by the EGO service controller, defining version, resources, allocations, activities, and other configuration parameters for the service.
Note: For extended service capabilities, the type attribute must be set either ASC or Conductor.

ServiceDefinition > Version

Description: Specifies the version of the schema.

Required or optional: Optional

ServiceDefinition > Description

Description: Describes this service.

Required or optional: Optional

Valid values: Specify 1 to 120 alphanumeric and special characters, except control characters.

ServiceDefinition > MinInstances

Description: Specifies the minimum number of instances this service requires to run, or the minimum percentage of available slots in the resource group that the service is using. When specifying a percentage, the type attribute must be set to ASC. Ensure also that you first set the resource group for the service.

Service instances can be started even if the number available slots do not satisfy MinInstances. A service with fewer than the number of MinInstances started will be in ALLOCATING state.

You can dynamically change this parameter in the service profile while a service is running.

Required or optional: Optional

Valid values: Specify a number greater than or equal to 1, or a percentage greater than 0% and less than 100%.

Default value: ""

ServiceDefinition > MaxInstances

Description: Specifies the maximum number of instances this service is allowed to run, or the maximum percentage of available slots in the resource group that the service is using. When specifying a percentage, the type attribute must be set to ASC. Ensure also that you first set the resource group for the service.

Specify a number greater than or equal to the value specified by MinInstances. You can dynamically change this parameter in the service profile while a service is running.

Required or optional: Optional

Valid values: Specify a number greater than or equal to 1, or a percentage greater than 0% and less than 100%.

Default value: ""

ServiceDefinition > MaxInstancesPerSlot

Description: Specifies the maximum number of instances of this service that is allowed per CPU slot. To fully utilize resources, it is recommended to configure MaxInstancesPerSlot so that it divides evenly into MaxInstancesPerHost.

This parameter is not valid for multidimensional scheduling.

Required or optional: Optional

Valid values: Specify a number greater than or equal to 1

Default value: 1

ServiceDefinition > MaxInstancesPerHost

Description: Specifies the maximum number of instances of this service that is allowed per host. Specify a number greater than or equal to 1.

Limitation: No service instance can be started on a host if the ceiling specified by MaxInstancesPerHost or MaxInstancesPerSlot is more than the number of free slots on that host. It may cause slot wastage if you configure MaxInstancesPerHost so that it does not divide evenly into MaxInstances.

Required or optional: Optional

Default value: Any number of instances can start on the host

ServiceDefinition > InstanceToSlotRatio

Description: Specifies the instance-to-slot ratio.
Note: For Enabling a service to use GPUs, the InstanceToSlotRatio parameter must be in the format 1:N (not N:1). For all other IBM Spectrum Conductor features, this parameter supports 1:N and N:1 (the setting acts the same as the parameter MaxInstancesPerSlot when the value is N:1 and it represents the multislot option when the value is 1:N).

This parameter is not valid for multidimensional scheduling.

Required or optional: Optional

Valid values: 1:N for a service with GPUs, and 1:N or N:1 for all other features, where N is a positive integer.

ServiceDefinition > UseGPU

Description: Specifies whether a service will use GPUs (instead of, or in addition to, CPU slots). The value can be true or false. If true, the service uses the GPUs configured for your cluster (the cluster must include hosts that have GPUs). The default is false.

If you set the UseGPU parameter to true, you can also set ExclusiveGPU to specify whether the requested GPU mode is exclusive.

The InstanceToSlotRatio parameter specifies the number of GPUs to use for a service, in the format of 1:N, where N is the number of GPUs for each service.

Required or optional: Optional

Default value: false

ServiceDefinition > ExclusiveGPU

Description: Set if you configured the UseGPU parameter to true, and you want to specify that the requested GPU mode is exclusive (versus default mode, which is sharable).

Required or optional: Optional

Default value: false

ServiceDefinition > Priority

Description: Specifies the order in which the service controller starts services at start time. Specify a number greater than or equal to 1 that represents the relative starting order for this service. A value of 1 is the lowest priority.

Required or optional: Optional

Default value: 1

ServiceDefinition > ControlPolicy

Description: Describes the service lifecycle parameters of a service. It defines parameters for starting and starting the service, and detecting hung services.

Specifies exit values, which, if received from all instances of a service on a host, should cause that host to be blocked from running this service. The EGO service controller should not restart instances on that host unless the host is unblocked.

Required or optional: Optional

Default value: No exit values are checked

ServiceDefinition > ControlPolicy > StartType

Description: Specifies whether the service starts automatically or manually. Specify AUTOMATIC or MANUAL.

Required or optional: Optional

Default value: AUTOMATIC

ServiceDefinition > ControlPolicy > MaxRestarts

Description: Specifies the maximum number of times this service can be restarted before it is flagged in an error state.

The counter of restart will be reset once the service keeps in RUN state longer than five minutes.

This attribute can be set in the service profile, and used with the ESC_SERVICE_START_FAIL_RETRY parameter in the egosc_conf.xml file.

Required or optional: Optional

Valid values: Specify a number greater than or equal to 0

Default value: Infinite

ServiceDefinition > ControlPolicy > HostFailoverInterval

Description: Specifies the length of time to wait after a host fails until the service should be restarted on another host.

Specify the duration in the format PTnHnMnS, where:
  • nH the number of hours
  • nM the number of minutes
  • nS the number of seconds

The number of seconds can include decimal digits to arbitrary precision.

Required or optional: Optional
Note: To use service instance fencing, you must also configure HostFailoverInterval. Otherwise, fencing will not be triggered while restarting SI manually.

ServiceDefinition > ControlPolicy > Dependency

Description: Specifies whether there is a dependency on another service. The type attribute of the element is used to describe the dependency type, and the content of the element holds the name of the service on which it is being depended.

Required or optional: Optional

Default value: No dependency

ServiceDefinition > ControlPolicy > Dependency > type

Description: Specifies whether service dependency is checked only when the service starts or the dependency relationship is maintained during the lifecycle of the service. To maintain the relationship of the dependent service with its antecedent service, type must be set to Conditional. If type is set to OnStart, the satisfy, keep, and autoStart attributes are ignored.

Required or optional: Optional

Valid values: OnStart or Conditional

Default value: OnStart

ServiceDefinition > ControlPolicy > Dependency > satisfy

Description: When Dependency > type is Conditional, defines a list of states that the antecedent service must be in before the dependent service can start.

Required or optional: Optional

Default value: STARTED

ServiceDefinition > ControlPolicy > Dependency > keep

Description: When Dependency > type is Conditional, defines a list of states that the antecedent service must be in for the dependent service to keep running. The resource orchestrator restarts the dependent service if any antecedent services are not in the state that is specified for the keep attribute. The states that are specified for the keep attribute must be a superset of the states that are specified for the satisfy attribute.

Required or optional: Optional

Default values: TENTATIVE, STARTED

ServiceDefinition > ControlPolicy > Dependency > autoStart

Description: When Dependency > type is Conditional, specifies whether starting a dependent service should automatically trigger its antecedent service to start. If set to true, the EGO service controller tries to start the dependent service's corresponding antecedent service. Antecedent services that are started by autoStart keep running even when the dependent service is stopped later.

Required or optional: Optional

Default value: false

ServiceDefinition > ControlPolicy > BlockHostExitValues > ExitValue

Description: Specifies an exit code (value), which, if received from all instances of a service on a host, causes that host to be blocked from running this service. The EGO service controller does not restart instances on that host, unless the host is unblocked.
Note: An exit code must be 0 to 255. If the EGO command exit code is less than 128, you must specify the BlockHostExitValues with the appropriate exit value. For example, if the exit code is 126, which is less than 128, you enter a value of 126. If the EGO command exit code is 128-255, specify the BlockHostExitValues with -(256 - exit code). For example, if the exit code is 137, you enter a value of -119, since 256-137=119.

This attribute can be set in the service profile, and used with the ESC_SERVICE_START_FAIL_RETRY parameter in the egosc_conf.xml file.

Required or optional: Optional

Valid values: Integer

ServiceDefinition > ControlPolicy > ServiceFailoverFencing

Description: Ties service instance fencing to resources that match given attributes. For example, use the hostType attribute to restrict fencing to hosts that run the same operating system on the same architecture; for example, LINUXResourceSpeci86.
Notes:
  1. Virtual IP conflicts can be solved by enabling fencing in the service profile. Use the fencing command to clean up the virtual IP on the old compute node before new service instances are started on new compute node.
  2. To use service instance fencing, you must also configure HostFailoverInterval. Otherwise, fencing will not be triggered while restarting the service instance manually.

Required or optional: Optional

Default value: Fencing is not enabled

ServiceDefinition > ControlPolicy > ServiceFailoverFencingrWaitPeriod

Description: Specifies the duration that the service controller waits for fencing to complete before terminating the activity for the service instance.

Specify the duration in the format PTnHnMnS, where:

  • nH identifies the number of hours
  • nM identifies the number of minutes
  • nS identifies the number of seconds (including decimal digits)

Required or optional: Optional

Default value: Infinite

ServiceDefinition > NetworkPolicy

Description: Specifies the network-related parameters of a service.

Required or optional: Optional

ServiceDefinition > NetworkPolicy > VirtualIPSettings

Description: Specifies the virtual IP-related settings that are used for high availability support. Virtual IP settings define all information that is needed to apply a virtual IP address to the target host.

Required or optional: Optional

ServiceDefinition > NetworkPolicy > BaseVirtualIP

Description: Specifies the basic virtual IP address for high availability. Each service instance has a unique virtual IP address. The virtual IP address for the specified service instance is BaseVirtualIP + service instance sequence number - 1. The virtual IP address must be IPv4 and in the x.x.x.x format.

Required or optional: Optional

ServiceDefinition > NetworkPolicy > Netmask

Description: Specifies the network mask for base virtual IP.

Because all VIPs are in the same subnet, netmask values are unique. If the net mask is not set, the default value would be the default net mask of the network class that could be derived from the address of the VIP, such as Class A: 255.0.0.0; Class B: 255.255.0.0; and Class C: 255.255.255.0.

Required or optional: Optional

ServiceDefinition > AllocationSpecification

Description: Describes the resource allocation information for this service.

ServiceDefinition > AllocationSpecification > ConsumerID

Description: Specifies the fully-qualified name of a consumer in the consumer tree. For example, /DeptA/ProjB/ConsumerC indicates that ConsumerC is part of ProjB, which is, in turn, part of DeptA.

Required or optional: Required

ServiceDefinition > AllocationSpecification > ResourceSpecification

Description: Describes the resources required by this service.

ServiceDefinition > AllocationSpecification > ResourceSpecification > ResourceGroupName

Description: Specifies the resource group for slot-based scheduling.
Important: If you define this property, ensure that ServiceDefinition > AllocationSpecification > ResourceSpecification > MdsProperties is not defined. Both ResourceGroupName (used for slot-based scheduling) and MdsProperties (used for multidimensional scheduling) cannot be defined simultaneously for a service.

Be aware that if you specify a resource plan created for multidimensional scheduling, the default number of slots scheduled for sharing (defined by slotmapping in MDPlan.xml) is used for the service.

Required or optional: Optional

Default value: "", which means that the service can use resources from all the resource groups associated with the consumer.

ServiceDefinition > AllocationSpecification > ResourceSpecification > ResourceRequirement

Description: Specifies the resources that are required to run. Specify an expression in a string. This expression is evaluated when you select candidate resources to fulfill an allocation. For the expression, you can enter either a host name, or a regular expression pattern for a host name. For example, select(hname ~* 'abc\.com'). The following strings can be used:
  • select(expression)
  • select(expression operator expression)
  • select((expression operator expression) operator expression)
Note: Always include a single quote (') in the regular expression pattern. For example, if the host name is abc.com, then you can use the pattern 'abc\.com' to match the string.
You can dynamically change this parameter in the service profile while a service is running. After the change is applied, any service instances that are running on a host that does not satisfy the new resource requirements are terminated. New allocations are requested to start service instances on a satisfactory host.
Note: For dynamic changes, the service type must be set to ASC or Conductor.

Required or optional: Optional

ServiceDefinition > AllocationSpecification > ResourceSpecification > AffinityRequirement

Description: Defines a set of affinity or anti-affinity relationships to another service or service group.

Required or optional: Optional

ServiceDefinition > AllocationSpecification > ResourceSpecification > AffinityRequirement > Affinity

Description: Defines an affinity relationship to another service or service group. The type attribute must be set to hard or soft. The content attribute defines the name of an existing service to which the service has affinity.

Required or optional: Optional

Valid values: hard or soft

Default type value: hard

ServiceDefinition > AllocationSpecification > ResourceSpecification > AffinityRequirement > AntiAffinity

Description: Defines an anti-affinity relationship to another service or service group. The type attribute must be set to hard or soft. The content attribute defines the name of an existing service to which the service has affinity.

Required or optional: Optional

Valid values: hard or soft

Default type value: hard

ServiceDefinition > AllocationSpecification > ResourceSpecification > MdsProperties

Description: Describes multidimensional scheduling parameters for the service.
Required or optional: Optional
Note: Required for multidimensional scheduling.
Important: If you define this section, ensure that ServiceDefinition > AllocationSpecification > ResourceSpecification > ResourceGroupName is not defined. Both MdsProperties (used for multidimensional scheduling) and ResourceGroupName (used for slot-based scheduling) cannot be defined simultaneously for a service.

ServiceDefinition > AllocationSpecification > ResourceSpecification > MdsProperties > ResourcePlanName

Description: Specifies a multidimensional resource plan.

Required or optional: Required

Default value: No multidimensional resource plan is defined.

ServiceDefinition > AllocationSpecification > ResourceSpecification > MdsProperties > ResourceMetric

Description: Defines the resource metrics that can be scheduled for this service. You can use any of four predefined resource metrics or specify your own metric.

Required or optional: Required

To define a resource metric, specify the metric and its value.
Important: Ensure that the metrics are defined identically in the service profile and the resource plan. If they are not identical, errors occur.
  • MetricName: Specify the name of the resource metric (predefined or user-defined). The following predefined metrics are available:
    • ncpus: Number of CPU cores that is used for multidimensional scheduling.
    • maxmem: Maximum amount of RAM (in MB) that is used for multidimensional scheduling.
    • maxswp: Maximum amount of virtual memory (swap space) (in MB) that is used for multidimensional scheduling.
    • maxtmp: Maximum amount of space in /tmp.
  • MetricValue: Specify the value for the resource metric.
For example:
<sc:ResourceMetric>                    
     <sc:MetricName>ncpus</sc:MetricName>                   
     <sc:MetricValue>1.00</sc:MetricValue>             
</sc:ResourceMetric>            
<sc:ResourceMetric>                  
     <sc:MetricName>maxmem</sc:MetricName>                 
     <sc:MetricValue>128.00</sc:MetricValue>
</sc:ResourceMetric>

ServiceDefinition > AllocationSpecification > ResourceSpecification > ResourceType

Description: Describes the resources required by this service.

Indicates the type of resource. The URI is intended to match the URI of the namespace of an XML schema that is used to further describe the resource.

Required or optional: Required

ServiceDefinition > ActivityDescription

Description: Ties a particular ActivitySpecification to resources that match given attributes. For example, on a compute host type of resource, you might use the hostType attribute to restrict an ActivitySpecification to hosts with a hostType of LINUXResourceSpeci86.

ServiceDefinition > ActivityDescription > Attribute

Description: Specifies a name-value pair of any type. The name provides an identifier for this attribute, and type indicates the XML schema type. The value of the Attribute is in the element content, which is optional. Thus, Attribute can be used both to provide the value of a given attribute, or can be used to express the names and types of attributes that are supported by various objects within the resource orchestration layer. In the service definition context, only hostType is a supported name.

Values:
  • "all": applies to any hostType
  • "X86_64": applies to 64-bit x86 Linux®

Required or optional: Optional

Default value: "all"

ServiceDefinition > ActivityDescription > Attribute > Name

Description: Specifies an identifier for the attribute.

Required or optional: Optional

ServiceDefinition > ActivityDescription > Attribute > Type

Description: Specifies an NCName that indicates the XML Schema type that represents this attribute. The type attribute must contain one of the names of the built-in types from the XML schema http://www.w3.org/TR/xmlschema-2/#built-in-datatypes specification.

Required or optional: Required

ServiceDefinition > ActivityDescription > ActivitySpecification

Description: Describes the execution parameters for an activity. The only required sub-element is the command that needs to be run to start the activity.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > ActivityName

Description: A name used to refer to an Activity. Not guaranteed to be unique within a cluster.

Required or optional: Optional

Default value: ""

ServiceDefinition > ActivityDescription > ActivitySpecification > Command

Description: Specifies the command to be run as part of an activity. Specify the full command line of the program to be run, including arguments.

Example: /usr/local/bin/blastall -p blastn -d nt -i sequences
Note: Not applicable for Dockerized services.

Required or optional: Required

ServiceDefinition > ActivityDescription > ActivitySpecification > Command > stdOutFile

Description: Specifies the path and file name where standard output (stdout) is stored on the target host when the activity runs.
Note: If you specify stdOutFile for a service that is configured to run more than one service instance on the same host, ensure that the specified path is unique for each service instance; for example: stdOut_${EGOSC_INSTANCE_SEQNO}.log.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Command > stdErrFile

Description: Specifies the path and file name where standard error (stderr) is stored on the target host when the activity runs.
Note: If you specify stdErrFile for a service that is configured to run more than one service instance on the same host, ensure that the specified path is unique for each service instance; for example: stdErr_${EGOSC_INSTANCE_SEQNO}.log.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > ExecutionUser

Description: Specifies the operating system user ID to use when running an activity.

Required or optional: Optional

Default value: The execution user defined in the consumer specified by AllocationSpecification.

ServiceDefinition > ActivityDescription > ActivitySpecification > Umask

Description: Specifies the file creation mask used within the context of a running activity, which determines the default permissions given to files created by the activity. This is an absolute mode.

Specify a 4-digit octal number (from 0 to 7) as described in the POSIX umask(1) man page.

Required or optional: Optional

Default value: 0077

ServiceDefinition > ActivityDescription > ActivitySpecification > WorkingDirectory

Description: Specifies the full path to the directory in which an activity executes. You can specify a path that is valid when interpreted on the resource used for execution.

The workingdirectory parameter specifies the base path for the command if the command attribute is constructed in a relative manner. For example, if the workingdirectory parameter is /example/scripts and the command attribute is ./script.sh, then the full command that is called is /example/scripts/script.sh

Required or optional: Optional

Default value: ""

ServiceDefinition > ActivityDescription > ActivitySpecification > EnvironmentVariable

Description: Models an operating system environment variable to indicate which environment variables should be set within the running context of an activity.

You can dynamically change this parameter in the service profile while a service is running. The change would then apply only to newly started or restarted service instances. Running service instances would not have the updated value.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > EnvironmentVariable > Name

Description: Specifies the name of the environment variable. Specify the name of the environment variable (for example, PATH or LD_LIBRARY_PATH), and specify any string for the content.

You can also use this parameter to indicate the location of a service instance, enabling the service to know the host or hosts that the antecedent service instances are running on. To configure environment variable substitution for service instance locations, define Name as (for example) the name of the service and define content as ${SERVICE_serviceName_LOCATION} or ${SERVICE_serviceName_LOCATIONS}.
  • If you specify ${SERVICE_serviceName_LOCATION}, the location of the first service instance is indicated. The serviceName in this case can only be a service that the current service depends on.
  • If you specify ${SERVICE_serviceName_LOCATIONS}, all the service instance locations are indicated as a comma-separated list. The serviceName in this case can only be a service that the current service depends on, or the current service name.

ServiceDefinition > ActivityDescription > ActivitySpecification > Rlimit

Description: Specifies an operating system limit within the context of a running activity. The type attribute is optional, and can be used to indicate whether a soft or hard limit is being specified. If a value is not specified, the rlimit of the root of the target host is used.

Note: In Linux, the following limits are supported:
  • CPU
  • FSIZE
  • DATA
  • STACK
  • CORE
  • RSS
  • NOFILE
  • MEMLOCK
  • VMEM

ServiceDefinition > ActivityDescription > ActivitySpecification > JobController

Description: Specifies a command to run when controlling the activity. Specify the full command line of the program to be run, including arguments.
Note: Not applicable for Dockerized services.

Example: /usr/local/jboss/bin/shutdown all

If JobController is defined, the command will be started as a means to stop the activity. The resource orchestrator will forcefully kill the activity if the command failed to stop the activity within ControlWaitPeriod.

If you do not have a JobController script for cleanup and shutdown activities, specify gracefulshutdown to enable shutdown of service instances. When gracefulshutdown is specified, the container to be terminated is marked for graceful shutdown when it is started. After the grace period (specified in ControlWaitPeriod) has passed, if the instance container is still alive, SIGKILL is sent to terminate the container.

Required or optional: Optional

Default value: No JobController. The container will be killed by a signal.

ServiceDefinition > ActivityDescription > ActivitySpecification > CleanupCommand

Description: Specifies the service controller cleanup command. The type attribute for the service must be set to ASC.

If you configure the CleanupCommand parameter, ensure that you also configure the InactivityPeriod parameter. If you configure the cleanup command for a service, ensure that the MaxInstancePerHost parameter for the service is set to 1.

Example: /opt/biginsights/spark/uninstall.sh

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > CleanupFinishWaitPeriod

Description: Specifies the duration that the service controller waits for the cleanup command to complete before it ends the cleanup activity. The type attribute for the service must be set to ASC.

Example: PT180S

Required or optional: Optional

Valid values: Greater than 0 seconds and less than 3600 seconds

Default value: 120S

ServiceDefinition > ActivityDescription > ActivitySpecification > InactivityPeriod

Description: Specifies the duration of inactive service instances that can occur on the host before the service controller starts the cleanup command. The type attribute for the service must be set to ASC.

Example: PT60S

Required or optional: Optional

Valid values: Greater than 0 seconds and less than 3600 seconds

ServiceDefinition > ActivityDescription > ActivitySpecification > JobMonitor

Description: Specifies the path of the Job Monitor script or binary.

Example: /opt/bin/JobMonitor.sh

Required or optional: Optional

Default value: None

ServiceDefinition > ActivityDescription > ActivitySpecification > Container

Description: Container support provides a way to limit resources for an activity per service instance. You can apply control groups, which includes subsystems and tunable parameters, to an application template or a service profile, so that an activity per service instance can be run and constrained by a control group on the system.

Note: For Dockerized services, cgroup settings are applied to the Docker controller process. This can cause the Docker controller process to not work properly if inappropriate values are entered. To configure resource parameters inside the Docker container for Dockerized services, apply these parameters to the DockerContainer resource type.
In the service profile, you can either have <ego:Container type="cgroups"/> to indicate that container resources are gathered from the multidimensional plan; or you can add the following optional resources under <ego:Container type="cgroups"/>:
  • CPULimit
  • DiskIOLimit
  • MemoryLimit
  • MemorySwapLimit
  • NetworkClassID

Example: "cgroups"

Required or optional: Optional

Valid values:"cgroups" or "jobObject"

Note: You can modify cgroup parameters in the service profile for services that are running.

ServiceDefinition > ActivityDescription > ActivitySpecification > Container > CPULimit

Description: If configured for cgroups, sets the maximum number of cores that the activity can use.

Example: 3

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Container > DiskIOLimit

Description: If configured for cgroups, sets the operation (read or write), device (disk device ID), and content (I/O limit in bytes per second) for the activity.

You can set more than one DiskIOLimit per container.

The disk device ID is in the format of major:minor, where major and minor are device types and node numbers that are specified in Linux Allocated Devices, otherwise known as the Linux Devices List and available from https://www.kernel.org/doc/Documentation/devices.txt

Example: Operation=read Device=8:0 Content=500

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Container > MemoryLimit

Description: If configured for cgroups, sets the maximum memory (RAM) in megabytes (MB) that the activity can use.

Example: 200

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Container > MemorySwapLimit

Description: If configured for cgroups, sets the maximum memory swap (RAM and swap) in MB that the activity can use.

Example: 500

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Container > NetworkClassID

Description: If configured for cgroups, it represents the net_cls.classid.

The network class ID is in the format: 0xAAAABBBB, where AAAA is the major number in hexadecimal and BBBB is the minor number in hexadecimal.

Example: 0x100001

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > DefaultURL

Description: Specifies a substitutable URL for a service if you want to display the service instance's URL. The type attribute for the service must be set to ASC.

Example: http://${HOSTNAME}:8080/mypath

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > JobMonitorMaxUpdateInterval

Description: Specifies the interval, in seconds, within which the resource orchestrator expects to receive the activity state from the Job Monitor. The Job Monitor is considered to be hanging if it fails to report its state within the interval.

Required or optional: Optional

Valid values: A positive integer

Default value: Infinite (Job Monitor updates the resource orchestrator only when necessary, without repeating the activity state.)

ServiceDefinition > ActivityDescription > ActivitySpecification > ControlWaitPeriod

Description: Specifies a wait period before killing an activity. Specify the duration in the format PTnHnMnS, where:
  • nH defines the number of hours.
  • nM defines the number of minutes.
  • nS defines the number of seconds. The number of seconds can include decimal digits.

Required or optional: Optional

Valid values: Greater than 0 seconds and less than 1 hour

Default value: 2 minutes

ServiceDefinition > ActivityDescription > ActivitySpecification > PreCommand

Description: Specifies an optional pre-execution command to run before running the EGO service controller command (specified in ServiceDefinition).

Specify the full command line of the program to be run, including arguments. You can optionally specify a timeout value, in seconds, using the timeout attribute.

You can optionally specify output and error log files for the pre-execution command, using the stdOutFile and stdErrFile attributes. Specify these files using either environment variables or the full path to the files.

Example: To specify a pre-execution command called myPreCommand, with a timeout value of 10 seconds, an output file using environment variables, and an error log file using the /tmp/myPreCommand_stdErrr.log path, specify:
<ego:PreCommand timeout="10" 
		stdOutFile="/tmp/${EGOSC_INSTANCE_HOST}/${EGOSC_SERVICE_NAME}/
		${EGOSC_INSTANCE_SEQNO}/myPreCommand_stdout.log" 
	stdErrFile="/tmp/myPreCommand_stdErrr.log"> 
	myPreCommand
</ego:PreCommand>
Example: To specify a pre-execution command called myPreCommand, with no timeout value, stdOutFile=/tmp/myPreCommand_stdout.log as the output file, and stdErrFile=/tmp/myPreCommand_stdErrr.log as the error log file, specify:
<ego:PreCommand
	stdOutFile="/tmp/myPreCommand_stdout.log" 
	stdErrFile="/tmp/myPreCommand_stdErrr.log"> 
	myPostcommand
</ego:PreCommand>

Required or optional: Optional

Default value: ""

ServiceDefinition > ActivityDescription > ActivitySpecification > PostCommand

Description: Specifies an optional post-execution command to run after running the EGO service controller command (specified in ServiceDefinition).

Specify the full command line of the program to be run, including arguments. The following environment variables can be used for the post-execution command:

  • EGOSC_INSTANCE_PRECMD_EXIT_REASON
  • EGOSC_INSTANCE_PRECMD_EXIT_STATUS
  • EGOSC_INSTANCE_COMMAND_EXIT_REASON
  • EGOSC_INSTANCE_COMMAND_EXIT_STATUS

You can optionally specify a timeout value, in seconds, using the timeout attribute.

You can optionally specify output and error log files for the post-execution command, using the stdOutFile and stdErrFile attributes. Specify these files using either environment variables or the full path to the files.

Example: To specify a post-execution command called myPostCommand, with a timeout value of 10 seconds, an output file using environment variables, and an error log file using the /tmp/myPostCommand_stdErrr.log path, specify:
<ego:PostCommand timeout="10" 
	stdOutFile="/tmp/${EGOSC_INSTANCE_HOST}/${EGOSC_SERVICE_NAME}/
		${EGOSC_INSTANCE_SEQNO}/myPostCommand_stdout.log"	
		stdErrFile="/tmp/myPostCommand_stdErrr.log"> 
	myPostCommand
</ego:PostCommand>
To specify a post-execution command called myPostCommand, with no timeout value, stdOutFile=/tmp/myPostCommand_stdout.log as the output file, and stdErrFile=/tmp/myPostCommand_stdErrr.log as the error log file, specify:
<ego:PostCommand
	stdOutFile="/tmp/myPostCommand_stdout.log" 
	stdErrFile="/tmp/myPostCommand_stdErrr.log"> 
	myPostcommand
</ego:PostCommand>

Required or optional: Optional

Default value: ""

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker

Description: Specifies common parameters for all Docker containers of a service and parameters for individual Docker containers.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > SharedProperties

Description: Specifies common parameters for all Docker pods or containers.

Required or optional: Required

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > SharedProperties > DockerNetwork

Description: Specifies Docker network parameters.

Required or optional: Required

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > SharedProperties > DockerNetwork > NetworkType

Description: Specifies the network type.

The following network types are available:
  • bridge uses normal Docker networking.
  • host uses the host's networking stack.
  • external uses an external network provisioning executable.
    Note: If you select external network, add EGO_DOCKER_NETWORK_PLUGIN to the ego.conf file to specify the network provisioning executable.
  • sdn uses multi-host networking, allowing containers to communicate with each other across Docker pods if connected to the same network. You can enable SDN on all Docker-supported operating systems for Linux. SDN is not supported for Linux on POWER®.

Valid values: bridge, host, external, or sdn

Required or optional: Required

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > SharedProperties > DockerNetwork > SDNName

Description: The specified name of the SDN network.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > SharedProperties > DockerNetwork > PodName

Description: The specified name for the network container in an SDN pod. As a best practice, the pod name should only be specified if you have also specified the network type as sdn. If specified, this name must be unique across the SDN network it is connected to.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > SharedProperties > DockerNetwork > DNSServer

Description: Specifies the DNS server IP address.

Example: 123.123.123.123.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > SharedProperties > DockerNetwork > DNSSearchDomain

Description: Specifies the DNS search domain.

Example: abc.com.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > SharedProperties > DockerNetwork > ExternalScriptVariable

Description: Specifies an external script variable name and its value as content.

Example: myname1/myvalue1

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > SharedProperties > StopTimeout

Description: Specifies, in seconds, the maximal allowed duration for the overall stop operation for the containers in a pod.

Example: 30

Required or optional: Optional

Default value: 20 seconds multiplied by the number of containers in a pod plus 60 seconds.

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > SharedProperties > StartupTimeout

Description: Specifies, in seconds, the maximal allowed duration of the overall start operation for the containers in a pod. PEM terminates the Docker Controller if it has not reported Docker container info to PEM during the time period. 

Example: 40

Required or optional: Optional

Default value: 20 seconds multiplied by the number of containers in a pod plus 60 seconds. 

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > SharedProperties > EnvironmentVariable

Description: Specifies an environment variable name and value for the container.

Example: name: MYVARIABLENAME content: myvariablevalue

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > SharedProperties > ContainerVolume

Description: Specifies the volume to create for the Docker container.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > SharedProperties > ContainerVolume > envname

Description: Specifies the volume environment name for the Docker container.

Example: ABC

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > SharedProperties > ContainerVolume > hostpath

Description: Specifies the volume path on the host.

Example: /myHostpath/path

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > SharedProperties > ContainerVolume > permission

Description: Specifies the Disk IO operation type as either read-write (rw) or read-only (wo).

Example: rw

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer

Description: Specifies Docker container parameters.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > Name

Description: A unique (to a pod definition) identifier that is used to distinguish a container within a pod.

Example: dockerContainer1

Required or optional: Required

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > Image

Description: Specifies the Docker image name.

Example: dockerImage1

Required or optional: Required

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > EntryPoint

Description: Specifies the path to overwrite the default ENTRYPOINT of the Docker image.

Example: /bin/bash

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > Command

Description: Specifies the command to be run inside the container. Specify the full command line of the program to be run, including arguments.

Example: Content: dockerCommand1

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > PublishedPort

Description: Specifies the port number to be published to the host. Optionally, specify the host port number, protocol, and the IP address to which to bind the port.

Example: PublishedPort: 177

Example:
  • hostPort: 7772
  • Protocol: tcp or udp. Default is tcp.
  • ip: 192.111.222.233

Required or optional: Optional

Valid values: 1 to 65535

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > CPUShares

Description: Specifies the CPU shares (relative weight).

Example: 1024

Required or optional: Optional

Valid values: 0 to 1024

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > CPUSet

Description: Specifies the CPUs to allow execution.

Example: 0-10 or 1, 2,

Required or optional: Optional

Valid values: Integers greater than or equal to 0

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > MemoryLimit

Description: Specifies the maximum memory to use, in MB.

Example: 2048

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > ImageRegistryURL

Description: Specifies the path to the registry to pull the Docker image.

Example: name: myRepository1/path1

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > EnvironmentVariable

Description: Specifies an environment variable name and value for the container.

Example: name: MYVARIABLENAME content: myvariablevalue

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > ContainerVolume

Description: Specifies the volume to create for the Docker container.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > ExecutionUser

Description: Specifies the container's user ID to use when running the Docker container, and this user must exist in the container.

Example: root

Required or optional: Optional
Note: If the impersonatemode parameter is specified, this user is required to exist on the host, but does not need to exist within the container.

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > GracefulStop

Description: The value can be true or false. If true, the Docker container will not be forcibly stopped until the time value (in seconds) that is set by the stop timeout parameter for ego:Docker. The default is false, which means that the container will be forcibly stopped.

Required or optional: Optional

Valid values: true or false

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > ShortRunning

Description: When a job monitor is not specified, the normal termination of a short-running container will not cause the Docker pod to be shut down if any other working container is still running.

Required or optional: Optional

Valid values: true or false

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > Privileged

Description: Specifies whether extended privileges are given to this Docker container.

Valid values: true or false

Default value: false

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > Dependency

Description: Indicates a dependency on another service or Docker container. If Dependency is defined in ego:DockerContainer, the type can only be OnStart. If the type is OnStart, the service is started only if the service that is being depended on is in the STARTED state; or the Docker container is started only if the Docker container that is being depended on is started. Other types are not supported.

Example: Type: OnStart Content: dockerContainer2

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > ReadyConditions

Description: Specifies user-defined conditions for when a container is considered to be ready. If no ready conditions are specified, the container is considered to be ready immediately after starting.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > ReadyConditions > RequiredContainerPort

Description: Specifies a port number that needs to be listening in the container in order for the container to be considered ready.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > ReadyConditions > RequiredContainerProcess

Description: Specifies a process name that must be running in the container in order for the container to be considered ready.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > ReadyConditions > ReadyCheckScript

Description: Specifies a user-defined script that returns with exit code 0 if a container is ready, or with exit code different from 0 if the container is not ready.

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > ExtraParameter

Description: Specifies a string that is passes as-is to the Docker Controller, to potentially be used to apply additional Docker parameters (requires customization of Docker Controller).

Example: --option1=value1 --option2=value2

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > ImpersonateMode

Description: Impersonates the execution user as a host level user when specified.

Valid values: merge or overwrite

Required or optional: Optional

ServiceDefinition > ActivityDescription > ActivitySpecification > Docker > DockerContainer > ImpersonateUserName

Description: Additional user names that need to be impersonated as a host user.

Required or optional: Optional

ServiceDefinition > ActivityDescription > LogPath

Description: Configure the service instance log path or the log directory path for a service in the service profile to display in the cluster management console or in the egosh service view command.

Example: C:\\myService.*.log or /tmp/srv1dir/$EGO_TOP/srv1dir/ /tmp/srvlogs/$SEQ_NUM/

ServiceDefinition > NeedCredential

Description: Specifies whether the service requires cluster administrative credentials. If set to true, cluster administrative credentials will be passed from the EGO_SERVICE_CREDENTIAL environment variable to the service, and the service can use the credentials to authenticate with IBM Spectrum Conductor daemons. To set the NeedCredential value to true, you must be a cluster administrator, or you must have Services Credential Configuration permissions. The execution user for the service should have the administrative role, as the EGO_SERVICE_CREDENTIAL environment variable is within the service process's environment variable list.
Note: You cannot define this property when the Impersonate parameter is defined.

Required or optional: Optional

Valid values: true or false

Default value: false

d

ServiceDefinition > Type

Description: Specifies the type of service. For extended service capabilities, the type attribute must be set either to ASC or Conductor.

Required or optional: Required

Valid values: Default, ASC, or Conductor

ServiceDefinition > CollectUsage

Description: Specifies if the service requires to monitor service resource consumption.

Required or optional: Optional

Valid values: true or false

ServiceDefinition > ServiceName

Description: Specifies the service name for the service profile.

Required or optional: Required

Valid values: Specify a mix of 1 to 40 alphanumeric characters and hyphens. The service name must start with a letter (that is, it cannot start with a number or a hyphen).

ServiceInfo

Description: For internal system use only.

StartOnBoot

Description: Reserved for future use.