Pular para o conteúdo principal

Criar Plugin

Nesta seção, você encontra um guia de como criar Plugins de App e de Infra.

Pré-requisitos

Atenção!
  • O Plugin será empacotado e compactado, e o pacote compactado deve ter, no máximo, 14MB.
  • O limite do nome do Plugin é de 60 caracteres.

Você pode criar Plugins do tipo 'Aplicação' (app) ou 'Infraestrutura' (infra), confira a seguir como criá-los, as diferenças entre eles e como editar o seus conteúdos.

Dica!
  1. Um Plugin adiciona novas capacidades a uma Aplicação. Você pode criar e aplicar Plugins em diferentes seções do Portal da StackSpot.
  2. Já um Starter é útil para que os criadores de Stack definam dentro da própria Stack combinações comuns de Plugins.

Criar Plugin de App

Diagrama mostrando os passos para criar e publicar um Plugin e Starter na StackSpot. Passo 1: Criar um Plugin de App. Passo 2: Editar o arquivo YAML do Plugin. Passo 3: Adicionar seus arquivos na pasta templates. Passo 4: Aplicar o Plugin para teste local. Passo 5: Publicar o Plugin. Passo 6: Criar ou acessar uma Stack. Passo 7: Adicionar Plugins à Stack. Passo 8: Criar um StarterDiagrama mostrando os passos para criar e publicar um Plugin e Starter na StackSpot. Passo 1: Criar um Plugin de App. Passo 2: Editar o arquivo YAML do Plugin. Passo 3: Adicionar seus arquivos na pasta templates. Passo 4: Aplicar o Plugin para teste local. Passo 5: Publicar o Plugin. Passo 6: Criar ou acessar uma Stack. Passo 7: Adicionar Plugins à Stack. Passo 8: Criar um Starter

Criar Plugin de Infra

Diagrama mostrando os passos para criar e publicar um Plugin de Infraestrutura na StackSpot. Passo 1: Criar um Plugin de Infraestrutura. Passo 2: Editar o arquivo YAML do Plugin. Passo 3: Adicionar seus arquivos na pasta templates. Passo 4: Aplicar o Plugin para teste local. Passo 5: Publicar o Plugin. Passo 6: Criar ou acessar uma Stack. Passo 7: Adicionar Plugins à Stack. Passo 8: Criar um StarterDiagrama mostrando os passos para criar e publicar um Plugin de Infraestrutura na StackSpot. Passo 1: Criar um Plugin de Infraestrutura. Passo 2: Editar o arquivo YAML do Plugin. Passo 3: Adicionar seus arquivos na pasta templates. Passo 4: Aplicar o Plugin para teste local. Passo 5: Publicar o Plugin. Passo 6: Criar ou acessar uma Stack. Passo 7: Adicionar Plugins à Stack. Passo 8: Criar um Starter

Confira os detalhes:

Passo 1. Criar a estrutura do Plugin no STK CLI

Execute o comando:

stk create plugin

Responda as perguntas no seu terminal:

- Nomeie seu Plugin: Informe um nome único para o seu Plugin;

- Iniciar um repositório git: Informe Sim (Y) ou Não (N) para adicionar um repositório local.

- Adicionar remote: Informe Sim (Y) ou Não (N). Se sim, informe a URL do repositório remoto.

- Descrição do Plugin: Adicione uma descrição para o Plugin;

- Versão: Informe uma versão para o seu Plugin, a versão deve seguir o formato de versionamento semântico (Ex.: 0.0.1);

- O tipo do Plugin: Escolha entre App ou Infra;

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

- Connection gerada: (Apenas Plugins do tipo 'Infra') Informe Sim (Y) ou Não (N). (Se quiser adicionar uma Connection, confira a lista de Connections).

Você também pode passar todos as opções acima diretamente pela linha de comando utilizando as flags do comando. Confira as opções disponíveis para o comando stk create app.

Passo 2. Confira os arquivos que foram gerados

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

/application-plugin-type
/docs #required
/templates #required
/templates/README.md #optional
plugin.yaml #required
  • No arquivo docs você consegue preencher a documentação para o seu Plugin;
  docs:
pt-br: docs/pt-br/docs.md
en-us: docs/en-us/docs.md
Dica!

