Como criar um Self-Hosted Runner do Bitbucket

Introdução

Em um cenário de desenvolvimento ágil e integração contínua, a flexibilidade é importante. É nesse contexto que os Self-Hosted Runners do Bitbucket emergem como uma solução poderosa, oferecendo controle total sobre seu ambiente de build e deploy.

Neste artigo, exploraremos passo a passo como criar seu próprio Bitbucket Runner Auto Hospedado. Essa abordagem não apenas amplia a capacidade de personalização do seu pipeline, mas também proporciona maior eficiência ao permitir a execução de builds em um ambiente familiar e sob seu controle direto.

Tipos de Runners do Bitbucket

O Bitbucket oferece flexibilidade na execução de pipelines de CI/CD através de dois tipos de Runners:

• Shared

• Self-Hosted

Shared Runner:

• Gerenciado pela Nuvem: Você não precisa hospedar ou gerenciar nenhum servidor. O runner compartilhado é gerenciado e hospedado pelo Bitbucket na nuvem.

• Pronto para Uso: É uma opção pronta para uso, eliminando a necessidade de configurações adicionais.

• Ideal para Projetos Menores: Adequado para projetos menores e equipes que buscam uma solução rápida e eficiente sem a necessidade de manutenção direta.

• Cobrança: Oferece um limite de minutos de execução no plano gratuito com possibilidade de realizar upgrades.

Self-Hosted Runner:

• Controle Total: Você precisa hospedar ou gerenciar o servidor. O runner self-hosted oferece controle total ao permitir que você configure e mantenha seus próprios agentes de build.

• Adaptabilidade ao Ambiente: Permite a execução de builds em um ambiente que você controla, com a flexibilidade de adaptar recursos conforme necessário.

• Adequado para Projetos Complexos: Ideal para projetos maiores, equipes que requerem ambientes específicos ou aqueles que precisam integrar com recursos internos.

• Cobrança: Você tem a cobrança do seu servidor, mas seus minutos são ilimitados e você não será cobrado pelo limite e preço do Bitbucket.

Nível do Workspace

Se você for um administrador do espaço de trabalho, poderá configurar e gerenciar vários runners para toda a sua conta para que possam ser usados ​​em pipelines em qualquer repositório no espaço de trabalho. Isso torna mais fácil e economiza tempo na criação e gerenciamento de seus runners quando você tem muitos repositórios em seu espaço de trabalho.

Nível do Repositório

Você opcionalmente pode configurar e gerenciar runners para determinados repositórios, limitando seu uso em toda a organização, porém isso pode demandar mais tempo de administração sua.

Benefícios do Self-Hosted Runner

• Configurações de build personalizadas: os runners permitem que você configure seu hardware para diferentes tipos de build. Por exemplo, se seu build tiver que consumir muitos recursos, usar hardware com mais memória pode melhorar o tempo de execução.

• Acesse aplicativos ou bancos de dados internos: ao executar pipelines na infraestrutura do Bitbucket com shared runners, dificulta o trabalho para poder acessar sistemas internos como banco de dados por exemplo. Se você precisa executar testes de integração em seus bancos de dados ou aplicativos internos, você poderá fazer isso com runners auto hospedados na mesma rede fornecendo acesso necessário aos serviços internos.

• Fluxos de trabalho híbridos: você pode otimizar seus recursos usando runners auto hospedados com configurações personalizadas para builds que exigem isso e usar a infraestrutura do Bitbucket com shared runners para outros trabalhos.

Todo esse contexto é interessante, mas talvez seu principal motivo seja resolver esse aviso em sua conta Bitbucket:

Se você atingir o limite mensal do plano gratuito, receberá esse aviso e ficará incapaz de continuar usando os shared runners até o próximo mês, você pode resolver isso realizando um upgrade de conta ou usando seu próprio runner, e sim, se você usar seu próprio runner você também terá os custos relacionados a isso, mas considerando que você pode cria-lo no seu mesmo ambiente e que pode obter minutos ilimitados (pois ele é seu), talvez faça sentido considerar esse custo ao invés do custo de upgrade de conta no Bitbucket, você deve colocar na balança o melhor custo-benefício e decidir pela melhor escolha no seu cenário.

Tutorial Prático - Pré-Requisitos

