Stitch macros

Stitch macros are reusable building blocks which group the common processors used inside of Stitch rules. Macros are defined in Stitch YAML files by setting the kind property to Macros, for example:

kind: Macros
metadata:
  namespace: k8s-add-labels
spec:
  - name: "k8s.MacroAddLabels"
    description: This is a macro for adding labels
    parameters:
      application: default-application-name
      const: default-value
    processor:
      - type: freemarker
        description: "Adding app and env label"
        parameters:
          templateFile: templates/label-macro.ftl

From the rule perspective, macros act like a processor and are called by using one of following syntax as a processor type:

namespaceName:macroName - will look for macro by namespace name and macro name

macroName - will look for a macro by name in the namespace from namespace in which the rule was defined

kind: Rules
metadata:
namespace: k8s-add-labels-rule
spec:
- name: "k8s.AddLastLabel"
condition:
  deployedType: k8s.Resources
processor:
  - type: "k8s-add-labels:k8s.MacroAddLabels" #Use macro and namespace names defined in previous code snippet
    description: "Adding last label to kubernetes spec by using macro"
    phase: POST_FLIGHT
    merge:
      type: overlay

Macro properties

Property	Description
kind (required)	Kind of stitch definition. To define a macro kind, the value has to be set to `Macros`
metadata (required)	The object which contains the macro metadata
spec (required)	List of macro specifications

Metadata

Property	Description
namespace (required)	Namespace inside which the macro will be stored.

Spec

Property	Description
name (required)	The name of the macro used to call the macro from the rules. The name should be unique inside of a namespace
description (optional)	Optional macro description
parameters (optional)	Default parameters which are passed to the processor. Parameters can be overwritten from rules by defining processor parameters.
processor (required)	See processor documentation

Passing parameters to macro

Similar to rule processor variables, when a macro is used as a rule processor it can accept different parameters. A parameter value can be assigned using SpEL.

kind: Rules
metadata:
  namespace: common-k8s-rules
spec:
  - name: "k8s.AppAndEnvLabelsRule"
    condition:
      deployedType: k8s.Resources
    processor:
      - type: "k8s.AppAndEnvLabels" # macro ‘k8s.AppAndEnvLabels’ is used as a processor
        decription: "Adding freemarker macro"
        parameters:
          application: "#{#ctx.getDeployedApplication().getName()}"
          environment: "#{#ctx.getDeployedApplication().getEnvironment().getName()}"

Inside a macro, parameters are stored in the params object, or by implicitly using the params object.

** Storing parameters in the params object ** As shown in the example below, in a freemarker processor, it is possible to access these parameters by explicitly assigning them to processor variables using SpEL.

kind: Macros
metadata:
  namespace: common-k8s-tasks
spec:
  - name: "k8s.AppAndEnvLabels"
    description: This is a macro for adding labels
    parameters:
      application: undefined
      environment: undefined
    processor:
      - type: freemarker
        description: "Adding app and env label to kubernetes spec"      
        parameters:
          template: |
            { "metadata" : {
              "labels": {
                "application": "${application}",
                    "environment": "${environment}",
              }
             }
            }
        variables:
          application: "#{#params['application']}"
          environment: "#{#params['environment']}"

** Whereas in the following example, parameters are accessed implicitly using the params object **

kind: Macros
metadata:
  namespace: common-k8s-tasks
spec:
  - name: "k8s.AppAndEnvLabels"
    description: This is a macro for adding labels
    parameters:
      application: undefined
      environment: undefined
    processor:
      - type: freemarker
        description: "Adding app and env label to kubernetes spec"      
        parameters:
          template: |
            { "metadata" : {
              "labels": {
                "application": "${params['application']}",
                "environment": "${params['environment']}",
              }
             }
            }