Install or Upgrade Product Installations with Composite Templates
After you complete the steps in this topic, you will have a set of Software AG products installed on several remote machines. You can use the steps to install fresh installations or upgrade existing installations to a higher release version. The products in the fresh or upgraded installations will have product instances, which are configured with the settings you define in the composite template(s).
Use composite templates when you want to provision large product environments (with lots of installations) in which you have:
Custom adjustments that are not standard across the product installations
Product configurations that are not managed through
Command CentralLevel of Difficulty
High. Composite templates are a complex topic that requires significant experience with the webMethods suite. They represent infrastructure as code, but require knowledge on how the products interact and work together. With that in mind, the composite templates are a powerful tool that can automate a huge number of tasks over a big deployment.
Prepare for the Install or Upgrade with Composite Templates
It takes some time to learn and become productive with composite templates. If you have DevOps experience, that will help you progress faster.
Install and configure
Command Central as described in the
Software AG Command Central Help.
Make sure you have valid license keys for the
Software AG products that you include in the composite templates.
When installing products, check
Installing Software AG Products for any product-specific requirements.
When upgrading products, follow the instructions in
Upgrading Software AG Products On Premises to prepare the existing installations for the upgrade.
Download the
Command Central bootstrap installer (for the release version of the fresh installation or the target upgrade version) and save the downloaded
Command Central bootstrap installer file into the $CC_HOME/profiles/CCE/data/installers directory. You can then add this bootstrap installer in the “nodes:” section of the composite templates.
Step 1: Set up Repositories
The repositories are the source of the product or fix installation files. You can connect to the Software AG repositories (hosted on Empower and added in Command Central as master repositories), create a local copy of the Empower repositories (added as mirror repositories), or use a product or fix image (created by the Software AG Installer or Software AG Update Manager and added as an image repository). Command Central will use the repositories to install the products and apply the fixes available for those products.
2. Set up the repository credentials:
3. Add the repositories:
Step 2: Import the Product License Keys in Command Central
Import the license keys for the products that you want to install (or upgrade) and assign an alias to each license key:
Import Product License Keys for Instances or Components and
sagcc add license-tools keys.
Step 3: Configure the SSH Connection to Each Remote Machine
Check if the UNIX or Windows operating system on the remote machine has a Secure Shell (SSH) server running or WinRM support (for Windows only). Also, make sure that the system is configured for remote access with the user account for the Software AG products.
Step 4: Prepare the Composite Template
You can design and develop composite templates from the default templates in the
sagdevops-templates project or from templates generated from existing installations (
sagcc exec templates composite generate). You can also design and develop custom templates on your own.
1. Choose how to design the composite templates.
Design Templates by Product
Typically, in a Software AG installation you have base products (such as Integration Server) and products that depend on the base products (such as Trading Networks). You have the following options:
Create a composite template for the base product(s) in the installation and define different environments in the template. For example, create one composite template for
Integration Server (IS) and another composite template for
Universal Messaging (UM). In the IS composite template, define an environment type for each IS installation that you want to create. For example, define one environment type for IS with the
Adapter for JDBC, and another environment type for IS with
Trading Networks.
Pros: With this approach, it is easier to run an installation or upgrade, because the order in which the products get installed and configured is handled inside the template.
Cons: The composite template(s) could get long and complex, which makes them harder to maintain.
Create one composite template for the base product and another template for the dependent products. For example, create one template for IS and a separate template for
Trading Networks (TN). When applying the templates, apply the IS template first and the TN template second.
Pros: The composite templates are smaller and not so complex, which makes them easier to read and maintain.
Cons: When applying the composite templates, you should follow specific steps, such as the specific order, in which to apply the templates. This approach leaves you open to errors.
Design Templates by Goal
You can design the composite templates around the intended goal of the template (provisioning or upgrade). The supported upgrade method will also influence the template design. The following list gives you the recommended design options with their pros and cons.
Create one composite template for provisioning and upgrade. This option is recommended when running cross-host upgrade.
Pros: All the data is in one template and you do not have duplicate sections and properties in the template.
Cons: The result is a very long template with data that is not required when using the composite template for upgrade.
Create two composite templates: one template contains the product and the other template contains the product configurations. Use both templates for provisioning: apply the product template first and the product configuration template second. When running a same host (overinstall or side-by-side) upgrade, use only the product template.
Pros: The product template has only the data you require for the upgrade.
Cons: You have some duplicate sections and properties across the two templates. To prevent the product from starting during the execution of the product template, you must set the parameters in the “options:” section of the product template. See
Options.
Note that if you use two composite templates (base and configuration) for cross-host migration, the base product template should include the configurations that change the host names.
2. Write the composite templates.
Use the following topics as reference when writing the template YAML file:
Step 5: Prepare the property files to use with the composite template(s)
Create one or more property files with the values for the input parameters defined in the "environments:env.type:" section of the composite template(s). Property files help you specify different values for the different environments (defined in a template) without editing the template YAML file directly.
Step 6: Apply the Composite Templates
Import the composite templates in
Command Central with the
sagcc exec templates composite import CLI command or from the Templates view in the web user interface.
If you have more than one composite template, apply each template in turn with the
sagcc exec templates composite apply CLI command. The order of applying the templates should go:
1. Base product templates
2. Dependent product templates
3. Product configuration templates
Command Central automatically validates a template after you run the apply composite templates command:
Validating a Composite Template.
Step 7: Monitor and Troubleshoot the Template Application
Use the Jobs view in the
Command Central web user interface to monitor the status of the template apply job and access the logs:
Correcting a Failed Composite Template Apply Operation.