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.
'{{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.
'{{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.
'{{repl ShipCustomerRelease }}'
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" }}'
Installation
func Installation(field string) string
Possible Options:
| Key | Type |
|---|---|
| state_file_path | string |
| customer_id | string |
| semver | string |
| channel_name | string |
| channel_id | string |
| release_id | string |
| installation_id | string |
| release_notes | []string |
| app_slug | []string |
| license_id | string |
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"}}'