Usar o Runtimes Self-Hosted Azure DevOps

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

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

Dica!

Recomenda-se priorizar o uso da Credencial de Serviço.

• O Runner do provedor deve suportar Docker in Docker;
• Ter uma Aplicação ou Infraestrutura criada e registrada na StackSpot.
• Ter dois buckets AWS para salvar os IaCs gerados e TFstates gerenciados (podem ser o mesmo bucket).

Como usar o Self-Hosted Runtimes

Para usar o Runtimes Self-hosted no Azure Pipelines, você deve primeiro criar e configurar uma pipeline para executar uma Action da StackSpot.

Confira os passos a seguir:

Implemente o exemplo do Workflow na sua pipeline

Passo 1. Crie um novo arquivo de Workflow em seu repositório. Por exemplo: stackspot_deploy.yml;

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

Manifesto de Pipeline para Action StackSpot

stackspot_deploy.yml

trigger:
  - none

name: Stackspot Deploy

pool:
  name: your-runner-of-choice

stages:
  - stage: Deploy
    displayName: Deploying Using Runtimes
    jobs:
      - job: InstallCLI
        displayName: "Installing CLI"
        steps:
          - bash: | # Installs AWS CLI
              if ! command -v aws &> /dev/null
              then
                  echo "AWS CLI not found. Installing..."
                  curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
                  apt install -y unzip
                  unzip awscliv2.zip
                  sh ./aws/install
              else
                  echo "AWS CLI is already installed."
              fi
            displayName: Check and Install AWS CLI
          - bash:
              | # Assumes the role that has permission to create/update aws services
              aws sts assume-role \
                --role-arn <role-arn> \
                --region <region> \
                --role-session-name azure-deploy \
                --output json >> ./cred.json

              # Output the variables for use in subsequent steps
              echo "##vso[task.setvariable variable=AWS_ACCESS_KEY_ID;isSecret=true]$(jq -r '.Credentials.AccessKeyId' cred.json)"
              echo "##vso[task.setvariable variable=AWS_SECRET_ACCESS_KEY;isSecret=true]$(jq -r '.Credentials.SecretAccessKey' cred.json)"
              echo "##vso[task.setvariable variable=AWS_SESSION_TOKEN;isSecret=true]$(jq -r '.Credentials.SessionToken' cred.json)"
            displayName: STS

          - bash: | # Installs Stackspots CLI to create deployment
              apt-get -qq update
              apt-get install -y curl git 

              # Clean CLI Install
              rm -rf $HOME/.stk

              # Faz o download e instala o STK CLI
              curl -fsSL https://stk.stackspot.com/install.sh | bash

              # Verifica a instalação do STK CLI
              $HOME/.stk/bin/stk --version
            displayName: Installing CLI
          - bash:
              | # Logins using your credentials - ID and Key should be secrets
              $HOME/.stk/bin/stk login --client-id $(STK_CLIENT_ID) --client-key $(STK_CLIENT_KEY) --realm <realm>
              $HOME/.stk/bin/stk use workspace runtime
            displayName: Logging In
          - checkout: self
            displayName: "Checking out repo"
          - bash: |
              export INPUTS_CLIENT_ID=$(STK_CLIENT_ID)
              export INPUTS_CLIENT_KEY=$(STK_CLIENT_KEY)
              export INPUTS_CLIENT_REALM=<realm>
              export INPUTS_TF_STATE_REGION=sa-east-1
              export INPUTS_IAC_REGION=sa-east-1
              export INPUTS_AWS_REGION=sa-east-1
              export INPUTS_IAC_BUCKET_NAME=000000000000-your-bucket-to-save-generated-iac
              export INPUTS_TF_STATE_BUCKET_NAME=000000000000-your-bucket-to-save-managed-tfstates
              export INPUTS_AWS_SECRET_ACCESS_KEY=$(AWS_SECRET_ACCESS_KEY)
              export INPUTS_AWS_ACCESS_KEY_ID=$(AWS_ACCESS_KEY_ID)
              export INPUTS_AWS_SESSION_TOKEN=$(AWS_SESSION_TOKEN)
              export INPUTS_ENVIRONMENT=<deployment-environment>
              export INPUTS_REPOSITORY_NAME=$(Build.Repository.Name)
              export INPUTS_VERSION_TAG=$(System.JobId)-$(System.JobAttempt)
              export INPUTS_DYNAMIC_INPUTS="--additional-input <additional-input-value>"

              # Download Deploy action 
              git clone https://github.com/stack-spot/workflow-stackspot-actions-runtime-selfhosted.git
              cd workflow-stackspot-actions-runtime-selfhosted
              export run_action_path=$(pwd)
              cd ..

              cd ./dot-stk-folder-parent
              $HOME/.stk/bin/stk run action $run_action_path --workflow_type deploy --non-interactive
            displayName: Deploying

