Skip to content

Template requirements and guidelines

Sergei Pogrebnyak edited this page Dec 21, 2018 · 3 revisions

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}