Confira um guia de Markdown com um template de como documentar o seu Plugin. Esse conteúdo ficará disponível no Portal da StackSpot quando você publicar o seu Plugin.

  • Na pasta /templates estão os arquivos que você deseja gerar ao aplicar o seu Plugin;
  • Em /templates-deploy (Apenas Plugins do tipo 'Infra'), semelhante a pasta templates, estão os arquivos IaC (Terraform) que deseja gerar ao aplicar o seu Plugin.
  • Os arquivos README.md e README-deploy.md são opcionais. Devem conter um breve resumo do que encontrar dentro do seu Plugin.
  • O arquivo plugin.yaml é o que constitui o seu Plugin, nele estão todas as informações do Plugin e configurações que você deve adicionar.

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

schema-version: v3
kind: plugin
metadata:
name: my-app-plugin-name
display-name: my-app-plugin-name
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: Type name of your resource
name: resource
type: text
required: true
default: Client
pattern: '([A-Z][a-z]+)+'
help: 'Inform your resource name (e.g.: Client)'
- label: Choose http method of new endpoint
name: method
type: select
items:
- GET
- POST
- PUT
- DELETE
- PATCH
default: GET
required: true
help: 'Inform the method of the endpoint (e.g.: post or delete)'

Passo 3. Configurar/Editar o seu Plugin no plugin.yaml

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

Usar Inputs

Você pode usar os inputs no seu Plugin para criar as interações do seu Plugin 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 os valores obtidos de um Plugin em outros Plugins ou acessar os dados de outros Plugins. Confira a documentação dos inputs avançados.

Usar Jinja

Jinja é uma linguagem de template que a engine da StackSpot usa para dar mais poder de uso e flexibilidade aos seus Plugins. 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 do seu Plugin, principalmente nos códigos adicionados na pasta /template, código IaC (Terraform) na pasta /templates-deploy, nos inputs do Plugin entre outros arquivos. Acesse a documentação do uso de Jinja na StackSpot.

Usar Hooks Declarativos

Use os Hooks Declarativos para definir ações a serem executadas em momentos específicos da aplicação do seu Plugin.

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;
  • Antes de interpolar os templates Jinja para a geração dos arquivos;
  • Depois de gerar os arquivos.

Existem diversos Hooks Declarativos com ações específicas, consulte os tipos e como usar na documentação de Hooks Declarativos.

Usar variáveis como valores de inputs

Na StackSpot você pode atribuir como valor de um input uma variável. Isso permite que você use as variáveis criadas em sua Conta ou as variáveis que a StackSpot disponibiliza.

Para saber como usar essas variáveis em seus inputs, acesse a página sobre Variáveis na StackSpot.

Usar Connections Interfaces

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.

As Connections possuem campos que são preenchidos ao criar um recurso de cloud durante a implantação da infraestrutura gerada pelos Plugins. Esses campos variam de acordo com o tipo da Connection.

Você deve usar as Connections em dois momentos nos seus Plugins:

1. Requerer Connections

Plugins do tipo 'Aplicação' (app) e 'Infraestrutura' (infra) podem requerer uma Connection. Isso significa que no momento em que ele for usado, o Plugin precisa usar uma Connection do mesmo tipo que foi gerada por um Plugin de Infraestrutura.

Exemplo de Plugin que requer uma Connection-Interface
inputs:
- label: Select the connection for my-ecs-task
type: required-connection
name: my-ecs-task
connection-interface-type: ecs-task-conn

2. Gerar Connections

Apenas Plugins do tipo 'Infraestrutura' (infra) podem gerar Connections. Quando um Plugin de Infraestrutura que gera uma Connection é utilizado, ele gera uma Connection com os campos necessários para gerar o recurso de cloud do tipo da Connection.

Exemplo de Plugin que gera uma Connection-Interface
generates:  
connections:
- type: aws-iam-role-conn
alias: sqs-access-iam-role
outputs:
- from: sqs-access-iam-role-arn
to: arn

Mapear outputs de uma IaC (Terraform)

Ao criar um Plugin do tipo 'Infraestrutura' (infra) que gera Connections, ele gera uma Connection com os campos necessários para gerar o recurso de cloud do tipo da Connection Interface. Para gerar a Connection, você precisa criar o seu código IaC (Terraform) com os dados para gerar o recurso ou usar um código pronto. Em seguida, mapear os 'outputs' do seu arquivo Terraform para os 'outputs' equivalentes da Connection Interface.