Passo 3. Crie um pipeline baseada neste workflow em seu repositório;

Passo 4. Adicione as variáveis STK_CLIENT_ID e STK_CLIENT_KEY da sua credencial de serviço como segredos:

Sobre o manifesto

Neste manifesto de pipeline, você encontra a configuração necessária para executar uma Action da StackSpot em uma imagem baseada em Ubuntu. Se estiver utilizando outro tipo de imagem, ajuste os comandos conforme necessário.

Este manifesto seguirá os passos a seguir para garantir que a Action funcione corretamente:

1. Instalação das dependências necessárias:

   • Curl;
   • Git;
   • STK CLI;
   • AWS CLI: caso o runner não tenha acesso direto as Clouds.
   • jq se precisar extrair credenciais AWS.

2. (Opcional) Clonar o repositório oficial da Action: Você pode clonar diretamente o repositório público da Action de Runtimes Self-Hosted da StackSpot: Repositório GitHub.

Dica!

StackSpot Action Este passo é opcional. Você pode clonar o repositório e publicá-lo na sua própria conta da StackSpot, permitindo assim controle e uso por versão semântica no comando de run action.

3. Definição dos inputs da Action: No arquivo, é abordada uma forma de definir os inputs das Actions StackSpot via variáveis de ambiente. Se preferir passar os inputs diretamente no comando run action, você pode modificar o arquivo. Para mais informações, consulte a documentação de Executar Actions.

4. Login na StackSpot: Realiza o login utilizando as credenciais de serviço.

5. Uso de um Workspace da StackSpot: Verifique se você está usando o Workspace correto da StackSpot, que corresponde à Aplicação ou Infraestrutura onde será realizado o deploy, destroy ou rollback.

6. Execução da Action StackSpot Runtimes Self-Hosted: A Action será executada na pasta da Aplicação ou Infraestrutura onde o deploy, destroy ou rollback será realizado. É fundamental que a Action esteja na pasta correta; caso contrário, a execução não funcionará.

O que a Action StackSpot Runtimes Self-Hosted faz

1. Analisa os Plugins aplicados na Infraestrutura ou Aplicação, e a API de Runtimes orquestra a ordem de provisionamento, retornando uma lista de tarefas para as próximas Actions executarem;

2. Gera o IaC (terraform) do Plugin aplicado à Infraestrutura ou Aplicação, substituindo as variáveis do template do Plugin;

3. Executa a task DEPLOY_SELF_HOSTED, que baixa e aplica o IaC (Terraform) na Infraestrutura do cliente. O arquivo tfstate gerado é armazenado no bucket configurado, e o processo continua;

4. Quando um Plugin é removido, uma task DESTROY_SELF_HOSTED é gerada, e a Action executa um Terraform destroy no tfstate do Plugin;

5. Notifica a API de Runtimes quando uma execução de pipeline é interrompida, seja por cancelamento manual, falha em um passo customizado ou desligamento do runner. Isso garante que a API seja informada sobre o erro, evitando bloqueios futuros na execução de pipelines para a mesma Aplicação e ambiente. Sem essa notificação, a API impediria novas execuções, exigindo intervenção manual. Essa Action assegura que o fluxo de execução não fique travado.

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

Acompanhar o status do deploy

Você pode acompanhar o status do deploy 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. Execute o comando a seguir para acompanhar o status:

stk deploy status <deploy-id> --watch

Você encontra o deploy id durante a execução do deploy na sua pipeline. Confira o exemplo a seguir:

