Migrate Plugin and Action Manifest

In this section, you will learn how to migrate from the v2 to the v3 version of the Plugin and Action manifests.

What has changed?

StackSpot has improved Connection Interfaces to offer greater flexibility when creating Actions and Plugins that need this feature. This update currently impacts Connection Interfaces declared in the requires field, and will eventually extend to those declared in the generates field of the manifest. Here are the key changes:

Schema Version

The manifest schema version is now v3:

Example of Plugin in schema v2
schema-version: v2
kind: plugin
metadata:
  name: plugin-v2-manifest
  display-name: plugin-v2-manifest
  description: Describe your plugin explaining its purpose.
  version: 0.0.1
spec:
  type: app
  compatibility:
    - python
  docs:
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  single-use: False
  technologies: # Ref: https://docs.stackspot.com/create-use/create-content/yaml-files/plugin-yaml/#technologies-1
    - Api
  stk-projects-only: false

Example of Plugin in schema v3 (also valid for Actions)
schema-version: v3
kind: plugin
metadata:
  name: plugin-v3-manifest
  display-name: plugin-v3-manifest
  description: Describe your plugin explaining its purpose.
  version: 0.0.1
spec:
  type: app
  compatibility:
    - python
  docs:
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  single-use: False
  technologies: # Ref: https://docs.stackspot.com/create-use/create-content/yaml-files/plugin-yaml/#technologies-1
    - Api
  stk-projects-only: false

New Input Types

In order to increase the flexibility of using Connection Interfaces in Actions and Plugins, it was necessary to modify their behavior to make them optional and controllable by the conditional action capacity of the inputs. As part of this change, three new input types were created:

These inputs are only available for schema-version: v3 of Actions and Plugins.

Using the Connection Interface as input enables the following usage:

Example of conditional usage of a Connection Interface
- type: required-connection
  name: bucket_s3
  label: Escolha o bucket s3 que ativará a função lambda
  connection-interface-type: aws-s3-conn
  condition:
    variable: s3_triggered
    operator: ==
    value: true

And its use as input flag:

--bucket_s3 my-bucket-2

These inputs are only available for schema-version: v3 of Actions and Plugins.

Using Connection Interfaces as Input in the v3 Schema

The behavior of Connection Interfaces has not changed, but their declaration within Plugins and Actions in the new version has been modified. See the changes below:

schema-version: v2
kind: plugin
metadata:
  name: plugin-v2-manifest
  display-name: boolean-plugin-test
  description: Describe your plugin explaining its purpose.
  version: 0.0.1
spec:
  type: app
  compatibility:
    - python
  docs:
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  single-use: False
  technologies: # Ref: https://docs.stackspot.com/create-use/create-content/yaml-files/plugin-yaml/#technologies-1
    - Api
  stk-projects-only: false
  requires:
  connections:
    - type: ecs-task-conn
      alias: my-ecs-task-conn

The previous Plugin had a Connection Interface ecs-task-conn. In v3, it is no longer in the scope of the requires: field and becomes an input:

schema-version: v3
kind: plugin
metadata:
  name: plugin-v3-manifest
  display-name: boolean-plugin-test
  description: Describe your plugin explaining its purpose.
  version: 0.0.1
spec:
  type: app
  compatibility:
    - python
  docs:
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  single-use: False
  technologies: # Ref: https://docs.stackspot.com/create-use/create-content/yaml-files/plugin-yaml/#technologies-1
    - Api
  stk-projects-only: false
  inputs:
    - label: Define task in ECS
      type: required-connection
      name: my-ecs-task-conn
      connection-interface-type: ecs-task-conn

The Connection Interface as input now has:

label: This is a field to add text that guides the completion of the Connection.
type: Currently only required-connection is available, eliminating the need to declare the Connection in the requires manifest field.
name: The name you define to identify the use of your Connection. It behaves like the alias field of the v2 manifest.
connection-interface-type: It defines the type of Connection interface used. It is the same behavior as the type field of the v2 manifest.

How to use Connection in Action scripts

Consider the following Action:

schema-version: v3
kind: action
metadata:
  name: action-nested-b1
  display-name: action-nested-b1
  description: Describe your action explaining its purpose
  version: 0.0.5
