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
;
- Para Aplicações:
- 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.
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:
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.
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:
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.
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.
stk create app --spec home/user/documents/my-spec-files/java-app-specs.yaml --starter my-studio/my-stack/starter-name
stk create infra --spec home/user/documents/my-spec-files/java-infra-specs.yaml --starter my-studio/my-stack/starter-name
stk apply plugin --spec home/user/documents/my-spec-files/java-plugin-specs.yaml