Inputs
Configuration files with the inputs
field:
These inputs collect information relevant to the scope of your Plugin or Action. The STK CLI interprets them during command execution to ask users for this information.
The Inputs are optional. Each .yaml file can have none or many inputs.
Input types
The Input types are defined in the type
field, check below:
Types | Value |
---|---|
text | String. |
textarea | String. |
bool | Boolean. |
int | Integer. |
password | Encrypts the entered value` (string) |
select | Lists the values, allowing only 1 value (string) to be chosen. |
multiselect | Lists the values, allowing to choose 1 or more values ​​(string). |
list | List of inputs of the same type (text, int, object, and required-connection). |
object | Stores a set of inputs within an object, making the object a parent input with a set of child inputs. |
required-connection | Stores a set of inputs required to connect to an Infrastructure inside an object. |
generated-connection | Stores a set of inputs required to create an Infrastructure inside an object. |
On STK CLI, check how to navigate:
- Navigate using arrow keys to choose your option(s), or type to search what you want.
- Select all: Use CTRL + a.
- To invert: Use CTRL + i.
Mandatory input fields
- name: Input name ( handled later).
- label: Text that will appear on the terminal. It asks the user for input.
- type:
text
(string).bool
(boolean).int
(integer).password
(The value is hidden on STK CLI. The format is:****
).multiselect
: Lists the values. It allows one or more values (string).list
(List of inputs of the same type. Accepted types are:text
,int
,object
).object
(string).required-connection
(string).
Inputs with mandatory fields examples
Type text
input
The text
input type accepts text as a string.
- label: Type your name
name: name
type: text
In text inputs you can use a variable as the value of this input. For more information, visit the Variables page on StackSpot.
The use of text lists in inputs has been deprecated!
inputs:
- label: Select a day
name: days
type: text
items:
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
- Sunday
The use of the text
input type with the items
field is no longer supported in the current version.
textarea
Input
The textarea
input receives text as a string and supports line breaks.
inputs:
- label: Type your name
name: name
type: textarea
Example:
Consider using a JSON code snippet as the value for the textarea
input. In both the STK CLI and the StackSpot Portal, when you use a value with a JSON structure, the formatting of the content—such as spaces and line breaks, remains intact. This behavior applies to all text that includes spaces and line breaks, not just code snippets.
Text visualization with text
input:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": "arn:aws:s3:::your-bucket-name" }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": "arn:aws:s3:::your-bucket-name/*" } ] }
Text visualization with textarea
input:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListBucket"
],
"Resource": "arn:aws:s3:::your-bucket-name"
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": "arn:aws:s3:::your-bucket-name/*"
}
]
}
In text inputs, you can use a variable as the value of this input. For more information, visit the Variables page on StackSpot.
Type select
input
The select
input type accepts a list of text items as a string. You can only select one item from the list.
inputs:
- label: Choose one color!
name: colors
type: select
items:
- Blue
- Yellow
- Pink
- Green
- Red
Multiselect
type input
The multiselect
input type accepts a list of text items as a string. You can select one or more items from the list.
inputs:
- label: Choose one or more days
name: days
type: multiselect
items:
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
Input of type int
The input of type int
receives an integer numeric value.
inputs:
- label: Type your age
name: age
type: int
The input of type int
can use the pattern parameter to define a regular expression for the value received in the input.
Input of type password
The input of type password
receives a value and encrypts it using a 256-bit AES key (Advanced Encryption Standard). When you type the value in your terminal, the values ​​are hidden and displayed only as asterisk symbols ("****
").
-
When creating Applications that have Plugins and Actions with the
password
input, deploys are executed. In case of deploy failure, you must re-execute it and re-enter the value of thepassword
input because the value does not persist for the security of the data used. -
After entering the value of the
password
input, further attempts to execute the deploy must occur within one hour. After this period, you must re-enter the input field password. -
When
password
input types are recorded in the deploy execution logs, the values displayed in the logs are masked.
inputs:
- label: Password
name: account_password
type: password
Input of type bool
The input of type bool
receives a boolean value, with Y
representing true and n
representing false.
inputs:
- label: Use SQL connection?
name: sql
type: bool
Input of type list
- This input is available only for Actions and Plugins with the manifest in version
v3
. For more details, refer to the guide to migrate your Actions and Plugins versions. - This input does not consider the properties of the fields default and pattern.
The input of type list
receives another input and structures the values obtained by this input as a list. The list must receive all values of the same type, with the accepted types being:
In the add-question
option, include a text as a question to be repeated to the user for each iteration in the list.
inputs:
- label: Type your ips
name: ips
type: list
add-question: Do you want to add more IPs to the list?
input:
type: text
label: Informe os ips
To access the values ​​in the list, you must inform the list index. The index starts at [0]
(zero). See the following example:
condition:
variable: input_list_2[0].input_text_1_from_input_object
operator: "=="
value: "ok"
Input of type object
- This input is available only for Actions and Plugins with the manifest in version
v3
. For more details, refer to the guide to migrate the versions of your Actions and Plugins. - This input does not consider the properties of the fields default and pattern.
The object
type input receives various inputs and organizes their values as objects. There are no restrictions on the types of inputs this object can have; it can be a simple object or a complex one containing multiple types.
In the inputs
option within the object declaration, you must include each input that will constitute the object type input.
inputs:
- type: object
name: firewall_rule
label: Enter the CIDR/Port of the firewall rule
inputs:
- type: text
name: cidr
label: CIDR
pattern: '^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}/\d{2}$'
- type: int
name: port
label: Port
required: false
condition:
variable: firewall_rule.cidr
operator: "=="
value: 192.168.0.1/25
inputs:
- type: object
name: firewall_rule
label: Enter the CIDR/Port of the firewall rule
inputs:
- type: text
name: cidr
label: CIDR
pattern: '^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}/\d{2}$'
- type: int
name: port
label: Port
required: false
condition:
variable: firewall_rule.cidr
operator: "=="
value: 192.168.0.1/25
- type: object
name: additional_rules
label: Additional Rules
required: true
inputs:
- type: select
name: name
label: Name
required: true
items:
- Dynamo
- Lambda
- type: text
name: description
label: Description
required: true
condition:
variable: firewall_rule.additional_rules.name
operator: "=="
value: Dynamo
- type: text
name: conditional_input
label: Conditional test
condition:
variable: firewall_rule.additional_rules.name
operator: "=="
value: Dynamo
Input of type required-connection
- This input is only available for Actions and Plugins with manifest version
v3
.. For more details, see the guide to migrating the versions of your Actions and Plugins. - This input does not consider the properties of the fields default, pattern, and required.
The required-connection
input is defined using a Connection Interface required by your Plugin or Action. Before using this input, refer to the types of available Connection Interfaces. Make sure to fill in the connection-interface-type
field with the name of the Connection Interface Type available for your StackSpot Account.
inputs:
- label: Select an Bucket s3
type: required-connection
name: my-s3
connection-interface-type: aws-s3-conn
Input of type generated-connection
- This input is only available for Plugins with manifest version
v3
. For more details, see the migrating guide to the versions of your Actions and Plugins. - This input does not consider the properties of the fields default, pattern, and required.
The generated-connection
input is defined using a Connection Interface required by your Plugin. Before using this input, please refer to the types of available Connection Interfaces. Ensure that you fill in the connection-interface-type
field with the name of the Connection Interface Type that is available for your StackSpot Account.
inputs:
- label: The s3 connection name
name: bucket_s3
type: generated-connection
connection-interface-type: aws-s3-conn
outputs:
- from: aws-s3-alias-arn
to: arn
- from: aws-s3-alias-bucket_name
to: bucket_name
Optional Input fields
Below are the optional fields available for use across various input types. However, certain fields may be exclusive to a specific type of input. In these cases, the description will specify the type of input required.
default
Default value when there is no value.
- label: Type your name
name: name
type: text
default: John
The default
field accepts an Account variable or StackSpot Variable, but does not support using computed inputs
.
For the multiselect
input type, use only the following formats:
- label: (Input multiselect required false com 1 valor default) Qual porta deseja expor ?
type: multiselect
name: port4
items:
- "8080"
- "8888"
default: ["8888"]
Or
- label: (Input multiselect required false com 1 valor default) Which port would you like to display?
type: multiselect
name: port4
items:
- "8080"
- "8888"
default:
- "8888"
Default Value in Non-Interactive Mode
When you run the stk apply plugin
command, you can use the -q
or --non-interactive
parameter to bypass inputs in the terminal as a non-interactive mode. If a value is set in the default
option, the command will use that value when applying the Plugin in the non-interactive mode.
This behavior applies only to the following input types:
required
Boolean indicates if a value is optional or not. The value is true
when no value is added.
- label: Type your name
name: name
type: text
required: true
items
List showing the possible input values (It is used with the select
or multiselect` types).
- label: Type your name
name: name
type: select # or multiselect
items:
- John
- Bill
source
It retrieves data from a public or private API with StackSpot domain to create an external source of values for select and multiselect input types.
Use a public API endpoint URL or a private API endpoint URL with a StackSpot domain.
- label: Select External Item
name: select_item
type: select
external-items:
source: https://external-source.com # The API endpoint URL.
value: $[*].id
label: $[*].name
To use the source option in the input, you cannot use the 'items' option simultaneously. You must choose between them.
The options of source are:
-
value (Mandatory): The JSON path of the value in the returned value that you want to use in the input list.
-
label (Optional): The object's path is now displayed as an alternative name for input item selection in the terminal.
Consider the following JSON object of the endpoint used in the source field:
[
{
"id": "id1",
"name": "item1"
},
{
"id": "id2",
"name": "item2"
},
{
"id": "id3",
"name": "item3"
}
]
If you want to use the ID values as the input values for the list. Use the JSON Path expression for the ID values in the value option.
For the values used in the value option. If you want to display a different label name for the ID, add the JSON Path for the other object. For example, the name object.
Example:
inputs:
- label: Select external item
name: select_items
type: select
external-items:
source: https://external-source.com
value: $[*].id
label: $[*].name
required: true
- label: Select Multiple Items
name: multiselect_items
type: multiselect
external-items:
source: https://external-source.com
value: $[*].id
label: $[*].name
required: true
Otherwise, the ID value is shown as the label in the terminal as the input list selection.
For more details about JSON Path, see the JSON PATH expressions reference.
pattern
Configures a field regex validation for the input.
- label: Type your name
name: name
type: text
pattern: "[A-Za-z]"
condition
After receiving a value in the input, a condition is set for a second input to show the user if the condition is true. If the condition is not true, nothing happens after the input with the condition
.
- variable: Name of the variable used to evaluate the condition.
- operator: Operator used to evaluate the condition. The valid operator's values are:
==
,!=
,>
,>=
,<
,<=
,containsAny
,containsAll
,containsOnly
,notContainsAny
andnotContainsAll
.
Use current index in list of objects in condition.variable
In the condition
parameter, the variable
option supports the use of the input of type list of objects. This way you can reference the index of the list as previously presented in the input of type list
or reference the current index by just informing the empty braces ("[ ]
").
This way of referencing the index allows you to create a condition to display different inputs according to previous responses.
Example:
inputs:
- label: Type your objects
name: obj_list
type: list
add-question: Would you like to add items to the object list?
input:
type: object
label: object_in_list
inputs:
- label: text_value
name: text_value
type: text
required: true
- label: int_value
name: int_value
type: int
required: true
condition:
variable: obj_list[].text_value
operator: "=="
value: "foo-bar"
- label: Type your objects
name: obj_list_nested
type: list
add-question: Would you like to add items to the object list?
input:
type: object
label: Object In List Nested
inputs:
- label: text_value
name: text_value_nested
type: text
required: true
- label: int_value
name: int_value_nested
type: int
required: true
condition:
variable: obj_list[].obj_list_nested[].text_value_nested
operator: "=="
value: "foo-bar"
You must use double quotes for the following operators: "=="
, "!="
, ">"
, ">="
, "<"
, "<="
.
Click here to see more details about operators:
Operator | Description |
---|---|
== | Validates if the values are equal. |
!= | Validates if the values are different. |
> | Validates if the variable is greater than the value. |
< | Validates if the variable is less than the value. |
>= | Validates if the variable is greater than or equal to the value. |
<= | Validates if the variable is less than or equal to the value. |
containsAny | Validates if the variable of list or text type contains any of the values contained in value . |
containsAll | Validates if the variable of the type list contains all the values contained in value . |
containsOnly | Validates if the variable list type contains all the values in value and no other elements. |
value
Value used for evaluation.
The condition
value
must be the same type as the referenced input.
Check an example below using condition
as an input. You can choose which language you want to use: Java and Kotlin. Depending on the language, you can check the available versions.
inputs:
- label: Which language do you want to use?
type: select
name: language
items:
- Java
- Kotlin
- label: Which Java version do you want to use?
type: select
name: java_version
items:
- 11
- 17
condition:
variable: language
operator: "=="
value: Java
- label: Which version of Kotlin do you want to use?
type: select
name: kotlin_version
items:
- 1.6
- 1.7
condition:
variable: language
operator: "=="
value: Kotlin
In the example, the condition
chooses which list to display. It depends on the input value language
. If the value equals Java, the Java list of versions shows up, if it equals Kotlin, the Kotlin versions list shows up.
When an input contains a condition
and receives a non-existent variable value: other inputs related to this condition
don’t show up.
Using JINJA in inputs
Inputs are responsible for receiving all the data that will make up the Plugins and Actions. They are essential for:
- Plugins to build the Application code; and
- Actions to create automation as expected.
Plugins generate the code from the templates/templates-deploy folder, and the automation is programmed in the Actions scripts.
When creating actions and plugins, it is important to use JINJA expressions in your inputs, source code, and scripts for a more dynamic use of these folders and scripts.
For more details, visit the page on how to use JINJA on StackSpot
Below are some examples of Plugin inputs using JINJA:
Consider the resource
and method
inputs.
inputs:
- label: Type the name of your resource
name: resource
type: text
required: true
default: Client
pattern: '([A-Z][a-z]+)+'
help: 'Inform your resource name (e.g.: Client)'
- label: Choose the http method of the new endpoint
name: method
type: select
items:
- GET
- POST
- PUT
- DELETE
- PATCH
default: GET
required: true
help: 'Inform the method of the endpoint (e.g.: post or delete)'
In the files in the templates folder of your Plugin, use the JINJA expressions "{{ variable_name }}
". Thus, the expressions used in the inputs of the previous example will be:
- resource:
{{ resource }}
- method:
{{ method }}
JINJA in inputs of type list
Consider the following example of the input ips
. It is a list that receives values ​​of type text:
inputs:
- type: list
label: List of IPs
add-question: Do you want to add ips to the list?
name: ips
input:
type: text
label: ip
pattern: '^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$'
default: '127.0.0.1'
As the plugin creator, you can determine the use of the ips
input in the following ways:
1. Access the entire list
Use the expression:
{{ variable_name }}
Example:
{{ ips }}
2. Access a list value by index
The list index indicates the position at which each item you added to the list, where the first index position starts at the value [0]
(zero). Use the following expression:
Make sure to perform a JINJA check to confirm the existence of this variable before querying its position.
{% if variable is defined %}
{{ variable[item_position_number] }}
{% endif %}
Example:
{% if ips is defined %}
{{ ips[0] }}
{% endif %}
3. Loop through all values ​​in a list
To loop through the values ​​in the list ips
, you must use the JINJA control structure, the "For Loop". To display all items, declare a variable, for example, ip
in the for loop to loop through the items added to the list. Use the following expression:
{% for [variable] in [input_list_name] %}
- list_item: {{ variable }}
{% endfor %}
Example:
{% for ip in ips %}
- ip value: {{ ip }}
{% endfor %}
JINJA on inputs of type object
Consider the following example of the input firewall_rule
. It is an object with two further inputs cidr
and port
:
inputs:
- type: object
name: firewall_rule
label: Enter the CIDR/Port of the firewall rule
inputs:
- type: text
name: cidr
label: CIDR
pattern: '^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}/\d{2}$'
default: '0.0.0.0/24'
- type: int
name: port
label: Port
default: 8080
The firewall_rule
input is a "parent or root" object, and the other inputs are all "children" of this object. Use the following expressions to access them:
1. Access the entire object
Use the expression:
{{ parent_object_name }}
Example:
{{ firewall_rule }}
2. Access child inputs
Repeat the expression for each child input:
Make sure to perform a JINJA check to confirm the existence of this variable before querying its position.
Use the expression:
{% if parent_object_name is defined %}
{{ parent_object_name.child_input }}
{% endif %}
Example:
- Input
cidr
:
{% if firewall_rule is defined %}
{{ firewall_rule.cidr }}
{% endif %}
- Input
port
:
{% if firewall_rule is defined %}
{{ firewall_rule.port }}
{% endif %}
JINJA on list
inputs with object
Consider the following example of the list buckets
. It contains an object made up of several types of inputs.
inputs:
- type: list
label: Buckets list
add-question: Would you like to add buckets?
name: buckets
input:
type: object
label: Inform the bucket
inputs:
- type: text
name: description
label: Bucket Description
- type: int
name: number
label: Bucket number
- type: bool
name: encrypted
label: Bucket Encrypted
- type: select
items:
- us-east-1
- us-east-2
- sa-east-3
name: region
label: Bucket Region
- type: multiselect
items:
- us-east-1
- us-east-2
- sa-east-3
name: region_bkp
label: Bucket Region Backup
- label: Select the connection for required_bucket_object
type: required-connection
name: required_bucket_object
connection-interface-type: aws-s3-conn
To access a list that has an object and access each item in the object, use the following expressions:
1. Access the entire list
Use the expression:
{{ variable_name }}
Example:
{{ buckets }}
2. Accessing a list value by index
The list index indicates the position at which each item was added to the list, where the first index position starts at the value [0]
(zero). Use the following expression:
Make sure to perform a JINJA check to confirm the existence of this variable before querying its position.
{% if variable_name is defined %}
{{ variable_name[item_position_number] }}
{% endif %}
Example:
{% if buckets is defined %}
{{ buckets[0] }}
{% endif %}
3. Loop through all the values ​​in the list
To loop through the values ​​in the list buckets
, you must use the JINJA control structure, the "Loop for
". To display all the items, declare a variable, for example bucket
in the for loop to loop through the items added to the list. Use the following expression:
{% for [variable] in [input_list_name] %}
- list_item1: {{ variable }}
- list_item2: {{ variable }}
- list_item3: {{ variable }}
- list_item4: {{ variable }}
- list_item5: {{ variable }}
- list_item6: {{ variable }}
- list_itemN: {{ variable }}
{% endfor %}
Example:
{% for bucket in buckets %}
- bucket.description: {{ bucket.description }}
- bucket.number: {{ bucket.number }}
- bucket.encrypted: {{ bucket.encrypted }}
- bucket.region: {{ bucket.region }}
- bucket.region_bkp: {{ bucket.region_bkp }}
- bucket.bucket_requerido_object.selected: {{ bucket.bucket_requerido_object.selected }}
- bucket.bucket_requerido_object.type: {{ bucket.bucket_requerido_object.type }}
{% endfor %}
JINJA on inputs of type required-connection
Consider the following example, it is a Connection Interface aws-s3-conn
required in a Plugin.
inputs:
- label: Select the connection for required_bucket_object
type: required-connection
name: required_bucket_object
connection-interface-type: aws-s3-conn
You should use the following expressions to access a Connection in two situations:
1. Access Connection data
This data is the name and type of the Connection used:
Make sure to perform a JINJA check to confirm the existence of this variable before querying its position.
Use the expressions:
{% if required_connection_name is defined %}
{{ required_connection_name.selected }}
{% endif %}
{% if required_connection_name is defined %}
{{ required_connection_name.type }}
{% endif %}
Example:
- Connection name:
{{ required_bucket_object.selected }}
- Connection type:
{{ required_bucket_object.type }}
2. Accessing Connection outputs (Only during Deployment)
You can only access this data during the Application deployment, which requires the Connection used in the Plugin. Each type of Connection has its own outputs, check the outputs of the aws-s3-conn
type Connection:
Output | Type | Description |
---|---|---|
arn | String | ARN |
bucket_name | String | AWS Bucket name. |
To access these values, use the following expressions for each one:
Make sure to perform a JINJA check to confirm the existence of this variable before querying its position.
{% if required_connection_name is defined %}
{{ required_connection_name.connection.connection_output }}
{% endif %}
Example:
- required_bucket_object
arn
:
{% if required_bucket_object is defined %}
{{ required_bucket_object.connection.arn }}
{% endif %}
- required_bucket_object
bucket_name
:
{% if required_bucket_object is defined %}
{{ required_bucket_object.connection.bucket_name }}
{% endif %}
Informing the value of an input as a parameter
In pipeline executions, the interactive mode of terminal commands available with the STK CLI cannot be used. To execute a command, you must specify all the required parameters, including the inputs. To do this, you need to provide both the input and its corresponding value as parameters.
Consider the following example, the snippet of a Plugin that has the following inputs:
# Other Plugin infos.
# ...
inputs:
- type: text
name: text_input
label: "Type some text:"
- type: bool
name: boolean_input
label: "Do you want to run optional job?"
- type: required-connection
name: some_s3_connection
label: "Give an alias for required S3 connection"
connection-interface-type: aws-s3-conn
When applying the Plugin or creating an Application that uses this Plugin. These inputs must be informed as follows:
After using the command and its parameters, use the syntax --input_name input value
.
stk apply plugin example-inputs --input_name input value
Example:
For the inputs highlighted in the Plugin excerpt, the values ​​informed as parameters are:
Inputs:
-
text_input
; -
boolean_input
; -
some_s3_connection
.
Input value filled as parameter:
stk apply plugin studio/stack/plugin-example-inputs --text_input "Text between quotes (string)" --boolean_input true --some_s3_connection s3_backup_logs
For Actions and Plugins commands you can also use the --inputs-json parameter to inform the inputs in JSON format:
stk apply plugin studio/stack/plugin-example-inputs --inputs-json '{"text_input": "Text between quotes (string)", "boolean_input": "true", "some_s3_connection": "s3_backup_logs"}'