spec:
  type: python
  docs:
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  inputs:
    - label: Select the Bucket s3
      type: required-connection
      name: my-s3
      connection-interface-type: aws-s3-conn
  python:
    workdir: .
    script: script.py

To use the Action data in your scripts, you must follow the syntax:

metadata.inputs.varname
metadata.varname

# if you are executing within a Jinja template, the metadata term is omitted.

{{ inputs.varname }}
{{ varname }}

script.py example
def run(metadata):
    print(f"Hello {metadata.inputs['my-s3']['connection']['bucket_name']}")

For more details, see the using metadata in Python scripts page.

How to use Connections in Inputs

Consider the following Plugin:

schema-version: v3
kind: plugin
metadata:
  name: plugin-nested-b1
  display-name: plugin-nested-b1
  description: Describe your plugin explaining its purpose
  version: 0.0.6
  picture: plugin.png
spec:
  type: app
  compatibility:
    - python
  docs:
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  single-use: False
  technologies: # Ref: https://docs.stackspot.com/create-use/create-content/yaml-files/plugin-yaml/#technologies-1
    - Api
  stk-projects-only: false
  inputs:
    - label: Select the Bucket s3
      type: required-connection
      name: my-s3
      connection-interface-type: aws-s3-conn

To use the Plugin data in the templates folder, you must follow the syntax in your inputs:

Use the syntax for Jinja variables:

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:

{% if required_bucket_object is defined %}
{{ required_bucket_object.selected }}
{% endif %}

Connection type:

{% if required_bucket_object is defined %}
{{ required_bucket_object.type }}
{% endif %}

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:

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 name:

{% if required_bucket_object is defined %}
{{ required_bucket_object.connection.bucket_name }}
{% endif %}

To use input variables with hyphens, you must call them as {{inputs["my-var"]}}. Alternatively, you can also call them as: {{myvar}} or {{inputs.myvar}}.

Examples:

Bucket Name: {{inputs["my-s3"]["connection"]["bucket_name"]}}
Arn: {{my_s3.connection.arn}}
Required Connection: {{my_s3}}

For more details, access all information about Inputs on StackSpot

Changes in Plugin Tests

The manifest files for Plugin test cases have been updated to accommodate new input types. It's important to note that Plugin testing has remained the same despite these updates. For more details, check the guide about Plugin testing.

1. Change in schema version from v1 to v2

Example of the Plugin test case manifest in v1
schema-version: v1
kind: test
spec:
  type: plugin
  mode: apply
  inputs: {}
  inputs-envs: {}
  requires:
    connections: []
  generates:
    connections: []

Example of the Plugin test case manifest in the new version v2
schema-version: v2
kind: test
spec:
  type: plugin
  mode: apply
  inputs: {}
  inputs-envs: {}
  generates:
    connections: []

2. Test required-connection as input

The requires.connections field has been removed, so required connection interfaces are now reported as inputs. Check out the plugin examples and their test cases below:

Example of Plugin v2 with 'requires.connections'
schema-version: v2
kind: plugin
metadata:
  name: plugin-infra
  display-name: plugin-infra
  description: My description
  version: 1.0.0
  picture: plugin.png
spec:
  type: infra
  ...
  requires:
    connections:
      - type: aws-s3-conn
        alias: bucket-s3
  inputs: []
  inputs-envs: []

Example test case for Plugin v2 'requires.connections'
schema-version: v1
kind: test
spec:
  type: plugin
  mode: deploy
  inputs: {}
  inputs-envs: {}
  requires:
    connections:
      - type: aws-s3-conn
        selected: my-bucket-s3
        alias: bucket-s3
        outputs:
          arn: "my-bucket-arn"
          bucket_name: "my-bucket-project"
  generates:
    connections: []

Next, see the same previous Plugin and test case with the updated manifests, respectively.

Example of Plugin v3 with the new type of input 'required-connection'
schema-version: v3
kind: plugin
metadata:
  name: plugin-infra
  display-name: plugin-infra
  description: My description
  version: 1.0.0
  picture: plugin.png
spec:
  type: infra
  ...
  inputs:
    - label: Select the connection for s3
      name: bucket-s3
      type: required-connection
      connection-interface-type: aws-s3-conn
  inputs-envs: []

