Carvel Package Supply Chains

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, Out of the Box Supply Chain with Testing, and Out of the Box Supply Chain with Testing and Scanning packages provide variations of the OOTB supply chains that output Carvel Packages.

Overview of the Carvel Package Supply Chains

The out of the box Supply Chains output a Deliverable object. These Deliverables are deployed to a cluster by the Out of the Box Delivery Supply Chain. The Carvel Package Supply Chains instead 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 Workload are the same for Carvel Package supply chains, but with additional, optional resources such as networking.k8s.io/v1 Ingress.

What do the Carvel Package Supply Chains do?

There are two Carvel Package Supply Chains per package:

Out of the Box Basic Supply Chain contains source-to-url-package and basic-image-to-url-package.
Out of the Box Supply Chain with Testing contains source-test-to-url-package and testing-image-to-url-package.
Out of the Box Supply Chain with Testing and Scanning contains source-test-scan-to-url-package and scanning-image-scan-to-url-package

These supply chains are identical to their non Carvel Package counterparts, 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:
      type: object
      additionalProperties: false
      properties:
        workload_name:
          title: Workload name
          type: string
          default: ""
        replicas:
          title: Replicas
          type: integer
          default: 1
        port:
          title: Port
          type: integer
          default: 8080
        hostname:
          title: Hostname
          type: string
          default: ""
        cluster_issuer:
          title: Cluster Issuer
          type: string
          default: tap-ingress-selfsigned
        http_route:
          type: object
          additionalProperties: false
          nullable: true
          properties:
            gateways:
              type: array
              items:
                type: object
                additionalProperties: false
                properties:
                  protocol:
                    type: string
                    default: ""
                  name:
                    type: string
                    default: ""
              default:
              - protocol: https
                name: default-gateway

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. Default is "tap-ingress-selfsigned".
http_route: Configuration of gateway.networking.k8s.io/v1beta1 HttpRoute. This is intended for use with Tanzu Application Engine. VMware does not recommend this setting when running on Tanzu Application Platform.

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 any Out of the Box Supply Chain and the Out of the Box Templates package with the following parameters:

Note
If you are installing Out of the Box Supply Chain with Testing, replace ootb_supply_chain_basic with ootb_supply_chain_testing in all of the following steps. If you are installing Out of the Box Supply Chain with Testing and Scanning, replace ootb_supply_chain_basic with ootb_supply_chain_testing_scanning in all of the following steps.

(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. For more informtation, 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 your Out of the Box Supply Chain package with your GitOps parameters. See GitOps versus RegistryOps.
Install the Out of the Box Supply Chain package.

Verifying the Carvel Package Supply Chains are Installed

Run kubectl get ClusterSupplyChains.
Confirm you see both Carvel Package supply chains with status Ready: True:
- Out of the Box Basic Supply Chain contains source-to-url-package and basic-image-to-url-package.
- Out of the Box Supply Chain with Testing contains source-test-to-url-package and testing-image-to-url-package.
- Out of the Box Supply Chain with Testing and Scanning contains source-test-scan-to-url-package and scanning-image-scan-to-url-package.

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.