KIWI: integrando com o Open Build Service e o Git

Temos estudado o KIWI, a ferramenta do openSUSE para criar imagens de sistema no Linux. Temos feito com ele imagens live, mas o KIWI também pode ser usado para fazer discos rígidos virtuais, imagens para dispositivos ARM como o Raspberry Pi e o PinePhone, dentre várias outras possibilidades. O que torna essa ferramenta ainda mais interessante é que é possível integrá-la a outra ferramenta também do Projeto openSUSE, o Open Build Service.

O Open Build Service (OBS) é um sistema genérico para compilar e distribuir pacotes binários a partir de códigos-fonte de forma automática, consistente e reprodutível. Se você desenvolve software para Linux, o OBS pode ser uma mão na roda pra você. Ele oferece um sistema de controle de versões próprio, mas também pode ser integrado a outros, como o Git (GitLab, GitHub, etc). Ele pode gerar pacotes prontos para instalar em diversos formatos (RPM, DEB, etc) para diversas distribuições (openSUSE, Fedora, Debian, Ubuntu, etc) e arquiteturas (i586, x86_64, ARM, etc). O OBS também pode ser integrado ao KIWI, então também é capaz de gerar todos os diversos tipos de imagens que este gera.

Você pode baixar o OBS, instalá-lo em um servidor próprio e usá-lo localmente na sua rede. Ou, mais facil, pode usar o servidor de referência, disponível pública e gratuitamente em build.opensuse.org – o mesmo usado pelo Projeto Linux Kamarada para gerar a imagem ISO que você pode baixar da página Download.

No tutorial de hoje, você verá como pode usar o OBS para criar imagens do KIWI. Também verá como opcionalmente integrá-lo ao Git (nesse cenário, portanto, você usaria OBS + KIWI + Git) – e é isso o que eu faço aqui no Projeto Linux Kamarada.

Tanto o KIWI quanto o OBS já foram assunto de outros posts aqui no blog. Talvez você queira conferi-los antes de continuar:

Como usar o KIWI em conjunto com o OBS está bem documentado:

Building in the Open Build Service

Mas acho essa documentação muito declarativa e explicativa (“isso deve ser assim por causa daquilo”), aqui vamos tentar uma abordagem mais prática (“faça isso, depois aquilo”). Claro, você pode consultá-la para mais informações a qualquer momento.

Vantagens de usar o KIWI com o OBS

A combinação KIWI + OBS tem vantagens quando comparada ao KIWI sozinho rodando localmente:

o OBS hospedará a imagem criada com sucesso mais recentemente para você, que não precisará se preocupar com hospedagem;
o OBS recriará suas imagens automaticamente se um dos pacotes incluídos, uma de suas dependências ou o próprio KIWI for atualizado, de modo que você terá sempre uma imagem com todas as atualizações aplicadas;
o processo de construção de imagens não será executado no seu próprio computador, mas sim no OBS, portanto, economizando seus recursos; e
se uma compilação falhar, você ainda receberá uma notificação por e-mail (se isso estiver habilitado nas suas preferências do OBS).

Exemplos de imagens criadas com KIWI + OBS

Para começar, o melhor é tomar como referência alguma imagem que já é criada com a combinação KIWI + OBS (e, dependendo da imagem, com o Git também).

Por exemplo, confira no OBS os subprojetos do projeto Virtualization:Appliances:Images. As imagens de exemplo que estão no repositório oficial do kiwi, na pasta build-tests, são criadas nesses projetos.

A aplicação da pasta x86/leap/test-image-live, que usamos como exemplo no primeiro tutorial do KIWI, é criada no OBS no pacote Virtualization:Appliances:Images:Testing_x86:leap/test-image-live.

Nos subprojetos mencionados, há também exemplos de imagens criadas apenas com OBS + KIWI, sem integração com o Git.

Como já vimos no primeiro tutorial do KIWI, as imagens live do openSUSE Leap 15.6, que podem ser baixadas em download.opensuse.org, são criadas no projeto openSUSE:Leap:15.6:Images.

O Linux Kamarada também serve de exemplo. A imagem ISO, que você pode baixar da página Download, tem seu código-fonte hospedado no GitLab, no repositório Linux-Kamarada-GNOME, branch (ramo) 15.6, e é gerada no OBS no pacote home:kamarada:15.6/Linux-Kamarada-GNOME.

Links para a versão equivalente em desenvolvimento: GitLab e OBS.

Começando a usar o OBS

