From b934c2deb32424f0e0a18a0e24f2783d49490589 Mon Sep 17 00:00:00 2001 From: Kimmo Lehto Date: Fri, 19 Jan 2018 14:37:27 +0200 Subject: [PATCH 1/4] Document default: and value: in variables doc --- references/stack-file-variables.md | 64 ++++++++++++++++++++++-------- 1 file changed, 47 insertions(+), 17 deletions(-) diff --git a/references/stack-file-variables.md b/references/stack-file-variables.md index 2905a9f..d49ae46 100644 --- a/references/stack-file-variables.md +++ b/references/stack-file-variables.md @@ -6,9 +6,9 @@ Here is an example how to declare variable named `mysql_root_pw` and how to use ```yaml variables: - mysql_root_pw: - type: string - from: + mysql_root_pw: + type: string + from: prompt: Enter a root password for MySQL or leave empty to auto generate random_string: 16 services: @@ -39,9 +39,47 @@ Kontena Stack File has several built-in default variables that may be used throu ## Variables Reference +### Type + +Defines the [data type](#data_types) of the variable. + +``` +variables: + variable_name: +    type: string +``` + +### Default + +Sets a default value. The value will be used when no other value for the variable has been supplied. + +``` +variables: + image_tag: + type: string + default: latest + from: +      env: IMAGE_TAG +``` + +The `image_tag` will get the value "latest" unless the environment variable `IMAGE_TAG` has been set. + +### Value + +Set a constant value that can only be changed by modifying the file. + +``` +variables: + image_tag: + type: string +    value: latest +``` + +The value of image_tag will always be "latest". Any `from:` sources will not be used. + ### From -Define where a value for the variable is obtained from. A list of resolvers and their options can be found further in this documentation. +Define where a value for the variable should be looked up from, for example an environment variable name, an interactive prompt or a random password generator. See the list of available resolvers and their options [here](#resolvers). You can define multiple sources, for example: @@ -106,31 +144,23 @@ Works just the same as `only_if`, but opposite. The processing of this variable skip_if: use_mysql # don't process this variable if use_mysql has a truthy value. ``` -### Type - -Data type for the variable, options are: string, integer, boolean, enum and uri. - -``` - type: string -``` - ### Type handler options -Everything else is passed to the type handler as options: +Everything else is passed to the type handler as options. Each data type can have a different set of options. ``` username: type: string - min_length: 10 # require length to be at least 10 characters + min_length: 10 # require string length to be at least 10 characters max_length: 16 # and maximum of 16 characters - downcase: true # make the string all lower case + downcase: true # make the string all lower case even if input is MixedCase ``` ## Data Types The data types can have several options, validations, sanitizations and transformations. For example, the minimum length of a string can be defined, the string can be converted to UPPER CASE characters and cleaned up of leading/trailing whitespace. -There's a global validation applicable to all data types: +There's one global validation rule that is applicable to all data types, the `in:` validator. You can use it to make the value valid if it is one of the accepted values listed under the `in:` keyword, known as `enum` in some languages. ``` type: string @@ -282,7 +312,7 @@ arr: The variable `arr` will have the value `a,b,c`. -## Resolvers (From:) +## Resolvers Resolvers are used to obtain a value for the variable from several inputs. If you define multiple sources, they will be processed one by one until one of them results in a non-null value. From f3e5cca29e9c26dc5be38a6e93a5a4a13c686a4e Mon Sep 17 00:00:00 2001 From: Kimmo Lehto Date: Fri, 19 Jan 2018 14:38:26 +0200 Subject: [PATCH 2/4] Broken link --- references/stack-file-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/references/stack-file-variables.md b/references/stack-file-variables.md index d49ae46..6e5f473 100644 --- a/references/stack-file-variables.md +++ b/references/stack-file-variables.md @@ -41,7 +41,7 @@ Kontena Stack File has several built-in default variables that may be used throu ### Type -Defines the [data type](#data_types) of the variable. +Defines the [data type](#data-types) of the variable. ``` variables: From c595c7399b4692ee066243c426dc0578f2f80e9b Mon Sep 17 00:00:00 2001 From: Kimmo Lehto Date: Fri, 19 Jan 2018 14:44:03 +0200 Subject: [PATCH 3/4] Strange grammar --- references/stack-file-variables.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/references/stack-file-variables.md b/references/stack-file-variables.md index 6e5f473..8e16ebf 100644 --- a/references/stack-file-variables.md +++ b/references/stack-file-variables.md @@ -2,7 +2,7 @@ [Kontena Stack File](../using-kontena/stack-file.md) variables, declared in `variables` section, may be used to fill in values or providing additional conditional logic. In addition, they may be used with [Kontena Stack File Template Language](../using-kontena/stack-file.md#template-language). All variables, including environment variables you might want to use, must be declared in this section. -Here is an example how to declare variable named `mysql_root_pw` and how to use it as part services of configuration: +Here is an example how to declare a variable named `mysql_root_pw` and how to use it in a service definition: ```yaml variables: @@ -11,6 +11,7 @@ variables: from: prompt: Enter a root password for MySQL or leave empty to auto generate random_string: 16 + services: mysql: image: mysql @@ -22,11 +23,10 @@ services: You can use resolved variables in Kontena Stack File [`services`](./stack-file.md#variables) section using bash-like `${VARIABLE_NAME}` syntax. -**IMPORTANT!** The variables are interpolated into the raw YAML before parsing. This can cause the YAML to become invalid. Often you can avoid that by using quotes. For example: +**IMPORTANT!** The stack YAML file has to be valid YAML before AND after the variable intepolation. Often you can avoid creating invalid YAML by using quotes. For example: ``` -environment: - - "PASSWORD=${some_password}" +image: "${imagename}" ``` ## Built-in Default Variables From 2d000f0f1f4a5a3cacd48269695820c851e19948 Mon Sep 17 00:00:00 2001 From: Kimmo Lehto Date: Fri, 19 Jan 2018 14:45:24 +0200 Subject: [PATCH 4/4] Trailing whitespace --- references/stack-file-variables.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/references/stack-file-variables.md b/references/stack-file-variables.md index 8e16ebf..358d286 100644 --- a/references/stack-file-variables.md +++ b/references/stack-file-variables.md @@ -7,8 +7,8 @@ Here is an example how to declare a variable named `mysql_root_pw` and how to us ```yaml variables: mysql_root_pw: - type: string - from: + type: string + from: prompt: Enter a root password for MySQL or leave empty to auto generate random_string: 16 @@ -23,7 +23,7 @@ services: You can use resolved variables in Kontena Stack File [`services`](./stack-file.md#variables) section using bash-like `${VARIABLE_NAME}` syntax. -**IMPORTANT!** The stack YAML file has to be valid YAML before AND after the variable intepolation. Often you can avoid creating invalid YAML by using quotes. For example: +**IMPORTANT!** The Stack YAML file has to be valid YAML before AND after the variable intepolation. Often you can avoid creating invalid YAML by using quotes. For example: ``` image: "${imagename}"