Integração entre o Concourse-CI e o Atlassian Open DevOps

Muitas equipes criam ferramentas próprias para atender as necessidades ou têm ferramentas antigas que usam há anos. São ferramentas essenciais para o processo de desenvolvimento adotado pelas equipes, mas não têm integrações prontas para uso com o Jira. No entanto, é fácil criar a integração personalizada usando as APIs REST da Atlassian contidas na Documentação do Cloud para desenvolvedores - Atlassian Developer . O Concourse-CI é um produto de integração/implementação contínuas (IC) que, no momento da redação deste artigo, não tem integração do Atlassian Marketplace. Este artigo demonstra como gerar uma integração básica entre o Jira e o Concourse-CI usando as APIs REST da Atlassian.

Pré-requisitos

Use a documentação necessária para configurar o Docker, o Docker Compose e o Concourse-CI. O Concourse-CI é executado no Docker e dispo script do Docker Compose para simplificar o início.

Saiba mais sobre o ImageLabeller, o aplicativo de demonstração da Atlassian, aqui. Este artigo demonstra como usar o Concourse-cI para implementar o componente SubmitImage do ImageLabeller no AWS.

Docker

Configure o Docker e o docker-compose seguindo a documentação associada:

Docker: https://docs.docker.com/get-docker/

Docker Compose: https://docs.docker.com/compose/install/

Concourse-CI

Assim que o Docker e o Docker Compose estiverem instalados, o Concourse-CI pode ser iniciado usando o arquivo docker-compose.yml disponibilizado.

Siga o guia de início rápido para começar a usar o Concourse-CI https://concourse-ci.org/quick-start.html#docker-compose-concourse. Este guia exige a transferência segura de credenciais para o Concourse-CI. O guia utiliza a integração entre o Concourse-CI e o AWS Secrets Manager para essa finalidade.

Integração entre o Concourse-CI e o AWS Secrets Manager

Aqui está a documentação sobre como realizar a integração entre o Concourse-CI e o AWS Secrets Manager. Siga as instruções na documentação para ativar e começar a usar a integração.

Para que a integração funcione, é necessário fazer algumas modificações no arquivo docker-compose.yml, usado para iniciar o Concourse-CI. Pegue o arquivo docker-compose.yml padrão oferecido pelo Concourse-CI e adicione

CONCOURSE_AWS_SECRETSMANAGER_ACCESS_KEY, CONCOURSE_AWS_SECRETSMANAGER_SECRET_KEY e CONCOURSE_AWS_SECRETSMANAGER_REGION.

1version: '3'
2
3services:
4  concourse-db:
5    image: postgres
6    environment:
7      POSTGRES_DB: concourse
8      POSTGRES_PASSWORD: concourse_pass
9      POSTGRES_USER: concourse_user
10      PGDATA: /database
11
12  concourse:
13    image: concourse/concourse
14    command: quickstart
15    privileged: true
16    depends_on: [concourse-db]
17    ports: ["8080:8080"]
18    environment:
19      CONCOURSE_POSTGRES_HOST: concourse-db
20      CONCOURSE_POSTGRES_USER: concourse_user
21      CONCOURSE_POSTGRES_PASSWORD: concourse_pass
22      CONCOURSE_POSTGRES_DATABASE: concourse
23      CONCOURSE_EXTERNAL_URL: http://localhost:8080
24      CONCOURSE_ADD_LOCAL_USER: test:test
25      CONCOURSE_MAIN_TEAM_LOCAL_USER: test
26      # instead of relying on the default "detect"
27      CONCOURSE_WORKER_BAGGAGECLAIM_DRIVER: overlay
28      CONCOURSE_CLIENT_SECRET: Y29uY291cnNlLXdlYgo=
29      CONCOURSE_TSA_CLIENT_SECRET: Y29uY291cnNlLXdvcmtlcgo=
30      CONCOURSE_X_FRAME_OPTIONS: allow
31      CONCOURSE_CONTENT_SECURITY_POLICY: "*"
32      CONCOURSE_CLUSTER_NAME: tutorial
33      CONCOURSE_WORKER_CONTAINERD_DNS_SERVER: "8.8.8.8"
34      CONCOURSE_WORKER_RUNTIME: "containerd"
35      CONCOURSE_ENABLE_ACROSS_STEP: "true"
36      CONCOURSE_ENABLE_PIPELINE_INSTANCES: "true"
37      CONCOURSE_AWS_SECRETSMANAGER_ACCESS_KEY: <add access key>
38      CONCOURSE_AWS_SECRETSMANAGER_SECRET_KEY: <add secret key>
39      CONCOURSE_AWS_SECRETSMANAGER_REGION: <add a region>