Não vou falar sobre os conceitos básicos do OBS aqui, seria assunto para um post inteiro. Para aprender o básico do OBS, consulte as páginas a seguir (em inglês):

Vou assumir que você já consegue entrar (“fazer login”) com sua conta do openSUSE em build.opensuse.org. Se você ainda não tem uma conta, crie uma clicando no link Sign Up (inscrever-se) no topo da página.

Crie um pacote vazio no OBS para a sua aplicação. Para isso, clique em Your Home Project (seu projeto pessoal) e, depois, em Create Package (criar pacote). Nomeie-o como desejar.

Aqui, vou usar kiwi_tutorial, com underline, para diferenciar de kiwi-tutorial, com traço, o repositório do GitLab (voltaremos a ele mais adiante).

Também vou assumir que você instalou o osc (o cliente de linha de comando do OBS) no seu computador. Se você usa openSUSE, pode instalar o osc executando:

# zypper install osc

Crie uma cópia local (“faça checkout”) do seu projeto pessoal do OBS:

$ osc checkout home:kamarada

Entre na pasta do pacote recém-criado:

$ cd home:kamarada/kiwi_tutorial

Copiando o código-fonte da imagem para o OBS

Vamos partir de onde paramos no tutorial anterior (commit 29e68afd).

Para compilar nossa imagem usando OBS + KIWI, não precisaremos mexer no script config.sh. Copie-o como está da pasta kiwi-tutorial para a pasta kiwi_tutorial.

Copie também o arquivo appliance.kiwi. Faremos ajustes nele depois.

Em vez de copiar a pasta root, prefiro compactá-la em um arquivo .tar.gz:

$ tar -czvf root.tar.gz root

Mova esse arquivo para a pasta kiwi_tutorial.

Criando o repositório images no OBS

Um projeto no OBS pode ter vários repositórios: o mesmo código-fonte pode ser usado para compilar pacotes para o openSUSE Leap 15.6, openSUSE Leap 15.5, openSUSE Tumbleweed, etc. E as imagens do KIWI são compiladas em um repositório à parte chamado images (imagens).

Para criá-lo, vamos editar as meta configurações do projeto.

Na interface web do OBS, acesse a página do projeto e clique na aba Meta:

Alternativamente, você pode fazer essa edição localmente usando o terminal:

$ osc meta -e prj

Crie o repositório images por meio do elemento repository. Esse elemento deve ser inserido como filho do elemento project (o de mais alto nível):

<repository name="images">
  <path project="home:kamarada" repository="15.6"/>
  <path project="Virtualization:Appliances:Builder" repository="openSUSE_Leap_15.6"/>
  <path project="openSUSE:Leap:15.6:Update" repository="standard"/>
  <arch>x86_64</arch>
</repository>

Essa configuração não apenas cria o repositório images, como também define de quais repositórios o OBS deve obter pacotes para instalar na imagem.

Configurando os repositórios da imagem

Ao usar o KIWI integrado com o OBS, é altamente recomendado que a configuração de quais repositórios usar seja movida da descrição da imagem do KIWI para a configuração do projeto do OBS.

Abra o arquivo appliance.kiwi. Descomente (ou insira) a configuração para usar os repositórios do OBS e comente (ou remova) os demais repositórios. Ao final, a configuração dos repositórios deve ficar assim:

    <repository type="rpm-md">
        <source path="obsrepositories:/"/>
    </repository>
    <!--<repository alias="repo-update" imageinclude="true" priority="1" type="rpm-md">
        <source path="obs://openSUSE:Leap:15.6:Update/standard"/>
    </repository>
    <repository alias="repo-oss" imageinclude="true" priority="2" type="rpm-md">
        <source path="obs://openSUSE:Leap:15.6/standard"/>
    </repository>-->

A configuração do projeto no OBS já fizemos. Apenas algumas observações.

A ordem em que você lista os repositórios importa: se mais de um repositório fornece o mesmo pacote, ele será obtido do primeiro repositório listado.

E o OBS faz expansão do último repositório listado: os repositórios dos quais ele depende também são considerados.

Portanto, como o repositório openSUSE_Leap_15.6 do projeto Virtualization:Appliances:Builder já usa o repositório standard do projeto openSUSE:Leap:15.6:Update (podemos conferir isso nas meta configurações daquele projeto), podemos simplificar as meta configurações do nosso projeto:

<repository name="images">
  <path project="home:kamarada" repository="15.6"/>
  <path project="Virtualization:Appliances:Builder" repository="openSUSE_Leap_15.6"/>
  <arch>x86_64</arch>
</repository>

Configuração do projeto no OBS

Para usar o KIWI para criar imagens, o OBS requer que toda uma configuração seja feita no projeto.

Na interface web do OBS, acesse a página do projeto e clique na aba Project Config (configuração do projeto):

Alternativamente, você pode fazer essa edição localmente usando o terminal:

$ osc meta -e prjconf

Em vez de começar do zero e fazer toda essa configuração manualmente, a recomendação é copiar a configuração atual de algum outro projeto já existente que use o KIWI para o seu próprio projeto. Isso fornece um bom ponto de partida e você pode adaptar conforme sua necessidade.

Aqui, eu copiei a configuração do projeto openSUSE:Leap:15.6:Images. O único ajuste que fiz foi substituir o pacote python3-kiwi pelo pacote python311-kiwi.

Se quiser mais informações sobre a configuração do projeto no OBS, consulte as documentações do KIWI e do OBS:

Compilando a imagem localmente

Embora o OBS seja um serviço online, não é necessário enviar toda e qualquer alteração para testá-la. O OBS permite compilar pacotes e imagens localmente do mesmo jeito que seria feito remotamente usando o comando osc build. Portanto, se você conseguir compilar com sucesso sua imagem localmente no seu próprio computador com o osc build, terá a certeza que ela também será compilada remotamente no servidor do OBS. Acho interessante testar pelo menos o primeiro envio.

Para compilar sua imagem localmente, execute:

$ osc build images appliance.kiwi

Resolvendo erros do OBS do tipo “unresolvable”

De cara, ao compilar a imagem pela primeira vez, já nos deparamos com um erro comum ao usar o KIWI integrado ao OBS:

Building appliance.kiwi for images/x86_64
Using local file: appliance.kiwi
Getting buildconfig from server and store to /home/linux/home:kamarada/kiwi_tutorial/.osc/_buildconfig-images-x86_64
Getting buildinfo from server and store to /home/linux/home:kamarada/kiwi_tutorial/.osc/_buildinfo-images-x86_64.xml
buildinfo is broken... it says:
unresolvable: have choice for pattern() = laptop: patterns-desktop-laptop patterns-desktop-mobile

Quando o KIWI é executado no OBS, este se responsabiliza pela resolução de dependências, e não começa a compilar a imagem se houver mais de um pacote que possa ser escolhido para satisfazer uma dependência de outro pacote. Daí mostra erros como esse (unresolvable: have choice for… “não foi possível resolver: há escolhas para…”):

unresolvable: have choice for PACOTE: PACOTE_1 PACOTE_2

Isso pode ser resolvido especificando explicitamente um dos dois pacotes na configuração do projeto por meio da seguinte configuração:

Prefer: PACOTE_1

Eu prefiro adicionar ao appliance.kiwi:

<!-- OBS: unresolvable: have choice for pattern() = laptop: patterns-desktop-laptop patterns-desktop-mobile -->
<package name="patterns-desktop-mobile"/>

Assim, garanto que o mesmo pacote será usado tanto na compilação local usando apenas KIWI quanto na compilação remota usando KIWI + OBS.

Faça a alteração que tiver que fazer, seja na configuração do projeto, seja na descrição da imagem, e tente o comando osc build de novo.

Dica: se você está usando algum sistema já instalado como referência para configurar sua imagem, pode ser útil consultar a lista de pacotes instalados nesse sistema para saber qual pacote escolher.

Para listar todos os pacotes instalados no sistema, use:

$ rpm -qa --qf '%{name}\n' | sort > pacotes_instalados

Para pesquisar um pacote nessa lista, use o comando grep:

$ grep tlp pacotes_instalados

tlp
tlp-rdw

$ grep power pacotes_instalados

cpupower
cpupower-bash-completion
cpupower-lang
libcpupower1
libupower-glib3
typelib-1_0-UpowerGlib-1_0
upower
upower-lang

Usando essa dica, resolvi mais dois erros desse tipo que apareceram pra mim:

<!-- OBS: unresolvable: tlp conflicts with power-profiles-daemon -->
<package name="tlp"/>

<!-- OBS: unresolvable: have choice for noto-sans-cjk-fonts needed by patterns-gnome-gnome_x11: google-noto-sans-cjk-fonts noto-sans-cjk-fonts -->
<package name="google-noto-sans-cjk-fonts"/>

