Pular para o conteúdo principal

Fork de Plugin de Infraestrutura

O fork de Plugins de Infraestrutura na StackSpot funcionam por meio do comando stk fork plugin, que permite que você acesse e edite o Terraform de um Plugin específico, sem expor o Terraform do projeto inteiro. O comando cria uma estrutura padrão de pastas e arquivos para o Terraform do Plugin, possibilitando que você faça alterações personalizadas.

Após realizar as modificações, o motor de deploy utiliza o Terraform que você editou para o provisionamento da infraestrutura, substituindo o código do original. Caso o Plugin padrão volte a atender às suas necessidades, você pode reverter facilmente para a versão original.

Habilitar o fork em um Plugin

Para possibilitar que outros usuários façam o fork de um Plugin, você precisa adicionar o parâmetro allowed-resource-fork no arquivo YAML:

Confira o exemplo a seguir de um Plugin com fork habilitado:

schema-version: v3
kind: plugin
metadata:
  name: plugin-infraestrutura-fork-habilitado
  display-name: plugin-infraestrutura-fork-habilitado
  description: Exemplo de Plugin de infra com fork habilitado
  version: 1.0.0
spec:
  type: infra
  allowed-resource-fork: 
    - aws_s3_bucket
    - aws_s3_bucket_policy
    - aws_s3_bucket_object
  docs:
    pt-br: docs/pt-br/doc.md
    en-us: docs/en-us/doc.md
  compatibility:
    - python
  technologies:
    - Api
  runtime:
    environment:
      - terraform-1-4
      - aws-cli-2
      - git-2

O allowed-resource-fork recebe uma lista de strings com o nome dos recursos do Terraform que podem realizar o fork. Para habilitar o fork, é obrigatório pelo menos um item na lista.

O exemplo a seguir estão listados três recursos que serão permitidos a serem copiados ao passar por um fork. Os recursos listados serão copiados do Terraform do Plugin original:

Exemplo em um arquivo main.tf
provider "aws" {
  region = "{{ aws_region }}"
}

# Criação do bucket S3
resource "aws_s3_bucket" "example" {
  bucket = "{{ bucket_name }}"
  acl    = "{{ bucket_acl }}"
  tags = {
    Name        = "{{ bucket_name }}"
    Environment = "Dev"
  }
}

# Política do bucket S3
resource "aws_s3_bucket_policy" "example" {
  bucket = aws_s3_bucket.example.id
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Sid       = "PublicReadGetObject"
        Effect    = "Allow"
        Principal = "*"
        Action    = "s3:GetObject"
        Resource  = "${aws_s3_bucket.example.arn}/*"
      }
    ]
  })
}

# Upload de um objeto ao bucket S3
resource "aws_s3_bucket_object" "example" {
  bucket = aws_s3_bucket.example.bucket
  key    = "{{ file_path | basename }}"
  source = "{{ file_path }}"
  acl    = "{{ bucket_acl }}"
}

Agora a cópia do seu fork poderá utilizar estes recursos.

Trecho de exemplo de um Plugin de Infraestrutura com o fork habilitado para os recursos da lista.
  allowed-resource-fork: 
    - aws_s3_bucket
    - aws_s3_bucket_policy
    - aws_s3_bucket_object

As Aplicações e Infraestruturas que utilizam um Plugin copiado com fork habilitado, terão o parâmetro fork definido como true na listagem de Plugins do manifesto stk.yaml.

schema-version: v2
kind: manifest
metadata:
  name: infraestrutura-com-fork
  description: "Infraestrutura criada com Plugins copiados."
  stack-version-id: 01J7NRFWSH6P0RFVR8
  stack: stack-infra@1.0.3
spec:
  type: infra
  plugins:
    - name: meu-studio/stack-infra@1.0.3/plugin-infraestrutura-fork-habilitado@1.0.0
      fork: true
      alias: plugin-infra-v2-no-req-gen-s3-1733230002287
      plugin-version-id: 01J724AM0WBA78663Y19K90B7J
      stack-version-id: 01J7NRNW12J28CFVCNYYZRZDBQ
      type: infra
      inputs:
        resource: Client
        method: GET
      inputs-envs: {}
      connections:
        generates:
          - type: aws-s3-conn
            selected: dasdsa
            alias: bucket-source
        requires: []
      links:
        generates: []
      global-inputs: {}
      global-computed-inputs: {}

FAQ sobre fork de Plugins

Realizar o fork de um Plugin de Infra permitido

  • O usuário pode executar o comando stk fork plugin para criar uma cópia independente do Terraform de um Plugin que está habilitado para fork, tentar o fork de Plugins não habilitados pode ocasionar em erros.
  • Apenas Plugins habilitados para fork serão exibidos na listagem.
  • Após o fork, o código do Plugin pode ser editado localmente.

Editar o código do Plugin após o fork

Você pode realizar alterações no código do Plugin copiado, e essas modificações serão aplicadas automaticamente durante o provisionamento da Infraestrutura pelo motor de deploy.

Sobrescrever um diretório existente

Se você já possui um diretório com o código do Plugin, pode sobrescrevê-lo ao usar o comando stk fork plugin. Confirme a mensagem exibida no terminal para substituir o conteúdo do diretório existente.

Reverter um fork executado anteriormente

Você pode usar o comando stk unfork plugin para reverter o fork. Isto deleta a pasta do Terraform e retorna o estado original do Plugin.

Atualizar um Plugin copiado com fork para uma versão mais recente

Use o comando stk update plugin para atualizar o Plugin para uma versão mais recente. Durante a atualização, o fork será revertido e os arquivos Terraform serão removidos.

Visualizar a marcação de fork nos Plugins

Após realizar o fork, o Plugin será marcado como "forkado" na lista de Plugins de Infraestrutura da Aplicação ou Infraestrutura no seu Workspace.

Consultar a lista de recursos criados

Acesse a aba de recursos criados no seu Workspace para verificar o impacto do fork no ambiente.

Utilizar o Terraform copiado localmente

Após o fork, você pode usar o Terraform copiado para personalizar o comportamento do Plugin. Para isso ele deve acessar o caminho: ​​{PATH_APP_OR_INFRA}/.stk/FORKED_PLUGIN/{plugin_alias} para ter acesso ao Terraform.

Executar pipelines com alterações no Plugin forkado

Você pode executar a pipeline do projeto para aplicar as alterações realizadas no código do Plugin, para que as mudanças sejam aplicadas durante o deploy.