Comandos de Plugins

Nesta seção, você encontra a lista de comandos de Plugin.

Comando Descrição
stk add plugin Adiciona um Plugin em uma Stack ou Starter.
stk apply plugin Aplica um Plugin que adiciona novas capacidades em uma aplicação.
stk create plugin Permite criar novos Plugins para a StackSpot.
stk list plugin Lista todos os Plugins dentro de um Workspace.
stk publish plugin Faz a publicação do seu Plugin na StackSpot.
stk remove plugin Remove os Plugins de Infraestrutura do manifesto da sua aplicação ou infraestrutura.
stk show plugin Exibe os detalhes de uma versão específica do Plugin ou da versão mais recente.
stk test plugin Executa os casos de teste do Plugin.
stk update plugin Atualiza Plugins de Infraestrutura aplicados em Aplicações e Infraestruturas do seu Workspace.
stk fork plugin Faz uma cópia do Terraform de um Plugin de Infraestrutura específico.
stk unfork plugin Reverte o fork de um Plugin .
stk validate plugin Valida a estrutura do seu Plugin.

Comando	Descrição
stk add plugin	Adiciona um Plugin em uma Stack ou Starter.
stk apply plugin	Aplica um Plugin que adiciona novas capacidades em uma aplicação.
stk create plugin	Permite criar novos Plugins para a StackSpot.
stk list plugin	Lista todos os Plugins dentro de um Workspace.
stk publish plugin	Faz a publicação do seu Plugin na StackSpot.
stk remove plugin	Remove os Plugins de Infraestrutura do manifesto da sua aplicação ou infraestrutura.
stk show plugin	Exibe os detalhes de uma versão específica do Plugin ou da versão mais recente.
stk test plugin	Executa os casos de teste do Plugin.
stk update plugin	Atualiza Plugins de Infraestrutura aplicados em Aplicações e Infraestruturas do seu Workspace.
stk fork plugin	Faz uma cópia do Terraform de um Plugin de Infraestrutura específico.
stk unfork plugin	Reverte o fork de um Plugin .
stk validate plugin	Valida a estrutura do seu Plugin.

stk add plugin

O comando stk add plugin adiciona um Plugin em uma Stack ou Starter.

Uso

Execute o comando dentro da pasta de uma Stack ou Starter:

stk add plugin [STUDIO-SLUG]/[STACK-NAME-AND-VERSION]/[PLUGIN-NAME]

Exemplo:

stk add plugin techwriter-studio/documentation-stack@1.0.0/react-page-plugin

Parâmetros

Opções	Descrição	Exemplo
`-o`, `--target`	A opção `-o`, `--target` define o caminho do diretório da Stack ou Starter onde o Plugin será adicionado. Caso contrário o comando deve ser executado dentro da pasta da Stack ou do Starter.	stk add plugin my-studio/my-stack@1.0.0/my-plugin --target home/user/Applications/my-other-stack
`-op`,`--optional TEXT`	Preencha para indicar se o Plugin será opcional ou obrigatório no Starter. Use 'true' para opcional e 'false' para obrigatório.	stk add plugin my-studio/my-stack@1.0.0/my-plugin --optional false
`-q`,`--non-interactive`	Não pergunta para o usuário os parâmetros de entrada retornando erro caso algum parâmetro obrigatório não tenha sido fornecido.	stk add plugin studio/stack/plugin --non-interactive
`-h`, `--help`	Exibe a ajuda do comando e sai.	stk add plugin --help

stk apply plugin

O comando stk apply plugin aplica um Plugin que adiciona novas capacidades em uma Aplicação ou novos recursos em uma Infraestrutura.

Uso

stk apply plugin [NOME_OU_CAMINHO]

Parâmetros

