Carvel Package Supply Chains (beta)

This topic explains what Carvel Package Supply Chains do, how they work, how operators can enable them, and how to create a Workload that uses them. You can use the Carvel Package Supply Chains with Supply Chain Choreographer to deliver applications to multiple production environments with configuration for each environment.

The Out of the Box Basic Supply Chain package introduces a variation of the OOTB Basic supply chains that outputs Carvel Packages.

Overview of the Carvel Package Supply Chains

The out of the box Basic Supply Chain outputs a Deliverable object. These Deliverable objects are deployed to a cluster by the Out of the Box Delivery Supply Chain. The Carvel Package Supply Chains output a Carvel Package object to a GitOps repository. These Packages have configurable parameters such as hostname and replicas that are configured per environment. GitOps tools such as Flux CD and Argo CD can deploy the Packages onto multiple environments.

Note
The Kubernetes resources created for your server Workload are the same for source-to-url or basic-image-to-url, optionally with a networking.k8s.io/v1 Ingress resource. For example, a resource named Deployment. The Carvel Package wraps these resources. You secure the Ingress by using the cluster_issuer tap-ingress-selfsigned by default.

What do the Carvel Package Supply Chains Do?

There are two Carvel Package Supply Chains, source-to-url-package and basic-image-to-url-package in the Out of the Box Supply Chain Package. They are identical to source-to-url and basic-image-to-url, except for three resources:

A new carvel-package resource is added. The supply chain stamps out a Tekton Task that bundles all application Kubernetes resources into a Carvel Package.
config-writer is modified to write the Carvel Package to a GitOps repository.
deliverable resource is removed.

When a Workload is created and all Supply Chain resources are stamped out, a Carvel Package is written to the GitOps repository at the path <package_name>/packages/<package_id>.yaml. <package_name> by default to <workload_name>.<workload_namespace>.tap, and is customized with the name_suffix parameter. <package_id> is a SemVer compatible version generated by the Bash command $(date "+%Y%m%d%H%M%S.0.0").

For example:

app.default.tap/
  packages/
    20230321004057.0.0.yaml

Note
By default, the <package_name> directory is created in the root directory of the GitOps repository. You can optionally create this directory at a subpath by configuring the gitops_subpath parameter.

For example, the following Carvel Package definition is stored in <package_id>.yaml:

apiVersion: data.packaging.carvel.dev/v1alpha1
kind: Package
metadata:
  name: app.default.tap.20230321004057.0.0
spec:
  refName: app.default.tap
  version: 20230321004057.0.0
  releaseNotes: |
    Release v20230321004057.0.0 of package app.default.tap
  template:
    spec:
      fetch:
      - imgpkgBundle:
          image: # imgpkg bundle containing all Kubernetes configuration
      template:
      - ytt:
          paths:
          - .
      - kbld:
          paths:
          - .imgpkg/images.yml
          - '-'
      deploy:
      - kapp: {}
  valuesSchema:
    openAPIv3:
      additionalProperties: false
      properties:
        cluster_issuer:
          default: tap-ingress-selfsigned
          description: CertManager Issuer to use to generate certificate for K8s Ingress.
          title: Cluster Issuer
          type: string
        hostname:
          default: ""
          description: If set, K8s Ingress will be created with HTTP rules for hostname.
          title: Hostname
          type: string
        port:
          default: 8080
          description: Port number for the backend associated with K8s Ingress.
          title: Port
          type: integer
        replicas:
          default: 1
          description: Number of replicas.
          title: Replicas
          type: integer
        workload_name:
          default: ""
          description: Required. Name of the workload, used by K8s Ingress HTTP rules.
          title: Workload name
          type: string
      type: object

By default, the Carvel Package generated by the Supply Chain has configurable parameters.

For the server workload type, the default parameters are:

