Pular para o conteúdo principal

(Descontinuado) Migrar Plugin v1 para v2

Nesta seção, você encontra um guia de como migrar um Plugin v1 para o v2.


Atenção!

Este guia de migração da versão do manifesto de Plugins foi descontinuado. Acesse o novo guia para atualizar os seus Plugins e Actions para a nova versão v3 do manifesto.

Por que mudou

Com a atualização dos Plugins v1 para v2, você pode criar recursos do mesmo tipo, como:

  • Disponibilizar o mesmo recurso mais de uma vez por Plugin de Aplicação (app) ou de Infraestrutura (infra), por meio de Connection Interfaces.

  • Gerar a Connection Interface para Plugins de Infraestrutura com o de/para de um arquivo Terraform para a StackSpot, e sem alterar o arquivo .tf.

  • Usar mais de uma Connection Interface do mesmo tipo.

Informações Complementares

  • É possível continuar usando a v1 dos Plugins. Você consegue aplicar e fazer o deploy de Plugins v1 com os comandos do STK CLI (stk apply plugin, stk deploy), mas não pode mais publicar novas versões dele sem fazer a migração.

  • Os Plugins v1 que utilizam Connection Interface ainda funcionam, porém com limitações. E não podem ser atualizados sem a migração para a v2.

Mudanças

Confira o que mudou:

  1. Implementação de Alias (apelidos) para as Connection Interfaces geradas e requeridas pelos Plugins.
  2. Implementação de Alias para criação de Aplicação de Plugins permitindo usar o mesmo recurso mais de uma vez.
  3. O parâmetro --environment foi alterado para --env ou -e.
  4. Implementação do mapeamento das variáveis de output do Terraform para a StackSpot, agora é possível usar um output com as opções “From: <terraform.output>” e “to: connection-interface-type.output”.
  5. Novo campo de runtime para Plugins de Infraestrutura:
runtime:
  environment:
    - terraform-1-3
Atenção!

Se você receber um erro de não autorização (http status 403) na pipeline, será preciso gerar novas Credenciais de Serviço com as permissões atualizadas.

  1. Mudança do parâmetro Link para Links.

  2. Atualização da Runtime Engine. Essa atualização implementa mudanças para suportar a nova versão v2 do esquema de Plugins e seus impactos no deploy de aplicações.

Principais diferenças

Diversos campos foram alterados do esquema v1 para o esquema v2 dos Plugins, confira a seguir os campos alterados:

  • schema-version, teve seu valor alterado de v1 para v2;
  • runtime: Novo campo adicionado na versão do esquema v2, informa metadados específicos para a Engine de Runtimes. Obrigatório apenas para Plugins de Infraestrutura;
  • requires.connection-interface, passou de uma lista de nomes dos tipos de Connection Interface para o atributo connections. O novo atributo conta com duas novas opções:
    • type: Nome do tipo da Connection Interface;
    • alias: Nome alternativo para o tipo da Connection Interface. Agora permite que você utilize mais de uma vez a mesma Connection Interface.
  • generates.connection-interface, passou de uma lista de nomes dos tipos de Connection Interface para o atributo connections. O novo atributo conta com as opções:
    • type: Nome do tipo da Connection Interface;
    • alias: Nome alternativo para o tipo da Connection Interface. Agora permite que você utilize mais de uma vez a mesma Connection Interface.
    • outputs.from: Nome do output do recurso do seu arquivo Terraform;
    • outputs.to: Nome do output da Connection Interface definida, equivalente ao recurso do arquivo Terraform;
  • link, o parâmetro foi alterado para links.
Atenção!
  • O campo generates, runtime e links são exclusivos para os Plugins de Infraestrutura;
  • As opções from e to do campo outputs são Obrigatórias se a Connection Interface definida possuir outputs.

Plugin na versão v1

schema-version: v1
kind: plugin
metadata:
  name: some-kebab-case-name
  description: some description
  display-name: Some display name
  version: 1.0.1
  picture: images/plugin.png