Seu arquivo appliance.kiwi agora deve estar assim.

Finalmente, o osc build para de apresentar erros do tipo unresolvable e segue adiante:

$ osc build images appliance.kiwi

Building appliance.kiwi for images/x86_64
Using local file: appliance.kiwi
Getting buildconfig from server and store to /home/linux/home:kamarada/kiwi_tutorial/.osc/_buildconfig-images-x86_64
Getting buildinfo from server and store to /home/linux/home:kamarada/kiwi_tutorial/.osc/_buildinfo-images-x86_64.xml
Updating cache of required packages

The build root needs packages from project 'openSUSE:Leap:15.6'.
Note that malicious packages can compromise the build result or even your system.
Would you like to ...
0 - quit (default)
1 - always trust packages from 'openSUSE:Leap:15.6'
2 - trust packages just this time
? 

Nesse caso, o osc vai precisar baixar pacotes e pergunta se pode confiar no repositório. Digite 1 para sempre confiar nesse repositório e tecle Enter. Ele pode repetir essa pergunta várias vezes, uma para cada repositório que o osc vai precisar usar. Responda todas da mesma forma.

Note que o OBS (e o osc) não roda o KIWI diretamente no sistema do computador. Ele baixa todos os pacotes necessários e faz uma instalação mínima do Linux “enjaulada” (chroot), para então instalar o KIWI e criar a imagem nessa instalação. Com isso, o OBS garante que a descrição da imagem foi escrita corretamente e que a imagem não está sendo compilada com sucesso apenas porque é no seu computador. Isso garante que a compilação da imagem pode ser reproduzida (reproducible build) por qualquer pessoa, em qualquer computador.

Quando terminar de baixar os pacotes, o osc vai exigir a senha do root para criar o ambiente chroot e começar a compilação da imagem.

Ao final, se tudo der certo, você terá uma saída parecida com esta:

[ 2976s] [ INFO    ]: 18:46:21 | Finalizing kiwi-tutorial.x86_64-15.6-Build.packages
[ 2976s] [ INFO    ]: 18:46:21 | Finalizing kiwi-tutorial.x86_64-15.6-Build.verified
[ 2976s] [ INFO    ]: 18:46:21 | Finalizing kiwi-tutorial.x86_64-15.6-Build.iso
[ 2976s] [ INFO    ]: 18:46:21 | --> Creating SHA 256 sum
[ 2982s] 
[ 2982s] kamarada-pc finished "build appliance.kiwi" at Sat Apr 19 18:46:27 UTC 2025.
[ 2982s] 


/var/tmp/build-root/images-x86_64/usr/src/packages/KIWI/kiwi-tutorial.x86_64-15.6-Build.verified
/var/tmp/build-root/images-x86_64/usr/src/packages/KIWI/kiwi-tutorial.x86_64-15.6-Build.iso
/var/tmp/build-root/images-x86_64/usr/src/packages/KIWI/kiwi-tutorial.x86_64-15.6-Build.iso.sha256
/var/tmp/build-root/images-x86_64/usr/src/packages/KIWI/kiwi-tutorial.x86_64-15.6-Build.packages

As últimas linhas indicam onde você pode encontrar os arquivos gerados pelo KIWI. Dentre eles, em especial, a imagem ISO.

Você pode testá-la usando o VirtualBox, como fez no tutorial anterior.

Enviando a imagem para o OBS

Assim que a imagem estiver como deseja, use os comandos a seguir para enviar seu trabalho para o OBS (se você já tiver familiaridade com algum sistema de controle de versões, como o Git, verá que a lógica é parecida).

Por algum motivo que desconheço, percebi que o comando osc build criou uma pasta repos. Se aconteceu com você também, apague-a antes de continuar:

$ rm -rf repos

Confira o status da pasta:

$ osc status

?    appliance.kiwi
?    config.sh
?    root.tar.gz

Nesse caso, nenhum dos 3 arquivos está no controle de versões do OBS. Para adicioná-los, use:

$ osc add *

A    appliance.kiwi
A    config.sh
A    root.tar.gz

Por fim, para enviar as alterações para o OBS, execute:

$ osc commit

Tal como no Git, o editor de texto é aberto para que você forneça uma mensagem para o commit (alteração, revisão). Uma vez que você redija a mensagem, salve e feche o arquivo, o envio é feito:

Sending    appliance.kiwi
Sending    config.sh
Sending    root.tar.gz
Transmitting file data ...
Committed revision 1.