Depois que a integração estiver configurada e o Concourse-CI estiver funcionando com a integração ativada, adicione os segredos a seguir ao AWS Secrets Manager.

/concourse/main/bitbucket_username

/concourse/main/bitbucket_api_key

/concourse/main/bitbucket_ssh_key

/concourse/main/docker_username

/concourse/main/docker_api_key

/concourse/main/AWS_ACCESS_KEY_ID

/concourse/main/AWS_SECRET_ACCESS_KEY

/concourse/main/AWS_DEFAULT_REGION

Pode ser necessário substituir os segredos do Bitbucket e do Docker se você não estiver usando o Bitbucket para a codificação e o JFrog como repositório do Docker. Como um exercício, faça os ajustes necessários para adequar as ferramentas que você utiliza.

Como trabalhar com o Concourse-CI

Execute o comando docker ps -a antes e depois do comando docker-compose up -d para ver se o Concourse-ci foi iniciado sem erros.

1docker ps -a
2CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES
3
4docker-compose up -d
5Creating network "restapiproject_default" with the default driver
6Creating restapiproject_concourse-db_1 ... done
7Creating restapiproject_concourse_1    ... done
8
9docker ps -a
10CONTAINER ID   IMAGE                 COMMAND                  CREATED         STATUS         PORTS                    NAMES
11bd2b5afd0ac7   concourse/concourse   "dumb-init /usr/loca…"   3 seconds ago   Up 2 seconds   0.0.0.0:8080->8080/tcp   restapiproject_concourse_1
12bd9005b45636   postgres              "docker-entrypoint.s…"   3 seconds ago   Up 2 seconds   5432/tcp                 restapiproject_concourse-db_1

Acesse http://localhost:8080/ depois de executar o comando fly -t tutorial login -c http://localhost:8080 -u test -p test

1fly -t tutorial login -c http://localhost:8080 -u test -p test
2logging in to team 'main'
3target saved

Não há pipelines definidos no momento.

Pipeline hello world

Configure o pipeline hello world seguindo a documentação do Concourse-CI a seguir: https://concourse-ci.org/tutorial-hello-world.html. Isso é necessário para introduzir a interface de linha de comando (CLI) Fly e se acostumar a trabalhar com o Concourse-CI a partir da linha de comando.

A próxima seção demonstra como implementar o AWS Lambda criado em Golang em uma única região do AWS com o Concourse-CI e como criar a atualização para o item do Jira como parte do processo.

Implementar o SubmitImage com o Concourse-CI

Há três etapas para implementar o SubmitImage no Lambda com o Concourse-CI. A primeira etapa é criar um script bash simples que use a API REST do Jira Cloud para escrever um comentário em item do Jira. Essa é a integração mais simples que pode ser criada. A segunda etapa é criar a imagem do Docker com as ferramentas necessárias para gerar e implementar o AWS Lambda criado em Golang. A etapa final é criar um par de arquivos de configuração do Concourse-CI. O primeiro arquivo de configuração, o parent.yml, monitora o repositório SubmiImage em busca de novas ramificações e cria novos pipelines para implementar confirmações dessas ramificações. O segundo arquivo de configuração, o child.yml, define o conjunto necessário de etapas para implementar a alteração.

Etapa 1 - Atualizar itens do Jira por meio da API REST

Esse script de atualização usa a API REST da plataforma Jira Cloud para escrever um comentário em um item específico do Jira. Há cinco parâmetros necessários que devem ser definidos toda vez que o script é executado. O jiraUserName (nome de usuário do Jira), o jiraApiToken (token de API do Jira) e a área de trabalho costumam ser os mesmos para cada execução do pipeline específico. A IssueKey (chave do item) vai depender do nome da ramificação específica que está sendo implantada. Uma prática recomendada do Jira é colocar o ID do item do Jira nos nomes das ramificações e enviar mensagens de confirmação ao trabalhar em um item específico. Este artigo pressupõe que as práticas recomendadas estão sendo seguidas e que os nomes das ramificações são equivalentes ao ID do item do Jira.

