Migrate BuildConfig resources to Builds for Red Hat OpenShift with Crane

Automate your migration with Crane

January 27, 2026
Prateek Singh Rathore
Related topics:
Application modernizationContainersOpen source
Related products:
Developer ToolsRed Hat OpenShift

For years, OpenShift BuildConfig has been the standard way to build container images directly on Red Hat OpenShift clusters. Now, new build tools are available as the cloud-native ecosystem changes.

Builds for Red Hat OpenShift is Red Hat's extensible framework for building container images on OpenShift. It is based on the open source project Shipwright, which provides a vendor-neutral framework for building container images on Kubernetes.

Built on top of OpenShift Pipelines (Tekton), Builds for Red Hat OpenShift offers a flexible way to build containers with enterprise support from Red Hat.

Today, we are announcing a developer preview for migrating from OpenShift BuildConfig resources to Builds for Red Hat OpenShift using Crane. This new upstream capability in Crane enables you to automatically convert your existing OpenShift BuildConfig resources to Builds for Red Hat OpenShift resources.

What is Crane?

Crane is an open source migration tool from the Konveyor community. It helps application owners migrate Kubernetes workloads and their state between clusters using an Extract, Transform, and Apply framework.

This new BuildConfig conversion capability adds to the Crane migration toolkit to help organizations modernize their container build infrastructure.

Developer preview notice

This BuildConfig migration feature is available as an upstream community capability in Crane. It is not yet included in official Red Hat product offerings. As a developer preview, it is intended for evaluation and feedback purposes and is not supported for production use.

What gets migrated?

Crane automatically converts your BuildConfig resources to Builds for Red Hat OpenShift. Here's what's supported.

Build strategies

Crane converts Docker strategy BuildConfig resources to the Buildah ClusterBuildStrategy. It also converts Source strategy BuildConfig resources to use Source-to-Image ClusterBuildStrategy.

Source types

The tool handles all major source types:

  • Git sources: Full support for repository URL, branch and tag references, and clone secrets.
  • Binary sources: Converted to Local source type with streaming support.
  • Image sources: Converted to OCI artifact sources for image-based builds.

Key features migrated

Crane migrates these configuration settings from your BuildConfig to the new Builds for Red Hat OpenShift format:

  • Environment variables: These transfer automatically to the Build specification.
  • Build arguments: Docker build arguments are converted to ParamValues.
  • Dockerfile paths: Custom Dockerfile locations are preserved.
  • Git proxy configuration: HTTP/HTTPS proxy settings are converted to environment variables.
  • Source secrets: Clone secrets for private Git repositories.
  • Push secrets: Registry authentication for pushing images.
  • Context directories: Build context paths are maintained.

How it works

The migration process follows the following workflow:

  1. Discovery: Crane connects to your cluster and lists all BuildConfig resources in the specified namespace.
  2. Analysis: Each BuildConfig is analyzed for its strategy type, source configuration, and output settings.
  3. Validation: Pull secrets are validated to ensure they contain the required credentials.
  4. Conversion: Resources are mapped to their Builds for Red Hat OpenShift equivalents.

Getting started: Migrating a BuildConfig with Docker strategy and Git source

Ready to try the developer preview? This sections explains how to get started, walking through a complete migration example step by step.

Prerequisites

You will need the following installed on your cluster:

  • Red Hat OpenShift Pipelines
  • Builds for Red Hat OpenShift

Step 1: Create the BuildConfig

Let's look at an example BuildConfig (ruby_docker_git_buildconfig.yaml):

  • spec.source uses the Git type and defines a GitHub URI and branch. It also defines context directory, inline Dockerfile, secrets, and ConfigMap resources available in the builder pod.
  • spec.strategy uses the Docker type and defines a from image that overrides the builder image in the project's Dockerfile. It also defines a pull secret to pull images from a private registry, flags (noCache, forcePull, imageOptimizationPolicy), volumes, environment variables, and build arguments.

Note

The git.uri field should point to the Git repository containing your application source code. This example uses https://github.com/psrvere/ruby-hello-world as a sample for demonstration purposes.

 

The from field refers to a private registry image, quay.io/prathore/ruby-27:latest, which requires a pullSecret for authentication. When using your own BuildConfig, replace this with your own image and secret, or use a public image and remove the pullSecret field.

apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
  name: ruby-docker-git
  namespace: default
spec:
  source:
    type: Git
    git:
      ref: interim
      uri: https://github.com/psrvere/ruby-hello-world
    contextDir: .
    dockerfile: |
      FROM ruby:2.7
      WORKDIR /app
      COPY . .
      RUN bundle install
      EXPOSE 4567
      CMD ["ruby", "app.rb"]
    secrets:
      - secret:
          name: database-credentials
        destinationDir: config
    configMaps:
      - configMap:
          name: app-config
        destinationDir: config
  strategy:
    type: Docker
    dockerStrategy:
      from:
        kind: DockerImage
        name: quay.io/prathore/ruby-27:latest
      pullSecret:
        name: registry-creds
      noCache: true
      env:
        - name: RACK_ENV
          value: production
      forcePull: true
      dockerfilePath: ./dockerfilelocation/Dockerfile
      buildArgs:
        - name: BUILD_VERSION
          value: 1.0.0
      imageOptimizationPolicy: SkipLayers
      volumes:
        - name: bundler-config
          source:
            type: Secret
            secret:
              secretName: bundler-secret
          mounts:
            - destinationPath: /workspace/Gemfile.lock

