Builds

Início
Definindo um BuildConfig
Opções Source-to-Image Strategy
Forçar o pull
Builds Incrementais
Sobrescrevendo Builder Image Scripts
Variáveis de Ambiente
Arquivos de Ambiente
Ambiente BuildConfig
Build Inputs
Opções Repositório Git
Usando um proxy para git cloning
Usando repositórios privados para builds
Binary Source
Image Source
Usando secrets durante o build
Definindo secrets no buildconfig
Source-to-Image Strategy
Iniciando um Build
Cancelando um Build
Deletando um BuildConfig
Acessando logs do build
Visualizando detalhes do build
Configurando duração máxima
Build Triggers
Webhook Triggers
Image Change Triggers
Configuration Change Triggers
Build Hooks
Usando credenciais do Docker para fazer push e pull de imagens
Build Output
Output Image variáveis de ambiente
Outpud Image labels
Usando Artefatos externos durante um Build
Troubleshooting

Início

Um build é o processo de transformação de parâmetros de entrada que resultam em um objeto. Mais frequentemente o processo é usado para transformar o código fonte em uma imagem executável.

Build configurations são caracterizados pela strategy e uma ou mais sources. A strategy determina o processo mencionado acima, enquanto as sources fornecem a entrada.

Existem três estrategias de build:

• Source-To-Image(S2I)(descrição, opções)
• Docker(descrição, opções)
• Custom(descrição, opções)

E exitem quatro tipos de build source:

• Git
• Dockerfile
• Image
• Binary

Cabe a cada strategy build considerar ou ignorar um tipo de build source, e qual vai ser usado.

Binary e git são exclusivos source types, enquanto Dockerfile e image podem ser usados por eles mesmo um com o outro, ou juntos com o Git ou Binary.

O Binary buid source é unico na forma de como é especificado no sistema. Exatamente como é descrito abaixo.

Definindo um BuildConfig

Um build config descreve uma definição única de build e um conjunto de triggers para saber quando um novo build deve ser criado.

Um build config é definido por BuildConfig, que é um REST objeto que pode ser usado em um POST para o servidor API criar uma nova instancia. O exemplo a seguir resulta em um novo BuildConfig toda vez que a tag Docker image ou source code for alterado:

Exemplo 1. Definição de Objeto BuildConfig

kind: "BuildConfig"
apiVersion: "v1"
metadata:
  name: "ruby-sample-build" 
spec:
  triggers: 
    -
      type: "GitHub"
      github:
        secret: "secret101"
    -
      type: "Generic"
      generic:
        secret: "secret101"
    -
      type: "ImageChange"
  source: 
    type: "Git"
    git:
      uri: "git://github.com/openshift/ruby-hello-world.git"
    dockerfile: "FROM openshift/ruby-22-centos7\nUSER example"
  strategy: 
    type: "Source"
    sourceStrategy:
      from:
        kind: "ImageStreamTag"
        name: "ruby-20-centos7:latest"
  output: 
    to:
      kind: "ImageStreamTag"
      name: "origin-ruby-sample:latest"
  postCommit: 
      script: "bundle exec rake test"

 Essa especificação vai criar um novo BuildConfig chamado ruby-sample-build.
 Você pode especificar uma lista de triggers, que vai fazer que um novo build seja criado.
 A seção source define o source do build. O type determina o source primário de entrada e pode ser o Git que aponta que aponta para um repositório; Dockerfile para fazer o build a partir do arquivo, ou Binary para aceitar binary payloads. Usar múltiplas sources de uma vez é possível. Veja a documentação para mais detalhes de cada tipo de source.
 A seção strategy descreve a strategy do build a ser usada para executar o build. Você pode especificar Source, Docker e Custom strategies aqui. No exemplo acima o Source-To-Image usa a imagem Docker ruby-20-centos7 para o build da aplicação.
 Depois que a imagem Docker é construída, vai ser feito o push dentro do repositório descrito na seção output.
 A seção postCommit define um build hook opcional.

Opções Source-to-Image Strategy

As opções a seguir são especificas do S2I build strategy. 

Forçar o pull

Por padrão, se o builder image especificado no build config esta disponível localmente no node, então essa imagem vai ser usada. Entretanto, para sobrescrever a imagem local e atualizar a partir do registro, crie um BuildConfig com a flag forcePull setada para true:

strategy:
  type: "Source"
  sourceStrategy:
    from:
      kind: "ImageStreamTag"
      name: "builder-image:latest" 
    forcePull: true  

 O builder image sendo usado, onde a versão local no node pode não estar atualizada com a versão no registro que o image stream aponta.
 Esta flag diz ao builder image para ser ignorado e uma versão atualizada ser baixada do registro que o image stream aponta. Definir o forcePull para false, resulta em um comportamento default de honrar a imagem armazenada localmente.

Builds Incrementais

S2I pode fazer builds incrementais, o que significa que vai reutilizar os artefatos de imagens de builds antigos. Para criar um build incremental, crie o BuildConfig com a seguinte modificação na definição de strategy:

strategy:
  type: "Source"
  sourceStrategy:
    from:
      kind: "ImageStreamTag"
      name: "incremental-image:latest" 
    incremental: true  

 Especifique uma imagem que suporta builds incrementais. Consulte a documentação do builder image para saber se suporta esse comportamento.

 Essa flag controla se houve uma tentativa de build incremental. Se o builder image não suporta builds incrementais. Se o builder image não suporta builds incrementais, o build ainda vai ter sucesso, mas você vai receber uma mensagem de log dizendo que o build incremental não teve sucesso por causa o script save-artifacts que estava faltando.

Veja o tópico S2I Requirements para mais informações de como criar um builder image que suporte builds incrementais.