Como encontrar os parâmetros

Nome de usuário do Jira

O nome de usuário do Jira é o endereço de e-mail usado para fazer login no Jira.

Token de API do Jira

Vá para Configurações da conta

Clique em Segurança

Clique em Criar e gerenciar tokens de API

Espaço de trabalho

Para a URL de instância do Jira, como https://pmmquickstartguides01.atlassian.net/jira/software/projects/IM/boards/1?selectedIssue=IM-203 a área de trabalho é pmmquickstartguide01.

Chave do item

Para a URL de item do Jira, como https://pmmquickstartguides01.atlassian.net/jira/software/projects/IM/boards/1?selectedIssue=IM-203 a chave do item do Jira é GI-203. Insira o ID do item do Jira nas mensagens de confirmação e nos nomes das ramificações para que a integração possa gravar as atualizações no local correto.

Comentário

O comentário pode ser qualquer coisa.

O script de atualização

O script de atualização é um script de shell bash simples que usa o terminal da API REST de comentário de itens do Jira. Aqui está a documentação para essa chamada de API. O script pode ser modificado para disponibilizar a integração mais profunda seguindo o padrão disponibilizado para fazer chamadas adicionais à API. Copie esse script para um arquivo chamado concourse-ci-integration.sh e o coloque em um repositório do Bitbucket ou do GitHub chamado updateScript.

1#!/usr/bin/env bash
2
3addCommentToIssue() {
4  printf "addCommentToIssue\n"
5
6  local jiraUsername=$1
7  shift
8  local jiraApiToken=$1
9  shift
10  local workspace=$1
11  shift
12  local issueKey=$1
13  shift
14  local comment=$1
15  shift
16
17  curl -s --request POST \
18  --url 'https://'"${workspace}"'.atlassian.net/rest/api/3/issue/'"${issueKey}"'/comment' \
19  --user "${jiraUsername}"':'"${jiraApiToken}" \
20  --header 'Accept: application/json' \
21  --header 'Content-Type: application/json' \
22  --data '{
23    "body": {
24      "type": "doc",
25      "version": 1,
26      "content": [{
27        "type": "paragraph",
28        "content": [{
29          "text": "'"${comment}"'",
30          "type": "text"
31        }]
32      }]
33    }
34  }' | jq
35}
36
37main() {
38  printf "main\n"
39
40  while getopts ":c:k:o:u:t:w:" opt; do
41    case $opt in
42    c)
43      local comment=$OPTARG
44      ;;
45    k)
46      local issueKey=$OPTARG
47      ;;
48    o)
49      local op=$OPTARG
50      ;;
51    u)
52      local jiraUsername=$OPTARG
53      ;;
54    t)
55      local jiraApiToken=$OPTARG
56      ;;
57    w)
58      local workspace=$OPTARG
59      ;;
60    *)
61      printf "invalid option: -${OPTARG}\n" >&2
62      exit 1
63      ;;
64    esac
65  done
66
67  case $op in
68    ac)
69      addCommentToIssue ${jiraUsername} ${jiraApiToken} ${workspace} ${issueKey} "${comment}"
70      ;;
71    *)
72      printf "invalid op: ${op}\n" >&2
73      exit 1
74      ;;
75  esac
76}
77
78main "$@"

Etapa 2 - Dockerfile personalizado

Crie um Dockerfile personalizado com as ferramentas necessárias para gerar e implementar o AWS Lambda criado em Golang. O Dockerfile instala alguns utilitários e adiciona o AWS SAM e o Golang. A imagem do Git clona o script de atualização criado na Etapa 1 a partir de um repositório do Bitbucket. É necessário substituir esse repositório do Bitbucket por qualquer repositório criado para armazenar o script de atualização. O Docker cria esse Dockerfile e o envia para um repositório Docker.

Dockerfile