workload_name: Name of the workload. Required. Default is "".
replicas: Number of pods that you want for the apps/v1 Deployment. Default is 1.
hostname: Host name for the networking.k8s.io/v1 Ingress. If you don’t need ingress, leave host name as an empty string. If host name is not in the file, you see an error.
port: Port for the networking.k8s.io/v1 Ingress. Default is 8080.
cluster_issuer: CertManager Issuer to use to generate certificate for Kubernetes Ingress. The default is "tap-ingress-selfsigned".

For the web workload type, the default parameters are:

workload_name: Name of the workload. Required. Default is "".

For the worker workload type, the default parameters are:

workload_name: Name of the workload. Required. Default is "".
replicas: Number of pods that you want for the apps/v1 Deployment. Default is 1.

You can configure the Supply Chain to produce Carvel Packages with custom parameters. See the installation section.

When a new commit is pushed to the source code Git Repository, such as source-to-url-package, or a new pre-built image is created, like basic-image-to-url-package, the Supply Chain stamps out a new version of the Carvel Package. This definition is written to <package_name>/packages/<package_id>.yaml with a new <package_id>.

The Carvel Package stored in GitOps repositories are deployed to multiple run clusters using GitOps tools, such as Flux CD or Argo CD. See Deploy Carvel Packages using Flux CD Kustomization.

Installing the Carvel Package Supply Chains as an Operator

This section describes operator tasks for enabling and configuring the Carvel Package Supply Chains.

Prerequisites

The Carvel Package Supply Chains require access to a GitOps repository and credentials. See GitOps versus RegistryOps.

Installation

In tap-values, configure the Out of the Box Basic Supply Chain and the Out of the Box Templates package with the following parameters:

(Required) Enable the Carvel Package workflow.

ootb_supply_chain_basic:
  carvel_package:
    workflow_enabled: true

(Optional) Set a GitOps subpath. This verifies the path in your GitOps repository where Carvel Packages are written. Defaults to "". See Template reference.
```
ootb_supply_chain_basic:
  carvel_package:
    workflow_enabled: true
    gitops_subpath: path/to/my/dir
```
(Optional) Set a name suffix. Carvel Package names are chosen using the <workload_name>.<workload_namespace>.<name_suffix> template. Defaults to tap. See Template reference.
```
ootb_supply_chain_basic:
  carvel_package:
    workflow_enabled: true
    name_suffix: vmware.com
```
(Optional) Enable OpenAPIv3 Schema Definition Generation. Defaults to true. See Template reference.
```
ootb_supply_chain_basic:
  carvel_package:
    workflow_enabled: true
    openapiv3_enabled: true
```
If the size of the resulting OpenAPIv3 specification exceeds roughly 3 KB, the Supply Chain does not function. See the known issue.
(Optional) Configure the Out of the Box Templates with custom Carvel Package parameters. See Template reference.
- Packages created by the Carvel Package Supply Chains contain the YTT Schema and YTT Overlays.
- Supply Chain decides which YTT Schema and YTT Overlays to use based on the selector field. Operators can specify as many labels as they want under selector.matchLabels. The selector with the highest amount of matching labels is used.
  
  A selector is only considered a match if all labels under selector.matchLabels match. If there is more than one matching selector, the selector with more labels is used. If there is more than one matching selector, and they have the same amount of labels, the Supply Chain fails. If there is no matching selector, the Supply Chain fails.
- The ootb_templates.carvel_package.openapiv3_enabled = true package has a generated OpenAPIv3 API specification.
- Setting ootb_templates.carvel_package.parameters overrides the default Carvel Package parameters. If an operator wants to leave the parameters the same for web and worker types, but add a parameter for server, they must copy the default ootb_templates.carvel_package.parameters from the template reference, and then make the modification.
```
ootb_templates:
  carvel_package:
    parameters:
    - selector:
        matchLabels:
          apps.tanzu.vmware.com/workload-type: server
      schema: |
        #@data/values-schema
        ---
        #@schema/title "Replicas"
        #@schema/desc "Number of replicas."
        replicas: 1
      overlays: |
        #@ load("@ytt:overlay", "overlay")
        #@ load("@ytt:data", "data")
        #@overlay/match by=overlay.subset({"apiVersion":"apps/v1", "kind": "Deployment"})
        ---
        spec:
          #@overlay/match missing_ok=True
          replicas: #@ data.values.replicas
    # copy the existing parameters for worker + web here
```
Configure the Out of the Box Basic Supply Chain package with your GitOps parameters. See GitOps versus RegistryOps.
Install the Out of the Box Basic Supply Chain package.

