Skip to content

Configuring Ocibuilder

This document is a reference for ocibuilder v0.1.0 specification keys used in ocibuilder.yaml.

You can find a complete ocibuilder.yaml example here.


Table of Contents


build

A build comprises of reusable build templates and a number of build steps

Name Type Description Required
templates (Array) v1alpha1.BuildTemplate Templates are set of build templates that describe steps needed to build a Dockerfile No
steps (Array) v1alpha1.BuildStep Individual build definitions to run Yes

templates

Templates are reusable build configurations that can be used accross a number of different build steps and are referred to by the name field. Multiple build commands can be entered which will be executed by ocibuilder.

Name Type Description Required
name string Name of the template Yes
cmd (Array) v1alpha1.BuildTemplateStep Steps are instructions within a template to build a Dockerfile Yes

Example

  templates:
    - name: go-build-template
      cmd:
        - docker:
            inline:
              - ADD . /src
              - RUN cd /src && go build -o goapp

The above example shows a very simple build template, using docker commands which have been passed inline.

name

Name is the name of the template. This can be referenced across multiple build steps and build stages allowing you to not have to rewrite standard build commands across different builds.

cmd

Cmd allows you to specify commands that you want to run in your build. This can be standard docker commands, which can be passed inline or through a file. Alternatively, you are able to specify an ansible step which you can use to point to a local ansible playbook or the name and requirements to pull from Ansible galaxy.

Name Type Description Required
ansible v1alpha1.AnsibleStep Ansible represents a ansible step within build template steps No
docker v1alpha1.DockerStep Docker represents a docker step within build template steps No

Example

  cmd:
    - docker:
        inline:
          - ADD . /src
          - RUN cd /src && go build -o goapp
    - docker:
        path: ./docker-commands.txt
    - ansible:
        galaxy:
          name: my-ansible-role
          requirements: ./requirements.yaml
        local:
          playbook: ./playbook.yaml

The above example shows all the possible flavours for inputting build commands into ocibuilder.

ansible

Ansible is used for entering references to local ansible playbooks or ansible roles in Ansible Galaxy. Each ansible step represents an ansible install as part of the build.

Name Type Description Required
galaxy v1alpha1.AnsibleGalaxy Galaxy contains information to install a ansible role through ansible-galaxy No
local v1alpha1.AnsibleLocal Local contains information to install a ansible role through local playbook No
galaxy

AnsibleGalaxy contains ansible role information to be installed at the build

Name Type Description Required
name string Name of the galaxy role Yes
requirements string Requirements refer to the requirements.yaml file No
local

AnsibleLocal contains information to install a ansible role through local playbook

Name Type Description Required
playbook string Playbook refers to playbook.yaml file Yes
docker

Docker is used for entering docker commands that you want to execute in your build. You have the option of passing commands inline with each docker command being a string array element.

Alternatively, you can pass in a filepath to a text file which contains your docker commands.

Name Type Description Required
inline (Array) string Inline Dockerfile commands No
path string Path to a file that contains Dockerfile commands No
url string Url to a remote command file No
auth v1alpha1.RemoteCreds Basic auth for accessing a remote file No
auth

You can specify remote basic auth credentials for accessing remote template files and overlays

Name Type Description Required
username string Username refers to an env var that holds the username Yes
password string Password refers to an env var that holds the password No

steps

Build steps are used to configure multiple unique builds with a single spec.yml.

This can be particularly useful when trying to build multiple modules or projects in a single repository, allowing you to reuse the templates that you have defined in the specification.

Each step is run consecutively by ocibuilder with concurrent build steps running in a future version of ocibuilder - progress can be tracked here.

Name Type Description Required
purge boolean Purge after built. Defaults is false. No
context v1alpha1.context Specify an image build context for the step No
stages (Array) v1alpha1.Stage Stages of the build Yes
tag string The tag of the built image No
metadata v1alpha1.ImageMetadata Image metadata, name, labels, annotations and source No

The purge flag allows you to purge your built images after they've been built. Ensures cleanup and is useful in build pipelines to prevent the constant persisting of images which will not be used.

Example

  # Steps are all the individual build steps you want to execute
  steps:
    # Metadata is where you define your final image build name as well as any labels
    - metadata:
        name: my-docker-registry:4555/art/go-service
      stages:
        - metadata:
            name: build-env
          base:
            image: golang
            platform: alpine
          template: go-build-template
      tag: v0.1.0
      purge: false
      context:
        localContext:
          contextPath: ./go-app