Opções	Descrição	Exemplo
`NOME_OU_CAMINHO`	Nome ou caminho da pasta do Plugin que será aplicado. O nome do Plugin deve seguir os seguintes formatos: 1. `<studio>/<plugin-name>[@plugin-version]:` Aplica um Plugin sem utilizar um contexto. Esse formato só pode ser usado quando não houver um Workspace ativo. 2. `<studio>/<stack>[@version]/<plugin-name>`: Aplica um Plugin usando um contexto definido para o Plugin em sua Stack. Esse formato utiliza um Workspace ativo.	Plugin path: stk apply plugin '/Users/my-username/plugins-folder/my-plugin' Sem Workspace: stk apply plugin studio/plugin@1.0.0 Com Workspace ativo: stk apply plugin studio/stack@1.0.0/plugin-name
`--deploy -stk_env`	Opção para aplicar um Plugin de Infraestrutura localmente. Ao informar o caminho local do Plugin de Infraestrutura use a opção `--deploy -stk_env` e o nome do ambiente para obter os dados das Connections Interfaces do seu Workspace para renderizar os arquivos do Plugin. Você precisa estar com um Workspace ativo. Para mais informações, confira como aplicar um Plugin de Infraestrutura	stk apply plugin path-to-my-plugin-folder --deploy environment-name
`-s ou --skip-warning`	Desabilita a advertência exibida quando o Plugin é aplicado fora de uma aplicação criada com a StackSpot.	stk apply plugin account/studio/plugin@1.0.0 --skip-warning
`-ar`, `--automatic-apply-requirements`	Ignora o aviso sobre a aplicação de Plugins requeridos e continua com a aplicação automática de Plugins.	stk apply plugin account/studio/plugin@1.0.0 --automatic-apply-requirements
`-i, --inputs-json`	Parâmetros de entrada no formato JSON. Os inputs precisam ser passados no padrão JSON entre aspas simples.	stk apply plugin studio/stack/plugin --inputs-json '{"input1_name": "Input 1 value", "input2_name": "Input 2 value"}'
`-q`,`--non-interactive`	Não pergunta para o usuário os parâmetros de entrada retornando erro caso algum parâmetro obrigatório não tenha sido fornecido.	stk apply plugin studio/stack/plugin --non-interactive Nesse caso, se algum input ou item necessário como Connection Interface não seja informado o usuário é informado de um erro e não serão feitas perguntas.
`-a`, `--alias`	Nome alternativo para o Plugin. O alias deve começar e terminar com letras minúsculas ou números. Pode ter apenas letras minúsculas, números e o caractere especial hífen `-`. Exemplo: valid-name123	stk apply plugin account/studio/plugin@1.0.0 --alias my-plugin3-alias
`-c`, `--connections`	Informe as Connections requeridas e geradas. As Connections devem seguir o padrão: `[{"alias": "<conn-alias>", "selected": "<selected-conn>"}]`	stk apply plugin studio/stack/plugin --connections '[{"alias": "conn-alias", "selected": "selected-conn"}, {"alias": "another-conn-alias", "selected": "another-selected-conn"}]'
`-sp`, `--spec PATH`	Caminho para o arquivo de especificação contendo os dados de inputs e as connections para o Plugin a ser aplicado.	stk apply plugin --spec Documents/spec-apply-plugin.yaml Para mais informações, confira a documentação do arquivo de especificação (spec file).
`-f`, `--fork`	Ao usar Plugins com Fork, informe o nome do Plugin (alias) que será usado.	stk apply plugin studio/stack@1.0.0/plugin-name --deploy --stk_env development --fork plugin-forked-name-alias123
`-h`, `--help`	Exibe a ajuda do comando e sai.	stk apply plugin --help

stk create plugin

O comando stk create plugin permite criar novos Plugins para a StackSpot.

Quando você executa o comando no terminal, você deve escolher qual tipo que o Plugin deve ser e uma pasta é gerada com a estrutura para criar o Plugin. O usuário deve editar o arquivo plugin.yaml e configurar os parâmetros de entrada do Plugin.

Informação Adicional

A opção -o, --target permite definir um nome de pasta diferente para criar o conteúdo do Plugin. Se a pasta não existir, ela será criada.

Se você não usar a opção -o ou --target, o nome da pasta do conteúdo do Plugin será o mesmo que você deu ao criar o seu Plugin.

Uso

stk create plugin [NOME]

Parâmetros

