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.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 of objects. Each object has three fields:

path, which describes the path in the workload where this configuration is appended or merged. It must start with spec.
schema, which defines a property. It must be a valid OpenAPI v3 schema. For more information, see the Kubernetes documentation and the OpenAPI documentation.
required, which determines whether the property that path references is marked as required.

Note
Use the required field in the spec.config array to mark properties as required. You can mark child properties separately in the schema.

Example

Given the following Component spec.config:

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 a new source
          type: string
        commit:
          description: A Git commit SHA to use
          type: string
        branch:
          description: A Git branch reference to watch for a new source
          type: string
        url:
          description: The URL to the Git source repository
          type: string
      required:
        - url
  - path: spec.image
    required: true
    schema:
      type: string
      description: Repository where the image is published

A SupplyChain that includes the Component defines the workload spec as follows in the CustomResourceDefinition:

properties:
  spec:
    type: object
    properties:
      image:
        type: string
        description: Repository where the image is published
      source:
        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:
          branch:
            type: string
            description: A Git branch reference to watch for a new source
          commit:
            type: string
            description: A Git commit SHA to use
          tag:
            type: string
            description: A Git tag reference to watch for a new source
          url:
            type: string
            description: The URL to the Git source repository
        required:
          - url
    - path: spec.source.subPath
      required: true    # makes subPath a required field
      schema:
        type: string
        description: the subPath of the repository to monitor for changes

spec.description

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

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

spec.inputs

The inputs this component requires. This component cannot be added to a supply chain unless a previous stage exposes the name and type as output.

  inputs:
    - name: source
      type: source

spec.outputs

The outputs this component emits. Outputs are references to an artifact located at the url. The URL string is json:"url,omitempty".

outputs:
  - name: source
    type: source
    digest: <cryptographic hash>
    url: <location of output artifact>

spec.outputs[].digest

The digest of this output. If not provided, the default is $(pipeline.results.digest).

Use a template replacement to describe where the digest originates, in either the pipeline or resumption. For example, $(resumption.results.commitId) or $(pipeline.results.shasum).

This digest must be a cryptographic hash function to assure operators of the supply chain that the value correlates to the data in the artifact at the url. Describe how the digest is formed so that it can be verified at a later date if the authenticity of the artifact needs to be checked.

spec.outputs[].url

The URL that holds the artifact of this output. If not provided, the default is $(pipeline.results.url).

Use a template replacement to describe where the URL originates, typically in the pipeline. For example, $pipeline.results.buildURL.

The storage of the resource at this URL must match in all instances of this output.type, including any expected accepts-* headers and so on.

Example

outputs:
  - name: source
    type: source
    digest: $(resumption.results.commitId)
    url: $(pipeline.results.buildURL)

spec.pipelineRun

The spec.pipelineRun section defines the work that this component performs. Tanzu Supply Chain uses spec.pipelineRun to create a Tekton PipelineRun, and there are many similarities between Tekton PipelineRun and spec.pipelineRun.

spec.pipelineRun.params

spec.pipelineRun.params are the same as Tekton PipelineRun parameters except for one major difference: You can populate spec.pipelineRun.params by using templates.

The available references for templates are:

Reference	Source	Example
`$(config.spec...)`	References to the config	`$(config.spec.source.git.url)`
`$(workload.spec...)`	The same as `$(config.spec)...` (deprecated)	`$(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)`

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.taskRunSpecs

If you need to define taskRunSpecs to pass to Tekton PipelineRun, use spec.pipelineRun.taskRunSpecs. This is identical to the Tekton PipelineRun taskRunSpecs specification.

spec.pipelineRun.taskRunTemplates

If you need to define taskRunTemplates to pass to Tekton PipelineRun, use spec.pipelineRun.taskRunTemplates. This is identical to the Tekton PipelineRun taskRunTemplates specification.

spec.pipelineRun.workspaces

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

Reference	Source	Example
`$(workload.spec...)` (deprecated)	The workload specification	`$(workload.spec.source.git.url)`
`$(workload.metadata...)`	The workload metadata	`$(workload.metadata.labels)`, `$(workload.metadata.name)`
`$(config.spec...)`	`config.spec` is derived from `workload.spec`, unless modified by `supplychain.spec.overrides`	`$(config.spec.source.git.url)`
`$(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: $(config.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.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

Make spec.resumptions[].name descriptive for the end users who will see it. Write it as 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...)` (deprecated)	The workload specification	`$(workload.spec.source.git.url)`
`$(workload.metadata...)`	The workload metadata	`$(workload.metadata.labels)`, `$(workload.metadata.name)`
`$(config.spec...)`	`config.spec` is derived from `workload.spec`, unless modified by `supplychain.spec.overrides`	`$(config.spec.source.git.url)`
`$(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: $(config.spec.source.git.branch)
        - name: git-url
          value: $(config.spec.source.git.url)
        - name: git-commit
          value: $(config.spec.source.git.commit)
        - name: git-tag
          value: $(config.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

status.docs

status.docs contains a human-readable explanation of the content of the component. It is useful for CLIs and UIs and provides a clean summary of the component.

Example

docs: |
  # source

  Version: 1.0.0

  ## Description

  Monitors a Git repository

  ## Inputs

  * _none_

  ## Outputs

  | Name   | Type                                            |
  |--------|-------------------------------------------------|
  | source | [source](../catalog/output-types.hbs.md#source) |

  ## Config

  `\``yaml
  spec:
    source:
      # 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.
      git:
        # A Git branch ref to watch for new source
        branch:
        # A Git commit SHA to use
        commit:
        # A Git tag ref to watch for new source
        tag:
        # The URL to the git source repository
        # +required
        url:
  `\``