Pular para o conteúdo principal

Migrar manifesto de Plugins e Actions

Nesta seção, você encontra:como migrar a versão v2 para a v3 dos manifestos de Plugins e Actions.


O que mudou?

A StackSpot aprimorou o uso de Connection Interfaces, trazendo mais flexibilidade ao criar Actions e Plugins que requerem esse recurso. Esta mudança afeta atualmente as Connections Interfaces declaradas no campo requires e futuramente será aplicada às declaradas no campo generates do manifesto. Confira a seguir as principais mudanças:

Versão do schema

A versão do schema do manifesto passa a ser v3:

Exemplo de Plugin no 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
Exemplo de Plugin no schema v3 (válido também para 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

Novos tipos de inputs

Para flexibilizar o uso de Connections Interfaces em Actions e Plugins, foi necessário alterar o comportamento das Connection Interfaces para um tipo de input. Com essa mudança, o uso da Connection Interface pode ser opcional e controlado pela capacidade de ações condicionais dos inputs. Para se adequar a essa abordagem, três novos tipos de inputs foram criados:

Utilizar a Connection Interface como input possibilita o seguinte uso:

Exemplo de uso condicional de uma 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

E o seu uso como input flag:

--bucket_s3 my-bucket-2

Estes inputs estão disponíveis apenas para o schema-version: v3 de Actions e Plugins.

Uso de Connections Interfaces como input no schema v3

O comportamento das Connection Interfaces não foi alterado, mas a sua declaração dentro dos Plugins e Actions na nova versão foi modificada. Confira as mudanças a seguir:

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

O Plugin anterior possuía uma Connection Interface ecs-task-conn. Na v3, ela deixa de estar no escopo do campo requires: e passa a ser um 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

A Connection Interface como input agora possui:

  1. label: um campo para adicionar um texto que oriente o preenchimento da Connection.
  2. type: atualmente está disponível apenas o required-connection, eliminando a necessidade de declarar a Connection no campo requires do manifesto.
  3. name: nome que você define para identificar o uso da sua Connection. É o mesmo comportamento do campo alias do manifesto v2.
  4. connection-interface-type: define o tipo da Connection interface utilizada. É o mesmo comportamento do campo type do manifesto v2.

Como usar Connection em scripts da Action

Considere a seguinte 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

Para utilizar os dados da Action em seus scripts, você deve seguir a seguinte sintaxe:

metadata.inputs.varname
metadata.varname

# caso esteja executando dentro de template jinja o termo metadata fica omitido.

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

Para mais detalhes, consulte o uso de metadata em scripts Python.

Como usar Connections em Inputs

Considere o Plugin a seguir:

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

Para utilizar os dados do Plugin na pasta templates, você deve seguir a seguinte sintaxe nos seus inputs:

Use a sintaxe para variáveis Jinja:

Considere o exemplo a seguir. Ele representa uma Connection Interface aws-s3-conn requerida em um Plugin.

inputs:
- label: Select the connection for required_bucket_object
type: required-connection
name: required_bucket_object
connection-interface-type: aws-s3-conn

Use as expressões a seguir para acessar uma Connection em duas situações:

1. Acessar dados da Connection

Esses dados são o nome e o tipo da Connection utilizada:

Informação Complementar

Faça uma verificação do JINJA para confirmar se essa variável existe antes de consultar uma posição dentro dela.

Use as expressões:

Exemplo para acessar o 'name' da connection
{% if required_connection_name is defined %}
{{ required_connection_name.selected }}
{% endif %}
Exemplo para acessar o 'type' da connection
{% if required_connection_name is defined %}
{{ required_connection_name.type }}
{% endif %}

Exemplo:

  • 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. Acessar os outputs da Connection (Apenas no Deploy)

Esses dados são acessados apenas durante o deploy da Aplicação que requer a Connection utilizada no Plugin. Cada tipo de Connection possui os seus outputs, confira os outputs da Connection do tipo aws-s3-conn:

OutputTypeDescrição
arnStringARN da Amazon.
bucket_nameStringNome do Bucket da AWS.

Para acessar esses valores, use as expressões a seguir para cada um:

Informação Complementar

Faça uma verificação do JINJA para confirmar se essa variável existe antes de consultar uma posição dentro dela.

{% if required_connection_name is defined %}
{{ required_connection_name.connection.connection_output }}
{% endif %}

Exemplo:

  • 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 %}

