Pular para o conteúdo principal

Arquivo de Especificação (spec file)

Sobre o arquivo de especificação (spec file)

Informações específicas são essenciais para a criação de Aplicações e Infraestruturas, e um arquivo YAML contendo todas as especificações necessárias pode fornecer essas informações de maneira conveniente.

O arquivo de especificação aborda os campos primários necessários para Aplicações e Infraestruturas. No entanto, ainda é necessário um Starter para criá-los.

Estrutura do arquivo de especificação

O arquivo de especificação deve ter uma extensão de arquivo .yaml. A única diferença entre os arquivos de especificação de Aplicação e Infraestrutura é o atributo kind.

Você precisa criar manualmente o arquivo de especificação, seguindo as regras:

  • O arquivo de especificação deve ser um arquivo YAML.
  • Ao criar o arquivo de especificação .yaml, você pode usar o nome que desejar. Exemplo:
    • Para Aplicações: app-spec.yaml;
    • Para Infraestruturas: infra-spec.yaml;
    • Ou para Plugins: apply-plugin-spec.yaml;
  • Você ainda deve utilizar um Starter para criar suas Aplicações ou Infraestruturas.

Atributos do arquivo de especificação

Dependendo dos Plugins que você usa, o recurso deve incluir o nome, inputs, inputs de ambiente e connections. Preencha cada campo conforme necessário:

kind:

Preencha com application, shared-infrastructure ou spec-apply-plugin.

metadata:

Preencha os metadados do seu Aplicativo ou Infraestrutura.

  • description: Descreva o Aplicativo ou Infraestrutura.
  • name: Insira o nome do Aplicativo ou Infraestrutura.
Atenção!

O arquivo de especificação de um Plugin não usa o campo metadata e nem o parâmetro description. Mas usa o parâmetro name, que representa o nome completo do Plugin, seguindo a seguinte sintaxe:

name: nome-estúdio/nome-stack/nome-plugin

Exemplo:

name: developers-studio/infra-stack/infra-dev-plugin

schema-version:

A versão atual é a v1.

Exemplo:

kind: application # or shared-infrastructure
metadata:
description: "Application description"
name: app-name # or infrastructure name
schema-version: v1

spec:

Adicione todos os atributos dos Plugins e do repositório remoto do seu projeto da Aplicação ou Infraestrutura.

applied-plugins:
Atenção!

No arquivo de especificação de Plugins, não use o campo applied-plugins. Em vez disso, use cada parâmetro a seguir conforme o indicado.

  • alias: O nome alternativo para uso do Plugin.
Atenção!

As Connections Interfaces requeridas e geradas passam a ser usadas como Inputs na versão 3 dos manifestos de Plugins e Actions. Acesse a página de Inputs para conferir o novo tipo de input required-connection e generated-connection.

  • inputs: Objeto do tipo input com o input e valor. Use a sintaxe: input-name: input-value.
  • inputs-envs: Objeto do tipo input de ambiente com o input e valor. Use a sintaxe: input-name: input-value.
  • name: O nome do Plugin que se qualifica para todas as especificações relacionadas. Use a sintaxe: name: your-studio-slug/the-stack-ofyour-plugins@semantic-version/app-plugin-name.

Exemplo:

spec:
applied-plugins:
- alias: plugin-app-alias-01-1711972020803
inputs:
input1: value1
inputs-envs: {}
name: your-studio-slug/the-stack-ofyour-plugins@1.0.0/app-plugin-name
repository:

A URL do repositório remoto do seu projeto.

stack-qualifier:

A Stack para aplicar a especificação para todos os Plugins da Stack.
Utilize a sintaxe:

stack-qualifier: your-studio-slug/your-stack@semantic-version-number.

Exemplo: tw-studio/documentation-infra-stack@1.0.0

Exemplo de um arquivo de especificação de uma Aplicação

Exemplo de um arquivo de especificação de Aplicação para uso com o comando stk create app:

app-spec.yaml
kind: application
metadata:
description: "Application description"
name: app-test-d4b28b91
schema-version: v1
spec:
applied-plugins:
- alias: plugin-app-alias-01-1711972020803
inputs:
input1: value1
inputs-envs: {}
name: tw-studio/documentation-stack@1.2.0/static-site-plugin
- alias: alias01
inputs:
topic1_name: test-sns-1
topic2_name: test-sns-2
input_generated-sns1: sns-generate-alias-1
outputs:
- arn: arn_value
- topic_name: sns-topic-name
input_generated-sns2: sns-generate-alias-2
outputs:
- arn: arn_value
- topic_name: sns-topic-name
inputs-envs: {}
name: tw-studio/documentation-infra-stack@1.0.0/database-infra-plugin
- alias: alias02
inputs:
method: GET
resource: Client
sns-require-alias-1: conn1-d9c3ca69
sns-require-alias-2: conn2-6011ee20
inputs-envs: {}
name: tw-studio/documentation-infra-stack@1.0.0/plugin-infra-requires-two-sns
repository: https://github.com/techwriter-team/tw-team-tests