RUN DEPLOY_SELF_HOSTED successfully started with ID: 01J9V6MWFTWQ392331QBCS46KQ

Inputs disponíveis

Inputs obrigatórios

• INPUT_AWS_ACCESS_KEY_ID obrigatório

  • ID da Chave de Acesso AWS.

• INPUT_AWS_SECRET_ACCESS_KEY obrigatório

  • Chave de Acesso Secreta AWS.

• INPUT_AWS_SESSION_TOKEN obrigatório

  • Token de Sessão AWS.

• INPUT_CLIENT_ID obrigatório

  • ID do Cliente para autenticação (Credencial de Serviço).

• INPUT_CLIENT_KEY obrigatório

  • Chave do Cliente para autenticação (Credencial de Serviço).

• INPUT_CLIENT_REALM obrigatório

  • Realm do Cliente para autenticação (Credencial de Serviço).

• INPUT_REPOSITORY_NAME obrigatório

  • Nome do repositório.

• INPUT_AWS_REGION obrigatório

  • Região AWS do deploy.

• INPUTS_IAC_REGION obrigatório

  • Região para o Bucket IAC a seguir.

• INPUTS_IAC_BUCKET_NAME obrigatório

  • Nome do bucket S3 para salvar o IaC gerado pelos Plugins.

• INPUTS_TF_STATE_REGION obrigatório

  • Região para o Bucket TFstate a seguir.

• INPUTS_TF_STATE_BUCKET_NAME obrigatório

  • Nome do bucket S3 para salvar os TFstates gerenciados do Terraform.

• INPUTS_ENVIRONMENT obrigatório

  • Ambiente de deployment cadastrado na conta da StackSpot(ex.: dev, staging, prod).

• INPUTS_VERSION_TAG obrigatório

  • Tag de versão para adicionar a tag mo deploy (ex.: v1.0.0).

    Atenção!

    Tags não são reutilizáveis para uma Infraestrutura no mesmo ambiente.

Inputs Opcionais

• INPUTS_DYNAMIC_INPUTS

  • Inputs dinâmicos adicionais. Inputs dinâmicos adicionais serão incluídos automaticamente em cada Plugin ao solicitar um deploy. (ex.: --additional-input <additional-input-value>)

• INPUT_PATH_TO_MOUNT

  • Caminho para montagem no Docker, caso o seu plugin precise de arquivos do repositório ou gerados em pipeline. Esse caminho será montado no diretório de trabalho (workdir) do Docker e poderá ser acessado pelo Terraform, se necessário.
  • Valor Padrão: .

• INPUT_TF_PARALLELISM

  • Nível de paralelismo do Terraform, utilizado apenas em deploys unificados, define o número máximo de execuções simultâneas do Terraform.
  • Valor Padrão: 10.

• INPUT_FEATURES_LEVEL_LOG

  • Nível de Log do Serviço StackSpot.

  • Valor Padrão: info.

    Atenção!

    Informações Sensíveis

  Evite usar os modos DEBUG ou TRACE sem necessidade, pois eles podem expor informações sensíveis na pipeline. Use-os com cautela para garantir a segurança dos dados.

  :::

• INPUT_FEATURES_TERRAFORM_LOGPROVIDER

  • Nível de Log para o provedor Terraform.
  • Valor Padrão: info.

• INPUT_FEATURES_RELEASE_LOCALEXEC

  • Liberação da funcionalidade de local-exec
  • Valor Padrão: False.

• INPUT_FEATURES_TERRAFORM_MODULES

  • Lista de módulos Terraform que serão utilizados no processo de deploy. Se um módulo externo for usado e não estiver incluído nesta lista, a execução será bloqueada.

  • Valor Padrão: [].

  • Estrutura do input:

    [
      {
        "sourceType": "gitHttps",
        "path": "github.com/stack-spot",
        "private": true,
        "app": "app",
        "token": "$(tokenToClone)"
      },
      {
        "sourceType": "terraformRegistry",
        "path": "hashicorp/stack-spot",
        "private": false
      }
    ]

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, selecione o ambiente onde você fez o deploy;

Passo 4. Vá para a seção de 'Atividades' no menu 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.