A opção outputs têm duas opções:

  • from (spec.generates.connections[n].outputs[n].from): No campo from você deve inserir o identificador do output do Terraform;

  • to (spec.generates.connections[n].outputs[n].to): O atributo da Connection que deve ser preenchido pelo atributo do output informado do Terraform.

'From' and 'to' options of Connection output
#...
spec:
type: infra
#...
generates:
connections:
- type: <connection-name>
alias: <connection-alias>
outputs:
- from: <terraform-output-name>
to: <connection-attribute>
Atenção!

Para cada output do Terraform você deve preencher os campos from e to para cada Connection.

Identificar os outputs do Terraform

Os atributos de cada output são declarados usando um bloco "output":

outputs.tf
output "instance_ip_addr" {
value = aws_instance.server.private_ip
}

O campo logo depois do output é o seu nome/identificador. O argumento value possui uma expressão onde o resultado é retornado para o usuário. O exemplo acima se refere ao atributo private_ip exposto por um recurso aws_instance definido em outro lugar no mesmo módulo Terraform.

Outros argumentos não obrigatórios podem estar presentes, como description, sensitive, entre outros.

Para o exemplo acima, o valor que precisa ser mapeado para o campo from da Connection deve ser o nome/identificador do output, o instance_ip_addr.

Exemplo do output

O exemplo a seguir demonstra um arquivo Terraform para gerar AWS bucket S3 sendo mapeado para a Connection do tipo aws-s3-conn. Para mapear todos os atributos necessários do campo to da Connection, consulte os outputs da Connection.

outputs.tf
output "aws-s3-bucket-name" {
value = aws_s3_bucket.{{ name }}.id
}
output "aws-s3-arn" {
value = aws_s3_bucket.{{ name }}.arn
}
/infra-plugins/my-s3-infra-plugin/plugin.yaml
generates:
connections:
- type: aws-s3-conn
alias: aws-s3-conn-alias270920231735
outputs:
- from: aws-s3-arn
to: arn
- from: aws-s3-bucket-name
to: bucket_name

Você pode adicionar links aos seus Plugins de Aplicação (app) ou Infraestrutura (infra). Os links adicionam um redirecionamento para ferramentas externas como documentações dos seus Plugins ou outro tipo de serviço.

Você também pode usar variáveis para compor um link dinâmico com os dados dos recursos gerados pelo seu Plugin, use para informar os recursos de forma dinâmica para serviços externos.

Confira a documentação de links estáticos e dinâmicos.

No campo spec.generates do seu Plugin, adicione o campo links. Cada link deve ter os seguintes parâmetros:

  • name: Nome do Plugin;
  • url: URL do link;
  • type: Use o tipo static;
  • picture: logotipo para o link.

Exemplo:

spec:
generates:
links:
- name: "AWS Cloud Watch monitoring"
url: "https://console.aws.amazon.com/cloudwatch/home"
type: static
picture: "/logos/aws-ico.png"

No campo spec.generates do seu Plugin, adicione o campo links. Cada link deve ter os seguintes parâmetros:

  • name: Nome do Plugin;
  • url: URL do link com variáveis em expressões Jinja;
  • type: Use o tipo dynamic;
  • picture (Opcional): logotipo para o link.
spec:
generates:
links:
- name: "Database Management Status"
url: "url: https://{{connections.test-alias-dynamo-conn.arn}}/{{inputs.resource}}/{{inputs.method}}/{{var.STK_ENV}}}/status"
type: dynamic
picture: "imgs/db_status_ico.png"

Passo 4. Adicionar seus arquivos na pasta templates

  • Na pasta /templates você deve adicionar todos os arquivos que você deseja gerar ao aplicar o seu Plugin;
  • Em /templates-deploy (Apenas Plugins do tipo 'Infra'), semelhante a pasta templates, você deve adicionar os arquivos IaC (Terraform) que deseja gerar ao aplicar o seu Plugin.

Passo 5. Validar o Plugin

