Template Function Types

Replicated Ship Template Functions

Template functions are the key to providing dynamic contents or behavior within a Ship application. They can be used to generate the contents of rendered files, skip unneeded steps, and provide more relevant messaging to users, along with a multitude of other things. Ship template functions extend those available within the text/template package of Go.

All Ship template functions must begin with {{repl, rather than the standard {{. See Static Functions for some examples.

Template Function List

The many template functions available within Ship can be thought of as belonging to several categories.

Sprig

Many of the utility functions provided come from Sprig, a third-party library of Go template functions. The Sprig documentation can be found here.

Static Functions

Additional utility functions, shared with Replicated Vendor. Implementations of these functions can be found here.

Now

func Now() string

Returns the current timestamp as an RFC3339 formatted string.

'{{repl Now }}'

NowFmt

func NowFmt(format string) string

Returns the current timestamp as a formatted string. See Go’s time formatting guidelines here.

'{{repl Now "20060102" }}'

ToLower

func ToLower(stringToAlter string) string

Returns the string, in lowercase.

'{{repl ConfigOption "company_name" | ToLower }}'

ToUpper

func ToUpper(stringToAlter string) string

Returns the string, in uppercase.

'{{repl ConfigOption "company_name" | ToUpper }}'

TrimSpace

func TrimSpace(s string) string

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

'{{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).

'{{repl ConfigOption "str_value" | Trim " " "." }}'

UrlEncode

func UrlEncode(stringToEncode string) string

Returns the string, url encoded. Equivalent to the QueryEscape function within the golang net/url library.

'{{repl ConfigOption "smtp_email" | UrlEncode }}:{{repl ConfigOption "smtp_password" | UrlEncode }}@smtp.example.com:587'

UrlPathEscape

func UrlPathEscape(stringToEncode string) string

Returns the string, url path encoded. Equivalent to the PathEscape function within the golang net/url library.

'{{repl ConfigOption "smtp_email" | UrlPathEscape }}:{{repl ConfigOption "smtp_password" | UrlPathEscape }}@smtp.example.com:587'

Base64Encode

func Base64Encode(stringToEncode string) string

Returns a Base64 encoded string.

'{{repl ConfigOption "name" | Base64Encode }}'

Base64Decode

func Base64Decode(stringToDecode string) string

Returns decoded string from a Base64 stored value.

'{{repl ConfigOption "base_64_encoded_name" | Base64Decode }}'

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.

'{{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.

'{{repl index (Split (index (Split (ConfigOption "github_url") "/") 2) ":") 0}}'

RandomString

func RandomString(length uint64, providedCharset ...string) string

Returns a random string with the desired length and charset. Provided charsets must be Perl formatted and match individual characters. If no charset is provided, [_A-Za-z0-9] will be used.

Each time that this function is called, it will return a different value.

'{{repl RandomString 64}}'

Or for a total of 64 as and bs:

'{{repl RandomString 64 "[ab]" }}'

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.

'{{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.

'{{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.

'{{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.

'{{repl Div (LicenseFieldValue "maximum_users") 2.0}}'

ParseBool

func ParseBool(str string) bool

ParseBool returns the boolean value represented by the string.

'{{repl ConfigOption "str_value" | ParseBool }}'

ParseFloat

func ParseFloat(str string) float64

ParseFloat returns the float value represented by the string.

'{{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).

'{{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).

'{{repl ConfigOption "str_value" | ParseUint }}'

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.

'{{repl ConfigOption "min_size_bytes" | HumanSize }}'

KubeSeal

func KubeSeal(certData string, namespace string, name string, value string) string

Installation Context Functions

Functions that refer to properties of the running ship installation, such as the license ID or app release notes. Implementations of these functions can be found here.

ShipCustomerRelease

func ShipCustomerRelease() string

ShipCustomerRelease returns a copy of the release metadata struct, marshalled as yaml. Config specs, collect specs, analyze specs, github contents and images are not included.

'{{repl ShipCustomerRelease }}'

ShipCustomerReleaseFull

func ShipCustomerReleaseFull() string

ShipCustomerReleaseFull returns a copy of the release metadata struct, marshalled as yaml.

'{{repl ShipCustomerReleaseFull }}'

EntitlementValue

func EntitlementValue(name string) string

EntitlementValue returns the value of the entitlement with the provided name.

'{{repl EntitlementValue "numSeats" }}'

LicenseFieldValue

func LicenseFieldValue(name string) string

LicenseFieldValue returns the value of the entitlement with the provided name. Is an alias for EntitlementValue.

'{{repl LicenseFieldValue "numSeats" }}'

CollectSpec

func CollectSpec() string

CollectSpec returns the Collect Spec currently promoted to the channel to which your license is associated.

'{{repl CollectSpec }}'

ConfigSpec

func ConfigSpec() string

ConfigSpec returns the Config Spec for the current ship release.

'{{repl ConfigSpec }}'

AnalyzeSpec

func AnalyzeSpec() string

AnalyzeSpec returns the Analyze Spec currently promoted to the channel to which your license is associated.

'{{repl AnalyzeSpec }}'

Installation

func Installation(field string) string

Possible Options:

Installation returns the value of the property with the provided key.

'{{repl Installation "license_id" }}'

Config Context Functions

Functions that refer to Implementations of these functions can be found here.

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.

'{{repl ConfigOption "hostname" }}'

ConfigOptionData

func ConfigOptionData(fileName string) string

Returns the base64 decoded value of a config option.

'{{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.

'{{repl ConfigOptionEquals "http_enabled" "1" }}'

ConfigOptionNotEquals

func ConfigOptionNotEquals(optionName string, expectedValue string) bool

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

'{{repl ConfigOptionNotEquals "http_enabled" "1" }}'

Ship Context Functions

Functions that refer to parts of Ship’s state. This includes paths to generated kubeconfigs and utilities to generate public key infrastructure. Implementations of these functions can be found here.

AmazonEKS

func AmazonEKS(cluster string) string

Returns the path to the generated kubeconfig for the cluster created with the named AmazonEKS asset.

'{{repl AmazonEKS "my_cluster"}}'

GoogleGKE

func GoogleGKE(cluster string) string

Returns the path to the generated kubeconfig for the cluster created with the named GoogleGKE asset.

'{{repl GoogleGKE "my_cluster"}}'

AzureAKS

func AzureAKS(cluster string) string

Returns the path to the generated kubeconfig for the cluster created with the named AzureAKS asset.

'{{repl AzureAKS "my_cluster"}}'

GetCaKey

func GetCaKey(caName string, caType string) string

Returns a key for a certificate authority with the desired properties. If a CA with this name has been requested before, the same value will be returned. The type can be RSA or ECDSA, with acceptable values being rsa-2048, rsa-4096, rsa-8192, P256 or P521. If no type is provided, rsa-2048 will be used.

'{{repl GetCaKey "my_certificate_authority" "P521"}}'

GetCaCert

func GetCaCert(caName string) string

Returns a cert for a previously generated certificate authority. Must be called after GetCaKey has been called for the desired CA name.

'{{repl GetCaCert "my_certificate_authority"}}'

GetKey

func GetKey(certName string, caName string, hosts string, certType string) string

Returns a key for a cert with the desired properties. hosts is a set of hosts that the certificate should be valid for, seperated by commas, such as example1.com,subdomain.example.io. If a cert with this name has been requested before, the same value will be returned, even if other request parameters differ. If a CA with the desired name has been requested before, that CA will be used to sign the generated cert for the requested hosts. If a CA with the desired name has not been requested before, one will be generated with the same type as this cert. The type can be RSA or ECDSA, with acceptable values being rsa-2048, rsa-4096, rsa-8192, P256 or P521. If no type is provided, rsa-2048 will be used.

'{{repl GetKey "my_cert" "my_certificate_authority" "example.com,myexampleapp.io,help.replicated.com" "P521"}}'

GetCert

func GetCert(caName string) string

Returns a cert for a previously generated key. Must be called after GetKey has been called for the desired cert name.

'{{repl GetCert "my_cert"}}'