(Descontinuado) Usar o Runtimes Self-Hosted GitHub

Atenção!

Este conteúdo está sendo descontinuado, saiba como fazer o deploy com Self-Hosted e o Workflow da StackSpot.

Nesta seção, você encontra como usar o Runtimes Self-Hosted na sua pipeline de deploy.

◀

Configurar Conta

Você está aqui!

Configurar Deploy

Criar Conteúdo

Usar Conteúdo

▶

Pré-requisitos

Atenção!

Esta configuração é feita apenas pelo Account Holder, Account Admin ou SRE.

• Pessoa usuária com permissão de escrita em um repositório do GitHub;
• Ter acesso a uma Conta AWS;
• Gerar Credencial de Serviço ou Token de Acesso Pessoal StackSpot;

Dica!

É indicado dar preferência ao uso da Credencial de Serviço.

• Cadastre as credenciais como segredos (secrets) no GitHub;
• O Runner do provedor (GitHub) deve suportar Docker in Docker;
• É necessário ter um Bucket na AWS para salvar os TFstates, e um para salvar os IaC gerados pelos Plugins (podem ser o mesmo Bucket).
• Ter uma Aplicação ou Infraestrutura criada e registrada na StackSpot.

Como usar o Self-Hosted

Antes de usar o Runtimes Self-hosted na sua Pipeline do GitHub, você deve criar e configurar uma pipeline para executar algumas GitHub Actions.

Confira os passos a seguir:

1. Cadastre sua credencial como segredo no GitHub

Use os segredos da etapa:

• Client ID como CLIENT_ID no segredo;
• Client Key como CLIENT_KEY no segredo;
• Realm como CLIENT_REALM no segredo;

Para mais detalhes, siga o uso de segredos na documentação do GitHub Actions.

Dica!

Defina seus segredos da AWS usando também os segredos do GitHub Actions.

2. Implemente o exemplo do workflow na sua pipeline

Passo 1. Crie um novo arquivo de workflow em seu repositório. Por exemplo: .github/workflows/workflow_example.yml.

Passo 2. Copie e cole o exemplo a seguir em seu novo arquivo de workflow:

.github/workflows/workflow_example.yml

name: Stk Self Hosted

on:
  push:
	  branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

