run” in an environment that contains everything the application needs,
but not more than necessary. The template will be deployed multiple
times and you will want to configure each deployed instance to give it a
personality and perhaps connect it with other components running
elsewhere. For this to work, you will need to understand the configuration
aspects of the application well. You might need a script that does some
or all of the configuration of the application once the template has
been deployed and the domain boots for the first time. Any
configuration not done by such a script will need to be done manually by
the user of the template after the domain has booted. It is usually
desirable to create templates in such a way that no further manual
configuration is required. I’ll not cover how to create such first-boot scripts here.
(Note: This article is the blog version of the second part of MOS DocID 2063739.1 reproduced here for convenient access.)
Here are the steps usually required to build a template:
- Create a new domain and install Solaris and the ovmt utilities.
- Define what properties will be needed to configure the application.
- Install and configure the application as much as possible.
- Write and test a first-boot script or SMF service that will read the
values for these properties using the ovmt utilities and configures the
application. - Unconfigure Solaris in your domain and remove any temporary files, then and shut it down.
- Create the template.
- Test your template. Go back to any of the previous steps to fix issues you find.
Before we look at each of these steps using an example, here is a little background about how properties work in this context.
Properties for Your Template
Most applications require some sort of configuration before they are ready. Typical configuration items might be TCP ports on which to listen for requests, admin passwords for a web user interface or the IP address of a central administration server for that application. These are usually set during manual installation of the application. Since the whole idea of an application template is that once you deploy it, the application is ready to run, there needs to be a way to pass these configuration items to the application during template deployment. This is where properties come in. Any configuration item that must be passed to the application at deployment time is defined as a property of the template. This happens in a properties definition file that is bundled with the actual OS image to build the template. Note that this file only contains the definition of these properties, not their values! Properties are populated with values at deployment time.
You have already seen an example of how to pass such values to a template during deployment in the first part of this mini-series, when Solaris properties were passed to the template.
Properties are defined in a small XML file, as they themselves have various properties. They have a name, which can be fully qualified or simple. They have a data type, like number, text, selection lists etc. These are covered in detail in the Template Authoring Guide. For the simple example in this article, we will use text properties only.
During deployment, you pass values for these properties to the target domain using the ovmtconfig utility. It will use one of two methods to pass these values to the domain. The more complex method is backmounting the target domain’s disk images to the control domain and then running a script which will put configuration items right into the filesystem of the target domain. This is how a Solaris AI profile is constructed and passed to the domain for first-boot configuration of Solaris itself. The other method currently uses VM variables to pass properties and their values to the domain. These can then be read at first boot using the ovmtprop utility. This is why the ovmt utilities should be installed in the template. In the example below, you will see how this is done.
Creating a Source Domain
The first step in developing a template is to create a source
domain. This is where you will install your application, configure it
as much as possible and test the first-boot script which will do the
rest of the configuration based on the template property values passed
during deployment. Here are a few hints and recommendations for this
step:
- Use a standalone SPARC sun4v system to build your template. Do not
attempt to build a template on SuperCluster – this is not supported. - Create a simple domain:
- Use only one network adapter if possible. This makes it easier to deploy the template in many different environments.
- Use only one disk image for the OS. Keep it small. Unnecessarily
large disk images will make it more difficult to transport and deploy
the template. - If required, you can use one or more additional disk images for the
application. Separating it from the OS is often a good idea. - Define CPU and memory resources only as needed. They can always be increased after deployment if necessary.
- Install only those OS packages required by your application. You
might want to start with “solaris-minimal-server” and then add any
packages required.
- You must use flat files for all disk images. A later version of the utilities will also support other disk backends.
- All your disk image files must have a filename ending in “.img”.
While this is not a restriction for general use, it is currently a
requirement if you intend to deploy your template on SuperCluster.
- Use a sensible name for the disk images, as they are used in the volume descriptions within the template.
- To speed up testing (create and deploy cycles) it is helpful to
install pigz, a parallel implementation of gzip. If present, it will be
used to speed up compression and decompression of the disk images. - As you will most likely be using ovmtprop to read properties for
your application, don’t forget to install the ovmtutilities into the
domain. - Apply all required configurations to make the application ready to
run. If this includes adding users, file systems, system configurations
etc. to the domain, then do that. All of these will be preserved
during template creation. - Note that system properties like IP addresses, root passwords, timezone information etc. will not be preserved.
Defining the Properties
What properties you need in your template depends on your application. So of course you should understand how to install and configure the application before you start building the template. Here is an example for a very very simple application: An Apache webserver that shows a plain text page displaying the properties passed to the domain. In this example, there are three properties defined in the properties file: property1, property2 and property3. Here is the full XML file defining these properties:
<ovf:ProductSection ovf:class="com.oracle.supercluster.client">
<ovf:Product>Oracle SuperCluster</ovf:Product>
<ovf:Category>OVM Templates</ovf:Category>
<ovf:Version>1</ovf:Version>
<ovf:Property ovf:key="property1" ovf:type="string"
ovf:userConfigurable="true" ovf:value="Value1">
<ovf:Description>Specifies property 1</ovf:Description>
</ovf:Property>
<ovf:Property ovf:key="property2" ovf:type="string"
ovf:userConfigurable="true" ovf:value="Value2">
<ovf:Description>Specifies property 2</ovf:Description>
</ovf:Property>
<ovf:Property ovf:key="property3" ovf:type="string"
ovf:userConfigurable="true" ovf:value="Value3">
<ovf:Description>Specifies property 3</ovf:Description>
</ovf:Property>
</ovf:ProductSection>
This
file will be bundled with the template when you create the template.
Note that although there are values defined in this file, these values
are not passed to the target domain during deployment! A detailed
description of all the options for template properties will be available
in the Template Authoring Guide, which is currently being written.
Installing and Configuring the Application
Again, this step very much depends on the application you intend for
your template. In this simple example, there is very little to do.
Note that this step also shows a very simple first-boot script which
does the configuration of the application:
root@source:~# pkg install ovmtutils
root@source:~# pkg install apache22
root@source:~# svcadm enable apache22
root@source:~# more /etc/rc3.d/S99template-demo
#!/bin/sh
# simplest of all first-boot scripts
# just for demo purposes
OUTFILE=/var/apache2/2.2/htdocs/index.html
OVMTPROP=/opt/ovmtutils/bin/ovmtprop
BASEKEY=com.oracle.supercluster.client.property
if [ ! -f $OUTFILE ]
then
cat >>$OUTFILE << EOF
<html><body>
<h1>OVM Template Demo</h1>
EOF
for i in 1 2 3
do
$OVMTPROP -q get-prop -k $BASEKEY$i >> $OUTFILE
echo "</br>" >> $OUTFILE
done
cat >>$OUTFILE << EOF
</body></html>
EOF
fi
After
you have completed the installation and are happy with how the
first-boot scripts work, the final step is to unconfigure Solaris. You
do this using the command “sysconfig unconfigure –destructive
–include-site-profile”. This removes system identity like hostname, IP
addresses, time zones and also root passwords from the system. It is
necessary so that after deployment, a new system identity can be passed
to the target domain. You might also want to remove other files like
ssh keys, temp files in /var/tmp etc. which were created during
configuration and testing but should not be left in the template.
Creating the Template
After all the preparations are complete, creating the actual template
is a very simple step. You only need to call ovmtcreate, which will
collect all the pieces and assemble the OVF container for you.
root@mars:~# ovmtcreate -d source -o /templates/apache-template.ova \
-s "OVM S11.2 SPARC Apache 2.2 Demo" \
-P /development/apache-template.properties.xml
This will collect all the disk images attached to the source domain as well as the property definition file and package them in OVF format. This file can now be transferred to any target system and deployed there. With the “-s” flag, a descriptive name is given to the template. This name can be used to identify the template. For example, it will be displayed in the library of templates available in SuperCluster.
To complete the example workflow, deployment and configuration with the three custom properties for the sample Apache configuration is shown next.
Deploying Your Template on a Standalone Server with Custom Properties
To prepare for deployment, you will need a small file containing values for the three custom properties defined above:
root@mars:~# cat custom.values
com.oracle.supercluster.client.property1=Value1
com.oracle.supercluster.client.property2=Value2
com.oracle.supercluster.client.property3=Value3
Of course, Solaris itself will also need some configuration. You have already seen this in Part 1. This example will simply reuse that configuration.
To deploy and configure the target domain, you now only need two simple commands:
root@mars:~# ovmtdeploy -d target -o /domains \
-s /templates/apache-template.ova
root@mars:~# ovmtconfig -d target \
-c /opt/ovmtutils/share/scripts/ovmt_s11_scprofile.sh \
-P solaris_11.props.values,custom.values
After
starting the domain, you should be able to point your browser to port
80 and see the simple html page created by the first-boot script.
Additional Notes
- You can check the properties passed to a domain from the control
domain. They are passed as normal VM variables, so the command “ldm
ls-variable <domain>” will display them. Note that this also
means that any sensitive information passed to a domain in this way will
be visible to anyone on the control domain with privileges to execute
the ldm command. The same information is also available to any user
logged into the target domain, as any user has read access to the
ovmtprop utility. So while this is a nice way to check if the right
variables have been passed to the target domain during testing, you
should not use template properties to pass clear text passwords or other
sensitive information to the domain. Use encrypted password strings
instead, if possible. If the application requires clear text sensitive
information, you should at least remove these variables after the target
domain is in production. Use the command “ldm rm-variable” to do so.
Triggering a change of passwords after first login is also a good idea. - In general, OVM Templates support Solaris Zones. This means you can
create a template domain that contains one or more Zones as part of the
template. However, you will need to care for the configuration (IP
addresses, hostnames, etc) of each zone as part of the first-boot
configuration, as this is not covered by the Solaris configuration
utilities. Also note that templates containing Zones are currently not
supported on SuperCluster.
For additional and background reading, please refer to the links I provided at the end of the first article in this mini-series.