Template requirements and guidelines

Requirements for each template.yaml

• Alias MUST start with sag-<product>
• MUST have a short description:
• MUST have only one environments/default section
• ALL parameters MUST be declared in the environments/default section
• Parameters MUST have sensible default values whenever possible
• SHOULD parameterize only what is necessary. Avoid too many parameters
• The following parameters SHOULD be declared, as they are not yet provided by the Stacks API
  • release.major: 10
• The following parameters are provided by the Stacks API. You do not need to declare them, but they MUST be provided when the template is executed as a standalone composite template outside of the Stacks API context
  • release
  • repo.product
  • repo.fix
  • nodes
  • os.platform
• All product-specific parameters MUST:
  • Start with a unique prefix
  • Have a comment on the same line or above starting with #
  • License key parameter
    • Name pattern: <prefix>.<productid>.license.key
    • Value wildcard: "*_<PRODUCTCODE>_${release.major}.*_*_${os.platform}"
  • Instance name parameter
    • Name ends with : .instance.name
    • Value: default
  • Credentials key parameter
    • Name ends with: .credentials.key
    • Value DEFAULT_ADMINISTRATOR or ${}
  • Port number parameter
    • Name ends with .port
    • Value must be a <number>
  • Fix list parameter
    • Name: ends with .fixes
    • Value must be: ALL
• SHOULD define only one runtime layer. It MAY have one additional db layer
• MUST define exactly one runtime instance
• MUST include minimal required configuration
• SHOULD include additional, optional configuration as *-config inline template that can be easily activated
• SHOULD include comments (#) for all lines/properties that are not self-explanatory
• SHOULD use 2 spaces for indentation

Example

alias: sag-myprod-server
description: My product standalone server
 
dslVersion: "1.1"
version: "1.0"
environments:
  default:
    release.major: 10                                                   # release major version number
    os.platform:   ${}                                                  # OS platform code: w64|lnxamd64|osx
 
    myprod.myproductid.license.key: "*_MYP_${release.major}.*_*_${os.platform}" # License key to use
    myprod.fixes: ALL                                                   # Fixes to install. ALL by default
    myprod.patches: []                                                  # Support patches to install. None by default
    myprod.instance.name: default                                       # Instance name
    myprod.http.port:  1234                                             # HTTP port number
    myprod.https.port: 1235                                             # HTTPS port number
    myprod.credentials: DEFAULT_ADMINISTRATOR                           # Administrator credentials
    myprod.memory.init: 128                                             # Minimum MB to run
    myprod.memory.max:  256                                             # Maximum MB to run
    myprod.foo:         bar                                             # foo configuration property
 
layers:
  runtime:                                                              # Main runtime layer
    productRepo: ${repo.product}                                        # Product repository to install from
    fixRepo:     ${repo.fix}                                            # Fix repository to install from
    templates:
      - myprod-server                                                   # Required template
      # - myprod-config                                                 # Optional configurations
 
templates:
  myprod-server:
    description: |
      Install, patch My Product, create, update or migrate instance
      and most critical configuration
    licenses:
      "MyProduct/licenseKey.xml": ${myprod.myproductid.license.key}     # Copy license file for My Product
    fixes: ${myprod.fixes}                                              # Install My Product fixes
    patches: []                                                         # Install support patches, none by default
    products:                                                           # Install products
      myProductOptionalComponentId:                                     # My Product | Optional Component
      myMainProductId:                                                  # My Product | Server
        ${myprod.instance.name}:                                        # Create, update or migrate main run-time instance
          http.port:    ${myprod.http.port}                             # HTTP port for new instance
          https.port:   ${myprod.https.port}                            # HTTPS port for for new instance
          license.file: MyProduct/licenseKey.xml                        # License key file
          # other.param: value
           
          configuration:                                                # Run-time instance config for create/update and after migration
            MYP-${instance.name}:                                       # Run-time instance id
              COMMON-MEMORY:                                            # JVM memory configuration type
                COMMON-MEMORY:                                          # JVM memory configuration instance
                  InitSize: ${myprod.memory.init}                       # Initial memory
                  MaxSize:  ${myprod.memory.max}                        # Maximum memory
            MyP-${instance.name}                                        # Instance component
              COMMON-SYSPRPOS:                                          # Generic tuneup properties
                COMMON-SYSPROPS-CATEGORY1: |                            # Configuration instance for Category1
                  VeryImportantProperty: ${myprod.foo}                  # Property that is very important
             
  myprod-config:
    description: Additional and optional configurations
    products:
      myMainProductId:                                                  # My Product | Server
        ${myprod.instance.name}:                                        # Update main run-time instance
            MyP-${instance.name}                                        # Instance component
              COMMON-SYSPRPOS:                                          # Generic tuneup properties
                COMMON-SYSPROPS-CATEGORY2: |                            # Configuration instance for Category2
                  NotVeryImportantProperty: exampleValue                # This property controls foo
                  AnotherProperty: "someValue"                          # This property controls bar
 
provision:
  default:
    runtime: ${nodes}