Sobrescrevendo Builder Image Scripts

Você pode sobrescrever os scripts S2I, assemble, run e save-artifacts providos pelo builder image em um de dois modos:

1. Fornecer um script assemble, run e/ou save-artifacts no diretório .s2i/bin da sua aplicação no seu repositório, ou
2. Fornecer a URL de um diretório contendo os scripts como parte da definição da strategy. Por exemplo:

strategy:
  type: "Source"
  sourceStrategy:
    from:
      kind: "ImageStreamTag"
      name: "builder-image:latest"
    scripts: "http://somehost.com/scripts_directory" 

 Este pa​th vai ter os scripts run, assemble e save-artifacts anexados a ele. Se algum script ou todos forem encontrados, eles serão usados no lugar dos scripts fornecidos na imagem.

Arquivos localizados na URL scripts precedem sobre os arquivos localizados no repositório .s2i/bin. Veja o tópico S2I Requirements e o S2I documentation para informações, sobre como os scripts S2I são usados.

Variáveis de Ambiente

Existem duas formas de tornar variáveis de ambiente disponíveis ao processo source build e resulting image: arquivos de ambiente(environment files) e definindo valores no ambiente do BuildConfig.

Arquivos de Ambiente

O source build habilita a usar variáveis de ambiente(uma por linha) dentro da sua aplicação, ao especifica-las no arquivo .s2i/environment no repositório. As variáveis de ambiente especificadas nesse arquivo estão presentes durante o processo de build e na imagem final do Docker. A lista completa de variáveis suportadas está disponível na documentação para cada imagem.

Se você fornecer o arquivo .s2i/environment no seu repositório, o S2I vai ler este arquivo durante o build. Isso permite a customização do comportamento do build ja que o script assemble vai usar essas variáveis.

Por exemplo, se você quer desabilitar a compilação de assets para sua aplicação Rails, você pode adicionar DISABLE_ASSET_COMPILATION=true no arquivo .s2i/environment para que os assets sejam ignorados durante o build.

Em adição aos buils, as variáveis de ambiente estão disponíveis na aplicação em execução. Exemplo, você pode adicionar RAILS_ENV=development ao arquivo .s2i/environment para que a aplicação Rails inicie em modo development em vez de production.

Ambiente BuildConfig

Você pode adicionar variáveis de ambiente a definição sourceStrategy do BuildConfig. As variáveis de ambiente definidas lá estão disponíveis durante a execução do script assemle e vão ser definidas na imagem de output, fazendo elas disponíveis também ao script run e código da aplicação.

Exemplo, desabilitando a compilação de assets para sua aplicação Rails:

sourceStrategy:
...
  env:
    -
      name: "DISABLE_ASSET_COMPILATION"
      value: "true"

Build Inputs

Existem diversas maneiras de fornecer dados para builds operar. Em ordem de precedência.

• Definições Dockerfile inline
• Conteúdo extraido de imagens existentes
• Repositório Git
• Binary inputs

Eles podem ser combinados em um build único. O Dockerfile inline é o primeiro, pode sobrescrever qualquer outro arquivo com nome Dockerfile fornecido por outro input. Binary input e o repositório Git são entradas mutuamente exclusivos.

Quando o build é executado, um diretório é criado e todo o conteúdo de input é colocado nesse diretório (ex. o repositório git de input é clonado dentro desse diretório, arquivos especificados a partir de imagens de input são copiados dentro desse diretório usando o path especificado). A seguir o processo de build vai entrar no contextDir se houver um definido. Então o Dockerfile inline(se existir) é escrito no diretório atual. Por último, o conteúdo do diretório atual vai ser fornecido ao processo de build para referência pelo Dockerfile, script assemble ou custom builder logic. Isso significa que qualquer conteúdo de input que estiver fora do contextDir vai ser ignorado pelo build.

Segue um exemplo de uma definição source que inclui múltiplos tipos de input e uma explicação de como eles são combinados. Para mais detalhes de como cada tipo é definido, veja a seção especifica para cada tipo de input.

source:
  git:
    uri: https://github.com/openshift/ruby-hello-world.git 
  images:
  - from:
      kind: ImageStreamTag
      name: myinputimage:latest
      namespace: mynamespace
    paths:
    - destinationDir: app/dir/injected/dir 
      sourcePath: /usr/lib/somefile.jar
  contextDir: "app/dir" 
  dockerfile: "FROM centos:7\nRUN yum install -y httpd" 

​ O repositório a ser clonado dentro do diretório para o build
 O /usr/lib/somefile.jar do myinputimage vai ser armazenado em <workingdir>/app/dir/injected/dir
 O diretório para o build vai se tornar <original_workingdir>/app/dir
 O Dockerfile com esse conteúdo vai ser criado em <original_workingdir>/app/dir, sobrescrevendo qualquer arquivo existente com esse nome.

Opções Repositório Git

Quando o BuildConfig.spec.source.type é Git, um repositório Git vai ser requerido, e o Dockerfile inline se torna opcional.

O código fonte é buscado a partir do local especificado e se o campo BuildConfig.spec.source.dockerfile for especificado, o Dockerfile inline substitui o que foi definido em contextDir do repositório Git.

A definição source é parte da seção spec no BuildConfig:

source:
  type: "Git"
  git: 
    uri: "git://github.com/openshift/ruby-hello-world.git"
    ref: "master"
  contextDir: "app/dir" 
  dockerfile: "FROM openshift/ruby-22-centos7\nUSER example" 