Opções	Descrição	Exemplo
`-d`, `--description`	Texto que descreve o Plugin e o seu propósito. Escreva o texto entre aspas para usar espaços na descrição	stk create plugin my-plugin --description "Plugin description"
`-v`, `--version`	Adiciona a versão do Plugin. É um dos requisitos para publicar o Plugin	stk create plugin my-plugin --version 1.0.0
`-t`, `--type`	Tipo do Plugin que será criado. Os valores possíveis são app ou infra.	stk create plugin my-plugin --type app
`-j`, `--justification`	Texto com a justificativa para publicar Plugins em contas que possuem governança habilitada.	stk create plugin my-plugin --type app --justification "Text with publishing justification of Plugin"
`-r`, `--remote`	URL Git para definir como origem do repositório do Plugin. Obrigatório quando o NOME não for fornecido, neste caso o NOME será definido como o nome do repositório Git.	stk create plugin --remote my-url-git-repository
`-sgi`, `--skip-git-init`	Use para não iniciar um repositório Git na pasta do Plugin.	stk create plugin my-plugin-name --skip-git-init
`-q`, `--non-interactive`	O comando não vai perguntar por inputs opcionais. Retorna um erro quando um input obrigatório não for informado.	stk create plugin my-plugin --non-interactive
`-st`, `source-type TEXT`	Formato do arquivo utilizado para gerar automaticamente Plugins de Infraestrutura. Formatos aceitos: `terraform`.	stk create plugin plugin-infra-legacy --type infra --source-type terraform --source-path localUser/Documents/infra-iac
`-sp`, `source-path TEXT`	Caminho da pasta com arquivos Terraform.	stk create plugin plugin-infra-legacy --type infra --source-type terraform --source-path localUser/Documents/infra-iac
`-o`, `--target`	A opção `-o`, `--target` permite definir um nome de pasta diferente para criar o conteúdo do Plugin. Se a pasta não existir, ela será criada. Se você não usar a opção `-o` ou `--target`, o nome da pasta do conteúdo do Plugin será o mesmo que você deu ao criar o seu Plugin.	stk create plugin my-plugin --type app --target home/user/Dev-Plugins/my-plugin
`-h`, `--help`	Exibe a ajuda do comando e sai.	stk create plugin --help

stk list plugin

O comando stk list plugin lista os Plugins. Você tem duas opções:

Listar Plugins de um Workspace. Nesse caso, você deve estar dentro de um Workspace, para isso, execute o comando stk use workspace antes de listar os Plugins.
Listar Plugins fora de um Workspace. Aqui, você precisa informar o Estúdio, mas não mostra as Stacks.

Você tem acesso ao nome, tipo, descrição e versão do Plugin. E também avisa se o Plugin está depreciado com a tag 'deprecated'.

Uso

stk list plugin

Parâmetros

Opções	Descrição	Exemplo
`-stu`, `--studio`	Filtra e exibe a listagem dos Plugins por Estúdio	stk list plugin --studio studio-name
`-sta`, `--stack`	Filtra e exibe a listagem dos Plugins por Stack	stk list plugin --stack stack-name
`-t`, `--type`	Tipo do Plugin que será exibido. Os valores possíveis são app ou infra.	stk list plugin --type app`ou`stk list plugin --type infra
`-h`, `--help`	Exibe a ajuda do comando e sai.	stk list plugin --help

stk publish plugin

O comando stk publish faz a publicação do seu Plugin na StackSpot.

Atenção!

Os arquivos listados no .stkignore não serão publicados na StackSpot, mas serão adicionados por commits do Git normalmente caso não sejam ignorados no .gitignore.

Uso

stk publish plugin --studio [TEXTO]

Parâmetros

Opções	Descrição	Exemplo
`-s`, `--studio`	Nome do Estúdio que você quer publicar o Plugin.	stk publish plugin --studio my-studio-name
`-v`, `--verbose`	Exibe as etapas da publicação com detalhes.	stk publish plugin --verbose
`--justification`	Insere o texto de justificativa de uso do Plugin para Estúdios que possuem governança habilitada.	stk publish plugin --studio my-studio-name --justification "my justification text"
`-h`, `--help`	Exibe a ajuda do comando e sai.	stk publish plugin --help

stk remove plugin

O comando stk remove plugin remove os Plugins do tipo infra do manifesto da aplicação ou infraestrutura automaticamente. Pode ser no modo interativo ou não.

Antes de executar o comando você deve:

Fazer o login na sua Conta com o comando stk login.
Executar o comando dentro da pasta do Plugin app ou infra.

Uso

Sintaxe

stk remove plugin [PLUGIN-ALIAS]

Exemplo

stk remove plugin my-plugin-alias

Atenção!

Não é obrigatório adicionar o Alias do Plugin no comando.
Se você não informar o nome do Plugin, a CLI busca no manifesto os Plugins existentes e mostra todas as opções disponíveis para a remoção.
O Plugin que está sendo removido pode ter dependências, mas nenhum outro Plugin pode depender dele.

Parâmetros

Opções	Descrição	Exemplo
`-q`, `--non-interactive`	Não pergunta os parâmetros de entrada, caso você não informar nenhum.	stk remove plugin my-plugin-alias --non-interactive
`-s`, `--skip-warning`	Desabilita a advertência exibida quando o Plugin é removido do manifesto da aplicação.	stk remove plugin my-plugin-alias --skip-warning
`-a`, `--all`	Remove todos os Plugins do tipo infra aplicados em uma Aplicação ou Infraestrutura.	stk remove plugin --all
`-h`, `--help`	Exibe a ajuda do comando e sai.	stk remove plugin --help

stk show plugin

O comando stk show plugin exibe com detalhes as informações de um Plugin específico ou da sua última versão. Não é obrigatório utilizar parâmetros. Ao ser executado o comando já pergunta o Estúdio, Plugin e a versão, não importa se está com Workspace ou não.

As informações apresentadas do Plugin são:

Detalhes do Plugin (Estúdio, tipo, versão, descrição, compatibilidade, tecnologias, repositório, etc).
Inputs
Inputs-envs
Connections geradas
Connections requeridas
Plugins requeridos
Actions requeridas

Uso

Sintaxe

Exemplo sem parâmetro:

stk show plugin
? Selecione o estúdio: example
? Selecione o plugin: plugin-test
? Selecione a versão do plugin: 1.0.0
> Buscando detalhes do plugin.

Exemplo com parâmetro:

stk show plugin [studio-slug]/[plugin-name][@version-number]

Exemplo

stk show plugin my-studio/plugin-example@2.3.0

Para exibir os dados da última versão do Plugin, não informe a versão:

stk show plugin my-studio/plugin-example

Parâmetros

Opções	Descrição	Exemplo
`-ot`, `--output-type`	Especifica o tipo de saída dos dados do Plugin. As opções são `list`, `tree`, ou `all` (ambas as opções)	stk show plugin my-studio/plugin-example -ot list
`-otm`, `--output-table-mode`	Especifica o tamanho da tabela de dados do Plugin. As opções são: `expanded` ou `compact`.	stk show plugin my-studio/plugin-example -otm expanded
`-h`, `--help`	Exibe a ajuda do comando e sai.	stk show plugin --help

stk test plugin

O comando stk test plugin executa os casos de testes de um Plugin. O comando não valida a estrutura do Plugin.

Uso

Dentro da pasta do seu Plugin, execute o comando:

stk test plugin [test-case-name]

Parâmetros

Opções	Descrição	Exemplo
`-m,`, `--mode`	Filtre os casos de testes por modo de execução. Os valores aceitos são `apply` e `deploy`.	Filtrar testes de Plugins de infraestrutura (modo deploy): stk test plugin --mode deploy
`-v`, `--verbose`	Apresenta no terminal mais detalhes da execução dos testes.	stk test plugin my-test-001 -v
`-h`, `--help`	Exibe a ajuda do comando e sai.	stk test plugin --help

stk update plugin

O comando stk update plugin atualiza os Plugins de Infraestrutura, aplicados em Aplicações e Infraestruturas de um Workspace.

Uso

Antes de atualizar um Plugin, acesse um Workspace executando o comando stk use workspace.

Para atualizar os Plugins de Infraestrutura de uma Aplicação ou Infraestrutura, informe o nome do Plugin e a nova versão da Stack com o Plugin atualizado:

stk update plugin [PLUGIN_ALIAS] --to [STUDIO-SLUG]/[STACK-SLUG]@[SEMANTIC-VERSION]/[PLUGIN_ALIAS]