spec:
  type: infra
  release-notes: docs/release-notes-1.md
  about: docs/about.md
  usage: docs/usage.md
  implementation: docs/implementation.md
  requirements: docs/requirements.md
  repository: https://github.com/stack-spot/something
  compatibility:
    - python
  technologies:
    - Api
  requires:
    connection-interface:
      - ecs-task-conn
  generates:
    connection-interface:
      - aws-iam-role-conn
    link:
      - name: Link
        url: http://www.stackspot.com
        type: static

Plugin na versão v2

schema-version: v2
kind: plugin
metadata:
  name: some-kebab-case-name
  description: some description
  display-name: Some display name
  version: 1.0.1
  picture: images/plugin.png
spec:
  type: infra
  release-notes: docs/release-notes-1.md
  about: docs/about.md
  implementation: docs/implementation.md
  requirements: docs/requirements.md
  repository: https://github.com/stack-spot/something
  compatibility:
    - python
  technologies:
    - Api
  runtime:
    environment:
      - terraform-1-4
  requires:
    connections:
      - type: ecs-task-conn
        alias: my-ecs-task-conn
  generates:
    connections:
    - type: aws-iam-role-conn
      alias: sqs-access-iam-role
      outputs:
        - from: sqs-access-iam-role-arn
          to: arn
    links:
      - name: Link
        url: http://www.stackspot.com
        type: static

Migrar o seu Plugin

A conversão de um Plugin é manual. Para migrar da v1 para v2, você precisa alterar a versão do schema-version.

Confira os passos para migrar o Plugin:

Atenção!

  • Se o Plugin não requer nenhuma Connection Interface, a única ação a ser feita é mudar de v1 pra v2.

  • Nos Plugins de App é possível requerer uma Connection Interface, você só não poderá gerá-las.

  • O campo generates, runtime e links são exclusivos para os Plugins de Infraestrutura;

  • As opções from e to do campo outputs são Obrigatórias se a Connection Interface definida possuir outputs.

Passo 1

Altere a versão do esquema de v1 para v2:

schema-version: v2

Passo 2

  1. Se o seu Plugin possuir Connection Interfaces, adicione ao nome do tipo da Connection Interface a opção - type.
  2. Adicione o campo alias e um valor para cada uma.

Se for um Plugin de Infraestrutura, verifique se as Connection Interfaces possuem outputs. Caso possuam, adicione o campo outputs e preencha as opções from e to de cada uma.

Passo 3

Se o seu Plugin possuir o campo link, altere para links.

Confira o De/Para a seguir:

De:

spec:
  type: infra
  release-notes: docs/release-notes-1.md
  about: docs/about.md
  usage: docs/usage.md
  implementation: docs/implementation.md
  requirements: docs/requirements.md
  repository: https://github.com/stack-spot/something
  compatibility:
    - python
  technologies:
    - Api
  requires:
    connection-interface:
      - ecs-task-conn
  generates:
    connection-interface:
      - aws-iam-role-conn
    link:
      - name: Link
        url: http://www.stackspot.com
        type: static

Para:

spec:
  type: infra
  release-notes: docs/release-notes-1.md
  about: docs/about.md
  implementation: docs/implementation.md
  requirements: docs/requirements.md
  repository: https://github.com/stack-spot/something
  compatibility:
    - python
  technologies:
    - Api
  runtime:
    environment:
      - terraform-1-4
  requires:
    connections:
      - type: ecs-task-conn
        alias: my-ecs-task-conn
  generates:
    connections:
    - type: aws-iam-role-conn
      alias: sqs-access-iam-role
      outputs:
        - from: sqs-access-iam-role-arn
          to: arn
    links:
      - name: Link
        url: http://www.stackspot.com
        type: static

Plugins de Infraestrutura

No Plugin do tipo Infra, você precisa fazer uma configuração específica e adicionar os novos atributos:

AtributoDescrição
spec.runtime.environmentObrigatório em Plugins de Infra
spec.requires.connections[n].aliasOpcional
spec.generates.connections[n].aliasObrigatório
spec.generates.connections[n].outputs[n].fromObrigatório apenas no objeto. A lista pode ser vazia.
spec.generates.connections[n].outputs[n].toObrigatório apenas no objeto. A lista pode ser vazia.

