Visão Geral do Concourse

Concourse é uma ferramenta open-source de CI/CD mantida originalmente pela Pivotal, projetada para executar tarefas através de mecanismos de pipeline com preservação de estado. A plataforma é frequentemente utilizada em conjunto com o Pivotal Cloud Foundry (PCF).

Principais características:

• Visualização de fluxos de recursos através de pipelines baseados em jobs
• Versionamento das configurações de pipeline para facilitar migração e recuperação
• Execução isolada em containers, evitando contaminação entre ambientes
• Configuração completa via arquivos YAML com suporte a múltiplos pipelines independentes

Recursos úteis:

• Site oficial
• Exemplos oficiais
• Documentação completa
• Tipos de recursos

Arquitetura Fundamental

A arquitetura do Concourse baseia-se em três abstrações principais: Resource, Job e Task. Estes componentes são combinados através de pipelines definidos em YAML, onde as construções ocorrem dentro de containers isolados.

Task (Tarefa)

Uma Task representa a unidade mínima de execução no Concourse. Ela roda scripts dentro de um container recém-criado, que já possui diretórios pré-configurados para entrada e saída de dados.

Características das Tasks:

• Execução em ambiente isolado com acesso aos recursos dependentes
• Pode ser invocada por um Job ou executada manualmente via CLI
• Funciona como uma função com parâmetros de entrada e saída
• Retorna código de saída 0 para sucesso ou código diferente para falha

Resource (Recurso)

Recursos representam entidades versionadas externas, como repositórios Git, buckets S3 ou até mesmo gatilhos temporais. Eles servem como pontos de abstração para dependências externas do sistema.

Comportamentos dos recursos:

• Monitoramento de novas versões (check)
• Download de conteúdo (get)
• Publicação de artefatos (put)
• Diferentes tipos encapsulam padrões comuns, oferecendo uma interface extensível

Job (Trabalho)

Jobs definem sequências de operações get, put e task que determinam como os recursos fluem pelo pipeline. Cada execução de um Job é chamada de Build.

Propriedades dos Jobs:

• Construído a partir de um plano que combina recursos e tasks
• Pode ser acionado automaticamente por mudanças em recursos ou manualmente
• Funciona como uma função que executa quando novos inputs estão disponíveis
• Pode encadear saídas de jobs anteriores como entrada
• Todas as tasks do plano devem ter sucesso para o build ser considerado bem-sucedido
• Builds falhos podem ser reexecutados localmente usando a ferramenta Fly

Pipeline

Pipelines orquestram recursos e jobs, representando todo o estado externo do sistema. Os tipos de recursos são definidos dentro do próprio pipeline, tornando-o autocontido e mantendo o núcleo do Concourse pequeno e genérico.

Configuração Detalhada

Definição de Resources

Recursos são declarados na seção resources do arquivo de pipeline e referenciados nos jobs através de operações get e put.

Propriedade	Descrição	Obrigatório
name	Identificador único do recurso	Sim
type	Tipo do recurso (git, s3, etc.)	Sim
source	Configurações específicas do tipo de recurso	Não
check_every	Intervalo de verificação de novas versões (padrão: 1m)	Não
tags	Filtra workers por tags específicas	Não

Configuração de Jobs

Cada Job contém um plano de execução que define a sequência de operações. Abaixo estão as principais propriedades:

Propriedade	Descrição
name	Nome identificador do job (obrigatório)
serial	Execução sequencial dos builds (padrão: false)
public	Torna logs públicos sem autenticação (padrão: false)
build_logs_to_retain	Número de logs de build a manter
max_in_flight	Limite de builds simultâneos
plan	Sequência de operações a executar (obrigatório)

Elementos disponíveis dentro do plan:

• task - Executa uma tarefa definida em arquivo YAML
• get - Baixa um recurso; com trigger: true ativa execução automática
• put - Publica ou modifica um recurso
• passed - Define pré-requisitos de jobs anteriores
• aggregate - Executa operações em paralelo

Especificação de Tasks

Tasks são definidas em arquivos YAML separados com a seguinte estrutura:

Seção	Descrição	Obrigatório
platform	Sistema operacional (linux, windows, darwin)	Sim
inputs	Lista de entradas com name e path opcionais	Sim
run	Comando a executar com path obrigatório e args/dir/user opcionais	Sim
outputs	Diretórios para artefatos gerados	Não

Exemplo de definição de task:

---
platform: linux

image_resource:
  type: docker-image
  source:
    repository: ubuntu
    tag: "22.04"

inputs:
  - name: codigo-fonte
    path: /app/src

outputs:
  - name: compilado