1# syntax = docker/dockerfile:1.3
2FROM ubuntu:20.04
3
4MAINTAINER wmarusiak@atlassian.com
5
6WORKDIR /workspace
7
8RUN apt-get update \
9&& apt-get -y upgrade \
10&& apt-get -y install curl unzip tar openssh-client git jq
11
12RUN curl https://github.com/aws/aws-sam-cli/releases/latest/download/aws-sam-cli-linux-x86_64.zip -L -o aws-sam-cli.zip \
13&& mkdir sam-installation \
14&& unzip aws-sam-cli.zip -d sam-installation \
15&& ./sam-installation/install \
16&& sam --version
17
18RUN curl https://go.dev/dl/go1.18.2.linux-amd64.tar.gz -L -o go.tar.gz \
19&& rm -rf /usr/local/go \
20&& tar -C /usr/local -xzf go.tar.gz
21
22RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan bitbucket.org >> ~/.ssh/known_hosts
23
24RUN --mount=type=ssh git clone git@bitbucket.org:pmmquickstartguides01/updatescript.git
25
26ENV PATH $PATH:/usr/local/go/bin

Etapa 3 - Arquivos yaml do pipeline de implementação do Concourse-CI

Crie um novo repositório chamado Concourse e adicione dois arquivos nele. O arquivo parent.yml cria um pipeline que monitora um repositório em busca de novas ramificações que correspondam a expressão regular. A expressão regular da ramificação (branch_regex) é IM-* que corresponde a todas as ramificações que começam com IM-. O parent.yml vai criar um novo pipeline usando a configuração no arquivo child.yml quando a nova ramificação que corresponda à expressão regular IM-* for criada. Esse arquivo deve ser atualizado para especificar a sua própria versão do repositório SubmitImage. O código do SubmitImage pode ser encontrado aqui. Copie o código desse repositório para um repositório com permissões de gravação.

parent.yml

1resource_types:
2- name: git-branches
3  type: registry-image
4  source:
5    repository: aoldershaw/git-branches-resource
6
7resources:
8- name: feature-branches
9  type: git-branches
10  source:
11    uri: git@bitbucket.org:pmmquickstartguides01/submitimage.git
12    branch_regex: IM-*
13    private_key: ((bitbucket_ssh_key))
14
15- name: examples
16  type: git
17  source:
18    uri: git@bitbucket.org:pmmquickstartguides01/concourse.git
19    private_key: ((bitbucket_ssh_key))
20
21jobs:
22- name: set-feature-pipelines
23  plan:
24  - in_parallel:
25    - get: feature-branches
26      trigger: true
27    - get: examples
28  - load_var: branches
29    file: feature-branches/branches.json
30  - across:
31    - var: branch
32      values: ((.:branches))
33    set_pipeline: dev
34    file: examples/child.yml
35    vars: {branch: ((.:branch.name))}

O arquivo child.yml define o pipeline com quatro etapas. Primeiro, ele executa o comando sam validate para verificar se o arquivo template.yml do AWS CloudFormation é válido. Em seguida, o comando sam build é executado para criar o pacote SubmitImage em um artefato implementável. Em terceiro lugar, o comando sam deploy é executado para implementar o código atualizado do SubmiImage no AWS. Por fim, o pipeline chama o script de atualização criado na etapa 1 para escrever um comentário no item correspondente do Jira.

child.yml