​ O campo git contem a URL do código fonte do repositório Git. Opcionalmente, especifique o campo ref para fazer check out a uma referência Git especifica. Um valor valido para ref pode ser SHA1 tag ou o nome do branch.
 O campo contextDir permite a você sobrescrever a localização default dentro do código fonte no repositório, onde o build procura pelo código fonte da aplicação. Se sua aplicação existir dentro do diretório, você pode sobrescrever a localização default(a raiz) usando este campo
 Se campo opcional dockerfile é fornecido, deve ser uma string contendo o Dockerfile que vai sobrescrever qualquer Docker file que possa existir no repositório.

Quando estiver usando um repositório Git como source sem especificar o campo ref, o OpenShift vai executar um shallow clone(--depth=1 clone). O que significa que apenas o HEAD(normalmente o branch master) vai ser baixado. Isso resulta em downloads bem mais rápidos de repositórios com o histórico de commits.

O shallow clone é usado também quando, o campo ref é especificado e é definido para um branch remoto existente. Entretanto, se você especificar o campo ref para um commit SHA256 o sistema vai cair para uma operação de git clone regular e então fazer o checkout do commit, porque quando estiver usando a opção --depth=1 apenas vai funcionar o branch nomeado refs.

Se você quer executar um full Git clone do master, do repositório especificado, você pode definir o ref para master.

Usando um proxy para git cloning

Se seu repositório Git só pode ser acessado usando um proxy, você pode definir o proxy para usar a seção source do BuildConfig. Você pode configurar proxy HTTP ou HTTPS para uso. Ambos os campos são opcionais.

A URL do source deve usar o protocolo HTTP ou HTTPS para funcionar.

source:
  type: Git
  git:
    uri: "git://github.com/openshift/ruby-hello-world.git"
    httpProxy: http://proxy.example.com
    httpsProxy: https://proxy.example.com

Usando repositórios privados para builds

Forneça as credenciais para fazer build de uma aplicação a partir de um repositório privado.

Atualmente existe dois tipos de autenticação suportado. basic username-password e autenticação SSH-key.

Autenticação Básica

A autenticação básica requer a combinação de um usuário e senha, ou um token para autenticar no SCM server. Um certificado CA ou um .gitconfig pode ser usado.

Uma secret é usada para armazenar suas keys.

1. Crie a secret antes de usar o usuário e senha para acessar o repositório privado:

$ oc secrets new-basicauth basicsecret --username=USERNAME --password=PASSWORD

a. Para criar uma Secret de Autenticação Básica com um token:

$ oc secrets new-basicatuh basicsecret --password=TOKEN

b. Para criar uma Secret de Autenticação Básica com um certificado CA:

$ oc secrets new-basicauth basicsecret --username=USERNAME --password=PASSWORD --ca-cert=FILENAME

c. Para criar uma Secret de Autenticação Básica com um .gitconfig:

$ oc secrets new-basicauth basicsecret --username=USERNAME --password=PASSWORD --gitconfig=FILENAME

2. Adicione a secret a conta de serviço do builder. Cada build é executado com a role serviceaccount/builder, assim você precisa liberar o acesso a sua secret com o seguinte comando:

$ oc secrets add serviceaccount/builder secrets/basicsecret

3. Adicione o campo sourceSecret a seção source dentro do BuildConfig e defina o nome da secret que você criou. Nesse caso basicsecret:

apiVersion: "v1"
kind: "BuildConfig"
metadata:
  name: "sample-build"
spec:
  output:
    to:
      kind: "ImageStreamTag"
      name: "sample-image:latest"
  source:
    git:
      uri: "https://github.com/user/app.git" 
    sourceSecret:
      name: "basicsecret"
    type: "Git"
  strategy:
    sourceStrategy:
      from:
        kind: "ImageStreamTag"
        name: "python-33-centos7:latest"
    type: "Source"

 A URL do repositório privado, acessado pela autenticação básica, é normalmente no formato http ou https.

Autenticação baseada em SSH Key

A autenticação baseada em SSH Key requer uma SSH key privada. O .gitconfig pode ser usado para anexar.

As chaves do repositório estão geralmente localizadas no diretório $HOME/.ssh/, e são nomeadas de id_dsa.pub, id_ecdsa.pub, id_ed25519.pub ou id_rsa.pub por padrão. Gere as credenciais da chave com o comando a seguir:

$ ssh-keygen -t rsa -C "your_email@example.com"

Criando a passprhase para as chaves SSH previne que OpenShift faça o build. Quando solicitado uma senha, deixe em branco.

Dois arquivos são criados: a chave publica e a chave privada correspondente(id_dsa, id_ecdsa, id_ed25519 ou id_rsa). Com ambas no local, consulte o manual do seu source control management(SCM) sobre como fazer upload da chave publica. A chave privada vai ser usada para acessar seu repositório privado.

Uma secret é usada para armazenar suas chaves.

1. Crie a secret antes de usar as chaves SSH para acessar o repositório privado:

$ oc secrets new-sshauth sshsecret --ssh-privatekey=$HOME/.ssh/id_rsa

a. Para criar uma Secret de autenticação baseada em SSH com o .gitconfig:

$ oc secrets new-sshauth sshsecret -ssh-privatekey=$HOME/.ssh/id_rsa --gitconfig=FILENAME

2. Adicione a secret a conta de serviço do builder. Cada build é executado com a role serviceaccount/builder, assim você precisar liberar o acesso a sua secret com o seguinte comando:

$ oc secrets add serviceaccount/builder secrets/sshsecret

3. Adicione o campo sourceSecret na seção source do BuildConfig e defina o nome da secret que você criou. Neste caso sshsecret:

apiVersion: "v1"
kind: "BuildConfig"
metadata:
  name: "sample-build"