Para usar variáveis de input que possuem hífen, você deve fazer a chamada como {{inputs["my-var"]}}. Caso contrário, a chamada é feita normalmente, como: {{myvar}} ou {{inputs.myvar}}.

Exemplos:

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

Para mais detalhes, acesse todas as informações sobre os Inputs na StackSpot

Mudanças nos testes de Plugins

Com a adição dos novos tipos de inputs, o manifesto dos arquivos dos casos de testes dos Plugins também foi atualizado. O teste de Plugins não sofreu alteração em seu uso, para mais detalhes, confira o guia sobre os teste de Plugins.

1. Mudança na versão schema de v1 para v2

Exemplo do manifesto do caso de teste de Plugin na v1
schema-version: v1
kind: test
spec:
type: plugin
mode: apply
inputs: {}
inputs-envs: {}
requires:
connections: []
generates:
connections: []
Exemplo do manifesto do caso de teste de Plugin na nova versão v2
schema-version: v2
kind: test
spec:
type: plugin
mode: apply
inputs: {}
inputs-envs: {}
generates:
connections: []

2. Testar required-connection como input

Com a remoção do campo requires.connections as connections interfaces requeridas agora são informadas como inputs. A seguir estão os exemplos dos Plugins e seu caso de teste:

Exemplo de Plugin v2 com '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: []
Exemplo do caso de teste para 'requires.connections' do Plugin v2
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: []

A seguir, confira o mesmo Plugin e os casos de teste anteriores com os manifestos atualizados, respectivamente.

Exemplo de Plugin v3 com o novo tipo de 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: []
Exemplo do caso de teste para o input do tipo 'required-connection' do Plugin v3
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: []

Entenda o uso do input:

Trecho do input required-connection
inputs:
- label: Select the connection for s3
name: bucket-s3
type: required-connection
connection-interface-type: aws-s3-conn
  • label: texto que orienta o usuário a selecionar uma connection.
  • name: nome do input que identifica a connection.
  • type: tipo do input.
  • connection-interface-type: tipo da Connection Interface que será usada.

Preencha o campo inputs do caso de teste da seguinte forma:

Em input_name: você deve preencher o valor do name: do input required-connection do seu Plugin, destacado no exemplo anterior. Em seguida:

Sintaxe para preencher o teste do input do tipo required-connection
inputs:
input_name:
selected: my-bucket-s3
outputs:
output_name1: "my-bucket-arn"
output_name2: "my-bucket-project"
inputs-envs: {}
generates:
connections: []

3. Testar inputs do tipo object que requerem uma connection

Exemplo de Plugin v3 que requer uma connection dentro de um input do tipo 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: []

O arquivo de teste será:

Exemplo de caso de teste do Plugin v3 anterior
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. Testar input do tipo list que requer uma connection

Exemplo de Plugin v3 que requer uma connection dentro de um input do tipo 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
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: []

O arquivo de teste será:

Exemplo de caso de teste do Plugin v3 anterior
schema-version: v2
kind: test
spec:
type: plugin
mode: apply
inputs:
data:
command-to-deploy: "deploy s3"
s3s-deploy:
- selected: my-s3
outputs:
arn: "mys3-arn"
bucket_name: "mys3-bucket"
- selected: other-s3
outputs:
arn: "my-other-arn"
bucket_name: "my-other-bucket"
- selected: my-last-s3
outputs:
arn: "last-s3-arn"
bucket_name: "last-s3-bucket"
inputs-envs: {}
generates:
connections: []