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.
The out of the box Supply Chains output a Deliverable
object. These Deliverable
s 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 Package
s onto multiple environments.
NoteThe Kubernetes resources created for your
Workload
are the same for Carvel Package supply chains, but with additional, optional resources such asnetworking.k8s.io/v1 Ingress
.
There are two Carvel Package Supply Chains per package:
source-to-url-package
and basic-image-to-url-package
.source-test-to-url-package
and testing-image-to-url-package
.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:
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
NoteBy 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 thegitops_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.
This section describes operator tasks for enabling and configuring the Carvel Package Supply Chains.
The Carvel Package Supply Chains require access to a GitOps repository and credentials. See GitOps versus RegistryOps.
In tap-values
, configure any Out of the Box Supply Chain and the Out of the Box Templates package with the following parameters:
NoteIf you are installing Out of the Box Supply Chain with Testing, replace
ootb_supply_chain_basic
withootb_supply_chain_testing
in all of the following steps. If you are installing Out of the Box Supply Chain with Testing and Scanning, replaceootb_supply_chain_basic
withootb_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 information, see the release notes.
(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.
kubectl get ClusterSupplyChains
.Confirm you see both Carvel Package supply chains with status Ready: True
:
source-to-url-package
and basic-image-to-url-package
.source-test-to-url-package
and testing-image-to-url-package
.source-test-scan-to-url-package
and scanning-image-scan-to-url-package
.This section describes developer tasks for using the Carvel Package Supply Chains.
Your operator must install the Carvel Package Supply Chains.
You must create your workload in a developer namespace. See Developer namespace.
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.
NoteDevelopers 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 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.
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.
You can deploy the Carvel Package
using tools such as Flux CD or Argo CD. See Deploy Carvel Packages using Flux CD Kustomization.