Command Central 10.11 | Common Use Cases with Command Central | Install or Upgrade Product Installations with Composite Templates
 
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 Central
Level 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.
*Check the Software AG Command Central Supported Features Matrix for the supported product configuration and migration types.
*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.
1. Choose a repository setup that works for you: Understanding Product and Fix Repositories.
2. Set up the repository credentials:
* Create Credentials Aliases (the web user interface)
*"COMMON-CREDENTIALS Usage Notes" in Configuration Types for Command Central and Platform Manager OSGI ENGINE (the command line interface)
3. Add the repositories:
* Connect to Software AG Repositories; Create, Refresh, or Change Sources for a Mirror Repository of Products or Fixes (the web user interface)
* sagcc add repository products; sagcc add repository fixes (the command line interface)
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.
*Set up the connection to the remote machine and the credentials alias for the SSH user: Bootstrapping Platform Manager Using the Default SSH and WinRM Templates; "COMMON-CREDENTIALS Usage Notes" in Configuration Types for Command Central and Platform Manager OSGI ENGINE
*Optional. Configure a substitute user: Bootstrapping on a Remote Machine with a Substitute User
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:
* Understanding the Composite Template Definition
*"How Command Central Processes a Composite Template" 10.3 or higher; 10.1 or lower
*Optional. Add a database layer in the product composite template: Managing Database Components Using a Template
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.