Se você abrir a página do seu pacote no OBS, verá que está sendo compilado (building):

https://build.opensuse.org/package/show/home:kamarada/kiwi_tutorial

Como a compilação local deu certo, é provável que a compilação pelo OBS também dê certo:

Você pode clicar no resultado (succeeded, “com sucesso”) para visualizar o relatório da compilação (build log):

Esse relatório é útil quando algo dá errado na compilação.

Voltando à página do pacote, você pode clicar no nome do repositório images para baixar a imagem ISO gerada para o seu computador:

Integrando com o Git

Opcionalmente, se você prefere o controle de versões do Git, pode integrar o OBS ao Git, mesmo nesse cenário em que o OBS é usado para compilar imagens do KIWI. Nesse caso, o que vai mudar um pouco é o arquivo _service (em comparação com o cenário em que OBS + Git são usados para compilar pacotes RPM).

A seguir, mostrarei como fiz para o projeto kiwi_tutorial do OBS obter seu código-fonte do repositório kiwi-tutorial do GitLab.

Usando o osc, configure o serviço de código-fonte (source service) do OBS para obter o código-fonte do GitLab:

$ osc add https://gitlab.com/kamarada/kiwi-tutorial.git

É criado na pasta do projeto um arquivo _service. Voltaremos a ele.

Antes, exclua os demais arquivos da pasta, deixando apenas ele:

$ rm appliance.kiwi
$ rm config.sh
$ rm root.tar.gz
$ osc status

A    _service
!    appliance.kiwi
!    config.sh
!    root.tar.gz

$ osc rm appliance.kiwi
$ osc rm config.sh
$ osc rm root.tar.gz
$ osc status

A    _service
D    appliance.kiwi
D    config.sh
D    root.tar.gz

Agora abra o arquivo _service e substitua seu conteúdo pelo seguinte:

<services>
    <service name="obs_scm">
        <param name="scm">git</param>
        <param name="url">https://gitlab.com/kamarada/kiwi-tutorial.git</param>
        <param name="revision">master</param>
        <param name="extract">appliance.kiwi</param>
        <param name="extract">config.sh</param>
        <param name="exclude">root</param>
    </service>
    <service name="obs_scm">
        <param name="scm">git</param>
        <param name="url">https://gitlab.com/kamarada/kiwi-tutorial.git</param>
        <param name="revision">master</param>
        <param name="version">_none_</param>
        <param name="subdir">root</param>
        <param name="filename">root</param>
    </service>
</services>

Note que estou usando o ramo (branch) master. Se você pretende obter o código-fonte de outro ramo, mude o valor do parâmetro revision (revisão).

“Comite” as alterações (“faça o commit” das alterações):

$ osc commit

osc commit
Deleting    appliance.kiwi
Deleting    config.sh
Deleting    root.tar.gz
Sending    _service
Transmitting file data .
Committed revision 2.
Waiting for server side source service run
........................
At revision 2.

“Comitar” para o OBS automaticamente dispara o serviço de código-fonte e o processo de compilação da imagem. Se você acessar build.opensuse.org, verá que a imagem está sendo compilada (building):

Note que, ao menos por enquanto, a integração entre OBS e Git está configurada em um sentido só: o OBS consegue obter o código-fonte do Git, mas a cada novo git push, você teria que acessar o OBS e disparar os serviços (Trigger Services) manualmente para compilar a imagem usando o código-fonte mais atual.

Para que o próprio Git possa notificar o OBS de atualizações no código-fonte, você precisa gerar um token de autorização (authorization token). Para ver como fazer isso, continue sua leitura a partir de um destes tutoriais:

Conclusão

Se você deseja criar uma distribuição Linux baseada no openSUSE, ou apenas uma imagem personalizada do openSUSE para usar nos computadores do seu trabalho, ou seja qual for seu propósito, espero que esse tutorial possa ter te ajudado a extrair o melhor das tecnologias KIWI, OBS e Git, assim como faço aqui no Projeto Linux Kamarada.

Se restaram dúvidas, você pode consultar as documentações oficiais do KIWI e do OBS:

Ou escrever suas dúvidas nos comentários. Até a próxima!

Se você gostou muito, se foi muito útil pra você, será que vale um café? Se quiser, você pode "me pagar um café" pelo PayPal ou contribuir com o projeto de outras formas.

Comentários

Please enable JavaScript to view the comments powered by Disqus.