Pular para o conteúdo principal

Criar Action

Nesta seção, você encontra um guia de como criar uma Action usando o STK CLI.


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.

Pré-requisitos

  • STK CLI instalado.
  • Ter permissão para criar e publicar no Estúdio.
Atenção!
  • O arquivo da Action deve ter, no máximo, 14MB.
  • O limite do nome da Action é de 60 caracteres.

Passo 1. Criar uma Action

Você pode criar Actions pelo CLI da StackSpot (STK CLI). Por padrão, toda Action possui um escopo local e só pode ser executada pelo STK CLI, mas você também pode configurar a Action em sua Conta e executá-la remotamente.

Confira os passos

Criar uma aplicação via o Portal da StackSpot.Criar uma aplicação via o Portal da StackSpot.

Para criar a estrutura inicial da sua Action, execute o comando stk create action e responda no terminal as perguntas a seguir:

stk create action

- Nomeie sua Action: Informe um nome para a sua Action;

- Adicionar repositório: Informe Sim (Y) ou Não (N). (Se você já possuir um repositório, em seguida adicione a URL do repositório remoto. Se não, a Action é criado no diretório atual);

- Descrição da Action: Adicione uma descrição para a Action;

- Versão: Informe uma versão para a sua Action. Use o valor que preferir para a versão da sua Action. Desde que você use o formato de versionamento semântico, por exemplo 1.0.0 ou 3.1.0;

- Selecione o tipo da Action: Escolha entre Python ou Shell;

- Connection requerida: Informe Sim (Y) ou Não (N). (Para adicionar uma Connection, confira a lista de Connections);

Informação Adicional

Quando você 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 o guia:

Confira os arquivos que foram gerados

Acesse a pasta da Action que você acabou de criar e confira os arquivos que foram gerados:

/my-python-action
/docs #required
/templates # optional
action.yaml #required
script.py # required
  • Na pasta /templates você deve adicionar quaisquer arquivos ou scripts que possam ser executados ou complementares ao tipo da sua Action.

Você deve criar a pasta /templates.

  • Na pasta /docs estão os arquivos Markdown para você preencher as documentações para a sua Action;

  • O arquivo action.yaml é o que constitui o seu Plugin, nele estão todas as informações do Plugin e configurações que você deve adicionar.

  • O arquivo script.py é gerado em Actions do tipo Python, é um script de exemplo para você editar ou substituir pelo seus próprios scripts.

Após criar o seu Plugin, você terá um dos exemplos:

schema-version: v3
kind: action
metadata:
  name: my-python-action
  display-name: my-python-action
  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: Who are you?
      name: user_name
      type: text
      required: false
      pattern: '([A-Z][a-z]+)+'
      help: 'Inform your name'
  python:
    workdir: .
    script: script.py
  • python.workdir: Pasta onde a Action deve ser executada.
  • python.script: Caminho para o script Python que será executado.

Passo 2. Editar a sua Action

Após criar a Action, dependendo das opções escolhidas a sua Action pode ser diferente dos exemplos apresentados acima. Os aquivos action.yaml gerados ao criar a Action possuem apenas o básico para uma Action e alguns campos de exemplo. Você deve editar alguns conteúdos do campo spec: para começar a usar a sua Action. Confira as principais mudanças que você pode fazer.

Usar Inputs

Você pode usar os inputs na sua Action para criar as interações da sua Action com a pessoa desenvolvedora pelo terminal. Os inputs podem direcionar escolhas ou obter valores de forma condicional.

O seu uso é opcional, confira a documentação de todos os tipos e uso dos Inputs.

Inputs avançados

Os inputs avançados além de interagir com a pessoa desenvolvedora pelo terminal, também podem interagir com inputs de outros Plugins.

Você pode usar na sua Action os valores obtidos de um Plugin em outros Plugins ou acessar os dados de outros Plugins. Confira a documentação dos inputs avançados

Action metadata

Metadata é um objeto criado durante a execução de um Plugin e Actions. Ele contém diversos valores que te auxiliam na execução de outros processos ou automações. Confira os exemplos na documentação de Metadata

Usar Jinja

Jinja é uma linguagem de template que a engine da StackSpot usa para dar mais poder de uso e flexibilidade aos seus Plugins e Actions. Como a maioria das linguagens de templates, permite através de marcações específicas em um texto, a definição de expressões que são interpoladas pela engine para renderizar o resultado final.

Você pode usar Jinja em diversas partes da sua Action, principalmente nos códigos adicionados na pasta /templates. Acesse a documentação do uso de Jinja na StackSpot.

Exemplos de uso dentro do python com Actions

from templateframework.metadata import Metadata

def run(metadata: Metadata = None):
  print('# list your project name', metadata.inputs['var']['STK_PROJECT_NAME'])
  print('# list your Stack name', metadata.inputs['var']['STK_STACK'])
  print('# list your Studio name', metadata.inputs['var']['STK_STUDIO'])
  print('# list your Workspace name', metadata.inputs['var']['STK_WORKSPACE'])

