Hooks Declarativos
Nesta seção você encontra: Como definir e quais são os tipos de Hooks Declarativos. Como executar condicional de um Hook Declarativo.
Sobre Hooks Declarativos
Os Hooks Declarativos são uma forma de definir ações a serem executadas em momentos específicos da aplicação de Plugin.
É possível trabalhar com Hooks Declarativos em Plugins de infraestrutura?
Sim, é possível usar Hooks Declarativos em Plugins de Infraestrutura, mas eles são executados apenas no momento da aplicação do Plugin, não durante o deploy. Quando você cria a Infraestrutura e faz o deploy pela interface da StackSpot, o sistema executa o comando stk apply plugin
e depois o stk apply plugin deploy
de maneira oculta.
Quando os Hooks Declarativos são executados na StackSpot?
Os Hooks Declarativos são executados no momento da aplicação do Plugin na Aplicação ou Infraestrutura. Quando você cria a Aplicação, o deploy ainda não é feito, e os Hooks Declarativos funcionam normalmente. No entanto, quando você executa o comando stk deploy app
, o Plugin já está aplicado e é usado apenas para gerar os arquivos Terraform, e nesse momento os Hooks Declarativos não são executados. Eles executam apenas durante a criação da Aplicação ou Infraestrutura.
A aplicação do Plugin possui duas fases distintas:
Fase 1. Perguntar ao usuário os parâmetros de entrada.
Fase 2. Interpolar os templates Jinja usando os valores informados pelo usuário para gerar arquivos.
Você pode executar as ações definidas nos Hooks Declarativos:
- Antes de inserir os parâmetros de entrada (before-input)
- Antes de interpolar os templates Jinja para a geração dos arquivos (before-render)
- Depois de gerar os arquivos (after-render)
Confira a seguir o Ciclo de renderização de Templates e Plugins:
Os parâmetros de entrada informados pelo usuário no passo 3 são usados como variáveis, elas podem ser usadas em expressões Jinja tanto nos templates usados para geração de arquivos, quanto em alguns pontos da configuração dos Plugins.
Definir um Hook Declarativo
As definições dos Hooks Declarativos de Plugin podem ser feitas no arquivo de configuração plugin.yaml, conforme o exemplo:
schema-version: v3
kind: plugin
metadata:
name: Declarative Hooks Plugin example
display-name: Declarative Hooks Plugin example
description: My Plugin with Declarative Hooks
version: 3.0.0
spec:
type: app
compatibility:
- python
docs:
pt-br: docs/pt-br/docs.md
en-us: docs/en-us/docs.md
technologies: # Ref: https://docs.stackspot.com/create-use/create-content/yaml-files/plugin-yaml/#technologies-1
- React
- Web
- JavaScript
hooks:
- type: run
trigger: before-input
working-dir: "{{project_name}}"
commands:
- echo plugin-python before-input!
- type: run-script
trigger: before-render
script: script.py
- type: edit
trigger: after-render
path: src/some-file.txt
changes:
- insert:
line: 0
value: "# Text inserted in first line\n\n"
when:
not-exists: "# Text inserted in first line"
- search:
string: "# Text inserted in first line"
insert-before:
snippet: snippets/insert-before-first-line.txt
when:
not-exists: "# Text inserted before first line"
- search:
pattern: (Text )inserted in( first line)
replace-by:
value: \1moved from\2
when:
not-exists: print(f"Hello {name}!")
- type: render-templates
trigger: after-render
path: templates-java
condition:
variable: language
operator: "=="
value: java
É possível definir vários hooks em um mesmo Plugin.
Gatilhos (Trigger)
Os gatilhos dos Hooks Declarativos são definidos pelo atributo trigger
e indicam em que momento o Hook Declarativo irá executar, podendo assumir um dos seguintes valores:
before-input
: Antes de inserir os parâmetros de entrada.before-render
: Antes de interpolar os templates Jinja para a geração dos arquivosafter-render
: Após gerar os arquivos.
Condições
A execução de um Hook Declarativo pode ser condicional e é controlada pelo atributo opcional condition
. Você deve definir uma condição com:
1. Uma variável (variable
);
2. Um operador (operator
);
3. Em seguida, o valor de referência (value
).
As variáveis acessíveis são as definidas pelos inputs computed-inputs
do Plugin. No trecho de exemplo apresentado, é verificado se o valor do input language
é igual à string java
. Em caso positivo, são gerados os arquivos definidos pelos templates que estão na pasta templates-java
.
hooks:
- type: render-templates
trigger: after-render
path: templates-java
condition:
variable: language
operator: "=="
value: java
Os operadores disponíveis para condições são:
"=="
: Valida se os valores são iguais."!="
: Valida se os valores são diferentes.">"
: Valida se a variável é maior ao valor."<"
: Valida se a variável é menor ao valor.">="
: Valida se a variável é maior ou igual ao valor."<="
: Valida se a variável é menor ou igual ao valor.containsAny
: Valida se a variável do tipo lista contém qualquer um dos valores contidos emvalue
. Sevalue
não for do tipo lista, considera-se uma lista ondevalue
é o único elemento. Sevalue
é uma lista vazia, false (falso) é retornado.containsAll
: Valida se a variável do tipo lista contém todos os valores contidos emvalue
. Sevalue
não for do tipo lista, considera-se uma lista ondevalue
é o único elemento. Sevalue
é uma lista vazia, true (verdadeiro) é retornado.containsOnly
: Valida se a variável do tipo lista é uma permutação dos itens devalue
. Sevalue
não for do tipo lista, considera-se uma lista ondevalue
é o único elemento.
Você deve usar aspas duplas para os seguintes operadores: "=="
, "!="
, ">"
, ">="
, "<"
, "<="
.
Confira os tipos de Hooks Declarativos:
Tipos de Hooks | O que fazem |
---|---|
run | Executam alguns comandos. |
run-script | Executam scripts Python, dentro de um arquivo plugin.yaml . |
edit | Definem alterações feitas em arquivos existentes. |
edit-xml | Definem alterações feitas em arquivos XML existentes. |
edit-json | Definem alterações feitas em arquivos JSON existentes. |
edit-yaml | Definem alterações feitas em arquivos YAML existentes. |
render-templates | Executam a geração condicional de arquivos. |
code-transformation | Permite inserir, remover e modificar qualquer código fonte. |
📄️ run
Nesta seção, você encontra: Referência de um Hook Declarativo do tipo run.
📄️ run-action
O Hook Declarativo do tipo run-action permite executar Actions de uma Stack quando um Plugin é aplicado em uma Aplicação ou Infraestrutura.
📄️ run-script
Nesta seção, você encontra: Referência de um Hook Declarativo do tipo run-script.
📄️ edit
Nesta seção, você encontra: Referência de um Hook Declarativo do tipo edit.
📄️ edit-xml
Nesta seção, você encontra: Referência de um Hook Declarativo do tipo edit-xml.
📄️ edit-json
Nesta seção, você encontra: Referência de um Hook Declarativo do tipo edit-json.
📄️ edit-yaml
Nesta seção, você encontra: Referência de um Hook Declarativo do tipo edit-yaml.
📄️ render-templates
Nesta seção você encontra: Referência de um Hook Declarativo do tipo render-templates.
🗃️ code-transformation
4 itens