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
:
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
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:
- 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:
label:
um campo para adicionar um texto que oriente o preenchimento da Connection.type:
atualmente está disponível apenas orequired-connection
, eliminando a necessidade de declarar a Connection no campo requires do manifesto.name:
nome que você define para identificar o uso da sua Connection. É o mesmo comportamento do campoalias
do manifesto v2.connection-interface-type:
define o tipo da Connection interface utilizada. É o mesmo comportamento do campotype
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 }}
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:
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:
{% if required_connection_name is defined %}
{{ required_connection_name.selected }}
{% endif %}
{% 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
:
Output | Type | Descrição |
---|---|---|
arn | String | ARN da Amazon. |
bucket_name | String | Nome do Bucket da AWS. |
Para acessar esses valores, use as expressões a seguir para cada um:
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
schema-version: v1
kind: test
spec:
type: plugin
mode: apply
inputs: {}
inputs-envs: {}
requires:
connections: []
generates:
connections: []
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:
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: []
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.
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: []
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:
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:
- selected: insira um nome qualquer para simular o nome que o usuário adiciona ao usar a connection.
- outputs: consulte a página sobre Connection Interfaces para adicionar o nome de cada output da Connection Interface utilizada:
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
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á:
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
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á:
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: []