Skip to main content

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.

info

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:

TypesValue
textString.
textareaString.
boolBoolean.
intInteger.
passwordEncrypts the entered value` (string)
selectLists the values, allowing only 1 value (string) to be chosen.
multiselectLists the values, allowing to choose 1 or more values ​​(string).
listList of inputs of the same type (text, int, object, and required-connection).
objectStores a set of inputs within an object, making the object a parent input with a set of child inputs.
required-connectionStores a set of inputs required to connect to an Infrastructure inside an object.
generated-connectionStores a set of inputs required to create an Infrastructure inside an object.
tip

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.

danger

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:

Example of an IAM role with permissions to access an S3 bucket in AWS using the text input type.
{ "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:

Example of an IAM role with permissions to access an S3 bucket in AWS using the textarea input type.
{
"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
tip

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 ("****").

warning
  • 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 the password 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

Attention!

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:

Example of using condition in an input that accesses a list item at index 0
condition:
variable: input_list_2[0].input_text_1_from_input_object
operator: "=="
value: "ok"

Input of type object

danger

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.

Example of an input of type object representing an object with a simple set of inputs
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
Example of an object type input representing a complex set of inputs
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

danger

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

danger

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.

warning

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.

Do not use this example in your project. This example is for demonstration purposes only on how to fill in the source field.
- 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 and notContainsAll.

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:

Input list with objects
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"
warning

You must use double quotes for the following operators: "==", "!=", ">", ">=", "<", "<=".

Click here to see more details about operators:
OperatorDescription
==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.
containsAnyValidates if the variable of list or text type contains any of the values contained in value.
containsAllValidates if the variable of the type list contains all the values contained in value.
containsOnlyValidates if the variable list type contains all the values in value and no other elements.

value

Value used for evaluation.

info

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.

info

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:

info

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:

info

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:

info

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:

info

Make sure to perform a JINJA check to confirm the existence of this variable before querying its position.

Use the expressions:

Example to access the 'name' of the connection
{% if required_connection_name is defined %}
{{ required_connection_name.selected }}
{% endif %}
Example to access the 'type' of the connection
{% 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:

OutputTypeDescription
arnStringARN
bucket_nameStringAWS Bucket name.

To access these values, use the following expressions for each one:

info

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"}'

Next steps