Logo

Documentation

Workload and Supply Chain Custom Resources

Workload

Workload allows the developer to pass information about the app to be delivered through the supply chain.

---
apiVersion: carto.run/v1alpha1
kind: Workload
metadata: {}
spec:

  # Build configuration, for the build resources in the supply
  # chain
  # +optional
  build:

    # Env is an array of environment variables to propagate to
    # build resources in the supply chain. See
    # https://kubernetes.io/docs/tasks/inject-data-application/environment-variable-expose-pod-information/
    # +optional
    env:
      - # EnvVar represents an environment variable present in a
        # Container.
        # +optional
        name: <string>
        value: <string>
        valueFrom: {}

  # Environment variables to be passed to the main container
  # running the application. See
  # https://kubernetes.io/docs/tasks/inject-data-application/environment-variable-expose-pod-information/
  # +optional
  env:
    - # EnvVar represents an environment variable present in a
      # Container.
      # +optional
      name: <string>
      value: <string>
      valueFrom: {}

  # Image refers to a pre-built image in a registry. It is an
  # alternative to specifying the location of source code for the
  # workload. Specify one of `spec.source` or `spec.image`.
  # +optional
  image: <string>

  # Additional parameters. See:
  # https://cartographer.sh/docs/latest/architecture/#parameter-hierarchy
  # +optional
  params:
    - # Name of the parameter. Should match a blueprint or
      # template parameter name.
      name: <string>

      # Value of the parameter.
      value: <any>

  # Resource constraints for the application. See
  # https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
  # +optional
  resources:
    limits: {}
    requests: {}

  # ServiceAccountName refers to the Service account with
  # permissions to create resources submitted by the supply chain.
  # If not set, Cartographer will use serviceAccountName from
  # supply chain. 
  # If that is also not set, Cartographer will use the default
  # service account in the workload's namespace.
  # +optional
  serviceAccountName: <string>

  # ServiceClaims to be bound through ServiceBindings.
  # +optional
  serviceClaims:
    - name: <string>
      ref:
        apiVersion: <string>
        kind: <string>
        name: <string>

  # The location of the source code for the workload. Specify one
  # of `spec.source` or `spec.image`
  # +optional
  source:

    # Source code location in a git repository.
    # +optional
    git:
      ref:
        branch: <string>
        commit: <string>
        tag: <string>
      url: <string>

    # OCI Image in a repository, containing the source code to be
    # used throughout the supply chain.
    # +optional
    image: <string>

    # Subpath inside the Git repository or Image to treat as the
    # root of the application. Defaults to the root if left empty.
    # +optional
    subPath: <string>

# Status conforms to the Kubernetes conventions:
# https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties
# +optional
status:

  # Conditions describing this resource's reconcile state. The top
  # level condition is of type `Ready`, and follows these
  # Kubernetes conventions:
  # https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties
  # +optional
  conditions:
    - # Condition contains details for one aspect of the current
      # state of this API Resource. --- This struct is intended
      # for direct use as an array at the field path
      # .status.conditions.  For example, 
      # type FooStatus struct{ // Represents the observations of a
      # foo's current state. // Known .status.conditions.type are:
      # "Available", "Progressing", and "Degraded" //
      # +patchMergeKey=type // +patchStrategy=merge //
      # +listType=map // +listMapKey=type Conditions
      # []metav1.Condition `json:"conditions,omitempty"
      # patchStrategy:"merge" patchMergeKey:"type"
      # protobuf:"bytes,1,rep,name=conditions"` 
      # // other fields }
      # +optional

  # ObservedGeneration refers to the metadata.Generation of the
  # spec that resulted in the current `status`.
  # +optional
  observedGeneration: <integer>

  # Resources contain references to the objects created by the
  # Supply Chain and the templates used to create them. It also
  # contains Inputs and Outputs that were passed between the
  # templates as the Supply Chain was processed.
  # +optional
  resources:
    - # Conditions describing this resource's reconcile state. The
      # top level condition is of type `Ready`, and follows these
      # Kubernetes conventions:
      # https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties
      # +optional
      conditions:
        - # Condition contains details for one aspect of the
          # current state of this API Resource. --- This struct is
          # intended for direct use as an array at the field path
          # .status.conditions.  For example, 
          # type FooStatus struct{ // Represents the observations
          # of a foo's current state. // Known
          # .status.conditions.type are: "Available",
          # "Progressing", and "Degraded" // +patchMergeKey=type
          # // +patchStrategy=merge // +listType=map //
          # +listMapKey=type Conditions []metav1.Condition
          # `json:"conditions,omitempty" patchStrategy:"merge"
          # patchMergeKey:"type"
          # protobuf:"bytes,1,rep,name=conditions"` 
          # // other fields }
          # +optional

      # Inputs are references to resources that were used to
      # template the object in StampedRef
      # +optional
      inputs:
        - # Name is the name of the resource in the blueprint
          # whose output the resource consumes as an input
          name: <string>

      # Name is the name of the resource in the blueprint
      name: <string>

      # Outputs are values from the object in StampedRef that can
      # be consumed by other resources
      # +optional
      outputs:
        - # Digest is a sha256 of the full value of the output
          digest: <string>

          # LastTransitionTime is a timestamp of the last time the
          # value changed
          lastTransitionTime: <string>

          # Name is the output type generated from the resource
          # [url, revision, image or config]
          name: <string>

          # Preview is a preview of the value of the output
          preview: <string>

      # StampedRef is a reference to the object that was created
      # by the resource
      # +optional
      stampedRef: {}

      # TemplateRef is a reference to the template used to create
      # the object in StampedRef
      # +optional
      templateRef: {}

  # SupplyChainRef is the Supply Chain resource that was used when
  # this status was set.
  # +optional
  supplyChainRef:
    apiVersion: <string>
    kind: <string>
    name: <string>
    namespace: <string>