spec:
  output:
    to:
      kind: "ImageStreamTag"
      name: "sample-image:latest"
  source:
    git:
      uri: "git@repository.com:user/app.git" 
    sourceSecret:
      name: "sshsecret"
    type: "Git"
  strategy:
    sourceStrategy:
      from:
        kind: "ImageStreamTag"
        name: "python-33-centos7:latest"
    type: "Source"

 A URL do repositório privado, acessado pela chave privada do SSH, é normalmente no formato git@example.com:<username>/<repository>.git.

Outras formas de autenticação

No caso do clone da sua aplicação depender do certificado CA ou do arquivo .gitconfig ou ambos, você pode criar uma secret que contenha ambos, adicione a conta de serviço do builder e depois ao seu BuildConfig.

1. Crie algum tipo de secret:

a. Para criar uma Secret a partir do .gitconfig:

$ oc secrets new mysecret .gitconfig=path/to/.gitconfig

b. Para criar uma Secret a partir do CA certificate:

$ oc secrets new mysecret ca.crt=path/to/certificate

c. Para criar uma secret a partir do CA certificate e .gitconfig:

$ oc secrets new mysecret ca.crt=path/to/certificate .gitconfig=path/to/.gitconfig

A verificação SSL pode ser desabilitada, se o sslVerify=false estiver setado na seção http no seu .gitconfig:

[http]         sslVerify=false

1. Adicione a secret a conta de serviço builder. Cada build é executado com a role serviceaccount/builder, assim você precisa liberar o acesso a sua secret com o seguinte comando:

$ oc secrets add serviceaccount/builder secrets/mysecret

Binary Source

O streaming de conteúdo em formato binário a partir do sistema de arquivos local para o builder é chamado de binary type build. O valor correspondente de BuildConfig.spec.source.type é Binary para esses builds.

Esse source type é único com base no seu uso de oc start-build.

Build do tipo binário requer conteúdo para ser transmitido do sistema local, o trigger de um binary type build não é possível, por que os arquviso binários não podem fornecidos. Você não pode iniciar build do tipo binary no console web.

Para utilizar builds binários, executa o comando oc start-build com uma das opções a seguir:

• --from-file: O conteúdo do arquivo especificado é enviado em formato binário para o builder. O builder então armazena os dados em um arquivo com o mesmo nome no topo do build context.
• --from-dir e --from-repo: O conteúdo é arquivado e enviado no formato binário para o builder. O builder então extrai o conteúdo do arquivo dentro do diretório do build context.

Em cada um dos casos acima:

• Se seu BuildConfig já tem o Binary source definido, vai ser ignorado e substituido pelo que os clientes enviarem.
• Se o seu BuildConfig já tem o Git source definido, vai ser dinamicamente desativado, desde que o Binary e Git sejam mutuamente exclusivos,e os dados no formato binário fornecidos ao builder sejam precedentes.

Quando usando o comando oc new-build --binary=true, o comando garante que as restrições associadas com o build binário são forçadas. O BuildConfig vai ter um source type Binary, o que significa que a unica forma de rodar o build para esse BuildConfig é usando o comando oc start-build com uma das opções --from para fornecer os dados binários.

O dockerfile e contextDir tem um significado especial com builds binários.

dockerfile pode ser usado com qualquer binary build source. Se o dockerfile é usado e o binary stream é um arquivo, seu conteúdo serve como substituto ao Dockerfile no arquivo. Se o dockerfile é usado com o argumento --from-file e o argumento de arquivo tem nome dockerfile, o valor de dockerfile substitui o valor do binary stream.

No caso do binary stream ter extraído o arquivo, o valor do campo contextDir é interpretado como um diretório dentro do arquivo e se for válido o builder entra no diretório antes de executar o build.

Image Source

Arquivos adicionais podem ser fornecidos ao processo de build através de imagens. Imagens de input são referenciadas da mesma forma que os targets de imagem From e To são definidos. Isso significa que ambas Docker images e image stream tags podem ser referenciadas. Em conjunto com a imagem, você deve fornecer um ou pais paths para indicar o path dos arquivos/diretórios a ser copiados da imagem e o destino que eles serão inseridos no build context.

O source path pode ser qualquer path absoluto dentro da imagem especificada. O destino pode ser um path relativo. No momento do build, a imagem vai ser carregada e os arquivos indicados e diretórios vão ser copiados dentro do diretório do build. É o mesmo diretório onde o conteúdo do repositório (se houver) é clonado. Se o source path termina em /. então o conteúdo do diretório vai ser copiado, mas o diretório em si não vai ser criado no destino.

Image inputs são especificados na definição source do BuildConfig:

source:
  git:
    uri: https://github.com/openshift/ruby-hello-world.git
  images: 
  - from: 
      kind: ImageStreamTag
      name: myinputimage:latest
      namespace: mynamespace
    paths: 
    - destinationDir: injected/dir 
      sourcePath: /usr/lib/somefile.jar 
  - from:
      kind: ImageStreamTag
      name: myotherinputimage:latest
      namespace: myothernamespace
    pullSecret: mysecret 
    paths:
    - destinationDir: injected/dir
      sourcePath: /usr/lib/somefile.jar

 Um array de um ou mais input images e arquivos.
 Uma referencia a imagem contendo os arquvios a serem copiados.
 Um array de source/destination paths.
 O diretório relativo a a raiz do build, onde o processo do build possa acessar o arquivo.
 A localização do arquivo a ser copiado fora da imagem referenciada.
 Uma secret opcional fornecida se as credenciais não forem necessárias para acessar a input image.

Essa feature não é suportada por builds usando o Custom strategy.

Usando secrets durante o build

Em alguns cenários, operações de build requer o uso de credenciais para acessar alguns recursos, mas não é desejavel que essas credenciais estejam disponíveis na imagem produzia pelo build.