Exemplo:

Considere uma Stack na versão 1.0.0 que possui o Plugin de Infraestrutura aws-sqs-plugin na versão 2.0.0. E uma nova versão desse Plugin foi publicada em uma nova Stack, resultando no Plugin aws-sqs-plugin na versão 2.0.1 e a Stack na versão 1.0.1.

Para atualizar o Plugin de Infraestrutura que uma Aplicação ou Infraestrutura do seu Workspace utilizam, execute o comando:

stk update plugin aws-sqs-plugin --to my-studio-slug/my-stack-slug@v1.0.1/aws-sqs-plugin

Dessa forma a Aplicação ou Infraestrutura terão o Plugin de Infraestrutura aws-sqs-plugin atualizados para a nova versão.

Informação Adicional

Você pode atualizar a versão dos Plugins da versão atual utilizada para qualquer outra versão maior ou menor;
A atualização dos Plugins contém o contexto do seu Workspace, dessa forma os valores definidos no seu Workspace serão preenchidos nos Plugins atualizados;
Preencha todos os inputs, inputs-envs e connections requeridas e geradas caso os valores não venham do contexto do Workspace;
Os inputs, inputs-envs e connections do Plugin estarão preenchidos com os valores anteriores, mas você pode alterá-los, se desejar.

Parâmetros

Opções	Descrição	Exemplo
`-t`, `--to`	Nova versão do Plugin de Infraestrutura que será atualizado na Aplicação ou Infraestrutura que o usam.	stk update plugin my-plugin-name --to my-studio-slug/my-stack-slug@1.1.0/my-plugin-name
`-h`, `--help`	Exibe a ajuda do comando e sai.	stk update plugin --help

stk fork plugin

O comando stk fork plugin faz uma cópia de um Plugin de Infraestrutura que estiver disponível para Fork. Você pode consultar os Plugins disponíveis pelo comando stk show plugin e ter autonomia para editar os arquivos Terraform da pasta templates-deploy.

Execute o comando em uma Aplicação ou Infraestrutura criada com a StackSpot. Para desfazer o fork de um Plugin, use o comando stk unfork plugin

Uso

Sintaxe

stk fork plugin [OPÇÕES]

Exemplo

Para conferir os Plugins disponíveis para Fork, execute o comando a seguir:

stk show plugin

Execute o comando dentro da pasta de uma Infraestrutura criada com a StackSpot:

stk fork plugin

Ou informe o parâmetro target para especificar a pasta que exista uma Infraestrutura criada com a StackSpot:

stk fork plugin --target user/home/Documentos/sqs-app

Atenção!

Ao realizar o fork de um Plugin de Infraestrutura, a sua cópia do código Terraform perde o suporte relacionado ao Plugin original publicado. Você assume a responsabilidade pelas edições do código Terraform a partir do fork.

Para editar o Plugin e o código Terraform, acesse seguinte caminho: {PATH_APP_OR_INFRA}/.stk/FORKED_PLUGINS/{plugin_alias}

Exemplo:

user/home/my-infrastructure/.stk/FORKED_PLUGINS/my-bucket-s3-logs-plugin

Após as alterações, você deve salvar e fazer o commit das mudanças para o repositório do seu projeto.

Parâmetros

Opções	Descrição	Exemplo
`-o`, `--target [TEXTO]`	Caminho para o manifesto de uma Aplicação ou Infraestrutura criada na StackSpot, que possua os Plugins de Infraestrutura que você deseja fazer o fork. Se você não informar o caminho do manifesto, o comando irá considerar o caminho do manifesto a pasta atual.	stk fork plugin --target user/home/Documentos/sqs-app
`-s`, `--skip_confirmation`	Confirma o fork sem exibir a mensagem da etapa de confirmação do fork.	stk fork plugin --target user/home/Documentos/sqs-app --skip_confirmation
`-h`, `--help`	Exibe a ajuda do comando e sai.	stk fork plugin --help

stk unfork plugin

O comando stk unfork plugin reverte as alterações do comando stk fork plugin. Um aviso é exibido sobre a exclusão da pasta do fork do Plugin que for selecionado para desfazer o fork.

Uso

Sintaxe

stk unfork plugin [OPÇÕES]

