Pular para o conteúdo principal

Hooks Declarativos

Nesta seção, você aprenderá o que são Hooks Declarativos, como defini-los e como utilizar execução condicional.

Sobre Hooks Declarativos

Os Hooks Declarativos definem ações que devem ser executadas em momentos específicos durante a aplicação de um Plugin.

Uso em Plugins de Infraestrutura

Sim, você pode utilizar Hooks Declarativos em Plugins de Infraestrutura. No entanto, eles são executados apenas no momento da aplicação do Plugin, e não durante o processo de deploy da infraestrutura.

Quando você cria uma Infraestrutura e realiza o deploy via Portal da StackSpot, o sistema executa os comandos stk apply plugin e, em seguida, stk apply plugin deploy de forma transparente. Os Hooks ocorrem apenas na primeira etapa.

Momento de execução na StackSpot

Os Hooks Declarativos executam quando o Plugin é aplicado em uma Aplicação ou Infraestrutura.

  1. Criação da Aplicação: O deploy ainda não ocorreu. Os Hooks Declarativos funcionam normalmente para configurar o projeto.
  2. Comando stk deploy app: Neste momento, o Plugin já foi aplicado e é utilizado apenas para gerar os arquivos Terraform. Os Hooks Declarativos não são executados nesta etapa, pois eles rodam apenas durante a criação.

O processo de aplicação de um Plugin possui duas fases principais:

  • Fase 1: Coleta dos parâmetros de entrada (inputs) do usuário.
  • Fase 2: Interpolação de templates Jinja com os valores informados para gerar os arquivos.

Você pode configurar os Hooks para executar ações em três momentos distintos:

  • before-input: Antes de solicitar os parâmetros de entrada.
  • before-render: Antes de interpolar os templates Jinja e gerar os arquivos.
  • after-render: Após a geração dos arquivos.

A imagem a seguir ilustra o ciclo de renderização de Templates e Plugins:

Fluxograma horizontal descrevendo os 8 passos do ciclo de execução de um Plugin, desde o carregamento do plugin.yaml até o merge de arquivos.Fluxograma horizontal descrevendo os 8 passos do ciclo de execução de um Plugin, desde o carregamento do plugin.yaml até o merge de arquivos.

Detalhamento do fluxo:

  1. Carregamento do arquivo de configuração (plugin.yaml);
  2. Execução dos Hooks com gatilho before-input;
  3. Solicitação dos inputs definidos na configuração ao usuário;
  4. Cálculo dos computed-inputs;
  5. Execução dos Hooks com gatilho before-render;
  6. Renderização dos templates Jinja (pasta templates do Plugin);
  7. Execução dos Hooks com gatilho after-render;
  8. Merge de arquivos, caso existam no destino.
informação

Os parâmetros informados pelo usuário no passo 3 são tratados como variáveis. Você pode utilizá-los em expressões Jinja nos templates de geração de arquivos e em configurações específicas do Plugin.

Como definir um Hook Declarativo

Você deve definir os Hooks Declarativos no arquivo de configuração plugin.yaml.

Confira um exemplo de configuração:

schema-version: v4
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?utm_source=stackspot
    - 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
informação

Você pode definir múltiplos Hooks em um único Plugin.

Gatilhos (Trigger)

O atributo trigger define o momento exato em que o Hook Declarativo será executado. Utilize um dos valores a seguir:

  • before-input: Executa antes da inserção dos parâmetros de entrada.
  • before-render: Executa antes da interpolação dos templates Jinja.
  • after-render: Executa após a geração dos arquivos.

Condições

Você pode controlar a execução de um Hook Declarativo através do atributo opcional condition. Para criar uma condição, defina os três elementos:

  1. Uma variável (variable);
  2. Um operador (operator);
  3. Um valor de referência (value).

As variáveis disponíveis são aquelas definidas nos inputs e computed-inputs do Plugin.

No exemplo a seguir, o Hook verifica se o input language é igual a java. Se verdadeiro, o Plugin gera os arquivos dos templates localizados na pasta templates-java.

hooks:
  - type: render-templates
    trigger: after-render
    path: templates-java
    condition:
      variable: language
      operator: "=="
      value: java

Operadores disponíveis

  • "==": Valida se os valores são iguais.
  • "!=": Valida se os valores são diferentes.
  • ">": Valida se a variável é maior que o valor.
  • "<": Valida se a variável é menor que o 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 (lista) contém qualquer um dos valores definidos em value.
    • Se value não for uma lista, é tratado como uma lista de elemento único.
    • Se value for vazio, retorna false.
  • containsAll: Valida se a variável (lista) contém todos os valores definidos em value.
    • Se value não for uma lista, é tratado como uma lista de elemento único.
    • Se value for vazio, retorna true.
  • containsOnly: Valida se a variável (lista) é uma permutação exata dos itens em value.
Atenção!

É obrigatório o uso de aspas duplas para os operadores de comparação: "==", "!=", ">", ">=", "<" e "<=".

Tipos de Hooks Declarativos

A tabela a seguir apresenta os tipos de Hooks disponíveis e suas funcionalidades.

Tipo de HookO que faz
Executar comandos de terminal (run)Executa comandos de terminal.
Executar scripts Python (run-script)Executa scripts Python referenciados no plugin.yaml.
Editar arquivos de texto (edit)Define alterações em arquivos de texto genéricos existentes.
Editar arquivos XML (edit-xml)Define alterações estruturadas em arquivos XML existentes.
Editar arquivos JSON (edit-json)Define alterações estruturadas em arquivos JSON existentes.
Editar arquivos YAML (edit-yaml)Define alterações estruturadas em arquivos YAML existentes.
Gerar arquivos com templates (render-templates)Executa a geração condicional de arquivos baseada em templates.
Transformar código-fonte (code-transformation)Permite inserir, remover e modificar trechos de código-fonte.