Por exemplo, quando estiver fazendo o build de uma aplicação NodeJS, você pode definir seu mirror privado para os módulos do NodeJS. Para fazer download dos módulos desse mirror privado, você deve fornecer através do arquivo .npmrc a URL, usuário e senha para o build. Por razões de segurança, você não quer expor suas credenciais na imagem da aplicação.

Esse exemplo descreve o NodeJS, mas você pode usar o exemplo para adicionar certificados SSL dentro do diretório /etc/ssl/certs, API keys ou tokens, arquivos de licença, etc.

Definindo secrets no buildconfig

1. Crie a Secret:

$ oc secrets new secret-npmrc .npmrc=~/.npmrc

Isso vai criar uma nova secret chamad secret-npmrc, que contem o conteúdo do arquivo ~/.npmrc codificado em base64.

2. Adicione a secret a seção source no build configuration existente.

source:
  git:
    uri: https://github.com/openshift/nodejs-ex.git
  secrets:
    - secret:
        name: secret-npmrc
  type: Git

Para incluir as secret no novo build config, execute o seguinte comando:

$ oc new-build openshift/nodejs-010-centos7~https://github.com/openshift/nodejs-ex.git --build-secret secret-npmrc

Durante o build, o arquivo .npmrc é copiado dentro do diretório onde o código fonte está localizado. No caso do OpenShift Origin S2I builder images, o diretório é definido usando a instrução WORKDIR no Dockerfile. Se você quer especificar outro diretório, adicione destinationDir na definição da secret:

source:
  git:
    uri: https://github.com/openshift/nodejs-ex.git
  secrets:
    - secret:
        name: secret-npmrc
    destinationDir: /etc
  type: Git

Você pode também especificar o diretório destino quando estiver criando um novo build config:

$ oc new-build openshift/nodejs-010-centos7~https://github.com/openshift/nodejs-ex.git --build-secret "secret-npmrc:/etc"

Em ambos os casos, o arquivo .npmrc é adicionado ao diretório /etc do ambiente de build. Para o Docker strategy o path de destino deve ser um path relativo. 

Source-to-Image Strategy

Quando estiver usando um Source strategy, todos os source secrets definidos são copiados para o respectivo destinationDir. Se você deixar o destinationDir em branco, então as secrets são colocar no diretório do builder image. A mesma regra se aplica quando o destinationDir é relativo ao path; as secrets são colocadas nos paths que são relativos ao diretório onde a imagem está utilizando. O destinationDir deve existir ou um erro vai ocorrer. Nenhum diretório é criado durante o processo de cópia.

Atualmente, qualquer arquivo com essas secrets podem ser editados por qualquer um(permissão 0666) e vão ser truncados para o tamanho zero depois da execução do script assemble. Isso significa que o arquivo da secret vai existir no resultado da imagem, mas o arquivo vai estar vazio por razões de segurança.

Iniciando um Build

Você pode iniciar um build manualmente a partir de um build config existente no seu projeto usando o seguinte comando:

$ oc start-build <buildconfig_name>

Re-executa o build usando a flag --from-build:

$ oc start-build --from-build=<build_name>

Especifique a flag --follow para exibir os logs em stdout:

$ oc start-build <buildconfig_name> --follow

Especifique a flag --env para definir a variável de ambiente para o build:

$ oc start-build <buildconfig_name> --env=<key>=<value>

Em vez de depender de um Git source pull ou Dockerfile para um build, você pode iniciar um build direto do seu código, que pode ser o conteúdo de um Git ou SVN, um conjunto de artefatos prebuilt binary que você quer fazer o deploy, ou um unico arquivo. Isso pode ser feito ao especificar uma das seguintes opções para o comando start-build:

Quando passando qualquer uma dessas opções diretamente ao build, o conteúdo é transmitido ao build e sobrescreve as configurações do source build atual.

Builds que foram ativados a partir de um binary input, vão preservar o source no servidor, então rebuilds que foram executados com base nesse image change vão usar o source especificado no build config.

Por exemplo, o comando a seguir envia o conteúdo de um repositório Git local como um arquivo a partir da tag v2 e inicia um build.

$ oc start-build hello-world --from-repo=../hello-world --commit=v2

Cancelando um Build

Você pode cancelar o build usando o console web, ou pela CLI:

$ oc cancel-build <build_name>

Deletando um BuildConfig

Delete um BuildConfig usando o seguinte comando:

$ oc delete bc <BuildConfigName>

Isso vai deletera todos os builds que foram instanciados a partir do BuildConfig. Especifique a flag --cascade=false se você não quer delete os builds:

$ oc delete --cascade=false bc <BuildConfigName>

Visualizando detalhes do build

Você pode ver detalhes do build usando o console web ou o seguinte comando na CLI:

$ oc describe build <build_name>

A saída  do comando describe inclui detalhes como build source, strategy e destino de saida. Se o build usa o Docker ou Source strategy, vai também incluir informações sobre o source revision usado pelo build: commit ID, author, commiter e message.

Acessando logs do build

Você pode acessar os logs do build usando o console web ou a CLI.

Para exibir os logs usando o build diretamente:

$ oc logs -f build/<build_name>

Para exibir os logs do último build para um build configuration:

$ oc logs -f bc/<buildconfig_name>

Para retornar os logs de uma determinada versão do build para um build configuration:

$ oc logs --version=<number> bc/<buildconfig_name>

Log Verbosity

Para habilitar um nível diferente de detalhes, defina a variável de ambiente BUILD_LOGVEL como parte do sourceStrategy ou dockerStrategy do BuildConfig:

sourceStrategy:
...
  env:
    -
      name: "BUILD_LOGLEVEL"
      value: "2" 

 Ajuste esse valor para o nível de detalhes do log.