Exemplo

Execute o comando para desfazer o fork de um Plugin:

stk unfork plugin

Uma lista vai exibir todos os Plugins que você fez o fork. Você deve selecionar o Plugin desejado e confirmar a mensagem para que o comando stk unfork desfaça as alterações e exclua a pasta do fork do Plugin selecionado.

Ou informe o parâmetro target para especificar a pasta que exista uma Infraestrutura criada com a StackSpot:

stk unfork plugin --target user/home/Documentos/sqs-app

Para confirmar se o fork foi revertido, confira a pasta dos forks dos Plugins: {PATH_APP_OR_INFRA}/.stk/FORKED_PLUGINS/{plugin_alias}

Exemplo:

user/home/my-infrastructure/.stk/FORKED_PLUGINS/my-bucket-s3-logs-plugin

Após as alterações, você deve salvar e fazer o commit das mudanças para o repositório do seu projeto. O projeto voltará a usar os Plugins originais publicados na StackSpot.

Parâmetros

Opções	Descrição	Exemplo
`-o`, `--target [TEXTO]`	Caminho para o manifesto de uma Aplicação ou Infraestrutura criada na StackSpot, que possua os Plugins de Infraestrutura que você deseja desfazer o fork. Se você não informar o caminho do manifesto, o comando irá listar todos os Plugins que foram copiados pelo comando stk fork plugin.	stk unfork plugin --target user/home/Documentos/sqs-app
`-s`, `--skip_confirmation`	Reverte o fork sem exibir a mensagem da etapa de confirmação da exclusão do fork.	stk unfork plugin --target user/home/Documentos/sqs-app --skip_confirmation
`-h`, `--help`	Exibe a ajuda do comando e sai.	stk unfork plugin --help

stk validate plugin

Para realizar a validação, acesse a pasta do seu Plugin e execute o comando. Ao final da execução do comando, ele apresenta uma mensagem com as inconsistências e o resultado da validação.

O comando:

Valida a estrutura do seu Plugin;
Remove pastas vazias;
Ignora arquivos e pastas que você não deseja ao finalizar o desenvolvimento do seu Plugin;
Arquivos ignorados em seu arquivo .gitignore não serão validados.

Uso

stk validate plugin --verbose --studio my_studio_slug

Parâmetros

Opções	Descrição	Exemplo
`-v`, `--verbose`	Opção para listar os detalhes de todos os itens analisados, validados e ignorados do seu Plugin.	stk validate plugin --verbose
`-stu`, `--studio` STUDIO_SLUG	Slug do Estúdio usado para validar as informações do Plugin com base na versão do Plugin publicado no Estúdio. Saiba mais detalhes em breaking changes	stk validate plugin --studio my_studio_slug
`-h`, `--help`	Exibe a ajuda do comando e sai.	stk validate plugin --help

Aviso de quebra de versão (Breaking Changes)

Na StackSpot, uma breaking change em Plugins ou Actions é uma alteração que pode quebrar a compatibilidade com versões anteriores. Isso significa que, após a atualização, Plugins ou Actions que funcionavam antes podem não funcionar da mesma forma ou precisar de ajustes para operar corretamente.

As breaking changes são detectadas pelo comando de validação ao informar o parâmetro --studio. Nele, você informa o slug do Estúdio para que a validação compare a versão do Plugin que você deseja publicar com a versão já publicada. Se alguma alteração causar a quebra de compatibilidade, um aviso será exibido no terminal informando que as mudanças vão gerar uma breaking change.

A alteração dos seguintes parâmetros no arquivo plugin.yaml causam uma breaking change no seu Plugin:

SchemaVersion: mudança da versão do schema;
Requires changes: mudanças nos itens dentro do campo requires;
Connections changes: mudanças nas Connections Interfaces;
Input change size: alterações no tamanho do input (quantidade de texto, adição de opções, etc);
Input type change: mudar o tipo do input;
Input condition change: mudar o valor da variável condicional usada na opção condition de um input;
Input sub-input change: qualquer alteração em inputs que estejam dentro de outros inputs. Como inputs que são itens dentro de uma lista ou objeto.
AppAllowed change: mudança do valor da opção AppAllowed.