context

context enables you to specify a build context for each individual build step. For example, if you have multiple directories and each directory is a separate build step, you are able to specify a particular directory as the build context that step.

Additionally, an upcoming version of ocibuilder will have support to set external build contexts of S3 buckets and Git paths.

Name Type Description Required
localContext context.LocalContext Local context contains local context information for a build No
localContext

LocalContext holds local context information for an image build

Name Type Description Required
contextPath string The path to your build context. Yes
gitContext

gitContext is the build context from git for an image build

Name Type Description Required
url string The path to your build context Yes
username Credentials Username for authentication No
password Credentials Password for authentication No
sshKeyPath string The path to your ssh key No
branch string Branch to pull your context resource from No
tag string Tag to pull your context resource from No
ref string Ref to use to pull trigger resource. Will result in a shallow clone and fetch No
remote GitRemoteConfig Remote to manage set of tracked repositories. Defaults to "origin" No
stages

Ocibuilder supports docker multi-stage builds to help drastically reduce final image sizes. You are able to define a multi-stage build in each build step.

In each stage you have the option to define build commands under the cmd field or pass in a previously specified build template.

A stage also takes in a base image.

Required to pass in either cmd or a build template.

Name Type Description Required
base v1alpha1.Base Refers to parent image for given build stage. Yes
cmd (Array) v1alpha1.BuildTemplateStep Cmd refers to a template defined in a stage without a template. No
template string Template refers to one of the build templates. No
metadata v1alpha1.ImageMetadata Image metadata, name, labels, annotations and source No

Example

  stages:
    - metadata:
        name: go-binary
      base:
        image: golang
        platform: alpine
      cmd:
        - docker:
            inline:
              - ADD . /src
              - RUN cd /src && go build -o goapp
    - metadata:
        name: alpine-stage
      base:
        image: alpine
      cmd:
        - docker:
            inline:
              - WORKDIR /app
              - COPY --from=go-binary /src/goapp /app/
              - ENTRYPOINT ./goapp

In the above example, the first stage of the build uses the golang:alpine base image to build our go binary and is named go-binary.

Our second build stage refers to just our binary built in the first stage with --from=go-binary and copies this into our new container image and sets an entrypoint.

More details about multi-stage builds can be found here

base

Base is where you define your base image.

Name Type Description Required
image string The name of the image Yes
platform string The specified platform of the image No
tag string The tag for the image No

Example

  base:
    image: golang
    platform: alpine
    tag: latest
metadata [image]

This is where any image metadata is defined, including image name, any labels and annotations that you want to specify for your build.

The metadata type is used both in build steps and build stages.

Within a build step name is used to name your final built image, but can be also used to refer to other build stages in a multi-stage build.

Any labels specified in your build configuration will be attached to your built image.

Name Type Description Required
annotations map Annotations for your build config No
labels map Labels for your build config and built image No
name string Name for your build configuration Yes
creator string Creator is the creator of the project Yes
source string Source is the URI to the source code repository Yes

login

Login is used to specify credentials necessary to login to an image registry. These credentials are required to push and pull images from an image registry.

You can specify credentials through plain, with environment variables, through the use of a token or a combination of the above.

Params can also be used in conjunction with login credentials to pass in environment variables as a token or plaintext credentials.

NOTE Using a token may also require you to pass in a username as a credential depending on your image registry.

Name Type Description Required
creds v1alpha1.RegistryCreds credentials required to log into the registry Yes
registry string Registry refers to a OCI image registry Yes
token string An image registry token No

Example

login:
  - registry: my-docker-registry:4555
    token: ThisIsMeloGinToken
    creds:
      plain:
        username: art

creds

Holds the specific credentials to login to a given image registry

Name Type Description Required
env v1alpha1.EnvCreds Env refers to the credentials stored in environment variables No
plain v1alpha1.PlainCreds Plain refers to the credentials set inline No
env

Credentials pulled from enviroment variables

Name Type Description Required
username string Username refers to an env var that holds the username Yes
password string Password refers to an env var that holds the password Yes

Example

login:
  env:
    username: REGISTRY_USER
    password: REGISTRY_PASS
plain

Plaintext credentials for image registry login

NOTE It is not recommended to store your credentials in plaintext

Name Type Description Required
username string Plaintext registry username Yes
password string Plaintext registry password Yes

Example

login:
  env:
    username: artsuser
    password: artsp4ss

push