Valide os dados que você está informando no arquivo plugin.yaml enquanto você customiza o seu Plugin. O comando mostra se o seu arquivo possui algum erro e alerta quais os campos que você precisa corrigir ou adicionar novas informações.

Execute o comando dentro da pasta do seu Plugin:

stk validate plugin
Cuidado!

A StackSpot não fornece suporte para os arquivos Markdown. Erros podem ocorrer durante a validação de um Plugin por conta de alguns caracteres utilizados no Markdown. Esses erros ocorrem devido à diferença de encoders (por exemplo: UTF-8) utilizados nos diferentes sistemas operacionais. Caso você se depare com algum erro no Markdown, identifique o caractere causador do erro e o substitua.

Antes de prosseguir, você precisa corrigir todos os erros que o comando informar.

Passo 6. Aplicar o Plugin

Esse é um teste local para Plugins de Aplicação. Aplique seu Plugin com o comando:

stk apply plugin your-plugin-directory-path

Na pasta onde você executou o comando para aplicar o Plugin, serão renderizados os arquivos da pasta templates.

Dica!

Ao aplicar Plugins em um fluxo de trabalho (workflow) de uma pipeline, os comandos não usam o 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 6.1. Aplicar plugin de Infraestrutura

Esse é um teste local para Plugins de Infraestrutura. Aplique o seu Plugin seguindo os passos a seguir:

  1. Acesse o seu Workspace:
stk use workspace your-workspace-name
  1. Execute o comando para aplicar o Plugin com o parâmetro --deploy:
stk apply plugin your-infra-plugin-directory-path --deploy environment-name

O STK CLI consulta os dados de Connections Interfaces do seu Workspace para utilizar na renderização dos arquivos de Infraestrutura (arquivos Terraform) localmente. Na pasta onde você executou o comando para aplicar o Plugin, serão renderizados os arquivos da pasta templates-deploy.

Simular dados da Connection Interface com o parâmetro --deploy

Você pode simular os dados de uma Connection Interface que não exista no seu Workspace para testar um Plugin de Infraestrutura com o parâmetro --deploy. Para simular os dados siga os passos abaixo:

  1. No diretório que você pretende aplicar o Plugin, crie um arquivo JSON com o nome stk-local-context.json;
  2. Neste arquivo, adicione uma lista de objetos com o nome connectors conforme o exemplo a seguir:
Arquivo JSON de exemplo para a configuração do 'stk-local-context.json'
{
// Objeto raiz
"connectors": [
// Lista de Connections Interfaces
{
"connector": "my-sns",
"type": "aws-sns-conn",
"pluginName": "studio-test/stack-test/plugin-teste@1.0.0",
// Objeto com os outputs da Connection Interface
"attributes": {
"topic_name": "topic-123",
"arn": "arn-123"
}
},
{
"connector": "my-s3",
"type": "aws-s3-conn",
"pluginName": "studio-test/stack-test/plugin-test@1.0.0",
// Objeto com os outputs da Connection Interface
"attributes": {
"arn": "arn-1232",
"bucket_name": "bucket-teste"
}
}
]
}
  • Objeto raiz: o JSON deve começar com o objeto raiz com a chave "connectors". O valor de "connectors" é uma lista de objetos, onde cada objeto representa uma Connection Interface.
{
"connectors": [...]
}
  • Lista de Connections Interfaces: cada item da lista é um objeto com as seguintes propriedades:

    • "connector": valor equivalente ao nome dado para uma Connection Interface.

    • "type": tipo da Connection Interface.

    • "pluginName": simula o Plugin que gera a Connection, a sintaxe é: studio-slug-name/stack-name/plugin-name@plugin-version.

    • "attributes": objeto JSON onde cada propriedade simula cada output da Connection Interface gerada:

      • "output_name1": "output_value1"
      • "output_name2": "output_value2"
      • "output_nameN": "output_valueN"

Para mais informações sobre as Connections Interfaces, consulte os tipos e seus outputs disponíveis na StackSpot.

Passo 7. Publicar Plugin

Se você já possui um Estúdio, publique o seu Plugin no Portal da StackSpot.

Publique seu Plugin

Passo 8. Criar/Acessar a Stack e adicionar o seu Plugin

Crie uma Stack e adicione seus Plugins nela.

Seu Plugin está pronto!

Próximos passos