O que é Action

Nesta seção, você encontra as estrutura e quais são os tipos de Actions.

Sobre Actions

Na StackSpot, Actions são uma estrutura que dão inteligência para scripts executarem automações de forma local em sua máquina. É possível usar inputs e arquivos que interagem com o seu script para automatizar algum processo, ou até mesmo facilitar processos burocráticos da sua organização.

Além de criar as suas Actions, é possível publicá-las e distribuí-las em sua organização para que todos sigam o mesmo tipo de processo da automação que a Action executa.

Actions são executadas apenas pelo STK CLI, e podem conter por exemplo, scripts que executam:

Integrações com outros sistemas através da StackSpot;
A execução de tarefas e comandos na máquina da pessoa desenvolvedora.

Tipos de Actions

Os tipos de Action são definidos pelo atributo --type em sua estrutura, mas a principal diferença entre os tipos estão nos atributos específicos do campo spec: em cada tipo de Action.

Confira nas seções a seguir os tipos de Actions e os atributos específicos para cada uma.

Shell Actions

Actions do tipo shell possuem em sua especificação um objeto shell com os seguintes atributos:

workdir: Pasta onde a Action deve ser executada;
requirements-check: Verificação de dependências para mapear se todos os requisitos para executar a Action estão presentes;
- check-command: Atributo presente em cada verificação. Define e executa o comando que verifica a dependência;
- info: Mensagem de erro exibida caso o comando executado retorne falha na verificação da dependência;
script: Define os comandos que serão executados no shell do sistema operacional. Podem ser definidos comandos diferentes para cada sistema operacional suportado, os sistemas suportados são Linux, MacOs e Windows.

Confira um exemplo:

Exemplo com um trecho da especificação de uma Action do tipo 'shell' do arquivo action.yaml
spec: 
  type: shell
# ... other spec attributes ...
  shell: # shell object
    workdir: .
    requirements-check:
      - check-command:
          linux: |
            git --version
          mac: |
            git --version
          windows: |
            git --version
        info: "Git is not installed!"
    script:
      linux: |
        echo "Hello {{inputs.user_name}}!"
      mac: |
        echo "Hello {{inputs.user_name}}!"
      windows: |
        echo "Hello {{inputs.user_name}}!"

Para scripts mais complexos com ações condicionais e interpolação de muitos valores, você precisa interpolar esses valores primeiro em um arquivo para depois executar o script da Action. Considere o script a seguir:

Script shell 'flag.sh' de exemplo que demonstra o cenário em que o script não será executado no corpo da Action.
if [ ! -z "{{inputs.verbose}}" ]; then
    echo "STK DEPLOY PLAN FLAGS = $FLAGS"
fi
$HOME/.stk/bin/stk use workspace {{ inputs.workspace }}

FLAGS=$(echo "--env {{ inputs.environment }} --version {{ inputs.version_tag }}")

if [ ! -z "{{ inputs.branch }}" ]; then
  FLAGS=$(echo "$FLAGS --branch ${{ inputs.branch }}")
fi

if [ ! -z "{{ inputs.open_api_path }}" ]; then
  FLAGS=$(echo "$FLAGS --open-api-path ${{ inputs.open_api_path }}")
fi

if [ ! -z "{{ inputs.dynamic_inputs }}" ]; then
  FLAGS=$(echo "$FLAGS {{ inputs.dynamic_inputs }}")
fi

if [ ! -z "{{ inputs.verbose }}" ]; then
  echo "STK DEPLOY PLAN FLAGS = $FLAGS"
fi

$HOME/.stk/bin/stk deploy plan $FLAGS

Para executar esse script, a sua Action precisa de inputs para capturar e interpolar os valores em um arquivo (pode ser um arquivo de texto ou script). A Action vai precisar:

Que você crie a pasta "templates".
Adicione um arquivo de texto ou script shell e coloque o script neste arquivo.
Edite os inputs da sua Action que correspondam com o script shell ou adicione as expressões JINJA no script que correspondam com os inputs da Action.
Use a propriedade component_path no campo script da Action. Esta propriedade possui a seguinte sintaxe:

Sintaxe do uso do 'component_path' na Action do tipo shell.
{{component_path}}/[file_path]

A Action terá a seguinte estrutura:

Estrutura da pasta de uma Action com a pasta 'templates/*.txt, *.sh'
.
├── action.yaml
├── docs
│   ├── en-us
│   │   └── docs.md
│   └── pt-br
│       └── docs.md
└── templates
    └── flag.sh

Exemplo de Action com 'component_path' para executar scripts shell complexos.
schema-version: v3
kind: action
metadata:
  name: flag-script
  display-name: flag-script
  description: Test flag script
  version: 1.0.0
