Using Parameters for Customization

You want to develop templates that can be used to provision multiple environment instances in dev, test and production.

Different environments will have to run on different hosts, use different resources, servers, and services. Such differences can be accounted for by designing flexible templates that use variables which can be set as input parameters at the time of template application.

1. Open templates/tutorial/template.yaml in the text editor and modify version: to be 0.2 to denote the change we're making
2. Add new changes: list and add a note about introduction of input parameters

alias: tutorial
description: How to add parameters
version: 0.2
changes:
  - Added input parameters

Parameters Definition

Parameters are optional but essential for designing flexible and reusable templates

1. Add environments: section with default: subsection where we can add our variables that can be controlled via input parameters
2. Add name and greeting variables as the following:

alias: tutorial
description: How to add parameters
version: 0.2
changes:
  - Added input parameters
   
environments:
  default:                     # global defaults defined here
    foo: bar                   # basic variable with default value
    name: ${}                  # required parameter, must be provided by the client
    greeting: "Hello ${name}!" # parameter value can reference other parameters

NOTES:

1. To improve usability always try to provide sensible default values for defined variables. This way the user does not have to specify the value unless he/she wants to overwrite the default. foo variable with default value bar is an example of that.
2. Variable values can reference other variable values using ${otherVarName}. Example of that is greeting variable using name variable.
3. If the default value is not possible and you want the user to provide the value at the template execution time then the variable value must use this special value of ${}

Applying Template with Parameters

Run ant up command to apply the template:

[user@linuxbox tutorial]$ ant up
...
 
BUILD FAILED
/home/user/Tutorial/tutorial/antcc/lib/sagenv.xml:86: The following error occurred while executing this line:
/home/user/Tutorial/tutorial/antcc/lib/sagenv.xml:88: The following error occurred while executing this line:
/home/user/Tutorial/tutorial/antcc/lib/sagenv.xml:76: The following error occurred while executing this line:
/home/user/Tutorial/tutorial/antcc/lib/sagenv.xml:138: Job execution failed with 'ERROR' status: [SPMCOME0007] Un-handled internal server error. There are unresolved variables in the provided properties: [name, greeting] >> RuntimeException: There are unresolved variables in the provided properties: [name, greeting]

The error indicates the names of the variables that could not be resolved: both name and greeting. To resolve this problem you need to provide either both variable values or if you know that you really need to provide only name and the greeting default value will allow to resolve it using name, you can provide only name.

The input parameter values are specified as simple name=value pairs in the environment/default/env.properties.

Open the file add the following line

name=foo

Apply the template:

[user@linuxbox tutorial]$ ant up
Buildfile: /home/user/Tutorial/tutorial/build.xml
 
apply:
       [cc] REST: POST http://linuxbox.user:8090/cce/templates/composite/apply/tutorial {includeHeaders=[false], properties=[id]}
       [cc] REST: GET http://linuxbox.user:8090/cce/jobmanager/jobs/84 {includeHeaders=[false]}
       [cc] 84  0   DONE    100 Applying template tutorial  Finished applying template tutorial.    DONE        http://linuxbox.user:8090/cce/diagnostics/logs/local/OSGI-CCE/default.log/full?includeHeaders=false&regex=.%2A%3FVLD28132806.%2A    ValidateCompositeTemplateJob:default.log    
       [cc] The expected values were successfully retrieved after 1 call within 1 second.
 
_jobresult:
       [cc] REST: GET http://linuxbox.user:8090/cce/jobmanager/jobs/84 {includeHeaders=[false], properties=[status]}
       [cc] REST: GET http://linuxbox.user:8090/cce/jobmanager/jobs/84 {includeHeaders=[false], properties=[statusAsString]}
 
BUILD SUCCESSFUL
Total time: 3 seconds

If you have not achieved the goals of this tutorial stage, use the following command to checkout everything that needed to be done so far:

[user@linuxbox tutorial]$ git checkout stage-02a -f
Switched to branch 'stage-02a'