O administrador da plataforma pode definir o nível de detalhes para o OpenShift ao utilizar a opção --loglevel ao comando openshift start. Se ambos --loglevel e BUILD_LOGLEVEL forem especificados, o BUILD_LOGLEVEL vai ser o utilizado.

Os valores disponíveis de log level para o Source builds são:

Level 0 Produz informações de containers rodando o script assemble e todos os erros encontrados. Esse é o default.

Level 1 Produz informações sobre o processo executo.

Level 2 Produz informações detalhadas sobre o processo executado.

Level 3 Produz informações detalhadas sobre o processo executado e listando o conteúdo dos arquivos.

Level 4 Produz o mesmo que o level 3.

Level 5 Produz tudo mencionado nos leveis anteriores e ainda exibe docker push messages.

Configurando duração máxima

Quando estiver definindo um BuildConfig, você pode definir a duração máxima ao configurar o campo completionDeadlineSeconds. É especificado em segundos e não é definido por padrão. Quando não configura, não tem tempo máximo de duração.

A duração máxima é contada a partir do tempo quando um build fica programado no sistema, e define quanto tempo pode ficar ativo, incluindo o tempo preciso para fazer o pull do builder image. Depois de atingir o tempo limite, o build é terminado pelo OpenShift.

O exemplo a seguir exibe part do BuildConfig especificando o campo completionDeadlineSeconds para 30 minutos:

spec:
  completionDeadlineSeconds: 1800 

Build Triggers

Quando definindo um BuildConfig, você pode definir triggers para controlar as circunstancias em que o BuildConfig deve rodar. A seguir os build triggers que estão disponíveis:

• Webhook
• Image change
• Configuration change

Webhook Triggers

Webhook triggers permite que você inicie um novo build ao enviar uma requisição ao endpoint OpenShift API. Você pode definir estes triggers usando o GitHub webhooks ou Generic webhooks.

GitHub Webhooks

GitHub webhooks lidam com a chamada feita pelo GitHub quando um repositório é atualizado. Quando definindo o trigger, você deve especificar uma secret, que vai ser parte da URL que você forneceu ao GitHub quando configurando o webhook. A secret garante que só existe aquela URL, prevenindo que outros iniciem o build. O exemplo a seguir é a definição YAML de uma trigger dentro do BuildConfig:

type: "GitHub"
github:
  secret: "secret101"

O campo secret na configuração do webhook trigger não é o mesmo que o campo secret que você encontra quando configurando um webhook no GitHub UI. Isso é para tornar a URL do webhook única e difícil de ser descoberta, o último campo string é opcional, usado para criar HMAC hexdigets do conteúdo, que é enviado como um cabeçalho X-Hub-Signature.

A URL payload é retornada como GitHub webhook URL pelo comando describe(como visto abaixo), e é estruturado como segue:

http://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github

Gogs suporta o mesmo formato de payload webhook URL que o GitHub. Portanto, se você esta usando um servidor Gogs, você pode definir um trigger do GitHub webhook no seu BuildConfig e acionar através do seu servidor Gogs também.

Generic Webhooks

Generic webhooks podem ser utilizados a partir de qualquer sistema capaz de fazer uma requisição web. Como um webhook GitHub, você deve especificar uma secret que vai ser parte da URL, o caller deve usar para iniciar o build. A secret garante que só existe aquela URL, prevenindo que outros iniciem o build. O exemplo a seguir é a definição YAML de uma trigger dentro do BuildConfig:

type: "Generic"
generic:
  secret: "secret101"
  allowEnv: true  

 Para permitir um webhook generico passar variáveis de ambiente, o campo deve ser definido para true.

Para configurar um caller, forneça ao calling system a URL do generic webhook para o seu build:

http://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic

O endpoint pode aceitar um payload opcional com o seguinte formato:

type: "git"
git:
  uri: "<url to git repository>"
  ref: "<optional git reference>"
  commit: "<commit hash identifying a specific git commit>"
  author:
    name: "<author name>"
    email: "<author e-mail>"
  committer:
    name: "<committer name>"
    email: "<committer e-mail>"
  message: "<commit message>"
env:
   - name: "<variable name>"
     value: "<variable value>"

Semelhante as variáveis de ambiente do BuildConfig, as variáveis de ambiente definidas no payload anterior, vão estar disponíveis ao seu build. Quando as variáveis de ambiente do payload acima forem as mesmas que as variáveis de ambiente do BuildConfig, as variáveis do payload vão ser preferenciais. Por padrão, variáveis de ambiente passadas via webhook são ignoradas. Você deve definir a allowEnv para true na definição do webhook para habilitar esse comportamento.

Exibindo as URL's de webhook do BuildConfig

Utilize o comando a seguir para exibir as URL's de webhook associada com o build config:

$ oc describe bc <name>

Se o comando anterior não exibir nenhuma URL de webhook, então nenhum webhook trigger foi definido para aquele build config.

Image Change Triggers

Image change triggers permite seu build ser automaticamente iniciado quando uma nova versão de um upstream image estiver disponível. Por exemplo, se um build é baseado na imagem do RHEL, então você pode acionar o build para executar sempre que a imagem do RHEL for alterada. Como resultado,  a imagem da aplicação vai estar sempre rodando na ultima versão do RHEL base image.

Configurando um image change trigger requer as seguintes ações:

1. Definir um ImageStream que aponta para o upstream image que você quer acionar:

kind: "ImageStream"
apiVersion: "v1"
metadata:
  name: "ruby-20-centos7"