Exemplo de um arquivo de especificação de uma Infraestrutura

Exemplo de arquivo de especificação de Infraestrutura para uso com o comando stk create infra.

infra-spec.yaml
kind: shared-infrastructure
metadata:
description: "Infrastructure description"
name: infra-test
schema-version: v1
spec:
applied-plugins:
- alias: alias01
inputs:
topic1_name: test-sns-1
topic2_name: test-sns-2
input_generated-sns1: sns-generate-alias-1
outputs:
- arn: arn_value
- topic_name: sns-topic-name
input_generated-sns2: sns-generate-alias-2
outputs:
- arn: arn_value
- topic_name: sns-topic-name
inputs-envs: {}
name: tw-studio/documentation-infra-stack@1.0.0/plugin-infra-requires-two-sns
- alias: alias02
inputs:
sns-require-alias-1: conn1-5fd6a946
sns-require-alias-2: conn2-5fd6a946
method: GET
resource: Client
inputs-envs: {}
name: tw-studio/documentation-infra-stack@1.0.0/plugin-infra-requires-two-sns
repository: https://github.com/techwriter-team/tw-team-tests
stack-qualifier: tw-studio/documentation-infra-stack@1.0.0

Exemplo de um arquivo de especificação com inputs do tipo list e object

kind: application
metadata:
description: "Application description"
name: new-inputs-app
schema-version: v1
spec:
applied-plugins:
- alias: plugin-app-alias-01-1711972020803
inputs:
input1: value1
inputs-envs: {}
name: tw-studio/documentation-stack@1.2.0/static-site-plugin
- alias: alias01
inputs:
topic1_name: test-sns-1
topic2_name: test-sns-2
input_generated-sns1: sns-generate-alias-1
outputs:
- arn: arn_value
- topic_name: sns-topic-name
input_generated-sns2: sns-generate-alias-2
outputs:
- arn: arn_value
- topic_name: sns-topic-name
inputs-envs: {}
name: tw-studio/documentation-infra-stack@1.0.0/database-infra-plugin
- alias: alias02
inputs:
method: GET
resource: Client
sns-require-alias-1: conn1-d9c3ca69
sns-require-alias-2: conn2-6011ee20
my_input_obj:
input_one: "abc123"
input_two: "dea456"
my_input_list_of_string:
- "abc123"
- "dea567"
my_input_list_of_obj:
- input_one: "abc123"
input_two: "dea456"
- input_one: "aaaa123"
input_two: "bbbbb456"
inputs-envs: {}
name: tw-studio/documentation-infra-stack@1.0.0/plugin-infra-requires-two-sns
repository: https://github.com/techwriter-team/tw-team-tests

Exemplo de um arquivo de especificação de um Plugin

schema-version: v1
kind: spec-apply-plugin
spec:
name: dev-studio/dev-stack/plugin-v3-inputs-v3
alias: plugin-dev-1001
inputs:
input_text: Test
input_int: 20
input_bool: true
input_select: Option 1
input_multiselect:
- Option 2
- Option 3
input_required_connection_s3: dev-s3-selected
input_generated_connection_lambda: new-lambda
obj_list:
- text_value: Dev
int_value: 30
object_internal:
text_value_internal: Developer test
int_value_internal: 50
input_list_text:
- Text 1
- Text 2
- Text 3
object_password:
test_pass: "success"
inputs-envs:
my_env:
dev:
use_keda: NONE
ha: false
prd:
use_keda: aws-sqs-queue
queueName: "queue name"
minReplicas: 20

Uso do arquivo de especificação

Para os comandos, stk create app, stk create infra e stk apply plugin adicione a opção --spec e o caminho absoluto do arquivo de especificação YAML:

Exemplos:

Campos como nome e descrição da Aplicação/Infraestrutura/Plugin não são obrigatórios ao executar o comando com o arquivo de especificação.

java-app-specs.yaml absolute path example
stk create app --spec home/user/documents/my-spec-files/java-app-specs.yaml --starter my-studio/my-stack/starter-name
java-infra-specs.yaml absolute path example
stk create infra --spec home/user/documents/my-spec-files/java-infra-specs.yaml --starter my-studio/my-stack/starter-name
java-plugin-specs.yaml absolute path example
stk apply plugin --spec home/user/documents/my-spec-files/java-plugin-specs.yaml