Confira mais detalhes sobre cada um:

1. spec.runtime.environment

Permite definir a configuração limitada a ser usada durante uma execução do deploy. Isso conforme definido no Run da configuração do ambiente. Se algum dado não é informado, Runtime utiliza os valores default durante a execução do deploy desse Plugin.

  • terraform: representa qual Terraform será usado. Suporta as versões 1-3, 1-4 e 1-5. Valor default: 1-3.
  • aws-cli-2: indica qual a versão do CLI da AWS. Suporta a versão 2. Valor default: 2.
  • git-2: representa qual a versão do Git. Suporta a versão 2. Valor default: 2.
spec:
  type: infra
  release-notes: docs/release-notes-1.md
  about: docs/about.md
  implementation: docs/implementation.md
  requirements: docs/requirements.md
  repository: https://github.com/stack-spot/something
  compatibility:
    - python
  technologies:
    - Api
  runtime:
    environment:
      - terraform-1-5
      - aws-cli-2
      - git-2

2. spec.requires.connections[n].alias

Permite definir o nome da variável que contém a Connection Interface no template. É útil para acessar a Connection Interface.

spec:
  type: infra
  release-notes: docs/release-notes-1.md
  about: docs/about.md
  implementation: docs/implementation.md
  requirements: docs/requirements.md
  repository: https://github.com/stack-spot/something
  compatibility:
    - python
  technologies:
    - Api
  runtime:
    environment:
      - terraform-1-4
  requires:
    connections:
      - type: ecs-task-conn
        alias: my-ecs-task-conn
  generates:  
    connections:
    - type: aws-iam-role-conn
      alias: sqs-access-iam-role
      outputs:
        - from: sqs-access-iam-role-arn
          to: arn
    links:
      - name: Link
        url: http://www.stackspot.com
        type: static

3. spec.generates.connections[n].alias

Permite definir um nome amigável para dar dicas aos usuários sobre o uso da Connection Interface. O alias é usado para ajudar os criadores a escolherem a Connection Interface correta e remover a ambiguidade quando houver mais de uma com o mesmo tipo.

spec:
  type: infra
  release-notes: docs/release-notes-1.md
  about: docs/about.md
  implementation: docs/implementation.md
  requirements: docs/requirements.md
  repository: https://github.com/stack-spot/something
  compatibility:
    - python
  technologies:
    - Api
  runtime:
    environment:
      - terraform-1-4
  requires:
    connections:
      - type: ecs-task-conn
        alias: my-ecs-task-conn
  generates:  
    connections:
    - type: aws-iam-role-conn
      alias: sqs-access-iam-role
      outputs:
        - from: sqs-access-iam-role-arn
          to: arn
    links:
      - name: Link
        url: http://www.stackspot.com
        type: static

4. spec.generates.connections[n].outputs[n].from e spec.generates.connections[n].outputs[n].to

Permite selecionar qual output de Terraform deve ser escrito em cada atributo da Connection Interface.

Exemplo:

spec:
  type: infra
  release-notes: docs/release-notes-1.md
  about: docs/about.md
  implementation: docs/implementation.md
  requirements: docs/requirements.md
  repository: https://github.com/stack-spot/something
  compatibility:
    - python
  technologies:
    - Api
  runtime:
    environment:
      - terraform-1-4
  requires:
    connections:
      - type: ecs-task-conn
        alias: my-ecs-task-conn
  generates:  
    connections:
    - type: aws-iam-role-conn
      alias: sqs-access-iam-role
      outputs:
        - from: sqs-access-iam-role-arn
          to: arn
    links:
      - name: Link
        url: http://www.stackspot.com
        type: static

Usar Connection Interface

Na versão v1 era necessário editar o seu arquivo Terraform seguindo uma sintaxe específica para que a Connection Interface pudesse acessar os outputs do seu Terraform.