Notes:

  1. labels serve as a way of indirectly selecting ClusterSupplyChain - Workloads without labels that match a ClusterSupplyChain’s spec.selector won’t be reconciled and will stay in an Errored state.
  2. spec.image is useful for enabling workflows that are not based on building the container image from within the supplychain, but outside.

ref: pkg/apis/v1alpha1/workload.go

ClusterSupplyChain

With a ClusterSupplyChain, app operators describe which “shape of applications” they deal with (via spec.selector), and what series of resources are responsible for creating an artifact that delivers it (via spec.resources).

Those Workloads that match spec.selector then go through the resources specified in spec.resources.

A resource can emit values, which the supply chain can make available to other resources.

---
apiVersion: carto.run/v1alpha1
kind: ClusterSupplyChain
metadata: {}
spec:

  # Additional parameters. See:
  # https://cartographer.sh/docs/latest/architecture/#parameter-hierarchy
  # +optional
  params:
    - # DefaultValue of the parameter. Causes the parameter to be
      # optional; If the Owner does not specify this parameter,
      # this value is used.
      # +optional
      default: <any>

      # Name of the parameter. Should match a template parameter
      # name.
      name: <string>

      # Value of the parameter. If specified, owner properties are
      # ignored.
      # +optional
      value: <any>

  # Resources that are responsible for bringing the application to
  # a deliverable state.
  resources:
    - # Configs is a list of references to other 'config'
      # resources in this list. A config resource has the kind
      # ClusterConfigTemplate 
      # In a template, configs can be consumed as:
      # $(configs.<name>.config)$ 
      # If there is only one image, it can be consumed as:
      # $(config)$
      # +optional
      configs:
        - name: <string>
          resource: <string>

      # Images is a list of references to other 'image' resources
      # in this list. An image resource has the kind
      # ClusterImageTemplate 
      # In a template, images can be consumed as:
      # $(images.<name>.image)$ 
      # If there is only one image, it can be consumed as:
      # $(image)$
      # +optional
      images:
        - name: <string>
          resource: <string>

      # Name of the resource. Used as a reference for inputs, as
      # well as being the name presented in workload statuses to
      # identify this resource.
      name: <string>

      # Params are a list of parameters to provide to the template
      # in TemplateRef Template params do not have to be specified
      # here, unless you want to force a particular value, or add
      # a default value. 
      # Parameters are consumed in a template with the syntax:
      # $(params.<name>)$
      # +optional
      params:
        - # DefaultValue of the parameter. Causes the parameter to
          # be optional; If the Owner does not specify this
          # parameter, this value is used.
          # +optional
          default: <any>

          # Name of the parameter. Should match a template
          # parameter name.
          name: <string>

          # Value of the parameter. If specified, owner properties
          # are ignored.
          # +optional
          value: <any>

      # Sources is a list of references to other 'source'
      # resources in this list. A source resource has the kind
      # ClusterSourceTemplate 
      # In a template, sources can be consumed as:
      # $(sources.<name>.url)$ and $(sources.<name>.revision)$ 
      # If there is only one source, it can be consumed as:
      # $(source.url)$ and $(source.revision)$
      # +optional
      sources:
        - name: <string>
          resource: <string>

      # TemplateRef identifies the template used to produce this
      # resource
      templateRef:

        # Kind of the template to apply
        kind: <[ClusterSourceTemplate|ClusterImageTemplate|ClusterTemplate|ClusterConfigTemplate]>

        # Name of the template to apply Only one of Name and
        # Options can be specified.
        # +optional
        name: <string>

        # Options is a list of template names and Selector. The
        # templates must all be of type Kind. A template will be
        # selected if the workload matches the specified selector.
        # Only one template can be selected. Only one of Name and
        # Options can be specified. Minimum number of items in
        # list is two.
        # +optional
        options:
          - # Name of the template to apply Name or PassThrough
            # must be specified
            # +optional
            name: <string>

            # PassThrough the input Name or PassThrough must be
            # specified
            # +optional
            passThrough: <string>

            # Selector is a criteria to match against  a workload
            # or deliverable resource.
            selector:

              # matchExpressions is a list of label selector
              # requirements. The requirements are ANDed.
              # +optional
              matchExpressions:
                - # A label selector requirement is a selector
                  # that contains values, a key, and an operator
                  # that relates the key and values.
                  # +optional

                  # key is the label key that the selector applies
                  # to.
                  key: <string>

                  # operator represents a key's relationship to a
                  # set of values. Valid operators are In, NotIn,
                  # Exists and DoesNotExist.
                  operator: <string>

                  # values is an array of string values. If the
                  # operator is In or NotIn, the values array must
                  # be non-empty. If the operator is Exists or
                  # DoesNotExist, the values array must be empty.
                  # This array is replaced during a strategic
                  # merge patch.
                  # +optional
                  values: [ <string> ]

              # MatchFields is a list of field selector
              # requirements. The requirements are ANDed.
              # +optional
              matchFields:
                - # Key is the JSON path in the workload to match
                  # against. e.g. for workload:
                  # "workload.spec.source.git.url", e.g. for
                  # deliverable: "deliverable.spec.source.git.url"
                  key: <string>

                  # Operator represents a key's relationship to a
                  # set of values. Valid operators are In, NotIn,
                  # Exists and DoesNotExist.
                  operator: <[In|NotIn|Exists|DoesNotExist]>

                  # Values is an array of string values. If the
                  # operator is In or NotIn, the values array must
                  # be non-empty. If the operator is Exists or
                  # DoesNotExist, the values array must be empty.
                  # +optional
                  values: [ <string> ]

              # matchLabels is a map of {key,value} pairs. A
              # single {key,value} in the matchLabels map is
              # equivalent to an element of matchExpressions,
              # whose key field is "key", the operator is "In",
              # and the values array contains only "value". The
              # requirements are ANDed.
              # +optional
              matchLabels: {}

  # Specifies the label key-value pairs used to select owners See:
  # https://cartographer.sh/docs/v0.1.0/architecture/#selectors
  # +optional
  selector: {}

  # Specifies the requirements used to select owners based on
  # their labels See:
  # https://cartographer.sh/docs/v0.1.0/architecture/#selectors
  # +optional
  selectorMatchExpressions:
    - # A label selector requirement is a selector that contains
      # values, a key, and an operator that relates the key and
      # values.
      # +optional

      # key is the label key that the selector applies to.
      key: <string>

      # operator represents a key's relationship to a set of
      # values. Valid operators are In, NotIn, Exists and
      # DoesNotExist.
      operator: <string>

      # values is an array of string values. If the operator is In
      # or NotIn, the values array must be non-empty. If the
      # operator is Exists or DoesNotExist, the values array must
      # be empty. This array is replaced during a strategic merge
      # patch.
      # +optional
      values: [ <string> ]

  # Specifies the requirements used to select owners based on
  # their fields See:
  # https://cartographer.sh/docs/v0.1.0/architecture/#selectors
  # +optional
  selectorMatchFields:
    - # Key is the JSON path in the workload to match against.
      # e.g. for workload: "workload.spec.source.git.url", e.g.
      # for deliverable: "deliverable.spec.source.git.url"
      key: <string>

      # Operator represents a key's relationship to a set of
      # values. Valid operators are In, NotIn, Exists and
      # DoesNotExist.
      operator: <[In|NotIn|Exists|DoesNotExist]>

      # Values is an array of string values. If the operator is In
      # or NotIn, the values array must be non-empty. If the
      # operator is Exists or DoesNotExist, the values array must
      # be empty.
      # +optional
      values: [ <string> ]

  # ServiceAccountName refers to the Service account with
  # permissions to create resources submitted by the supply chain.
  # If not set, Cartographer will use serviceAccountName from
  # supply chain. 
  # If that is also not set, Cartographer will use the default
  # service account in the workload's namespace.
  # +optional
  serviceAccountRef:

    # Name of the service account being referred to
    name: <string>

    # Namespace of the service account being referred to if
    # omitted, the Owner's namespace is used.
    # +optional
    namespace: <string>

ref: pkg/apis/v1alpha1/cluster_supply_chain.go