spec:
  type: shell
  docs:
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  inputs:
    - label: Verbose Mode
      name: verbose
      type: bool
      required: false
    - label: Workspace
      name: workspace
      type: text
      required: true
    - label: Environment
      name: environment
      type: text
      required: true
    - label: Version Tag
      name: version_tag
      type: text 
      required: true  
    - label: Branch
      name: branch
      type: text
      required: false
    - label: Open API Path
      name: open_api_path
      type: text
      required: false
    - label: Dynamic Inputs
      name: dynamic_inputs
      type: text   
      required: false
  shell:
    workdir: .
    script:
      linux: cat {{ component_path }}/flag.sh
      mac: cat {{ component_path }}/flag.sh
      windows: type {{ component_path }}/flag.sh

Confira mais detalhes sobre o component_path em Conteúdo de templates e metadados da Action.

Python Actions

Actions do tipo python possuem em sua especificação um objeto python com os seguintes atributos:

Exemplo com um trecho da especificação de uma Action do tipo 'python' do arquivo action.yaml
spec: 
  type: python
# ... other spec attributes ...
  python: # python object
    workdir: .
    script: script.py

workdir: Pasta onde a Action deve ser executada;
script: Caminho para o script Python que será executado.

Estrutura de arquivos e metadados de uma Action

Quando você cria uma Action, uma estrutura inicial é gerada para que você possa desenvolver o script da sua Action.

A Action possui uma pasta com o nome que foi fornecido na sua criação e um arquivo de configuração, o arquivo action.yaml. Além de arquivos específicos para o tipo de Action escolhido.

Estrutura de arquivos

O exemplo ilustra uma Action com todas as variações dos tipos possíveis de estrutura de arquivos.

~ ➜ my-action-name-folder  
├── templates
├── docs
├── action.yaml  
├── script.py  
└── Dockerfile  

A estrutura de uma Action é gerada pelo STK CLI, com o comando stk create action suportando os seguintes tipos de estrutura definidos pelo parâmetro --type:

Exemplos de cada estrutura de arquivo por tipo:

Para testar, execute em seu terminal o comando stk create action para criar cada um dos tipos de Actions e confira a estrutura gerada por cada um.

Action do tipo shell
Action do tipo python

stk create action shell-action --type shell

~ ➜  shell-action  
└── action.yaml  

stk create action python-action --type python

~ ➜  python-action  
├── action.yaml  
└── script.py  

Metadados da Action (arquivo `action.yaml`)

O arquivo de configuração ou metadados de uma Action é o action.yaml. Nele estão descritas todas as informações sobre a Action.

Esse arquivo pode mudar de acordo com o tipo da Action, pois existem alguns dados específicos para cada tipo.

Exemplo da estrutura do action.yaml básico de uma Action do tipo python
schema-version: v3
kind: action
metadata:
  name: python-action-test
  display-name: python-action-test
  description: Describe your action explaining its purpose.
  version: 1.0.0
spec:
  type: python
  docs:
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  inputs:
    - label: What is your name?
      name: user_name
      type: text
      required: false
      pattern: '^[A-Za-z]+(?:\s[A-Za-z]+)*$'
      help: 'Inform your name'
  python:
    workdir: .
    script: script.py

As Actions possuem em sua estrutura quatro atributos principais que são obrigatórios para todas as Actions além dos atributos comuns:

Principais Atributos da Action
Atributos comuns da especificação da Action

Início de um arquivo action.yaml
schema-version: v3
kind: action
metadata:
  name: my-action
  display-name: my-action
  description: python action test
  version: 1.0.0
spec:
# ... other action specs ...

schema-version: Versão da especificação;
kind: Sempre possui o valor action;
metadata: Metadados comuns;
- name: Nome da Action;
- display-name (Opcional): Nome Action que será apresentado ao usuário no Portal;
- description: Descrição da Action informando o seu propósito;
- version: Versão da Action;
- picture (Opcional): Imagem exibida no Portal para representar a Action publicada.

Especificações comuns do arquivo action.yaml
# ... other action attributes ...
spec: 
  type: python
  docs:
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  repository: https://github.com/some-org/my-action
  inputs:
    - label: Connection Interface for my bucket-1
      name: bucket-1
      type: required-connection
      connection-interface-type: aws-s3-conn
    - label: Who are you?
      name: user_name
      type: text
      required: false
      pattern: '([A-Z][a-z]+)+'
      help: 'Inform your name'
  python:
    workdir: .
    script: script.py
# ... type dependent structure ...                

type: Tipo da Action, podendo ser:
- shell
- python
docs: Caminho para os arquivos Markdown com os conteúdos das documentações em português e inglês da Action no Portal;
requires (Opcional): Defina as Connection Interfaces que a Action depende.

Informação Adicional

Quando você for criar uma Action para associá-la a um Plugin de Infra, você precisa selecionar aqui pelo menos uma das Connection Interfaces gerada pelo Plugin. Para saber mais, acesse os guias:

inputs (Opcional): Define os inputs de entrada da Action. São permitidos os mesmos inputs dos Plugins;
repository (Opcional): Endereço do repositório Git onde o código fonte da Action está hospedado para exibição no Portal.

Próximos Passos

Para mais informações sobre Actions, acesse os guias: