The component descriptor contains one component entity, defining either a singleton component or an instantiable class of components. There is no difference between the definition of a singleton and a class, except that instantiable classes are required to reside in a library of components referred to as a catalog. Also, either type of component can be used in an assembly, but a singleton can appear only once in the structure of an application, while an instantiable component can be used multiple times.
Below are two examples of the component descriptor structure; the first example is the current standard form, the second example shows the old format of the boot information specification. The old format is fully supported for compatibility with existing catalog appliances.
component name
{
volume sname : dev= pathname [, mount= pathname][, ro] [, high_bw]
resource cpu : min= val , max= val
resource mem : min= val , max= val , abs= val
resource bw : min= val , max= val
(input|output) sname : protocol= name [, mandatory ][, alias = dnsname ]
interface sname
property sname : type=(string|integer|ip_addr) [, filter= regexp ] \
[,min= val ,max= val ] [, (mandatory| dflt= val) ]
property sname : type=(string|integer) [, values= v1|v2|v3... ] \
[, (mandatory| dflt= val ) ]
.config_mode=(dhcp|volfix)
virtualization: modes="[xen_pv][,xen_hvm][,vmware][,...]"
{
path = filename
initrd = filename
options = " string "
console = " string "
device_schema = " string "
}
visual
{
...
}
}
component name
{
volume sname : dev= pathname, [, ro] [, high_bw]
resource cpu : min= val , max= val
resource mem : min= val , max= val , abs= val
resource bw : min= val , max= val
(input|output) sname : protocol= name = [, mandatory][, alias = dnsname =]
interface sname
property sname : type=(string|integer|ip_addr) [, filter= regexp ] \
[,min= val ,max= val ] [, (mandatory| dflt= val) ]
property sname : type=(string|integer) [, values= v1|v2|v3... ] \
[, (mandatory| dflt= val ) ]
cfgfiles
[
vol= sname , path= filename
vol= sname , path= filename
...
]
kernel: path= filename [, initrd = filename ] [, options = " string" ]
visual
{
...
}
}
The component entity has the following attributes defined:
|
.migrateable |
If set, it allows the component to be moved from one CPU to another (provided that the component is running in a virtual machine and there is VM migration support). There is no need to specify this attribute in a component - the default, if not specified, is 1 (TRUE). This is a Boolean attribute (valid values: 0,no,false,1,yes,true; also may be specified inline without value at all, meaning '1'). |
|
.server |
If .migrateable is set to 0, defines the name of the server on which this component is to run. This attribute, with the .migrateable attribute are usually set from an outer assembly, not in the component descriptor itself. The compiler will display a warning if this attribute is set in the component. |
|
.standby |
If set, this means the component is not started automatically when the application is started. The .standby attribute is not meant to be set in a component descriptor directly. Typically, it is set from an assembly that contains the component or re-directed to the top-level assembly of an application to allow enabling/disabling parts of the application by modifying the application's properties (stored in the top assembly - see the Package Descriptor). This is a Boolean attribute. |
|
.boot_tout |
Boot timeout, in seconds. If specified and set to a non-zero value, indicates the amount of time the application controller is to wait for the component to become active before assuming that it has failed to start. If this attribute is omitted or is set to zero, a default value that is configured for the CA AppLogic controller is used. |
|
.os_type |
obsolete This attribute should not be used in newly created descriptors. See the virtualization entity description instead. .os_type specifies the OS that this component uses. This information is necessary for support of multiple OS types running in virtual machines. The value provided is not interpreted by the ADL build system; together with the data in 'kernel' entity described below it is intended to be passed along to the VM boot loader. If not specified, 'linux' is assumed. |
|
.config_mode |
Specifies how the component should be configured. The allowed values are: dhcp and volfix. The default is dhcp. This attribute should be used explicitly only for backward compatibility, if the volfix functionality should be retained for a given component. This attribute is ignored and the mode is set to volfix if the descriptor does not have the virtualization entity. This is to allow old descriptors (which belong to components that rely on volfix and do not support the dhcp configuration) to work without modification. |
|
.field_opt |
A bitmask of options for enabling various debugging and troubleshooting support. This attribute does not follow the normal rules for overriding property values from an assembly, which apply to all other pre-defined attributes - the .field_opt value specified for a component is kept as class field options, while any setting of the same attribute for an instance of the component in an assembly is kept as instance field options. |
|
.category |
An arbitrary string that defines the general category to which the component belongs. It is allowed by the ADL syntax, but is not interpreted in any way. It is intended for use by the CA AppLogic visual tools to organize components in component libraries (catalogs). |
|
.description |
A short description of the component. Similarly to .category , the value of this attribute is arbitrary and intended for documentation purposes only. |
|
.console |
OS System console configuration parameters. The format of this string is not part of ADL, the currently supported console parameters are defined in the Grid User Guide. If ".console" is not specified for a component, CA AppLogic uses a system-default configuration setting. Unless overridden manually by a user with administrator privileges, the system default setting defines the component's console to be ssh on port 22. |
All component attributes are optional and need not be present in the descriptor.
All the attributes are also valid properties of the component, which can be overridden in an assembly that contains the component.
Note: The attribute names are prefixed with a dot to avoid name conflicts with regular properties. See the property entity below.
The table below is a summary of the valid sub-entities in a component, followed by sections that explain each sub-entity in detail.
|
volume |
Defines a volume that contains a file system used by the component. At least one volume entity must appear in each component. |
|
resource |
Defines the requirements of the component toward the hardware resources that must be made available for it to run. |
|
input, output |
Define terminals of the component, which are network interfaces intended for connection with other components in the same application. |
|
interface |
Used to enable and configure network interfaces that are not meant for connecting to other components (as the input and output terminals are) |
|
property |
Defines a configurable property of the component. |
|
cfgfiles |
Defines a list of configuration files that need to be verified for property markup and updated accordingly. |
|
kernel |
obsolete - Use virtualization instead. This entity contains OS-specific boot information, its contents depend on the value of the .os_type attribute of the component. |
|
virtualization |
Defines the virtual environment for which the component is designed and contains boot-specific options to be provided to the component's boot loader. The 'mode' field is still supported for backward compatibility with older descriptor files. |
|
visual |
Visual presentation data. ADL does not define the contents of this entity. It is intended for a GUI editor to store information related to how the component displays in the editor window. For example, the color, icon shape, and layout of terminals. The contents of this entity must conform to the general syntax rules of UDL, which were presented in the Syntax Rules that Apply to All Descriptor Types section. Also, for additional details, refer to the UDL specification. |
Defines a volume that contains a file system used by the component. At least one volume entity must appear in each component. The volume entity has the following attributes:
|
dev= |
The device name, as it is seen by the host OS of the component. The physical device containing the filesystem (and which can be either local or remote) will be made available to the host OS under that name. This attribute must be specified for all volumes. No two volumes in the same component can have the same value for this attribute. |
|
mount= |
Optional mount path for the volume. This attribute can be specified for volumes that are not mounted automatically by the component's operating system. Specifying this attribute for system-mounted volumes (for example, the boot volume) has no effect, as the OS will mount those volumes before it receives any configuration from CA AppLogic. The software resident on the component will receive the mount path for each volume as part of its configuration and is responsible for mounting the volume appropriately. A CA AppLogic component is not required to support this. The meaning of mount path may vary between OS types and is not necessarily supported by every OS. |
|
class |
If specified for an instantiable component that resides in a catalog, this attribute specifies that the volume |
|
type= |
This attribute is mandatory for volumes that have the class attribute set. It specifies how the common class image of the volume is to be provided to each instance of the class. It can have the following values:
blank - there is no image provided, each instance is to receive an empty un-initialized volume upon boot. 'null' is intended for specifying swap volumes. It also requires that the 'size=' attribute be specified. |
|
size= |
Volume size, for volumes of type blank . This must be a non-zero integer value, specifying the size in bytes. K, M and G suffixes can be used, meaning Kbytes, Mbytes, and so on. |
|
mandatory |
This applies only to volumes that do not have the class attribute and indicates that the volume is required for the operation of the component. If mandatory is not set, the component must be prepared to work correctly even if the device (which is seen by the component's software as specified by the dev= attribute) is not present. |
|
ro |
Means the filesystem on the volume is not written to by the component. Specifying this attribute does not guarantee that the component itself will not attempt to write to the volume. However, the presence of this attribute may be used to prevent write operations from going through. Specifying ro also implies shared - see below. |
|
shared |
This attribute, if present, means that the volume image can be shared among multiple instances of the same component, as well as with other components.This is mostly useful if the ro attribute is also specified, or if the filesystem on the volume has a built-in mechanism for read/write sharing at block level. Shared need not be specified for class volumes of type common (see type= above). |
|
boot |
Marks the volume as an OS boot volume. The file paths specified in the kernel sub-entity are relative to the root directory of the boot volume. Exactly one volume in a component must have the boot attribute. |
|
high_bw |
Identifies a volume that is accessed frequently and large amounts of data are transferred to/from it. This is a hint used for resource allocation, making it preferable to use a local resource for this filesystem. |
|
local_only |
If specified, this attribute means that the volume must reside on the same host as the component instance that uses it. |
A volume entity that has no class attribute also defines a configurable property on the boundary of the component, which can be set the same way as other properties of the component - see the property entity below. The mandatory attribute for such volumes works the same way as the mandatory attribute for properties. A volume property should be set to the logical name of one of the application's volumes (as found in the application's package descriptor).
Note: This means volumes and properties share namespace and one cannot define a volume and a property of the same name.
The resource entities define the requirements of the component toward the hardware resources that must be made available for it to run. The name of a resource entity must be one of: cpu, mem or bw. The definition of these entities is as follows:
|
cpu |
The min and max attributes of this sub-entity define the CPU time needed by the component, relative to the CPU time of other components that are allocated on the same physical CPU expressed as a decimal fraction or as percentage value. The value may exceed 1 (or 100%), if the component requires 2 or more CPUs on an SMP system. |
|
mem |
Defines the amount of memory needed by the component; The three attributes of mem are interpreted as follows: |
|
bw |
Defines the minimum and maximum network bandwidth necessary for the component to operate, expressed in bits/sec (scale modifiers like K and M and G are allowed; unlike the memory units, these modifiers follow the networking tradition - they mean decimal orders of magnitude K=1000, M=1,000,000, and so on, (for example, 1000M means 1 gigabit/s, same as 1G). |
The resource entities are mandatory, all must be specified in a component's description and all must have the min and the max value specified. The abs value may be omitted and is assumed to be equal to min by default.
These entities define terminals of the component, which are network interfaces intended for connection with other components in the same application. A terminal is a special kind of network interface - it is used only for one specific protocol and only in one direction (direction here refers to flow of control, not of data - that is, an output terminal is an interface used by a protocol client; while an input terminal is for a server). The presence of a terminal entity automatically defines a host name that resolves to the remote side of the connection in which this terminal participates. The terminal entities have the following attributes:
|
protocol |
This is the name of the network protocol filter for this terminal. The protocol name corresponds either to a pre-defined protocol (for example, http, nfs, and so on) or to a custom protocol that has filtering rules defined in the application's package descriptor. This attribute must be present for each input or output. If no protocol control is needed for the terminal, use protocol=any. |
|
mandatory |
If present, this binary attribute means that the terminal may not be left unconnected. Mandatory terminals will trigger a compilation error in an assembly that includes a component with such a terminal left unconnected. |
|
gateway |
(for outputs only) - If present, identifies the terminal as the default gateway for the component. A gateway output, instead of being programmed for connection to a single input on the remote side, is configured as the interface through which all connections outside the local network should go. When it is connected in an assembly, the remote end of the connection becomes the default gateway in the IP routing table and it is also programmed as the DNS server. Usually, a gateway terminal would be connected to a NAT router with DNS forwarding (or cache) or something similar. |
|
alias |
Output terminals can also have an alias attribute, defining an additional host name under which the remote side of the connection is known (in addition to the terminal name itself, which is always added to the hosts file). |
This entity type is used to enable and configure network interfaces that are not meant for connecting to other components (as the terminals are - see previous section) and have no restrictions on the type of connections that can be made.
The syntax for the interface entity is as follows:
interface <name>
Any number of interface name definitions can be found in the component descriptor. The names must be unique in the scope of the component. The name space for interfaces is shared with that for terminals. You cannot have an input/output and an interface with the same name.
The interface entity supports multiple interface and mandatory attributes.
In versions of CA AppLogic prior to 3.5, you could use the following construct:
interface default
In CA AppLogic 3.5 and later, this construct is accepted for backward compatibility, but you cannot use the name 'default' for an actual raw interface. Using the name 'default' for an input or output terminal results in an error.
The property entity defines a configurable property of the component. Any parameter that may need to be configured can be defined as a property. The values of properties are made available to the component's software in the following ways:
Note: Because a volume can appear as a configurable property on the boundary, volumes and properties share namespace and one cannot define both a volume and a property of the same name.
The property entity has the following attributes:
|
type= |
Defines the property type, the value of this attribute must be one of: string, integer, ip_addr, or IP_owned. If the type= attribute is not specified, string is assumed. Note: The 'IP_owned' type is the same as 'ip_addr' - it holds an ipv4 or ipv6 address. Using 'IP_owned instead of 'ip_addr' indicates that the address is one that will be assigned to the component itself (that is, the component's IP subsystem will answer to this address). Addresses that aren't owned by the application, but to which the application is supposed to connect (as external services) should have the 'ip_addr' type. A property of type 'IP_owned' is subject to verification prior to application start. If the given value is not within the range allowed for use by the applications on the grid, application start will be refused. Existing appliances that were created prior to adding the 'IP_owned' type (and therefore use 'ip_addr') will operate normally, but will not benefit from the start-time check of the configured IP address(es). If they are set up with incorrect addresses, they will simply fail to operate when started (network packets with an IP address that is "foreign" to the grid will be dropped before they reach the appliance, even if the appliance's OS is configured to answer to that address). |
|
filter= |
A regular expression defining the set of valid values for the property. The expression must be coded in the syntax defined by Perl for regular expression pattern matching. The match is done on the entire property value - that is as if /^expression$/ was used in a Perl statement to check for a match (where expression is the value of the filter attribute. |
|
values= |
This attribute can be used as an alternative to the filter= attribute. It is treated exactly as the filter attribute by the ADL compiler, except that the use of values= expr instead of filter= expr is a hint to the GUI editor that the regular expression is a simple concatenation of strings to be matched, in the normal regular expression form string1!string2!... and so on. This can be used to display a drop-down list of values in a property sheet instead of a free-text edit box. |
|
min= |
Minimum and maximum values for an integer property. If the specified property type is integer, these optional attributes specify the limits of valid values. They are applied in addition to any regular expression pattern specified by the filter= attribute. |
|
mandatory |
If present, this attribute indicates a property with no default value. When the component is used in an assembly, a value for the property must be supplied in the assembly or it must be redirected to the assembly boundary; in the latter case, the corresponding property of the assembly also takes on the mandatory attribute. |
|
dflt= |
Specifies a default value for the property. This attribute cannot be used together with mandatory. |
|
lowercase |
Indicates that the property value is to be converted to lowercase before it is used to configure the component. This should be used for properties that need to appear as case-insensitive to the user, but provide the component a consistent value that can be compared using case-sensitive compare. The lowercase conversion is done in the C locale. |
Defines the configuration files that need to be checked for property markup and updated accordingly. This entity is an array, each entry defines one configuration file and has these attributes:
vol - Names the volume on which the file is located (this should match one of the component's volumes, as defined by the volume entities). A value for this attribute must be specified for each cfgfiles array element.
path - This is the file name of the configuration file, relative to the volume on which it is located. This may be different from the path where the application sees that file - depending on how the particular volume is mounted by the component. A value for this attribute must be specified for each cfgfiles array element.
quoting - Defines the method for quoting meta-characters in the configuration file. A meta-character is any character that has a special meaning in the config file and must be quoted (or escaped) in some manner to appear as a data character and not in its special-function role. The quoting attribute can be set to one of the following strings:
Note: the cfgfiles sub-entity is useful only when .config_mode is set to volfix. In the dhcp mode, the component's boot volume will not be modified and it is expected to configure itself dynamically over the network.
This entity contains the boot information needed to start the component in the virtual environment for which it is designed. The virtualization entity supersedes the kernel/os_info definitions and should be used instead of them. The presence of this entity also indicates a new-style component descriptor and turns off the compatibility mode, which includes forced .config_mode=volfix.
The following attributes are defined for the virtualization entity:
|
modes= string |
Defines the component's virtual environment. Valid values are paravirt (for components that have a para-virtualized kernel supported by the host system) and hvm (for components designed to run directly on hardware and require hardware-assisted virtualization if ran in a virtual machine). The value of this attribute is a comma-separated list of virtual machine manager identifiers that this component can use. The supported VMMs may vary with the CA AppLogic version. The following are VMM names supported in version 3.0 or higher:
For compatibility with component classes created prior to version 3.0, the former 'mode' attribute is also supported (it is simply an alias of 'modes'). In addition, the old mode names are supported and translated as follows:
|
|
options= string |
Arguments to pass to the bootloader. If mode=paravirt, the string is passed to the component's kernel command line, and may be available to the code running in the component's virtual environment, if the component's OS kernel supports that. |
|
path= filename or |
The name of the kernel image file, relative to the boot volume's root directory. This attribute is meaningful only if mode=paravirt and is ignored otherwise. If path is not set, it is assumed that the component has the GRUB bootloader installed and its configuration file contains the correct location of the kernel image and the initial ramdisk, if one is used. |
|
initrd= filename |
The name of the ramdisk filesystem image to use during boot. This attribute is meaningful only if mode=paravirt and is ignored otherwise. initrd is ignored if path is not set (in this case the names of both files are looked up in the GRUB configuration file found on the component's boot volume). |
|
device_schema= string |
This is used to store the disk device naming convention, as used by the component's OS. The format of this string is not part of ADL: The device_schema attribute is reserved for use by the CA AppLogic infrastructure editor. See the Class Editor Property Sheet Quick Reference. |
This entity is obsolete, use virtualization instead. The presence of a kernel or os_info sub-entity in the descriptor indicates an old descriptor and the volfix configuration mode is forced automatically.
This entity contains OS-specific boot information, its contents depend on the value of the .os_type attribute of the component. The keywords kernel and os_info are equivalent, kernel is retained for backward compatibility.
When .os_type=linux , the following attributes are defined for the os_info entity:
path= filename - the name of the kernel image file, relative to the boot volume's root directory.
initrd= filename - the name of the ramdisk filesystem image to use during boot. The kernel image file and the ramdisk image file are typically produced as a result of building the Linux kernel.
options= "string" - other arguments to pass to the bootloader's kernel command line.
When .os_type=legacy, the following attributes are defined:
options=" name=value name=value ... "
The legacy OS type is used for all hardware-assisted virtual machines. The name=value pairs are not interpreted, they are passed on to the HVM emulator directly. Examples of parameters supported by the qemu emulator (used in Xen) include: acpi=(0!1), apic=(0!1), pae=(0!1), and so on.
|
Copyright © 2013 CA Technologies.
All rights reserved.
|
|