Verifying the Carvel Package Supply Chains are Installed

Run kubectl get ClusterSupplyChains.
Confirm you see both source-to-url-package and basic-image-to-url-package with status Ready: True.

Using the Carvel Package Supply Chains as a Developer

This section describes developer tasks for using the Carvel Package Supply Chains.

Prerequisites

Your operator must install the Carvel Package Supply Chains.

You must create your workload in a developer namespace. See Developer namespace.

Create a Workload

To use the Carvel Package Supply Chains, you must add the label apps.tanzu.vmware.com/carvel-package-workflow=true to your workload.

Use the --label apps.tanzu.vmware.com/carvel-package-workflow=true Tanzu CLI flag.

For example:

tanzu apps workload create tanzu-java-web-app \
 --namespace DEVELOPER_NAMESPACE \
 --app tanzu-java-web-app \
 --type server \
 --label apps.tanzu.vmware.com/carvel-package-workflow=true \
 --image springcommunity/spring-framework-petclinic

Expect to see the following output:

Create workload:
   1 + |---
   2 + |apiVersion: carto.run/v1alpha1
   3 + |kind: Workload
   4 + |metadata:
   5 + |  labels:
   6 + |    app.kubernetes.io/part-of: tanzu-java-web-app
   7 + |    apps.tanzu.vmware.com/carvel-package-workflow: "true"
   8 + |    apps.tanzu.vmware.com/workload-type: server
   9 + |  name: tanzu-java-web-app
  10 + |  namespace: DEVELOPER_NAMESPACE
  11 + |spec:
  12 + |  image: springcommunity/spring-framework-petclinic

You can override most parameters set by the operator.

Note
Developers cannot override carvel_package_parameters as it presents a security risk.

(Optional) Set a GitOps subpath. This verifies the path in your GitOps repository where Carvel Packages are written. Defaults to "". See Template reference.

Set this parameter by modifying workload.spec.params.carvel_package_gitops_subpath, using the --param carvel_package_gitops_subpath=path/to/my/dir Tanzu CLI flag.
(Optional) Set a name suffix. Carvel Package names are chosen using the template <workload_name>.<workload_namespace>.<name_suffix>. Defaults to tap. See Template reference.

Set this parameter by modifying workload.spec.params.carvel_package_name_suffix, using the --param carvel_package_name_suffix=vmware.com Tanzu CLI flag.
(Optional) Enable OpenAPIv3 specification generation. Defaults to true. See Template reference.

Set this parameter by modifying workload.spec.params.carvel_package_openapiv3_enabled, using the --param carvel_package_openapiv3_enabled=false Tanzu CLI flag.
(Optional) You can override GitOps parameters. See GitOps versus RegistryOps.

Verify the Carvel Package was Created

Verify that you see a Carvel Package stored in your GitOps repository. For example, at the path tanzu-java-web-app.default.tap/packages/20230321004057.0.0.yaml you see a valid Carvel Package definition.

Git commit SHA in Package version

By default, the Git revision identifier for the software in the Carvel Package is added to the package version, in the format +build.${git_commit}, in the following cases:

The source-to-url-package builds the package and the image building resource is either kpack-template or the kaniko-template. These templates add the label Git commit SHA of the source code used to the label org.opencontainers.image.revision on the OCI image container.
An OCI image container is used with the label org.opencontainers.image.revision. The package version might look similar to 20230518150903.0.0+build.6db88c7 where 6db88c7 is the Git commit SHA.

Next Steps

You can deploy the Carvel Package using tools such as Flux CD or Argo CD. See Deploy Carvel Packages using Flux CD Kustomization.