Isso definie que o image stream seja amarrado a imagem Docker do repositório localizado em <system-registry>/<namespace>/ruby-20-centos7. O <system-registry> é definido como um serviço com o nome docker-registry rodando o OpenShift.

2. Se um image stream é o base image para o build, defina o campo from no build strategy para apontar ao image stream:

strategy:
  type: "Source"
  sourceStrategy:
    from:
      kind: "ImageStreamTag"
      name: "ruby-20-centos7:latest"

Nesse caso a definição sourceStrategy esta usando a tag latest do image stream nomeado ruby-20-centos7 localizado dentro desse namespace.

3. Define um build com uma ou mais triggers que apontam para os image streams:

type: "imageChange" 
imageChange: {}
type: "imagechange" 
imageChange:
  from:
    kind: "ImageStreamTag"
    name: "custom-image:latest"

 Um image change trigger que monitora o ImageStream e Tag como definido n build strategy do campo from. O objeto imageChange aqui deve estar em branco.
 Um image change trigger que monitora um image stream arbitrário. O imageChange nesse caso deve incluir o campo from que referencia o ImageStreamTag ao monitor.

Quando usando um image change trigger para a strategy image stream, o build gerado é fornecido com uma tag Docker imutável que aponta para a última imagem que corresponde com a tag. Esta nova referencia de imagem vai ser usada pelo strategy quando for executar o build. Para outro image change triggers que não tem referencia alguma a uma strategy image stream, um novo build vai ser iniciado, mas o build strategy não vai ser atualizado com uma única imagem de referencia.

No exemplo acima que tem um image change trigger para o strategy, o resultado do build vai ser:

strategy:
  type: "Source"
  sourceStrategy:
    from:
      kind: "DockerImage"
      name: "172.30.17.3:5001/mynamespace/ruby-20-centos7:immutableid"

Isso garante que os triggered build utilizarão a nova imagem que foi feito o push para o repositório, e o build pode ser re-executado qualquer hora com o mesmo input.

Além de de configurar o campo image para todos os tipos de Strategy, para custom builds, a variável de ambiente OPENSHIFT_CUSTOM_BUILD_BASE_IMAGE é checada. Se não existir, então é criado com uma referencia de imagem imutável. Se já existir, então vai ser atualizado com a referencia de imagem imutável.

Se o build é acionado duas vezes por um webhook trigger ou requisição manual, o build que foi criado usa o imutableid do ImageStream referenciado pelo Strategy. Isso garante que o build é executado usando tags de imagens consistente para uma reprodução fácil.

Image streams que apontam para Imagems Docker em registros Docker v1 apenas acionam um build quando o image stream tag se torna disponível e não tem subsequente atualizações do image. Isso é devido a falta de imagens identificáveis nos registros Docker v1.

Configuration Change Triggers

A configuration change trigger permite que o build seja automaticamente iniciado assim que um novo BuildConfig é criado. A seguir um exemplo de definição de trigger YAML dentro do BuildConfig:

  type: "ConfigChange"

Configuration change triggers atualmente funcionam apenas quando estiver criando um novo BuildConfig. Em um update futuro as change triggers vão conseguir iniciar um novo build sempre que o BuildConfig for atualizado.

Build Hooks

Build hooks permitem que configurações adicionais sejam passadas ao processo do build.

Use o campo postCommit para executar comandos dentro de um container temporário que esta rodando o build output image. O hook é executado imediatamente depois do ultimo layer da imagem ser commitado e antes de ser feito o push da imagem para o registro.

O diretório atual é definido para WORKDIR, que é o default do Docker Image. Para a maioria das imagens, é aqui que o código fonte está localizado.

O hook falha se o script ou command retornar um resultado diferente de zero ou se o container temporário falhar ao iniciar. Quando o hook falha, ele marca o build como failed e a imagem não é feito o push para o registro. O motivo para falhar pode ser inspecionado ao olhar os logs do build.

Build hooks podem ser usados para rodar unit testes para verificar a imagem antes do build ser marcado como completo e a imagem estar disponível no registro. Se todos os testes forem bem sucedidos e o test runner retornar 0, o build é marcado como sucesso. No caso de qualquer falha, o build é marcado como failed. Em todos os casos, o log do build vai conter o output do test runner, que pode ser usado para identificar failed tests.

O postCommit hook não é limitado a running tests e pode ser usado por outros comandos. Desde que rode em um container temporário, as alterações feitas pelo hook não persistem, significa que a execução do hook não pode afetar a imagem final. Esse comportamente permite entrou outros usos, a instalação e uso de teste de dependências que são automaticamente descartadas e não vão estar presente na imagem final.

Existem diferentes maneiras de configura o post build hook. Todas as formas nos exemplos a seguir são equivalentes e executam bundle exec rake test --verbose:

• Shell script:

postCommit:
  script: "bundle exec rake test --verbose"

O valor de script é um shell script a ser executado com /bin/sh -ic. Use isso quando o shell script é apropriado a executar o build hook. Por exemplo, para rodar teste de unit como acima. Para controlar o image entry point, ou se a imagem não tem /bin/sh use o command e/ou args.

A flag adicional -i foi criada para melhorar a experiencia ao trabalhar com imagens CentOS e RHEL, e pode ser removido em um release futuro.

• Command como image entry point:

postCommit:
  command: ["/bin/bash", "-c", "bundle exec rake test --verbose"]

Dessa forma o command é o comando a ser executado, o que sobrescreve o image entry point no exec form, como documentado no Dockerfile reference. Isso é preciso se a imagem não tem o /bin/sh ou se você não quer usar um shell. Em todos outros casos, usando script é mais conveniente.

• Passe argumentos ao default entry point:

postCommit:
  args: ["bundle", "exec", "rake", "test", "--verbose"]