A nova versão melhorou a experiência de uso, agora é necessário apenas identificar os outputs do seu Terraform e preencher o output da Connection Interface que você definiu.

Uso na versão v1

Considere a Connection Interface aws-iam-role-conn em seu plugin.yaml. Você deve editar o seu arquivo Terraform (por exemplo: output.tf) da seguinte maneira:

Seguindo a sintaxe a seguir:
"<connection-interface-type>__{{<connection-interface-type__CONNECTOR>}}__<resource-name>"

De:

./output.tf
output "sqs-access-iam-role-arn" {
  description = "ARN of IAM role"
  value       = module.iam_assumable_role_admin.iam_role_arn
}

O arquivo deve ficar:

./output.tf
# "<connection-interface-type>__{{<connection-interface-type__CONNECTOR>}}__<resource-name>"
output "aws-iam-role-conn__{{aws-iam-role-conn__CONNECTOR}}__iam_role_arn" {
  description = "ARN of IAM role"
  value       = module.iam_assumable_role_admin.iam_role_arn
}

Usar na versão v2

Considere a Connection Interface aws-iam-role-conn em seu plugin.yaml. Você deve mapear os outputs do seu arquivo Terraform (por exemplo: output.tf) da seguinte maneira:

  1. No seu arquivo Terraform, identifique o nome do output:
./output.tf
#  "Output name to use into 'outputs.from' field of your plugin.yaml file"
output "sqs-access-iam-role-arn" {
  description = "ARN of IAM role"
  value       = module.iam_assumable_role_admin.iam_role_arn
}
  1. No arquivo do seu Plugin (plugin.yaml):
  • Adicione o nome identificado no Terraform no campo from;
  • Adicione o output da Connection Interface no campo to que equivale ao atributo value que você identificou no seu Terraform;

Confira como o seu Plugin deve ficar após mapear o output:

spec:
  type: infra
  release-notes: docs/release-notes-1.md
  about: docs/about.md
  implementation: docs/implementation.md
  requirements: docs/requirements.md
  repository: https://github.com/stack-spot/something
  compatibility:
    - python
  technologies:
    - Api
  runtime:
    environment:
      - terraform-1-4
  requires:
    connections:
      - type: ecs-task-conn
        alias: my-ecs-task-conn
  generates:  
    connections:
    - type: aws-iam-role-conn
      alias: sqs-access-iam-role
      outputs:
        - from: sqs-access-iam-role-arn
          to: arn
    links:
      - name: Link
        url: http://www.stackspot.com
        type: static

Para mais detalhes, confira a a seção para mapear outputs de uma Connection Interface com os outputs do seu arquivo Terraform.

Confira os Outputs das Connections Interfaces.

Usar atributo alias

O uso de alias permite que você defina um nome alternativo para o tipo das Connections requeridas ou geradas no seu Plugin. Com isso, ao aplicar um Plugin, esses nomes alternativos removem o problema de duplicidade de recursos no seu Plugin, evitando comportamentos inesperados no momento do deploy da aplicação.

Ou seja, você pode usar mais de uma vez o mesmo tipo de Connection sem que um recurso sobrescreva o outro e sem se preocupar com a ordem em que foram declarados.

Confira o uso do alias:

  • Comportamento de alias para Plugins de app não é obrigatório. Você ainda pode informar usando a flag --alias. Se não for informado um valor, o alias é gerado automaticamente.

  • Para Plugins de Infra, a pergunta sobre o alias ainda existe, mas para facilitar o uso, o campo já vem preenchido com um valor gerado automaticamente, você pode alterar se quiser.

Para mais detalhes, confira os exemplos na seção de plugin.yaml.

Executar deploy

Em um processo de deploy, você pode aplicar um Plugin v1 apenas:

  • Se os Plugins já foram configurados como apenas Plugins de Infra;
  • Se for o primeiro deploy do projeto, caso contrário não será possível executar o Plugin v1 na nova versão do Runtime devido a restrições do arquivo terraform.tfstate.

Para mais detalhes, confira a seção de Runtimes.

Próximos Passos