run:
  path: /bin/bash
  args:
    - -c
    - |
      cd /app/src
      make build
      cp -r dist/* /compilado/
  user: root

Utilizando a CLI Fly

Fly é a ferramenta de linha de comando do Concourse para gerenciamento de instâncias, pipelines e jobs.

Instalação

Baixe o binário correspondente ao seu sistema operacional na página de releases. Adicione o executável ao PATH do sistema e verifique a instalação:

fly --version

É importante que a versão do Fly seja idêntica à versão do servidor Concourse para evitar problemas de compatibilidade.

Autenticação

fly --target meutarget login \
  --team-name equipe-devops \
  --concourse-url https://ci.exemplo.com

Gestão de Pipelines

# Definir ou atualizar pipeline com variáveis de múltiplos arquivos
fly -t meutarget set-pipeline \
  -p pipeline-deploy \
  -c pipeline.yml \
  -l variaveis.yml \
  -l segredos.yml \
  -v ambiente=staging

# Ativar pipeline
fly -t meutarget unpause-pipeline -p pipeline-deploy

# Listar todos os pipelines
fly -t meutarget pipelines

# Visualizar configuração atual de um pipeline
fly -t meutarget get-pipeline -p pipeline-deploy

# Remover pipeline
fly -t meutarget destroy-pipeline -p pipeline-deploy

Operações em Jobs

# Ativar job específico
fly -t meutarget unpause-job -p pipeline-deploy -j compilar-app

# Disparar execução manual com acompanhamento de logs
fly -t meutarget trigger-job \
  -j pipeline-deploy/compilar-app \
  --watch

# Cancelar build em andamento
fly -t meutarget abort-build \
  -j pipeline-deploy/compilar-app \
  -b 42

# Listar jobs de um pipeline
fly -t meutarget jobs -p pipeline-deploy

# Histórico de builds
fly -t meutarget builds -j pipeline-deploy/compilar-app

Monitoramento de Resources

# Verificar status dos recursos
fly -t meutarget resources -p pipeline-deploy

# Forçar verificação de um recurso com acompanhamento
fly -t meutarget check-resource \
  -r pipeline-deploy/codigo-fonte \
  --watch

Execução Local de Tasks

# Executar task localmente com inputs
fly -t meutarget execute \
  --config task-teste.yml \
  --input codigo-fonte=./meu-projeto

Aliases e Abreviações

O Fly oferece aliases para comandos frequentes:

Alias	Comando completo
sp	set-pipeline
gp	get-pipeline
up	unpause-pipeline
dp	destroy-pipeline
tj	trigger-job
js	jobs
bs	builds
w	watch

Exemplo de Pipeline Completo

---
resource_types:
  - name: slack-notifier
    type: docker-image
    source:
      repository: cfcommunity/slack-notification-resource

resources:
  - name: repo-app
    type: git
    source:
      uri: https://github.com/equipe/app.git
      branch: main

  - name: bucket-artefatos
    type: s3
    source:
      bucket: artefatos-ci
      region_name: us-east-1
      access_key: ((aws_access_key))
      secret_key: ((aws_secret_key))

  - name: notificacao-slack
    type: slack-notifier
    source:
      url: ((slack_webhook_url))

jobs:
  - name: compilar
    public: true
    plan:
      - get: repo-app
        trigger: true
      - task: build-app
        file: repo-app/ci/tasks/compilar.yml
      - put: bucket-artefatos
        params:
          file: resultado-build/*.tar.gz

  - name: testar
    serial: true
    plan:
      - get: repo-app
        passed: [compilar]
      - get: bucket-artefatos
        passed: [compilar]
      - task: executar-testes
        file: repo-app/ci/tasks/testar.yml
      - put: notificacao-slack
        params:
          channel: '#ci-alerts'
          text: "Testes do build $BUILD_NAME concluídos"
    on_failure:
      put: notificacao-slack
        params:
          channel: '#ci-alerts'
          text: "FALHA nos testes do build $BUILD_NAME"

  - name: implantar-producao
    serial: true
    serial_groups: [deploy]
    plan:
      - get: bucket-artefatos
        passed: [testar]
      - task: deploy
        file: repo-app/ci/tasks/deploy.yml
        params:
          DESTINO: producao
    ensure:
      put: notificacao-slack
        params:
          channel: '#ci-alerts'
          text: "Deploy para produção finalizado"

Diagnóstico de Problemas

Fluxo recomendado para investigar falhas em pipelines:

1. Verificar se o pipeline está ativo: fly -t alvo status -p nome-pipeline
2. Listar builds recentes do job: fly -t alvo builds -j pipeline/job
3. Cancelar builds pendentes antigos: fly -t alvo abort-build -j pipeline/job -b 15
4. Inspecionar status dos recursos: fly -t alvo resources -p pipeline
5. Monitorar verificação de recursos: fly -t alvo check-resource -r pipeline/recurso --watch
6. Visualizar logs do build: fly -t alvo watch -j pipeline/job -b 15

Recursos de Aprendizado

• Tutorial interativo do Concourse
• Tutorial no GitHub
• Amostras de pipelines
• Wiki oficial