Introducing Shipwright Beta API

By Enrique Encalada (@qu1queee) | Tuesday, November 07, 2023

About a year ago, we published a blog post in which we outline our vision and our values. Part of this vision was to advance our API to enhance its simplicity and consistency, and to signal a higher level of maturity.

Today, as part of our release v0.12.0, we are introducing our beta API. The beta API brings multiple changes as a result of accumulated experience operating the alpha API and incorporating valuable user feedback.

With the introduction of the beta API, users can have confidence that our core components have been battle-tested, and using our different features is considered a safe practice.

We want to thank our community for their contributions and support in redefining this new API!

Beta API

The beta API is available starting from the v0.12.0 release. The release is available across our cli, operator and build repository.

Within the v0.12.0 release, a conversion webhook has been introduced to ensure backward compatibility between the v1alpha1 and v1beta1.

We strongly encourage both current and future users to adopt the beta API to benefit from its enhanced definition.

Migration guidelines

Deprecated fields

Resource	Field	Alternative
Build	`.spec.sources`	`.spec.source`
Build	`.spec.dockerfile`	`spec.paramValues[]` with `dockerfile`
Build	`.spec.builder`	none
Build	`.spec.volumes[].description`	none
BuildRun	`.spec.serviceAccount.generate`	`.spec.serviceAccount` with `.generate`
BuildRun	`.spec.sources`	`.spec.source`
BuildRun	`.spec.volumes[].description`	none

Changes to Build API fields

Old field	New field
`.spec.source.url`	`.spec.source.git.url`
`.spec.source.bundleContainer`	`.spec.source.ociArtifact`
`.spec.sources` for `LocalCopy`	`.spec.source.local`
`.spec.source.credentials`	`.spec.source.git.cloneSecret` or `.spec.source.ociArtifact.pullSecret`
`.spec.output.credentials`	`.spec.output.pushSecret`

See this example of the Git source type:

# v1alpha1
---
apiVersion: shipwright.io/v1alpha1
kind: Build
metadata:
  name: a-build
spec:
  source:
    url: https://github.com/shipwright-io/sample-go
    contextDir: docker-build
  strategy:
    name: buildkit
    kind: ClusterBuildStrategy
  output:
    image: an-image

# v1beta1
---
apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: a-build
spec:
  source:
    type: Git
    git: 
      url: https://github.com/shipwright-io/sample-go
    contextDir: docker-build
  strategy:
    name: buildkit
    kind: ClusterBuildStrategy
  output:
    image: an-image

Changes to BuildRun API fields

Old field	New field
`.spec.buildSpec`	`.spec.build.spec`
`.spec.buildRef`	`.spec.build.name`
`.spec.sources`	`.spec.source` only for `Local`
`.spec.serviceAccount.generate`	`.spec.serviceAccount` with `.generate`

Note: generated service accounts is a deprecated feature, and may be removed in a future release.

See example:

# v1alpha1
---
apiVersion: shipwright.io/v1alpha1
kind: BuildRun
metadata:
  name: a-buildrun
spec:
  buildRef:
    name: a-build
  serviceAccount:
    generate: true


# v1beta1
---
apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
  name: a-buildrun
spec:
  build:
    name: a-build
  serviceAccount: ".generate"

Changes to Strategies API fields

Old field	New field
`.spec.buildSteps`	`.spec.steps`

References

For more information, see SHIP 0035.

← Previous