Step 2: Validate the BuildConfig

Make sure the BuildConfig is valid and runs correctly. Ensure secrets and ConfigMap resources are available in the cluster.

oc create imagestream ruby-docker-git
oc apply -f ruby_docker_git_buildconfig.yaml
oc start-build ruby-docker-git
oc get build

Step 3: Download Crane CLI

Download the latest crane CLI tool by running the following command:

curl -fsSL https://raw.githubusercontent.com/psrvere/download-crane/main/download-crane.sh | bash

This script automatically detects your platform and downloads the appropriate Crane binary.

Alternatively, you can manually download the binary for your platform from the Crane Releases page.

Step 4: Run the migration

Run the migration with the following command:

crane convert -r BuildConfigs -n default

Flags:

  • -r BuildConfigs: Required for BuildConfig migration
  • -n default: Specifies the namespace (mandatory)

The Crane CLI tool finds all BuildConfig resources in the namespace and migrates them to the Builds for Red Hat OpenShift format.

Output directories:

  • ./convert/buildconfigs/<namespace>/: All extracted BuildConfig resources.
  • ./convert/builds/<namespace>/: All migrated Build resources and supporting files.

You will see detailed logs for each BuildConfig. Here's an example output:

INFO Converting BuildConfigs in namespace: default 
INFO Found 1 BuildConfig to convert              
INFO -------------------------------------------------------- 
INFO Processing BuildConfig: ruby-docker-git at index 0 
INFO -------------------------------------------------------- 
INFO Docker strategy detected                     
WARN From Field in BuildConfig's Docker strategy is not yet supported in built-in Buildah ClusterBuildStrategy in Shipwright. RFE: https://issues.redhat.com/browse/BUILD-1746 
WARN NoCache flag is not yet supported in the built-in Buildah ClusterBuildStrategy in Shipwright. RFE: https://issues.redhat.com/browse/BUILD-1578 
INFO Processing Environment Variables             
WARN ForcePull flag is not yet supported in the built-in Buildah ClusterBuildStrategy in Shipwright. RFE: https://issues.redhat.com/browse/BUILD-1580 
INFO Processing Dockerfile path                   
INFO Processing Build Args                        
WARN ImageOptimizationPolicy (--squash) flag is not yet supported in the built-in Buildah ClusterBuildStrategy in Shipwright. RFE: https://issues.redhat.com/browse/BUILD-1581 
WARN Unlike BuildConfig, Volumes have to be supported in the Buildah Strategy first in Shipwright. Please raise your requirements here: https://issues.redhat.com/browse/BUILD-1747 
ERRO Inline Dockerfile is not supported in buildah strategy. Consider moving it to a separate file. 
INFO Processing Git Source                        
INFO Processing Git CloneSecret                   
WARN ConfigMaps are not yet supported in Shipwright build environment. RFE: https://issues.redhat.com/browse/BUILD-1745 
WARN Secrets are not yet supported in Shipwright build environment. RFE: https://issues.redhat.com/browse/BUILD-1744 
WARN Push to Openshift ImageStreams is not yet supported in Shipwright. RFE: https://issues.redhat.com/browse/BUILD-1756

Understanding the logs:

  • INFO: Successfully migrated fields
  • WARN: Feature not yet supported but on the roadmap (includes RFE links)
  • ERRO: Feature not planned for support

In the generated OpenShift Build file, the Build resource defines a ClusterBuildStrategy (Buildah), a Git source with URL and branch, environment variables, build arguments, a custom Dockerfile location, and an output registry:

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  creationTimestamp: "2025-12-16T11:17:37Z"
  name: ruby-docker-git
  namespace: default
spec:
  env:
    - name: RACK_ENV
      value: production
  output:
    image: image-registry.openshift-image-registry.svc:5000/default/ruby-docker-git:latest
  paramValues:
    - name: dockerfile
      value: dockerfilelocation/Dockerfile
    - name: build-args
      values:
        - value: BUILD_VERSION=1.0.0
  source:
    git:
      revision: interim
      url: https://github.com/psrvere/ruby-hello-world
    type: Git
  strategy:
    kind: ClusterBuildStrategy
    name: buildah

Step 5: Run the generated build

Review and modify if needed. First, check if you need to modify the generated files. In our case, we might need to change the output image. Although ImageStreams have been migrated to a correct URL in the generated file, this feature is not fully supported yet (see warnings).

You can change the output image to use any public registry.

Create a BuildRun resource (ruby_docker_buildrun.yaml):

apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
  name: ruby-docker-buildrun
  namespace: default
spec:
  build:
    name: ruby-docker-git
  serviceAccount: ruby-docker-git

Run the BuildRun:

oc apply -f ruby_docker_buildrun.yaml
oc get buildrun

You can also view a video demo.

Current availability and support

This migration tool is currently available as an upstream developer preview in the Crane project.

This feature is not yet included in official Red Hat product offerings. We encourage you to try the developer preview and share your feedback as we work toward broader availability.

If you have questions or issues, open an issue on the Crane GitHub repository.