Environment Types

It often makes sense to have different defaults for different environment types. An environment type is just a concept that is easy to understand if you take dev, test and production environment types, but you can come up with different types of environments in your design. Command Central allows you to control variables definition and resolution based on specified environment type. This is how it works.

Open templates/tutorial/template.yaml in the editor and add additional dev and test environment types with new variables as shown below.

alias: tutorial
description: How to add parameters
version: 0.2
changes:
  - Added input parameters
   
environments:
  default:                     # global defaults
    foo: bar                   # basic variable with default value
    name: ${}                  # required parameter, must be provided by the client
    greeting: "Hello ${name}!" # parameter can reference other parameters
  dev:                         # parameters for environment.type=dev
    hello: Hi                  # new default value for existing parameter
    name: Developer            # default value for previously required parameter
  test:                        # parameters for environment.type=test
    hello: ${}                 # now hello parameter is required
    prev.name: Developer       # new optional parameter
    greeting: "Goodbye ${prev.name}, ${hello}, ${name}!!!" # different default

Edit environment/default/env.properties and add the following lines:

#default
name=foo
 
#dev
#environment.type=dev
 
#test
#environment.type=test
#hello=foo
#name=bar

When no environment.type variable is not explicitly specified then it will to the value of default. If you want to choose a different environment type, uncomment the respective environment.type=* line. Experiment with the different environment types and observe which variables will get resolved.

Apply the template. If the variables are not resolved the run will fail:

[user@linuxbox tutorial]$ ant up
Buildfile: /home/user/Tutorial/tutorial/build.xml
 
BUILD FAILED
/home/user/Tutorial/tutorial/antcc/lib/sagenv.xml:86: The following error occurred while executing this line:
/home/user/Tutorial/tutorial/antcc/lib/sagenv.xml:88: The following error occurred while executing this line:
/home/user/Tutorial/tutorial/antcc/lib/sagenv.xml:76: The following error occurred while executing this line:
/home/user/Tutorial/tutorial/antcc/lib/sagenv.xml:138: Job execution failed with 'ERROR' status: [SPMCOME0007] Un-handled internal server error. There are unresolved variables in the provided properties: [name, greeting, hello] >> RuntimeException: There are unresolved variables in the provided properties: [name, greeting, hello]
 
Total time: 3 seconds

Experiment with the different environment.type values and rerun the template using ant up command.

NOTES:

1. Specialized environment type can overwrite defaults defined in the default environment section
2. Specialized environment type can add new variables with or without default values
3. All default section variables are still available for specialized environment type

Refer to Command Central Documentation for more details on parameters resolution logic.

If you have not achieved the goals of this tutorial stage, use the following command to checkout everything that needed to be done so far:

[user@linuxbox tutorial]$ git checkout stage-02b -f
Switched to branch 'stage-02b'

Environment Instance Configuration

You want to capture your environment instance configuration input parameters into a file that can be placed under version control.

1. Under the environments folder create a new subfolder called test1 and then an env.properties file in this folder. Add the following lines of the environment/test1/env.properties file:

# Test1
environment.type=test
hello=foo1
name=bar1

2. Create environment/test2/env.properties with the following content:

# Test2
environment.type=test
hello=foo2
name=bar2

3. Apply template to provision environment instances test1 and test2 using their instance configuration files:

[user@linuxbox tutorial]$ ant up -Denv=test1
...
BUILD SUCCESSFUL
Total time: 3 seconds

[user@linuxbox tutorial]$ ant up -Denv=test2
...
BUILD SUCCESSFUL
Total time: 3 seconds

If you have not achieved the goals of this tutorial stage, use the following command to checkout everything that needed to be done so far:

[user@linuxbox tutorial]$ git checkout stage-02c -f
Switched to branch 'stage-02c'

Summary

Congratulations! You have successfully developed a template that supports customization via parameters for different environment types. You also defined two environment instance configurations.