Para a instalação de um Runner auto hospedado do Bitbucket, como o nome sugere você precisará de uma máquina, isso pode ser desde seu próprio computador até qualquer VPS de sua preferência.

Criando uma instância Lightsail

1- Acesse o console AWS → Lightsail → Create Instance

2- Escolha a região

3- Escolha o sistema operacional

4- Não adicione um script de inicialização, não altere sua chave key-pair e não habilite snapshots automáticos, as opções padrões parecem boas aqui.

5- Escolha Dual Stack, pois ainda há limitações para uso do IPv6 e precisamos que nossa instância tenha IPv4 também.

6- Selecione o tamanho da instância

7- Defina um nome, opcionalmente você pode inserir tags e clique em criar instância

8- Aguarde até o status Pending mudar para Running

Criando um IP Fixo

Se olharmos bem, a instância Lightsail recebeu um IPv4 e IPv6 público dinâmicos, isso aconteceu porque selecionamos a opção Dual Stack quando criamos a instância. O dinâmico significa que quando desligarmos essa instância e ligarmos novamente, esses endereços IPs irão mudar, isso pode ser um pouco chato e frustrante de se lembrar, principalmente quando você está tentando se conectar a ela.

Então vamos resolver isso criando um IP Fixo.

1- No console AWS Lightsail → Networking

2- Clique em Create Static IP

3- Mantenha a mesma região e zona de disponibilidade da sua instância → escolha a instância recém criada

4- Defina um nome → Create

Conectando via SSH na instância Lightsail

Se você não quiser usar um cliente SSH, pode fazer isso diretamente no console da AWS clicando nesse botão:

Se você estiver usando uma distribuição linux, como por exemplo ubuntu, poderia acessar também através do seu terminal com o comando:

ssh -i <LightsailDefaultKey.pem> <user>@<public-ip>

# Example
ssh -i LightsailDefaultKey.pem ubuntu@44.198.68.63

Porém como estou usando em meu computador o sistema operacional Windows, eu poderia fazer isso através do WSL2 com Prompt de Comando , Powershell ou Terminal do Windows, o Putty e muitas outras opções de clientes SSH disponíveis.

Mas prefiro usar o cliente gratuito chamado Termius, você pode obtê-lo em sua página de download e talvez seja necessário criar uma conta gratuita, há planos pagos disponíveis, mas o gratuito aqui é suficiente.

Também há opções disponíveis para Mac e Linux no final da página;

Não importa qual ferramenta SSH você usará, vimos agora que há muitas opções, tudo que você precisa ter em mente aqui é que você precisa se conectar na instância de alguma forma para seguirmos o tutorial.

1- Acesse o console AWS Lightsail → Account → SSH Keys

2- Procure por Default Keys → download

3- Abra o cliente SSH (em nosso exemplo Termius) → clique no ícone de engrenagem

4- Defina um nome de sua preferência → mova o arquivo da sua chave keypair que baixou do console AWS

5- Clique em New Host

6- Preencha os campos com:

• Address: o IP da instância

• Label: nome de sua preferência

• User: ubuntu

• Selecione Key

Clique em Connect

Clique em Continue

Instalando o Docker e Docker Compose

Uma vez conectado na instância, você precisará instalar o Docker e o Docker Compose, por favor copie o código de instalação que criamos em outro artigo disponível aqui:

• 👉 Como Instalar ou Atualizar o Docker e o Docker Compose

Cole em seu terminal e pressione Enter.

Aguarde a instalação e ao final você deverá ver algo parecido com:

Adicionando um Self-Hosted Runner do Bitbucket

1- Acesse sua conta Bitbucket → ícone de engrenagem → Workspace Settings

2- Clique em Workspace runners → Add runner

3- Escolha Linux Docker (x86_64)

4- Defina um nome de sua preferência → crie um label

5- Clique em Next → e ele fornecerá uma saída de comando como a seguinte

docker container run -it \
-v /tmp:/tmp -v /var/run/docker.sock:/var/run/docker.sock \
-v /var/lib/docker/containers:/var/lib/docker/containers:ro \
-e ACCOUNT_UUID={xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} \
-e REPOSITORY_UUID={xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} \
-e RUNNER_UUID={xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} \
-e RUNTIME_PREREQUISITES_ENABLED=true \
-e OAUTH_CLIENT_ID=xxxxxxxxxxxxxxxx \
-e OAUTH_CLIENT_SECRET=xxxxxxxxxxxxxxxxxx \
-e WORKING_DIRECTORY=/tmp --name runner-xxxxxxxxxxxxxxxxxx docker-public.packages.atlassian.com/sox/atlassian/bitbucket-pipelines-runner:1