Push enables you to specify multiple registries to push your image to. Push expects the registry you want to push to have a corresponding login specification.

Name Type Description Required
image string Image to push Yes
registry string Registry is the name of the registry Yes
tag string Tag version of the image (e.g: v0.1.1) Yes

Example

push:
  - registry: my-docker-registry:4555
    image: art/go-service
    tag: v0.1.0

params

Params is where you can define parameters, allowing you to replace any value in the specification with a value or an environment variable.

You specify the destination of the value you want to replace in the dest key using dot notation to access nested elements.

NOTE: A specific array item is referred to by index in the dest field. For example, if you want to access the first step element you would have steps.0

Name Type Description Required
dest string Dest is the destination of the field to replace with the parameter Yes
value string Value of the environment variable. No
valueFromEnvVariable string a variable which is to be replaced by an env var No

Example

params:
  # Replaces the value in location build.steps.0.tag with 0.0.3
  - dest: build.steps.0.tag
    value: 0.0.3
  # Replaces the value in location build.steps.0.metadata.name with the environment variable $BUILD_DEV
  - dest: build.steps.0.metadata.name
    valueFromEnvVariable: BUILD_DEV

daemon

Daemon is a boolean which allows you to specify whether you want to use the docker daemon, or buildah as an alternative.

A true value will execute all commands using docker, a false flag will execute all commands using buildah.

This value can be overriding by the builder command line flag which takes priority.

Name Type Description Required
daemon boolean Allows you to specify whether to use the docker daemon as a builder or buildah. Default is true. No

metadata

Metadata allows you to define all the configurations for pushing build and image metadata into a metadata store like Grafeas.

Name Type Description Required
storeConfig v1alpha1.StoreConfig StoreConfig holds the configuration for connecting to a metadata store No
signKey *v1alpha1.SignKey SignKey holds the signing key for signing image IDs for image attestation purposes No
hostname string Hostname is the hostname of your metadata store No
data []v1alpha1.MetadataType Data holds a list of all the metadata types that you would like to push to your metadata store No

Example

metadata:
  hostname: "http://localhost:8080"
  signKey: 
    envPublicKey: OCI_PUB_KEY
    envPrivateKey: OCI_PRI_KEY
  storeConfig:
    grafeas:
      project: "image-build"
      notes:
        build: "projects/image-build/notes/oci-build"
        attestation: "projects/image-build/notes/oci-attest"
        image: "projects/image-build/notes/oci-image"
  data:
    - image
    - build
    - attestation

storeConfig

Store config holds store specific configurations to do with connection and required fields. Currently the only metadata store support by the ocibuilder is Grafeas.

Name Type Description Required
grafeas *v1alpha1.Grafeas Grafeas holds the config for the Grafeas metadata store Yes
grafeas

Grafeas holds any grafeas specific configurations. This allows you to specify a project to push metadata to as well as define individual notes for each type of metadata that can be pushed.

Name Type Description Required
project string Project is the name of the project ID to store the occurrence Yes
notes v1alpha1.Notes Notes holds the notes for each of the three occurrence types Yes
notes

Notes is where you can specify Grafeas note names for Build, Attestation and DerivedImage metadata.

Name Type Description Required
attestation string Attestation is the analysis note associated with a attestation occurrence, in the form of projects/[PROVIDER_ID]/notes/[NOTE_ID] Yes
build string Build is the analysis note associated with a build occurrence, in the form of projects/[PROVIDER_ID]/notes/[NOTE_ID] Yes
image string Image is the analysis note associated with a derived image occurrence, in the form of projects/[PROVIDER_ID]/notes/[NOTE_ID] Yes

signKey

SignKey holds your private and public signing keys to sign your image after it has been built which can be used later for image attestation.

Name Type Description Required
plainPrivateKey string PrivateKey is an ascii armored private key used to sign images for image attestation No
plainPublicKey string PublicKey is the ascii armored public key for verification in image attestation No
envPrivateKey string EnvPrivateKey is an env variable that holds an ascii armored private key used to sign images for image attestation No
envPublicKey string EnvPublicKey is an env variable that holds an ascii armored public key used to sign images for image attestation No
passphrase string Passphrase is the passphrase for decrypting the private key No

data

Data holds a list of the types of metadata that you want pushed to the Metadata store.

Name Type Description Required
attestation string Attestation in the data array signifies you want to store attestation metadata No
build string Build in the data array signifies you want to store build metadata No
image string Image in the data array signifies you want to store image metadata No