jobs:
  orquestrar_e_planejar:
    runs-on: <self-hosted-runner> # Aqui você deve usar um runner que possa acessar sua conta na nuvem
    outputs:
        apply_tasks: ${{ steps.orquestrar_e_planejar.outputs.apply_tasks }}
        run_id: ${{ steps.orquestrar_e_planejar.outputs.run_id }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Deployar Infrastructure
        uses: stackspot/edp-deploy-orchestration-action@v3
        id: orquestrar_e_planejar
        with:
            TFSTATE_BUCKET_NAME: "000000000000-tfstate-bucket"
            TFSTATE_BUCKET_REGION: sa-east-1
            IAC_BUCKET_NAME: "000000000000-iac-bucket"
            IAC_BUCKET_REGION: sa-east-1
            WORKSPACE: "meu-workspace"
            ENVIRONMENT: "prod"
            VERSION: "v1.0.0"
            REPOSITORY_NAME: ${{ github.event.repository.name }}
            PATH_TO_MOUNT: /home/runner/_work/${{ github.event.repository.name }}/${{ github.event.repository.name }}
            WORKDIR: /caminho/para/pasta/pai-da-.stk # Caso seu repositório tenha um .stk que não esteja na pasta raiz do repositório
            STK_CLIENT_ID: ${{ secrets.CLIENT_ID }}
            STK_CLIENT_SECRET: ${{ secrets.CLIENT_SECRET }}
            STK_REALM: <realm>
            AWS_IAM_ROLE: ${{ secrets.AWS_ROLE_ARN }}
            AWS_REGION: sa-east-1
            SKIP_DEPLOY: false
            FEATURES_TERRAFORM_MODULES: >-
              [
                  {
                    "sourceType": "gitHttps",
                    "path": "github.com/stack-spot",
                    "private":  true,
                    "app": "app",
                    "token": "token"
                  },
                  {
                    "sourceType": "terraformRegistry",
                    "path": "hashicorp/stack-spot",
                    "private":  false
                  }
              ]

  aprovar_plano_aplicar:
    name: Deploy
    needs: [orquestrar_e_planejar]
    runs-on: <self-hosted-runner> # Aqui você deve usar um runner que possa acessar sua conta na nuvem
    environment: prod # Aqui você define os ambientes nos quais o usuário deve aprovar as alterações planejadas a partir da etapa de orquestração
    steps:
      - name: Service Provision
        id: run-task
        uses: stack-spot/runtime-tasks-action@v2.1
        if: needs.orquestrar_e_planejar.outputs.run_id != ''
        with:
          RUN_ID: ${{ needs.orquestrar_e_planejar.outputs.run_id }}
          TASK_LIST: ${{ needs.orquestrar_e_planejar.outputs.apply_tasks }}
          REPOSITORY_NAME: ${{ github.event.repository.name }}
          PATH_TO_MOUNT: /home/runner/_work/${{ github.event.repository.name }}/${{ github.event.repository.name }}
          AWS_REGION: sa-east-1
          AWS_ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }}
          FEATURES_TERRAFORM_MODULES: >-
              [
                  {
                    "sourceType": "gitHttps",
                    "path": "github.com/stack-spot",
                    "private":  true,
                    "app": "app",
                    "token": "token"
                  },
                  {
                    "sourceType": "terraformRegistry",
                    "path": "hashicorp/stack-spot",
                    "private":  false
                  }
              ]
          CLIENT_ID: ${{ secrets.CLIENT_ID }}
          CLIENT_KEY: ${{ secrets.CLIENT_SECRET }}
          CLIENT_REALM: <realm>

  cancel: # caso algo na sua pipeline quebre ou alguém a cancele no meio do deployment, é necessário executar esta ação para informar à StackSpot que ocorreu um erro e evitar que os próximos deployments sejam bloqueados
    runs-on: ubuntu-latest
    needs: [orquestrar_e_planejar, aprovar_plano_aplicar]
    if: ${{ always() && (contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')) }}
    steps:
      - name: Cancel run
        if: needs.orquestrar_e_planejar.outputs.run_id != ''
        id: run-cancel
        uses: stack-spot/runtime-cancel-run-action@v1
        with:
          CLIENT_ID: ${{ secrets.CLIENT_ID }}
          CLIENT_KEY: ${{ secrets.CLIENT_SECRET }}
          CLIENT_REALM: <realm>
          RUN_ID: ${{ needs.orquestrar_e_planejar.outputs.run_id }}

3. Funcionamento das Actions

Processo de Deploy atual da StackSpot

O processo de deploy atual da StackSpot gera o IaC do template de deploy de cada Plugin de Infraestrutura e o aplica na cloud, um de cada vez. O processo é interativo, não paralelizado, e cada Plugin terá um TFstate separado armazenado no bucket.

EDP Orchestrator Action

Esta Action analisa o arquivo stk.yaml e gera um manifesto que será enviado para os serviços da StackSpot. Esses serviços orquestram a ordem que os Plugins serão aplicados na cloud e retornarão uma lista de tarefas que serão executadas no próximo passo.

A ordem de aplicação dos Plugins é determinada pelo relacionamento entre as Connection Interfaces definidas nos campos requires e generates no stk.yaml. Plugins que geram uma Connection Interface utilizada por outro Plugin no mesmo manifesto serão processados primeiro.

Caso não haja dependências, os Plugins serão aplicados na ordem em que aparecem no manifesto. Além disso, tarefas de destroy sempre serão executadas por último.

Tasks Action

Cada tarefa (task) recebida será processada de forma interativa por esta action.

Os tipos de tarefa são:

• IAC:
  • Esta tarefa processa o template de deploy de cada Plugin e seguida, salva o IaC gerado em um bucket.
• DEPLOY:
  • A tarefa de Deploy aplica o Terraform na cloud, salvando o TFstate gerenciado no bucket fornecido.
• DESTROY:
  • Quando um Plugin é removido do stk.yaml, uma tarefa de destroy é criada. Essa tarefa utiliza o IaC da última execução bem-sucedida e executa um o comando terraform destroy para remover o Plugin.

Deploy StackSpot Unificado BETA

Funcionamento do Deploy Unificado Habilitado Por Feature Flag

O Deploy Unificado foi criado para que a StackSpot pudesse visualizar as alterações que serão feitas na cloud, antes de serem aplicadas. Isso resolve o problema de Plugins que dependem de outputs de outros Plugins que podem mudar no mesmo deploy, dificultando o planejamento completo.

Nesse modelo, todos os templates são unidos e processados em um único projeto Terraform, que será aplicado à cloud e onde cada Plugin se tornará um módulo separado de um único projeto Terraform.

Exemplo: Há dois Plugins na Infraestrutura a seguir:

• alias: sns-topic-1728484987960
• alias: sqs-queue-1728485030410

Após processar os templates, a estrutura do Terraform gerado tem a seguinte estrutura:

├── /sns-topic-1728484987960 ## templates-deploy do plugin
│   ├── default-tags.tf
│   ├── module-sns-topic.tf
│   ├── provider.tf
│   └── /sns-topic-module
│       ├── sns-topic-locals.tf
│       ├── sns-topic-main.tf
│       ├── sns-topic-outputs.tf
│       ├── sns-topic-ssm.tf
│       └── sns-topic-variables.tf
├── /sqs-queue-1728485030410 ## templates-deploy do plugin
│   ├── default-tags.tf
│   ├── provider.tf
│   ├── sqs-queue-outputs.tf
│   └── sqs-queue.tf
├── sqs-queue-1728485030410-outputs.tf
├── sns-topic-1728484987960-outputs.tf
└── stk-modules.tf

stk-modules.tf

  module "sns-topic-1728484987960" {
    source = "./sns-topic-1728484987960"
  }

  module "sqs-queue-1728485030410" {
    source = "./sqs-queue-1728485030410"
  }

Durante o processamento, a StackSpot realiza a interpolação das referências internas das Connection Interfaces definidas em requires e generates. E mapeia os outputs de cada módulo Terraform nos campos to e from dos Plugins para gerar as Connection Interfaces.

Funcionamento das Actions

Orchestrator Action

A Orchestrator Action valida o deploy verificando se um Plugin pode ser removido e adiciona as informações necessárias para o processo.

Em seguida a StackSpot processa os templates do Plugin para uní-los em um único projeto Terraform. Os Plugins removidos serão reaplicados com os inputs do último deploy, para os seus providers estarem presentes durante o destroy.

Por fim, é gerado um plano (deploy plan) que mostra ao usuário todas as alterações que serão feitas na sua nuvem.

Informação Adicional

Durante o processo de Plan, se algum Plugin for removido, serão gerados dois Plans separados:

1. Para os módulos dos Plugins que permanecem aplicados.

2. Para os Plugins que serão removidos.

   Plan Deploy

     $ terraform plan -target="module.<alias-plugin-aplicado>" ...

   Plan Destroy

     $ terraform plan -destroy -target="module.<alias-plugin-removido>"

Tasks Action

Esta Action, irá aplicar o Terraform gerado pelo processo anterior na cloud do usuário.

• Deploy Durante o processo de Deploy, os Plugins removidos serão destruídos separadamente.

  Apply Deploy

    $ terraform apply -target="module.<alias-plugin-aplicado>" ...

  Apply Destroy

    $ terraform destroy -target="module.<alias-plugin-removido>"

Cancel Run Action

Esta Action atua como uma proteção contra falhas para evitar travamentos nos processos. A StackSpot gerencia cada deploy para prevenir deploy paralelizados e outras ações que possam causar problemas aos usuários.

Se uma pipeline for cancelada manualmente ou um runner falhar durante o deploy, é necessário informar aos serviços da StackSpot que o deploy foi abortado. Caso contrário, futuros deploys poderão ser bloqueados.

Atenção!

É obrigatório utilizar o if: always().

cancel:
  needs: [orquestrar_e_planejar, aprovar_plano_aplicar]
  if: ${{ always() && (contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')) }}
  # Executará sempre que houver um erro ou a pipeline for cancelada
  steps:
    - name: Cancel run
      if: needs.orquestrar_e_planejar.outputs.run_id != ''
      id: run-cancel
      uses: stack-spot/runtime-cancel-run-action@v1
      with:
        CLIENT_ID: ${{ secrets.CLIENT_ID }}
        CLIENT_KEY: ${{ secrets.CLIENT_SECRET }}
        CLIENT_REALM: <realm>
        RUN_ID: ${{ needs.orquestrar_e_planejar.outputs.run_id }}

Agora você está pronto para configurar e executar a Action da StackSpot em sua pipeline!

Dica!

Para saber mais sobre os inputs das Action, confira os repositórios a seguir:

• Cancel Run Action
• Deploy Orchestrator Action
• Runtime Tasks Action

4. Inputs especiais

AWS_IAM_ROLE

• Descrição: o AWS IAM Role a ser utilizado para deploy de Infraestrutura.
• Observação: se os inputs AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e AWS_SESSION_TOKEN forem fornecidos, eles não devem ser utilizados. A Action assumirá automaticamente a role no runner.

AWS_ACCESS_KEY_ID

• Descrição: o AWS Access Key ID para deploy de Infraestrutura.
• Observação: deve ser fornecido apenas se AWS_IAM_ROLE não for utilizada.

AWS_SECRET_ACCESS_KEY

• Descrição: o AWS Secret Access Key para deploy de Infraestrutura.
• Observação: deve ser fornecido apenas se AWS_IAM_ROLE não for utilizada.

AWS_SESSION_TOKEN

• Descrição: o AWS Session Token para deploy de Infraestrutura.
• Observação: deve ser fornecido apenas se AWS_IAM_ROLE não for utilizada.

SKIP_DEPLOY

• Descrição: se for definido como true, ele verifica se houve alguma mudança no Manifesto. Caso ele não tenha sido alterado, o deploy será definido como SKIPPED e não aplicará os Plugins de Infraestrutura na nuvem.
• Observação: Caso a sua pipeline adicione inputs dinâmicos usando o input da Github Action DYNAMIC_INPUTS que mude todas as execuções, essa flag nunca reconhecerá o manifesto como não alterado.
• Exemplo:

    with:
      DYNAMIC_INPUTS:  ' --commit-sha="${{ github.sha }}" '

Regras de Uso

1. Uso do AWS_IAM_ROLE:

   • Se o input AWS_IAM_ROLE for fornecido, a Action assumirá automaticamente a role no runner. Neste caso, não forneça os inputs AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e AWS_SESSION_TOKEN.
   • Certifique-se de que o runner possui permissões para assumir a role fornecida.

2. Uso de Credenciais AWS Diretas:

   • Se você optar por não utilizar o AWS_IAM_ROLE, forneça diretamente os inputs AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e AWS_SESSION_TOKEN.
   • Certifique-se de que as credenciais fornecidas possuem as permissões necessárias para acessar a AWS.

Observações

• Recomenda-se o uso de AWS_IAM_ROLE para maior segurança, pois elimina a necessidade de utilizar credenciais sensíveis diretamente.
• Se ambos os métodos forem configurados (fornecendo AWS_IAM_ROLE e as credenciais diretas), a Action dará prioridade ao uso do AWS_IAM_ROLE e desconsiderará as credenciais diretas.

Uso de Plugins de Infraestrutura Forkados com Self-Hosted

Confira como configurar o uso de Plugins de Infraestrutura forkados em um ambiente Self-Hosted.

Path dos Plugins Forkados

Quando um Plugin de Infraestrutura é forkado, os templates de deploy são armazenados no seguinte caminho dentro do repositório: .stk/FORKED_PLUGINS/<plugin-alias>

Para que o deploy funcione corretamente, é necessário garantir que o Docker tenha acesso à pasta onde estão os arquivos do repositório, incluindo os Plugins que foram forkados.

O input PATH_TO_MOUNT deve ser configurado para apontar para o diretório onde esses arquivos estão localizados. Isso é essencial para garantir que o Docker tenha acesso aos arquivos do repositório, incluindo os Plugins forkados.

Confira a seguir um Exemplo de Configuração do input no GitHub Actions:

WITH:
  PATH_TO_MOUNT: /home/runner/_work/${{ github.event.repository.name }}/${{ github.event.repository.name }}

Este caminho aponta para os arquivos do repositório após a execução de um checkout no workflow.

Observações

1. Certifique-se de que o repositório foi clonado corretamente no runner antes de configurar o PATH_TO_MOUNT.
2. O runner precisa ter permissões adequadas para acessar os arquivos do repositório e o diretório .stk/FORKED_PLUGINS/<plugin-alias>.
3. Caso o caminho padrão não seja adequado para o seu ambiente, ajuste o valor de PATH_TO_MOUNT para refletir o local correto dos arquivos do repositório. Com essa configuração, o deploy de Plugins forkados será realizado com sucesso em um ambiente Self-Hosted.

Acompanhar o status do deploy

É possível acompanhar o status do deploy através de duas formas:

1. Localmente no STK CLI

Passo 1. Execute o comando para acessar o Workspace da sua Aplicação:

stk use workspace <workspace-slug>

Passo 2. Executando o comando para acompanhar:

stk deploy status <deploy-id> --watch

Você encontra o deploy id ao finalizar a execução do deploy na sua pipeline. Deve aparecer como no exemplo a seguir:

RUN DEPLOY_SELF_HOSTED successfully started with ID: 01J9V6MWFTWQ392331QBCS46KQ

2. Via Portal da StackSpot EDP

Confira o passo a passo:

Passo 1. Acesse o seu Workspace no Portal da StackSpot EDP;

Passo 2. Acesse sua Aplicação ou Infraestrutura;

Passo 3. No menu lateral, selecione o ambiente onde você fez o deploy;

Passo 4. Vá para a seção de 'Atividades' e clique na aba 'Deploy Self-hosted'.

Próximos passos

• Configure o comando de registro de deploy de Aplicação na sua pipeline;
• Configure Webhook para registrar atividades do repositório da sua Aplicação na tela de Atividades;
• Gerencie sua Aplicação.