Usar Connections Interfaces

Atenção!

O campo de input connections é importante se você quiser associar uma Action a um Plugin de Infra.

A Action tem que requerer pelo menos uma Connection Interface que o Plugin de Infra gera para que você consiga associá-lo a ele. Acesse o guia Associar Action a Plugin de Infra para ver mais informações.

A StackSpot possui Connections Interfaces para estabelecer todos os dados que um recurso de cloud precisa ter para ser conectável. As Connections Interfaces são separadas por tipos de recurso de cloud onde cada tipo gera uma Connection.

Durante a execução de uma Action, ela pode depender de uma connection. O exemplo a seguir destaca no corpo da Action de tipo Python a dependência com uma connection:

Exemplo de arquivo action.yaml de uma Action tipo Python

schema-version: v3
kind: action
metadata:
  name: some-kebab-case-name
  description: some description
  display-name: Some display name
  version: 1.0.1
  picture: images/plugin.png
spec:
  type: python
  docs:
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  inputs:
    - label: Connection label for connection name
      name: Name of your connection
      type: required-connection
      connection-interface-type: connection_type
  python:
    workdir: another/random/path
    script: random_name/a_cool_name.py

Exemplo do arquivo script.py

def run(metadata):
    print(f"Arn: {metadata.inputs.get('some-type__alias__arn')}")
    print(f"Name: {metadata.inputs.get('some-type__alias2__name')}"

Usar template dentro da Action (Opcional)

Antes de executar uma Action, você pode utilizar valores pré-definidos e scripts para serem utilizados na sua execução. Para isso você deve criar a pasta templates dentro da sua Action e nela colocar os arquivos desejados para compor a Action.

Confira o exemplo a seguir de uma Action do tipo shell utilizando o conteúdo da pasta templates:

Conteúdo da Action

user/project-actions/my-shell-action
➜  my-shell-action
.
├── action.yaml
├── docs
│   ├── pt-br: docs/pt-br/docs.md
│   ├── en-us: docs/en-us/docs.md
└── templates
    └── name-value.txt
Informação Adicional

Você deve criar a pasta templates dentro da Action. Adicione quaisquer arquivos ou scripts que possam ser executados ou complementares ao tipo da sua Action.

Conteúdo de templates e metadados da Action

Arquivo de texto name-value.txt contém os valores que serão utilizados pela Action antes da sua execução.

my-shell-action/templates/name-value.txt
Hello {{full_name}} !

O arquivo action.yaml contém os inputs que irão coletar os valores que serão interpolados no arquivo name-value.txt para serem utilizados na Action.

No action.yaml você deve usar a pasta component_path para conseguir renderizar o conteúdo interpolado dos seus arquivos ou scripts da pasta templates junto aos conteúdos da Action.

A sintaxe utilizada para o component_path é:

{{component_path}}/[file_path]
Informação Adicional
  • Quantidade de arquivos na pasta templates: Use quantos arquivos você quiser.
  • Exemplos de component_path: Confira exemplos e saiba mais em Metadata.
  • Inputs Avançados: Saiba mais sobre o computed-inputs e outros em inputs avançados.
  • Interpolar valores: Aprenda mais sobre o interpolar valores com Jinja na StackSpot.

Passo 3. Executar uma Action (teste local)

Ao executar uma Action, todas as ações definidas nela serão executadas localmente em sua máquina. Porém, existem algumas obervações antes de executar essas Actions localmente, confira a seguir:

Executar Action não publicada

Actions que não foram publicadas podem ser executadas localmente em sua máquina para testar as funções que a Action executa, para isso, execute o comando informando o caminho da pasta da Action:

Execute o comando stk run action.

Exemplo:

stk run action /Users/user.name/my-action-name
Dica!

Ao executar Actions em um fluxo de trabalho (workflow) de uma pipeline, a Action não usa o modo interativo (perguntas dos inputs pelo terminal). Para informar os valores dos inputs você precisa informar o input e o valor como parâmetro. Para mais informações, confira como informar os valores dos inputs como parâmetros.

Passo 4. Validar a Action

Passo 1. Execute o comando stk validate action dentro da pasta da Action.

Dentro da pasta da Action: '/Users/user.name/my-action-name' 
stk validate action

Passo 2. Se a validação executar com sucesso, siga as instruções para publicar a sua Action.

Atenção!

Se retornar algum erro, você precisa corrigi-los e executar a validação novamente.

Próximo passos

📄

Publicar sua Action em um Estúdio

Confira como publicar a sua Action em um Estúdio.

📄

Publicar uma Action com STK CLI

Confira os comandos para publicar uma action via STK CLI.

📄

Associe Actions à Plugins de Infraestrutura

Confira como associar Actions à Plugins de Infra.

📄

Connection Interfaces

Confira mais detalhes sobre as Connections Interfaces.