Criar Stack e Starter via STK CLI

Nesta seção, você encontra um guia de criação, validação e publicação de Stacks e Starters utilizando o STK CLI.

Criar Stack via STK CLI

Antes de você começar

Antes de iniciar, verifique:

Instale o STK CLI;
Tenha conhecimentos básicos sobre o uso de uma interface de linha de comando (CLI);
Familiarize-se com os comandos do STK CLI.

Siga as etapas a seguir para criar sua Stack.

Passo 1. Verificar seus Plugins

Confira se você já criou e publicou os Plugins necessários no seu Estúdio.

No terminal, execute:

stk login

Passo 3. Criar a Stack

Para criar uma Stack, execute o comando:

stk create stack

Passo 4. Responder às perguntas no terminal

Responda às perguntas apresentadas no STK CLI:

Nomeie sua stack: exemplo-stack
Versão: (0.0.1)
Você deseja iniciar um repositório git? No
Adicionar remote? (adicionar o seu repositório já criado para armazenar a Stack) Yes
Git URL para definir como remote origin: informe a URL do repositório
Descrição da stack: descreva a Stack explicando o seu propósito

Passo 5. Configurar o arquivo `stack.yaml`

Abra a pasta da Stack e edite o arquivo stack.yaml, preenchendo os parâmetros da Stack.

Dentro dos parâmetros spec:, preencha as seguintes opções.

1. `repository:`

Se você iniciou o repositório Git, informe o repositório remoto, por exemplo:

spec:
  repository: git@github.com:GitHub-UserName/my-local-repository.git

Exemplo:

spec:
  repository: git@github.com:JohnDoe/my-stack.git

2. `docs:`

Se você tem documentação da sua Stack, nomeie o arquivo Markdown da documentação como docs.md e coloque o arquivo nas seguintes pastas:

docs/en_us: para documentação em inglês;
docs/pt_br: para documentação em português.

Exemplo:

spec:
  # ...Outras opções de spec acima
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md

3. `links:`

Preencha o nome, a URL e a imagem para adicionar um link à sua Stack. O link aparecerá no Portal da StackSpot.

Exemplo:

spec:
  # ...Outras opções de spec acima
  links:
    - name: My Stack link
      url: https://github.com/JohnDoe/my-stack
      picture: stack-image.png

4. `plugins:`

Para os dois tipos de Plugins, app e infra, preencha os Plugins com a seguinte sintaxe:

spec:
  # ...Outras opções de spec acima
  plugins:
    app:
      - name: studio-slug/app-plugin-name@<semantic-version>
    infra:
      - name: studio-slug/infra-plugin-name@<semantic-version>

Dica!

Os Plugins podem ser de Estúdios diferentes do Estúdio em que você vai publicar a Stack, desde que você tenha acesso a eles.

Exemplo:

spec:
  # ...Outras opções de spec acima
  plugins:
    app:
      - name: my-studio/java-app-plugin@1.1.0
    infra:
      - name: my-studio/sqs-infra-plugin@2.1.0

5. `actions:`

Para definir Actions na sua Stack, preencha os nomes das Actions da seguinte forma:

spec:
  # ...Outras opções de spec acima
  actions:
    - name: studio-slug/action-name1@<semantic-version>
    - name: studio-slug/action-name2@<semantic-version>
    - name: studio-slug/action-name3@<semantic-version>

Dica!

As Actions podem ser de Estúdios diferentes do Estúdio em que você vai publicar a Stack, desde que você tenha acesso a elas.

Exemplo:

spec:
  # ...Outras opções de spec acima
  actions:
    - name: my-studio/my-personal-action@3.0.0
    - name: organization-studio/action-with-connection@1.0.0
    - name: data-studio/action-get-data@0.0.1

Exemplo completo de `stack.yaml`

Ao final, você terá um arquivo stack.yaml semelhante ao exemplo:

schema-version: v1
kind: stack
metadata:
  name: my-stack
  display-name: my-stack
  description: My Stack description
  version: 1.0.0
spec:
  repository: git@github.com:GitHub-UserName/my-local-repository.git
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  links:
    - name: My Stack link
      url: https://github.com/my-github-org/my-stack
      picture: stack-image.png
  plugins:
    app:
      - name: studio-slug/app-plugin-name@1.0.0
    infra:
      - name: studio-slug/infra-plugin-name@1.2.0
  actions:
    - name: studio-slug/action-name1@0.0.1
    - name: studio-slug/action-name2@1.0.1
    - name: studio-slug/action-name3@2.1.0

Passo 6. Salvar o arquivo e seguir para o Starter

Salve o arquivo stack.yaml. Em seguida, crie o seu Starter.

Criar Starter via STK CLI

Adicione os Plugins que o Starter usará, ou o comando de validação da Stack falhará.

Passo 1. Confirmar o diretório da Stack

Certifique-se de que você já tem uma Stack criada e que está dentro da pasta dessa Stack para criar um Starter.

Passo 2. Criar o Starter

No terminal, execute:

stk create starter

Passo 3. Responder às perguntas no terminal

Responda às perguntas apresentadas:

Nomeie seu starter: basic-starter
Você deseja iniciar um repositório git? Yes/No
Adicionar remote? (adicionar o repositório remoto para armazenar o Starter) Yes/No
Git URL para definir como remote origin: informe a URL
Descrição do starter: descreva o Starter explicando o seu propósito

Atenção!

Adicione o nome do Starter manualmente ao arquivo stack.yaml da sua Stack.

Exemplo:

spec:
  # ...Outras opções de spec acima
  starters:
    - path: starters/basic-starter
    - path: starters/java-starter

Passo 4. Configurar o arquivo `starter.yaml`

Abra a pasta da Stack e, em seguida, a pasta do Starter. Edite o arquivo starter.yaml e preencha os parâmetros do Starter.

1. `type:`

Tipo de Plugin que será adicionado ao Starter. Atualmente, somente o tipo app é suportado.

2. `docs:`

Se você tem documentação do seu Starter, nomeie o arquivo Markdown da documentação como docs.md e coloque o arquivo nas seguintes pastas:

docs/en_us: para documentação em inglês;
docs/pt_br: para documentação em português.

Exemplo:

spec:
  # ...Outras opções de spec acima
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md

3. `plugins:`

No parâmetro plugins, adicione a opção required: com os Plugins obrigatórios no seu Starter:

spec:
  # ...Outras opções de spec acima
  plugins:
    required:
      - name: studio-slug/<plugin-name>

Exemplo:

spec:
  # ...Outras opções de spec acima
  plugins:
    required:
      - name: my-studio/app-java-plugin

Exemplo completo de `starter.yaml`

O seu arquivo starter.yaml ficará semelhante ao exemplo:

schema-version: v1
kind: starter
metadata:
  name: basic-starter
  description: basic-starter
spec:
  type: app
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md
  plugins:
    required:
      - name: my-studio/app-java-plugin

Salve o arquivo e valide as mudanças.

Informação adicional

Você pode gerar uma estrutura básica de Starter dentro de uma Stack no momento em que cria a Stack. Para isso, execute o comando para criar a Stack com a opção --from para criar o seu Starter a partir de uma Stack existente.

Use a seguinte sintaxe:

stk create stack --from [studio-slug]/[stack-slug]@[semantic-version]

Exemplo:

stk create stack --from other-studio-slug/source-stack-slug@1.2.0

Confira o(s) nome(s) do(s) Starter(s) gerado(s) e atualize o campo starters no arquivo de configuração da sua Stack (stack.yaml).

Validar Starter

Dentro da pasta do seu Starter, execute o comando:

stk validate starter

Em seguida, valide a sua Stack para conferir se todas as mudanças estão corretas.

Validar Stack via STK CLI

Para validar a Stack e seus Starters, siga os passos:

Entre na pasta da sua Stack;
Execute o comando:

stk validate stack

Publicar Stack via STK CLI

Pré-requisitos

Cuidado!

É obrigatório que a sua Stack tenha Starters com Plugins. Os Plugins podem ser de Estúdios diferentes do Estúdio em que você vai publicar a Stack, desde que você tenha acesso a eles. Se necessário, confira como adicionar Plugins em seu Starter;
Verifique se os Starters criados foram adicionados no arquivo de configuração da sua Stack (stack.yaml). Para isso, confira no passo 5 o item starters em como adicionar os Starters em sua Stack;
A pasta da sua Stack não pode estar vazia.

Ao publicar uma Stack, os Starters também serão publicados e terão versões em conjunto.

Atenção!

Se você adicionar outro Starter à sua Stack, será preciso alterar a versão e publicá-la novamente. O mesmo fluxo de trabalho se aplica ao Portal da StackSpot.

Passo 1. Publicar a Stack

No diretório da sua Stack, execute:

stk publish stack

Passo 2. Selecionar o Estúdio

Selecione o seu Estúdio e pressione Enter, ou informe diretamente o nome do Estúdio com a opção --studio.

Exemplo:

stk publish stack --studio my-personal-studio

Criar Stack via STK CLI

Antes de você começar

Passo 1. Verificar seus Plugins

Passo 2. Fazer login no STK CLI

Passo 3. Criar a Stack

Passo 4. Responder às perguntas no terminal

Passo 5. Configurar o arquivo stack.yaml

1. repository:

2. docs:

3. links:

4. plugins:

5. actions:

Exemplo completo de stack.yaml

Passo 6. Salvar o arquivo e seguir para o Starter

Criar Starter via STK CLI

Passo 1. Confirmar o diretório da Stack

Passo 2. Criar o Starter

Passo 3. Responder às perguntas no terminal

Passo 4. Configurar o arquivo starter.yaml

1. type:

2. docs:

3. plugins:

Exemplo completo de starter.yaml

Validar Starter

Validar Stack via STK CLI

Publicar Stack via STK CLI

Pré-requisitos

Passo 1. Publicar a Stack

Passo 2. Selecionar o Estúdio

Passo 5. Configurar o arquivo `stack.yaml`

1. `repository:`

2. `docs:`

3. `links:`

4. `plugins:`

5. `actions:`

Exemplo completo de `stack.yaml`

Passo 4. Configurar o arquivo `starter.yaml`

1. `type:`

2. `docs:`

3. `plugins:`

Exemplo completo de `starter.yaml`