Example test case for Plugin v3 input type 'required-connection'
schema-version: v2
kind: test
spec:
  type: plugin
  mode: deploy
  inputs:
    bucket-s3:
      selected: my-bucket-s3
      outputs:
        arn: "my-bucket-arn"
        bucket_name: "my-bucket-project"
  inputs-envs: {}
  generates:
    connections: []

Understand the use of input:

Snippet from input required-connection
inputs:
    - label: Select the connection for s3
      name: bucket-s3
      type: required-connection
      connection-interface-type: aws-s3-conn

label: text that guides the user in selecting a connection.
name: name of the input that identifies the connection.
type: type of input.
connection-interface-type: type of connection interface that will be used.

Fill in the inputs field of the test case as follows:

In input_name:, as highlighted in the previous example, you must fill in the name: value of the required-connection input for your Plugin. Then:

selected: enter any name to simulate the name that the user adds when using the connection.
outputs: see the page about Connection Interfaces to add the name of each output of the Connection Interface used:

Syntax to complete the required-connection type input test
inputs:
  input_name:
    selected: my-bucket-s3
    outputs:
      output_name1: "my-bucket-arn"
      output_name2: "my-bucket-project"
inputs-envs: {}
generates:
  connections: []

3. Test inputs of type `object` that require a connection

Example of Plugin v3 that requires a connection within an input of type object.
schema-version: v3
kind: plugin
metadata:
  name: plugin-infra
  display-name: plugin-infra
  description: My description
  version: 1.0.0
  picture: plugin.png
spec:
  type: infra
  compatibility:
    - python
  docs:
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  justification: My justification
  single-use: False
  runtime:
    environment:
      - terraform-1-4
      - aws-cli-2
      - git-2
  repository: https://github.com
  technologies: # Ref: https://docs.stackspot.com/create-use/create-content/yaml-files/plugin-yaml/#technologies-1
    - Api
  stk-projects-only: false
  inputs:
    - label: Data of deploy
      type: object
      name: data
      inputs:
        - label: Type the command will be executed at deploy
          type: text
          required: true
          name: command-to-deploy
        - label: Select the connection for s3-deploy
          type: required-connection
          name: s3-deploy
          connection-interface-type: aws-s3-conn
        - label: Select the connection for sns-rollback
          type: required-connection
          name: sns-rollback
          connection-interface-type: aws-sns-conn
        - label: Type the command will be executed at rollback
          type: text
          required: true
          name: command-to-rollback
  inputs-envs: []

The test file will be:

Previous Plugin v3 test case example
schema-version: v2
kind: test
spec:
  type: plugin
  mode: apply
  inputs:
    data:
      command-to-deploy: "deploy s3"
      s3-deploy:
        selected: mybuket-s3
        outputs:
          arn: "s3-arn"
          bucket_name: "s3-bucket"
      command-to-rollback: "rollback sns"
      sns-rollback:
        selected: my-sns
        outputs:
          arn: "mysns-arn"
          topic_name: "mysns-topic"
  inputs-envs: {}
  generates:
    connections: []

4. Testing input of type `list` that requires a connection

Example of Plugin v3 that requires a connection inside an input of type list.
schema-version: v3
kind: plugin
metadata:
  name: plugin-infra
  display-name: plugin-infra
  description: My description
  version: 1.0.0
  picture: plugin.png
spec:
  type: infra
  compatibility:
    - python
  docs:
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  justification: My justification
  single-use: False
  runtime:
    environment:
      - terraform-1-4
      - aws-cli-2
      - git-2
  repository: https://github.com
  technologies: # Ref: https://docs.stackspot.com/create-use/create-content/yaml-files/plugin-yaml/#technologies-1
    - Api
  stk-projects-only: false
  inputs:
    - label: Data of deploy
      type: object
      name: data
      inputs:
        - label: Type the command will be executed at deploy
          type: text
          required: true
          name: command-to-deploy
        - label: Buckets
          type: list
          name: s3s-deploy
          add-question: "Add s3?"
          input:
            label: Select the connection for s3-deploy
            type: required-connection
            connection-interface-type: aws-s3-conn
  inputs-envs: []