Dessa forma, args é uma lista de argumentos que são fornecidos ao default entry point da imagem. O image entry point deve ser habilitado para passar esses argumentos.

• Shell script com argumentos:

postCommit:
  script: "bundle exec rake test $1"
  args: ["--verbose"]

Use essa forma se você precisa passar argumentos que de outra forma seria mais difícil de escrever no shell script. No script, $0 vai ser "/bin/sh" e $1, $2, etc, são argumentos posicionais do args.

• Command com argumentos:

postCommit:
  command: ["bundle", "exec", "rake", "test"]
  args: ["--verbose"]

Esta forma é equivalente a atribuir os argumentos ao command.

Fornece ambos script e command simultaneamente e cria um build hook invalido.

Usando credenciais do Docker para fazer push e pull de imagens

Forneça ao arquivo .docker/config.json as credenciais validas para o Registro Docker em ordem de fazer push da imagem em um Registro Docker privado ou fazer o pull do builder image a partir do registro Docker que requer autenticação. Para o registro Docker do OpenShift, você não tem que fazer isso por que a secrets são geradas automaticamente pelo OpenShift.

O arquivo .docker/config.json esta no seu diretório home por padrão e tem o seguinte formato:

{
  "auths": {
    "https://index.docker.io/v1/": { 
      "auth": "YWRfbGzhcGU6R2labnRib21ifTE=", 
      "email": "user@example.com" 
    }
  }
}

 URL do registro.
 Senha criptografada.
 E-mail de login

Você pode definir múltiplas entradas de registro Docker nesse arquivo. Você também pode adicionar entradas de autenticação nesse arquivo ao rodar o comando docker login. O arquivo vai ser criado caso não exista. O Kubernetes fornece objetos do tipo secret que são usados para armazenar sua configuração e senhas.

1. Cria a secret a partir do arquivo local .docker/config.json:

$ oc secrets new dockerhub ~/.docker/config.json

É gerado uma especificação JSON da secret com nome dockerhub e a criação do objeto.

2. Assim que a secret é criada, ela é adicionada a conta de serviço builder. Cada build é executado com a role serviceaccount/builder, ou seja você precisa liberar o acesso a sua secret com o seguinte comando:

$ oc secrets add serviceaccount/builder secrets/dockerhub

3. Adicione o campo pushSecret dentro da seção output do BuildConfig e defina o nome da secret que você criou, que no exemplo anterior é dockerhub:

1. spec:
     output:
       to:
         kind: "DockerImage"
         name: "private.registry.com/org/private-image:latest"
       pushSecret:
         name: "dockerhub"

4. Faça o pull do builder docker image a partir de um registro privado Docker, especificando o campo pullSecret, que é parte da definição do build strategy:

Esse exemplo define o pullSecret em um Source build mas pode ser definido no Docker e Custom builds.

Build Output

O Docker e Source builds resultam na criação de uma nova imagem Docker. É feito o push da imagem ao registro especificado na seção output da especificação Build.

Se o output é ImageStreamTag, então a imagem vai ser feito o push da imagem para o registro integrado do OpenShift e tagged no image stream especificado. Se o output é do tipo DockerImage, então o nome do output via ser usado como uma especificação de push Docker. A especificação pode conter o registro ou vai ser default para o DockerHub caso nenhum registro seja especificado. Se a seção output do da especificação build estiver em branco, então não vai ser feito push da imagem no final do build.

Exemplo 2. Output para um ImageStreamTag

output:
  to:
    kind: "ImageStreamTag"
    name: "sample-image:latest"

Exemplo 3. Output para uma especificação Docker Push

output:
  to:
    kind: "DockerImage"
    name: "my-registry.mycompany.com:5000/myimages/myimage:tag"

Output Image variáveis de ambiente

Docker e Source builds configuram as seguintes variáveis de ambiente nas imagens de output:

Outpud Image labels

Docker e Source builds configuram os seguintes labels nas imagens de output:

Usando Artefatos externos durante um Build

Não é recomendado armazenar arquivos binários no repositório. Portanto, você talvez ache necessário definir um build que vai fazer pull de arquivos adicionais(como java .jar) durante o processo de buils. Como isso é feito, depende da strategy build que você esta usando.

Para um Source build strategy, você deve colocar os comandos apropriados dentro do script assemble:

Exemplo 4. Arquivo .s2i/bin/assemble

#!/bin/sh
APP_VERSION=1.0
wget http://repository.example.com/app/app-$APP_VERSION.jar -O app.jar 

Exemplo 5. Arquivo .s2i/bin/run

#!/bin/sh
exec java -jar app.jar

Para mais informações sobre como controlar os scripts assemble e run usado pelo Source build, veja Sobrescrevendo Builder Image Scripts.

Para um Docker build strategy, você deve modificar o Dockerfile e rodar comandos com a instrução RUN:

Exemplo 6. Resumo do Dockerfile

FROM jboss/base-jdk:8

ENV APP_VERSION 1.0
RUN wget http://repository.example.com/app/app-$APP_VERSION.jar -O app.jar

EXPOSE 8080
CMD [ "java", "-jar", "app.jar" ]

Na pratica, você talvez queira usar uma variável de ambiente para a localização do arquivo, para que o arquivo especificado seja baixado para ser customizado usando uma variável de ambiente definida no BuildConfig, em vez de atualizar o script assemble ou Dockerfile.

Você pode escolher entre diferentes métodos para definir variáveis de ambiente:

• Usando o arquivo .s2i/environment(apenas para Source build strategy)
• Configurando no BuildConfig
• Usando o comando oc start-build --env(apenas para builds que são iniciados manualmente)

Troubleshooting

Tabela 1. Guia de Troubleshooting