1resources:
2- name: repo
3  type: git
4  source:
5    uri: git@bitbucket.org:pmmquickstartguides01/submitimage.git
6    branch: ((branch))
7    private_key: ((bitbucket_ssh_key))
8
9jobs:
10- name: deploy-submit-image
11  plan:
12  - get: repo
13    trigger: true
14  - task: run-sam-validate
15    config:
16      platform: linux
17      image_resource:
18        type: registry-image
19        source:
20          repository: docker.atl-paas.net/wmarusiak/ubuntuawssam
21          username: ((docker_username))
22          password: ((docker_api_key))
23      inputs: # add the get step as an input to this task
24      - name: repo
25      run:
26        path: sam
27        args: ["validate", "-t", "repo/template.yml"]
28      params:
29        AWS_ACCESS_KEY_ID: ((AWS_ACCESS_KEY_ID))
30        AWS_SECRET_ACCESS_KEY: ((AWS_SECRET_ACCESS_KEY))
31        AWS_DEFAULT_REGION: ((AWS_DEFAULT_REGION))
32  - task: run-sam-build
33    config:
34      platform: linux
35      image_resource:
36        type: registry-image
37        source:
38          repository: docker.atl-paas.net/wmarusiak/ubuntuawssam
39          username: ((docker_username))
40          password: ((docker_api_key))
41      inputs: # add the get step as an input to this task
42      - name: repo
43      run:
44        path: sam
45        args: ["build", "-t", "repo/template.yml"]
46      params:
47        AWS_ACCESS_KEY_ID: ((AWS_ACCESS_KEY_ID))
48        AWS_SECRET_ACCESS_KEY: ((AWS_SECRET_ACCESS_KEY))
49        AWS_DEFAULT_REGION: ((AWS_DEFAULT_REGION))
50  - task: run-sam-deploy
51    config:
52      platform: linux
53      image_resource:
54        type: registry-image
55        source:
56          repository: docker.atl-paas.net/wmarusiak/ubuntuawssam
57          username: ((docker_username))
58          password: ((docker_api_key))
59      inputs: # add the get step as an input to this task
60      - name: repo
61      run:
62        path: sam
63        args: ["deploy", "-t", "repo/template.yml", "--stack-name", "OpenDevOpsSubmitImage", "--s3-bucket", "open-devops-code-us-west-1-756685045356", "--capabilities", "CAPABILITY_IAM", "CAPABILITY_NAMED_IAM"]
64      params:
65        AWS_ACCESS_KEY_ID: ((AWS_ACCESS_KEY_ID))
66        AWS_SECRET_ACCESS_KEY: ((AWS_SECRET_ACCESS_KEY))
67        AWS_DEFAULT_REGION: ((AWS_DEFAULT_REGION))
68  - task: run-update-script
69    config:
70      platform: linux
71      image_resource:
72        type: registry-image
73        source:
74          repository: docker.atl-paas.net/wmarusiak/ubuntuawssam
75          username: ((docker_username))
76          password: ((docker_api_key))
77      input:
78      -name: repo
79      run:
80        path: /workspace/updatescript/concourse-ci-integration.sh
81        args: ["-c", "successfully deployed submitImage via concourse-ci", "-k", "((branch))", "-o", "ac", "-u", "((bitbucket_username))", "-t", "((bitbucket_api_key))", "-w", "pmmquickstartguides01"]

Como iniciar o pipeline pai

Execute os três comandos a seguir no diretório com o arquivo parent.yml. O primeiro comando efetua login na instância do Concourse-CI em execução local. O segundo comando cria um pipeline chamado wm com base na configuração existente no arquivo parent.yml. O terceiro comando aciona o pipeline wm.

1fly -t tutorial login -c http://localhost:8080 -u test -p test
2fly -t tutorial set-pipeline -p wm -c parent.yml
3fly -t tutorial unpause-pipeline -p wm

Acesse o cliente web do Concourse-CI depois de executar esses três comandos para ver se o pipeline wm está funcionando.

Depois de executar o comando fly set-pipeline com o arquivo parent.yml, tem o pipeline wm. Esse pipeline monitora o SubmitImage em busca de novas ramificações de função e cria um pipeline para cada ramificação de função que corresponda à expressão regular existente em parent.yml.

Clique no pipeline wm para ver as etapas executadas. Observe que a etapa feature-branches (ramificações de função) lista a ramificação chamada GI-61. Essa é a única ramificação no momento em SubmitImage que corresponde à expressão regular existente em parent.yml. Clique no pipeline dev com início automático para ver as etapas executadas.

Observe que há uma etapa para obter o repositório SubmitImage e que a ramificação é GI-61. Observe também que há etapas run-sam-validate, run-sam-build, run-sam-deploy e run-update-script.

Depois que o pipeline dev terminar de realizar todos os procedimentos, volte ao item GI-61 do Jira e observe que há um novo comentário registrado há um minuto que corresponde à sequência de comentários do arquivo child.yml

Conclusão…

Este guia demonstra como configurar o pipeline para implementação automática do AWS Lambda criado em Golang em uma única região do AWS usando o Concourse-CI. Ele também demonstra como usar um script de shell bash para criar a integração simples com o Jira. O script de integração pode ser expandido com o aprofundamento na documentação da API REST da Atlassian disponível aqui.