Template Functions

Using template functions to make your Swarm YAML dynamic

Template functions are marked by the double curly bracket + “repl” escape sequence. They allow for user input to be dynamically inserted into application configuration values. The sequence should be {{repl, not {{ repl.

Go Templates

Replicated uses Go’s template package to execute the following functions. In addition to the functions listed here, all functions from the Go text/template package are available. Please note that Go template functions must still be escaped with “repl” escape sequence as demonstrated below. This is to ensure other template engines, such as Handlebars or Mustache, or Go templating used in application configuration files will work as expected.

{{repl if pipeline}} T1 {{repl else}} T0 {{repl end}}

Conditionals

Parts of the release YAML can be applied conditionally using Go’s templating. This can be used with Docker Swarm to conditionally insert environment variables in situations where empty environment variables can’t be used. For example:

services:
  app-app:
    image: myapp
    ports:
      - 5000:80
    networks:
      - myapp
    depends_on:
      - redis
    environment:
{{repl if eq (ConsoleSetting "airgap.install") true}}
      - AIRGAP="true"
{{repl end}}
    deploy:
      mode: replicated
      replicas: 2
      labels: [APP=VOTING]
      placement:
        constraints: [node.role == worker]

In this instance, the AIRGAP environment variable will be inserted into the compose YAML if this release is run on an airgapped installation.

List Of Template Functions In Docker Swarm

ConfigOption

func ConfigOption(optionName string) string

Returns the value of the config option as a string. The config screen and associated options are described here.

properties:
  app_url: http://{{repl ConfigOption "hostname" }}

ConfigOptionData

(only supports type: file)

func ConfigOptionData(fileName string) string

Returns the contents of the file uploaded for a configuration option as a string.

config_files:
- filename: /opt/certs/server.key
  contents: {{repl ConfigOptionData "ssl_key"}}

ConfigOptionEquals

func ConfigOptionEquals(optionName string, expectedValue string) bool

Returns true if the configuration option value is equal to the supplied value.

environment:
- SMTP_ENABLED={{repl ConfigOptionEquals "smtp_enabled" "1" }}

ConfigOptionNotEquals

func ConfigOptionNotEquals(optionName string, expectedValue string) bool

Returns true if the configuration option value is not equal to the supplied value.

environment:
- RETURN_TO_SENDER={{repl ConfigOptionNotEquals "address_unknown" "1" }}

LicenseFieldValue

func LicenseFieldValue(customLicenseFieldName string) string

Returns the value for the Custom License Field as a string.

config_files:
- filename: /opt/app/config.yml
  contents: |
    max_users: '{{repl LicenseFieldValue "maximum_users" }}'

LicenseProperty

func LicenseProperty(propertyName string) string

Returns a property from the License as a string. Valid propertyNames are “assignee”, “channel.name”, “expiration.date”, “expiration.policy”, and “license.id”.

config_files:
- filename: /opt/app/config.yml
  contents: |
    expiration.date: {{repl LicenseProperty "expiration.date"}}

AppID

func AppID() string

Returns the app id.

environment:
- APP_ID={{repl AppID }}

AppVersion

func AppVersion() int

Returns the app version sequence.

environment:
- APP_VERSION={{repl AppVersion }}

AppVersionFirst

func AppVersionFirst() int

Returns the version sequence of the first version installed.

environment:
- APP_VERSION_FIRST={{repl AppVersionFirst }}

AppVersionCurrent

func AppVersionCurrent() int

Returns the current app version sequence.

environment:
- APP_VERSION_CURRENT={{repl AppVersionCurrent }}

RunOffline

func RunOffline() bool

Returns whether or not we are running in airgap mode.

environment:
- IS_AIRGAP={{repl RunOffline }}

AppSetting

func AppSetting(key string) string

Returns a setting from the current app release.

Possible Options: version.label release.notes release.date install.date release.channel

environment:
- VERSION={{repl AppSetting "version.label"}}
- RELEASE_NOTES={{repl AppSetting "release.notes"}}
- INSTALL_DATE={{repl AppSetting "install.date"}}
- RELEASE_DATE={{repl AppSetting "release.date"}}
- RELEASE_CHANNEL={{repl AppSetting "release.channel"}}

ConsoleSetting

func ConsoleSetting(consoleSettingName string) string

Returns customer defined console settings for the TLS data or proxy settings. Values are returned as a string.

Option Returned Value
tls.key.name TLS key filename
tls.key.data TLS key contents
tls.cert.name TLS cert filename
tls.cert.data TLS cert contents
tls.authority.cert TLS certificate authority contents
tls.hostname Hostname used to secure Replicated TLS traffic
tls.source Source of the TLS cert, either “self-signed”, “key-cert” or “server-path”
http.proxy Proxy http address (e.g. http://10.128.0.4:3128)
http.proxy.enabled Proxy is enabled when value is 1, not enabled when it is 0
config:
- name: console_info
  title: Console Info
  items:
  - name: key_filename
    type: text
    readonly: true
    value: '{{repl ConsoleSetting "tls.key.name"}}'

ConsoleSettingEquals

func ConsoleSettingEquals(name string, value string) bool

Returns a bool indicating if the value is the currently applied value for ConsoleSetting with name.

ConsoleSettingNotEquals

func ConsoleSettingNotEquals(name string, value string) bool

Returns a bool indicating if the value is not the currently applied value for ConsoleSetting with name.

LdapCopyAuthFrom

func LdapCopyAuthFrom(keyName string) interface{}

Possible Options:

Key Type
Hostname string
Port string
SearchUsername string
SearchPassword string
BaseDN string
UserSearchDNFirst string
UserSearchDNAll string
RestrictedGroupCNFirst []string
RestrictedGroupCNAll []string
FieldUsername string
LoginUsername string
AdvancedSearchBool boolean
UserQuery string
RestrictedGroupQuery string
environment:
- LDAP_HOSTNAME={{repl LdapCopyAuthFrom "Hostname"}}

Now

func Now() string

Returns the current timestamp as an RFC3339 formatted string.

environment:
- START_TIME={{repl Now }}

NowFmt

func NowFmt(format string) string

Returns the current timestamp as a formatted string. See Golang’s time formatting guidelines [here](https://golang.org/pkg/time/#pkg-constants.

environment:
- START_DATE={{repl Now "20060102" }}

TrimSpace

func TrimSpace(s string) string

Trim returns a string with all leading and trailing spaces removed.

environment:
- VALUE={{repl ConfigOption "str_value" | TrimSpace }}

Trim

func Trim(s string, args ...string) string

Trim returns a string with all leading and trailing string contained in the optional args removed (default space).

environment:
- VALUE={{repl ConfigOption "str_value" | Trim " " "." }}

Split

func Split(s string, sep string) []string

Split slices s into all substrings separated by sep and returns an array of the substrings between those separators.

environment:
- BROKEN_APART_A_B_C={{repl Split "A,B,C" "," }}

Combining Split and index: Assuming the github_url param is set to https://github.mycorp.internal:3131, the following would set GITHUB_HOSTNAME to github.mycorp.internal.

environment:
- GITHUB_HOSTNAME={{repl index (Split (index (Split (ConfigOption "github_url") "/") 2) ":") 0}}

ToLower

func ToLower(stringToAlter string) string

Returns the string, in lowercase.

environment:
- COMPANY_NAME={{repl ConfigOption "company_name" | ToLower }}

ToUpper

func ToUpper(stringToAlter string) string

Returns the string, in uppercase.

environment:
- COMPANY_NAME={{repl ConfigOption "company_name" | ToUpper }}

HumanSize

func HumanSize(size interface{}) string

HumanSize returns a human-readable approximation of a size in bytes capped at 4 valid numbers (eg. “2.746 MB”, “796 KB”). The size must be a integer or floating point number.

environment:
- MIN_SIZE_HUMAN={{repl ConfigOption "min_size_bytes" | HumanSize }}

UrlEncode

func UrlEncode(stringToEncode string) string

Returns the string, url encoded.

environment:
- SMTP_CONNECTION_URL={{repl ConfigOption "smtp_email" | UrlEncode }}:{{repl ConfigOption "smtp_password" | UrlEncode }}@smtp.example.com:587

Base64Encode

func Base64Encode(stringToEncode string) string

Returns a Base64 encoded string.

environment:
- NAME_64_VALUE={{repl ConfigOption "name" | Base64Encode }}

Base64Decode

func Base64Decode(stringToDecode string) string

Returns decoded string from a Base64 stored value.

environment:
- NAME_PLAIN_TEXT={{repl ConfigOption "base_64_encoded_name" | Base64Decode }}

ParseBool

func ParseBool(str string) bool

ParseBool returns the boolean value represented by the string.

environment:
- VALUE={{repl ConfigOption "str_value" | ParseBool }}

ParseFloat

func ParseFloat(str string) float64

ParseFloat returns the float value represented by the string.

environment:
- VALUE={{repl ConfigOption "str_value" | ParseFloat }}

ParseInt

func ParseInt(str string, args ...int) int64

ParseInt returns the integer value represented by the string with optional base (default 10).

environment:
- VALUE={{repl ConfigOption "str_value" | ParseInt }}

ParseUint

func ParseUint(str string, args ...int) uint64

ParseUint returns the unsigned integer value represented by the string with optional base (default 10).

environment:
- VALUE={{repl ConfigOption "str_value" | ParseUint }}

Add

func Add(x interface{}, y interface{}) interface{}

Adds x and y.

If at least one of the operands is a floating point number, the result will be a floating point number.

If both operands are integers, the result will be an integer.

environment:
- MAX_USERS_PLUS_ONE={{repl Add (LicenseFieldValue "maximum_users") 1}}

Sub

func Sub(x interface{}, y interface{}) interface{}

Subtracts y from x.

If at least one of the operands is a floating point number, the result will be a floating point number.

If both operands are integers, the result will be an integer.

environment:
- MAX_USERS_MINUS_ONE={{repl Sub (LicenseFieldValue "maximum_users") 1}}

Mult

func Mult(x interface{}, y interface{}) interface{}

Multiplies x and y.

If at least one of the operands is a floating point number, the result will be a floating point number.

If both operands are integers, the result will be an integer.

environment:
- DOUBLE_NUM_ADDRESSES={{repl Mult (NodePrivateIPAddressAll "DB" "redis" | len) 2}}

Div

func Div(x interface{}, y interface{}) interface{}

Divides x by y.

If at least one of the operands is a floating point number, the result will be a floating point number.

If both operands are integers, the result will be an integer and will be rounded down.

environment:
- HALF_MAX_USERS={{repl Div (LicenseFieldValue "maximum_users") 2.0}}

Namespace

func Namespace() string

Namespace returns the value of the namespace the vendor application is installed in.

SwarmIngressAddress

SwarmIngressAddress() string

SwarmIngressAddress returns the ingress address of the swarm cluster.

properties:
  app_url: '{{repl SwarmIngressAddress }}'

PremkitAPIAddress

PremkitAPIAddress() string

PremkitAPIAddress returns the address of the Premkit service in the cluster.

services:
  api:
    image: mycompany/myapp:1.0
    environment:
    - REPLICATED_INTEGRATIONAPI={{repl PremkitAPIAddress }}

PremkitNetworkName

PremkitNetworkName() string

PremkitNetworkName returns the name of the premkit docker network.

StatsdAddress

StatsdAddress() string

StatsdAddress returns the address of the Statsd service in the cluster.

services:
  api:
    image: mycompany/myapp:1.0
    environment:
    - STATSD_HOST={{repl (index (Split (StatsdAddress) ":") 0)}}
    - STATSD_PORT={{repl (index (Split (StatsdAddress) ":") 1)}}

StatsdNetworkName

StatsdNetworkName() string

StatsdNetworkName returns the name of the Statsd docker network.