Component API

This topic gives you reference information about the Component resource for Tanzu Supply Chain.

Caution
Tanzu Supply Chain is currently in beta and is not intended for production use. It is intended only for evaluation purposes for the next generation Supply Chain. For the current Supply Chain solution, see the Supply Chain Choreographer documentation.

Components define the work to be performed in one Stage of the SupplyChain.

Type and Object Metadata

apiVersion: supply-chain.apps.tanzu.vmware.com/v1alpha1
kind: Component

metadata.name

metadata.name: must have an -M.m.p suffix, representing the major, minor, and patch of this version of the component. Changes to the config section should coincide with an update to major or minor versions. Reserve patch increments for changes that do not alter the API or the behavior significantly.

metadata:
  name: source-1.0.0

Spec

spec.description

spec.description describes the component’s purpose. You will see this description in tanzu workload run list.

spec:
  description: Gets the latest source and stores it in an OCI Image

spec.config

spec.config defines the configuration in a workload (spec of the workload) that is required for the component to operate.

spec.config is an array with three fields:

path: describes the path in the workload where this configuration is appended/merged. It must start with spec.
schema and required define a property. For more information, see the Kubernetes documentation.

Example

  config:
    - path: spec.source.git
      schema:
        type: object
        description: |
          Fill this object in if you want your source to come from git.
          The tag, commit and branch fields are mutually exclusive,
          use only one.
        properties:
          tag:
            description: A git tag ref to watch for new source
            type: string
          commit:
            description: A git commit sha to use
            type: string
          branch:
            description: A git branch ref to watch for new source
            type: string
          url:
            description: The url to the git source repository
            type: string
        required:
          - url

spec.pipelineRun

The spec.pipelineRun section defines the work done by this component. spec.pipelineRun is used to create a [Tekton PipelineRun] and has many similarities.

spec.pipelineRun.pipelineRef

The spec.pipelineRun.pipelineRef is required, and it has one field name that must refer to the metadata.name of a [Tekton Pipeline] that resides in the same namespace as the Component and SupplyChain.

spec.pipelineRun.workspaces

If you need to define workspaces to pass to the Tekton PipelineRun, use spec.pipelineRun.workspaces. This field is an array of workspace definitions, and is identical to the Tekton Workspaces specification.

spec.pipelineRun.params

spec.pipelineRun.params are the same as [Tekton PipelineRun Parameters] with one major difference: You can populate them using templates.

The available references for templating are:

Reference	Source	Example
`$(workload.spec...)`	The workload spec	`$(workload.spec.source.git.url)`
`$(workload.metadata...)`	The workload metadata	`$(workload.metadata.labels)`, `$(workload.metadata.name)`
`$(inputs.<input-name>.[url\\|digest])`	An input url or digest	`$(inputs.image.url)`, `$(inputs.image.digest)`
`$(resumptions.<resumption-name>.results...)`	A resumption result	`$(resumptions.check-source.results.sha)`

Example

spec:
  pipelineRun:
    pipelineRef:
      name: source
    params:
      - name: git-url
        value: $(workload.spec.source.git.url)
      - name: sha
        value: $(resumptions.check-source.results.sha)
    workspaces:
      - name: shared-data
        volumeClaimTemplate:
          spec:
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                storage: 1Gi

spec.outputs

  outputs:
    - name: source
      type: source

spec.resumptions[]

spec.resumptions[] define Tekton TaskRuns. They are optional, but useful to describe small fast tasks that check for dependency changes, such as new source, or new base images.

For a detailed explanation of resumptions, see Core Concepts: Resumptions.

spec.resumptions[].name

spec.resumptions[].name is visible to end users, so make sure it’s suitably meaningful. It’s recommended that it’s in the form: check-RESOURCE-TYPE where RESOURCE-TYPE is the kind of resource being polled, such as source or base-image.

spec.resumptions[].trigger.runaAfter

spec.resumptions[].trigger.runaAfter describes the rerun period for the task. The task is executed, and after it finishes (successfully or otherwise), Tanzu Supply Chain waits for the runaAfter period and then executes the task again. This continues indefinitely.

runAfter can be specified by using the time.ParseDuration() specification.

spec.resumptions[].taskRef

The spec.resumptions[].taskRef has one field name that must refer to the metadata.name of a Tekton Task that resides in the same namespace as the Component and SupplyChain.

This is the task that runs on the resumptions spec.resumptions[].trigger

spec.resumptions[].params

spec.resumptions[].params are the same as Tekton TaskRun parameters with one major difference: You can populate them by using templates.

The available references for templates are:

Reference	Source	Example
`$(workload.spec...)`	The workload spec	`$(workload.spec.source.git.url)`
`$(workload.metadata...)`	The workload metadata	`$(workload.metadata.labels)`, `$(workload.metadata.name)`
`$(inputs.<input-name>.[url\\|digest])`	An input url or digest	`$(inputs.image.url)`, `$(inputs.image.digest)`

Example

  resumptions:
    - name: check-source
      trigger:
        runAfter: 60s
      taskRef:
        name: check-source
      params:
        - name: git-branch
          value: $(workload.spec.source.git.branch)
        - name: git-url
          value: $(workload.spec.source.git.url)
        - name: git-commit
          value: $(workload.spec.source.git.commit)
        - name: git-tag
          value: $(workload.spec.source.git.tag)

Status

status.conditions[]

Every status.conditions[] in Tanzu Supply Chain resources follows a strict set of conventions

Component resources are “living”, however they are resistant to changes in their specification. They are designed to be immutable on production servers so that accidental specification changes do not break the API delivered to end users.

If a Component’s top-level condition Ready is ever something other than status: "True" then the reason field should describe the problem with the component.

status.details

status.details describe some of the observations that Tanzu Supply Chains made about this component. These fields are used to improve the output of kubernetes get component <name> -owide, and they summarize the component for platform engineers when they author a SupplyChain.

status:
  conditions:
  - lastTransitionTime: "2024-02-25T00:40:46Z"
    message: ""
    reason: Ready
    status: "True"
    type: Ready
  details:
    hasResumptions: "False"
    inputs: conventions[conventions[]
    outputs: oci-yaml-files[oci-yaml-files[], oci-ytt-files[oci-ytt-files[]
  observedGeneration: 1