6- Cole em seu terminal SSH → Enter

7- Feche seu terminal SSH → retorne para sua conta Bitbucket

8- Abra novamente seu terminal → obtenha o ID do container do seu runner com o comando:

docker ps --format 'table {{.ID}}\t{{.Names}}\t{{.Status}}'

9- Digite o comando abaixo para atualizar o restart policy deste container:

docker update --restart always <your-container-id>

10- Verifique a inspeção de container com o novo restart policy definido:

docker inspect -f '{{ json .HostConfig.RestartPolicy }}' <your-container-id>

Use o Self-Hosted Runner do Bitbucket

Para usar seu Self-Hosted Runner criado, você deve definir o seguinte trecho em seu arquivo bitbucket-pipelines.yml:

runs-on:
  - "lightsail1"

Vamos para um exemplo:

1- Crie um arquivo bitbucket-pipelines.yml na raíz do seu repositório, por exemplo:

definitions:

  hello_my_self_hosted_runner: &hello_my_self_hosted_runner
    name: Hi
    image: atlassian/default-image:4
    services:
      - docker
    runs-on:
      - "lightsail1"
    script:
      - echo "Hello, I'm running on Bitbucket's Self-Hosted Runner"

pipelines:

  branches:

    main:
      - stage:
          name: Production
          deployment: production
          steps:
            - step: *hello_my_self_hosted_runner

Bônus - Segurança

Se você utilizar uma conexão entre Bitbucket e AWS com OpenID Connect, descrevemos o passo a passo de como fazer isso aqui:

• 👉 Como configurar a Autenticação entre Bitbucket e AWS com OpenID Connect (OIDC)

Você pode aumentar ainda mais a sua segurança limitando o acesso apenas a este Self-Hosted Runner com o trecho SourceIp da seguinte forma:

{
  "Effect": "Allow",
  "Principal": {
    "Federated": "arn:aws:iam::{AWS_ACCOUNT_NUMBER}:oidc-provider/api.bitbucket.org/2.0/workspaces/{WORKSPACE}/pipelines-config/identity/oidc"
  },
  "Action": "sts:AssumeRoleWithWebIdentity",
  "Condition": {
    "StringLike": {
      "api.bitbucket.org/2.0/workspaces/{WORKSPACE}/pipelines-config/identity/oidc:sub": "{REPO_UUID}:*"
    },
    "IpAddress": {
      "aws:SourceIp": [
        "<your-runner-ip>"
      ]
    }
  }
}

Limites de Uso

O Self-Hosted Runner tem os seguintes limites de uso:

• Máximo de memória disponível: você pode configurar até 32 GB (8x) de memória

• Número total de runners: você pode configurar até 100 runners por workspace e 100 runners por repositório

• Tempo de fila dos steps: os steps podem ficar na fila por no máximo 2,5 horas

Conclusão

Em resumo, a escolha entre um Shared Runner e um Self-Hosted Runner no Bitbucket Pipelines depende das necessidades específicas do seu projeto. O Shared Runner oferece praticidade para projetos menores, enquanto o Self-Hosted Runner proporciona controle total, personalização e eficiência em ambientes mais complexos.

Vimos em um tutorial prático o passo a passo de como criar um Self-Hosted Runner hospedado na AWS. Também vimos que é possível limitar a segurança para um IP específico para que você tenha certeza de estar usando somente seu runner.

Se você observar bem, todo o processo ainda é manual e você pode repeti-lo quantas vezes precisar. Você ainda pode pensar em uma solução automática para lançar seus runners e escalar eles, mas para a grande maioria esse procedimento manual será suficiente.

Ao entender os benefícios do Self-Hosted Runner, como controle total do ambiente, personalização flexível e integração com recursos internos, você pode tomar decisões mais informadas para otimizar seus processos de CI/CD. Escolha o tipo de Runner que se alinha melhor com os requisitos únicos do seu projeto, garantindo uma implementação eficaz e adaptada ao seu ambiente de desenvolvimento.