spec-reference.hbs.md

Parameter reference

This topic tells you about the default supply chains and templates provided by Tanzu Application Platform (commonly known as TAP). It describes the workload.spec.params parameters that are configured in workload objects, and the deliverable.spec.params parameters that are configured in the deliverable object.

Workload Parameter Reference

The supply chains and templates provided by the Out of the Box packages contain a series of parameters that customize supply chain behavior. This section describes the workload.spec.params parameters that can be configured in workload objects.

The following table provides a list of supply chain resources organized by the resource in the supply chain where they are used. Some of these resources might not be applicable depending on the supply chain in use.

List of Supply Chain Resources for Workload Object

Supply Chain Resource	Output Type	Purpose	Basic	Testing	Scanning
source-provider	Source	Fetches source code	Yes	Yes	Yes
source-tester	Source	Tests source code	No	Yes	Yes
source-scanner	Source	Scans source code	No	No	Yes
image-provider	Image	Builds application container image	Yes	Yes	Yes
image-scanner	Image	Scans application container image	No	No	Yes
config-provider	Podtemplate spec	Tailors a pod spec based on the application image and conventions set up in the cluster	Yes	Yes	Yes
app-config	Kubernetes configuration	Creates Kubernetes config files (knative service/deployment - depending on workload type)	Yes	Yes	Yes
service-bindings	Kubernetes configuration	Adds service bindings to the set of config files	Yes	Yes	Yes
api-descriptors	Kubernetes configuration	Adds api descriptors to the set of config files	Yes	Yes	Yes
config-writer	Kubernetes configuration	Writes configuration to a destination (git or registry) for further deployment to a run cluster	Yes	Yes	Yes
deliverable	Kubernetes configuration	Writes deliverable content to be extracted for use in a run cluster	Yes	Yes	Yes

For information about supply chains, see:

• Out of the Box Supply Chain Basic
• Out of the Box Supply Chain Testing
• Out of the Box Supply Chain Testing Scanning

source-provider

The source-provider resource in the supply chain creates objects that fetch either source code or pre-compiled Java applications depending on how the workload is configured. For more information, see Building from Source.

GitRepository

Use gitrepository when fetching source code from Git repositories. This resource makes further resources available in the supply chain, such as the contents of the Git repository as a tarball available in the cluster.

Parameters:

Parameter name	Meaning	Example
gitImplementation	VMware recommends that you use the underlying library for fetching the source code.	- name: gitImplementation value: go-git
gitops_ssh_secret	The name of the secret in the same namespace as the Workload used for providing credentials for fetching source code from the Git repository. For more information, see Git authentication.	- name: gitops_ssh_secret value: git-credentials

For information about the features supported by each implementation, see Git implementation in the Flux documentation.

For information about how to create a workload that uses a GitHub repository as the provider of source code, see Create a workload from GitHub repository.

For more information about GitRepository objects, see Git Repository in the Flux documentation.

ImageRepository

Use the ImageRepository when fetching source code from container images. It makes the contents of the container image available as a tarball to further resources in the supply chain. The contents of the container image are fetched by using Git or Maven. For more information, see Create a workload from local source code.

Parameters:

Parameter Name	Meaning	Example
serviceAccount	Name of the service account (in the same namespace as the workload) to use to provide the credentials to ImageRepository for fetching the container images.	- name: serviceAccount value: default

The --service-account flag sets the spec.serviceAccountName key in the workload object. To configure the serviceAccount parameter, use --param serviceAccount=SERVICE-ACCOUNT.

For information about custom resource details, see the ImageRepository reference topic.

For information about how to use ImageRepository with the Tanzu CLI, see Create a workload.

MavenArtifact

When carrying pre-built Java artifacts, MavenArtifact makes the artifact available to further resources in the supply chain as a tarball. You can wrap the tarball as a container image for further deployment. Differently from git and image, its configuration is solely driven by parameters in the workload.

Parameters:

Parameter Name	Meaning	Example
maven	Points to the maven artifact to fetch and the polling interval.	- name: maven value: artifactId: springboot-initial groupId: com.example version: RELEASE classifier: sources # optional type: # optional artifactRetryTimeout: 1m0s # optional

For information about the custom resource, see the MavenArtifact reference documentation.

For information about how to use the custom resource with the Tanzu apps CLI plug-in, see the Tanzu CLI Command Reference documentation.

source-tester

The source-tester resource is in ootb-supply-chain-testing and ootb-supply-chain-testing-scanning. This resource is responsible for instantiating a Tekton PipelineRun object that calls the execution of a Tekton Pipeline, in the same namespace as the workload, whenever its inputs change. For example, the source code revision that you want to test changes.

A Runnable object is instantiated to ensure that there's always a run for a particular set of inputs. The parameters are passed from the workload down to Runnable's Pipeline selection mechanism through testing_pipeline_matching_labels and the execution of the PipelineRuns through testing_pipeline_params.

Parameters:

Parameter name	Meaning	Example
testing_pipeline_matching_labels	The set of labels to use when searching for Tekton Pipeline objects in the same namespace as the workload. By default, a Pipeline labeled as apps.tanzu.vmware.com/pipeline: test is selected, but when using this parameter, it's possible to override the behavior.	- name: testing_pipeline_matching_labels value: apps.tanzu.com/pipeline: test my.company/language: golang
testing_pipeline_params	The set of extra parameters, aside from source-url and source-revision, to pass to the Tekton Pipeline. The Tekton Pipeline must declare both the required parameters source-url and source-revision and the extra ones declared in this table.	- name: testing_pipeline_params value: verbose: true

For information about how to set up the Workload namespace for testing with Tekton, see Out of the Box Supply Chain with Testing.

For information about how to use the parameters to customize this resource to test using a Jenkins cluster, see Out of the Box Supply Chain with Testing on Jenkins.

source-scanner

The source-scanner resource is available in ootb-supply-chain-testing-scanning. It scans the source code that is tested by pointing a SourceScan object at the same source code as the tests.

You can customize behavior for both CVEs evaluation with parameters.

Parameters:

Parameter name	Meaning	Example
scanning_source_template	The name of the ScanTemplate object (in the same namespace as the workload) to use for running the scans against the source code.	- name: scanning_source_template value: private-source-scan-template
scanning_source_policy	The name of the ScanPolicy object (in the same namespace as the workload) to use when evaluating the scan results of a source scan.	- name: scanning_source_policy value: allowlist-policy

For more information, see Out of the Box Supply Chain with Testing and Scanning for details about how to set up the workload namespace with the ScanPolicy and ScanTemplate required for this resource, and SourceScan reference for details about the SourceScan custom resource.

For information about how the artifacts found during scanning are catalogued, see Supply Chain Security Tools for Tanzu – Store.

image-provider

The image-provider in the supply chains provides a container image carrying the application already built to further resources.

Different semantics apply, depending on how the workload is configured, for example, if using pre-built images or building from source:

• pre-built: an ImageRepository object is created aiming at providing a reference to the latest image found matching the name as specified in workload.spec.image

• building from source: an image builder object is created (either Kpack's Image or a Runnable for creating Tekton TaskRuns for building images from Dockerfiles)

Kpack Image

Use the Kpack Image object to build a container image out of source code or pre-built Java artifact.

This makes the container image available to further resources in the supply chain through a content addressable image reference that's carried to the final deployment objects unchanged. For more information, see Tanzu Build Service.

Parameters:

Parameter name	Meaning	Example
serviceAccount	The name of the serviceaccount (in the same namespace as the workload) to use for providing credentials to Image for pushing the container images it builds to the configured registry.	- name: serviceAccount value: default
clusterBuilder	The name of the Kpack cluster builder to use in the Kpack Image object created.	- name: clusterBuilder value: nodejs-cluster-builder
buildServiceBindings	The definition of a list of service bindings to use at build time. For example, providing credentials for fetching dependencies from repositories that require credentials.	- name: buildServiceBindings value: - name: settings-xml kind: Secret apiVersion: v1
additionalTags	The additionalTags is a list of locations the built OCI image will be written to in addition to the default tag. Additional tags must be in the same registry as the default tag.	- name: additionalTags value: - my-registry.com/my-app - my-other-registry.com/other-app:other-tag
live-update	Enables the use of Tilt's live-update function.	- name: live-update value: "true"

The --service-account flag sets the spec.serviceAccountName key in the workload object. To configure the serviceAccount parameter, use --param serviceAccount=SERVICE-ACCOUNT.

For information about the integration with Tanzu Build Service, see Tanzu Build Service Integration.

For information about live-update, see Developer Conventions and Overview of Tanzu Developer Tools for IntelliJ.

For information about using Kpack builders with clusterBuilder, see Builders.

For information about buildServiceBindings, see Service Bindings.

Runnable (TaskRuns for Dockerfile-based builds)

To perform Dockerfile-based builds, all the supply chains instantiate a Runnable object that instantiates Tekton TaskRun objects to call the execution of kaniko builds.

Parameters:

Parameter name	Meaning	Example
dockerfile	The relative path to the Dockerfile file in the build context.	./Dockerfile
docker_build_context	The relative path to the directory where the build context is.	.
docker_build_extra_args	List of flags to pass directly to Kaniko, such as providing arguments to a build.	--build-arg=FOO=BAR

For information about how to use Dockerfile-based builds and limitations associated with the function, see Dockerfile-based builds.

Pre-built image (ImageRepository)

For applications that already have their container images built outside the supply chains, such as providing an image reference under workload.spec.image, an ImageRepository object is created to keep track of any images pushed under that name.

This makes the content-addressable name, such as the image name containing the digest, available for further resources in the supply chain.

Parameters:

Parameter name	Meaning	Example
serviceAccount	The name of the serviceaccount (in the same namespace as the workload) to use for providing the credentials to ImageRepository for fetching the container images.	- name: serviceAccount value: default

The --service-account flag sets the spec.serviceAccountName key in the workload object. To configure the serviceAccount parameter, use --param serviceAccount=....

For information about the ImageRepository resource, see the ImageRepository reference documentation. For information about the prebuild image function, see Using a prebuilt image.

image-scanner

The image-scanner resource is included only in ootb-supply-chain-testing-scanning.

This resource scans a container image (either built by using the supply chain or prebuilt), persisting the results in the store, and gating the image from moving forward in case the CVEs found are not compliant with the ScanPolicy referenced by the ImageScan object create for doing so.

Parameters:

Parameter name	Meaning	Example
scanning_image_template	The name of the ScanTemplate object (in the same namespace as the workload) to use for running the scans against a container image.	- name: scanning_image_template value: private-image-scan-template
scanning_image_policy	The name of the ScanPolicy object (in the same namespace as the workload) to use when evaluating the scan results of an image scan.	- name: scanning_image_policy value: allowlist-policy

For information about the ImageScan custom resource, see ImageScan reference.

For information about how the artifacts found during scanning are catalogued, see Supply Chain Security Tools for Tanzu – Store.

config-provider

The config-provider resource in the supply chains generates a PodTemplateSpec to use in application configs, such as Knative services and deployments, to represent the desired pod configuration to instantiate to run the application in containers. For more information, see PodTemplateSpec in the Kubernetes documentation.

The config-provider resource manages a PodIntent object that represents the intention of having PodTemplateSpec enhanced with conventions installed in the cluster whose final representation is then passed forward to other resources to form the final deployment configuration.

Parameters:

Parameter name	Meaning	Example
serviceAccount	The name of the serviceaccount (in the same namespace as the workload) to use for providing the necessary credentials to PodIntent for fetching the container image to inspect the metadata to pass to convention servers and the serviceAccountName set in the podtemplatespec.	- name: serviceAccount value: default
annotations	An extra set of annotations to pass down to the PodTemplateSpec.	- name: annotations value: name: my-application version: v1.2.3 team: store
debug	Put the workload in debug mode.	- name: debug value: "true"
live-update	Enable live-updating of the code (for innerloop development).	- name: live-update value: "true"

The --service-account flag sets the spec.serviceAccountName key in the workload object. To configure the serviceAccount parameter, use --param serviceAccount=SERVICE-ACCOUNT.

For more information about the controller behind PodIntent, see Cartographer Conventions.

For more details about the two convention servers enabled by default in Tanzu Application Platform installations, see Developer Conventions and Spring Boot conventions.

app-config

The app-config resource prepares a ConfigMap with the Kubernetes configuration that is used for instantiating an application in the form of a particular workload type in a cluster.

The resource is configured in the supply chain to allow, by default, three types of workloads with the selection of which workload type to apply based on the labels set in the workload object created by the developer:

• apps.tanzu.vmware.com/workload-type: web
• apps.tanzu.vmware.com/workload-type: worker
• apps.tanzu.vmware.com/workload-type: server

Only the server workload type has the following configurable parameters:

Parameter name	Meaning	example
ports	The set of network ports to expose from the application to the Kubernetes cluster.	- name: ports value: - containerPort: 2025 name: smtp port: 25

For more information about the three different types of workloads, see Overview of workloads.

For a more detailed overview of the ports parameter, see server-specific Workload parameters.

service-bindings

The service-bindings resource adds ServiceBindings to the set of Kubernetes configuration files to promote for deployment.

Parameters:

Parameter name	Meaning	Example
annotations	The extra set of annotations to pass down to the ServiceBinding and ResourceClaim objects.	- name: annotations value: name: my-application version: v1.2.3 team: store

For an example, see the Tanzu CLI Command Reference documentation.

For an overview of the function, see Consume services on Tanzu Application Platform.

api-descriptors

The api-descriptor resource adds an APIDescriptor to the set of Kubernetes objects to deploy. This enables API auto registration.

Parameters:

Parameter name	Meaning	Example
annotations	An extra set of annotations to pass down to the APIDescriptor object.	- name: annotations value: name: my-application version: v1.2.3 team: store
api_descriptor	Information used to fill the state that you want of the APIDescriptor object (its spec).	- name: api_descriptor value: type: openapi location: baseURL: http://petclinic-hard-coded.my-apps.tapdemo.vmware.com/ path: "/v3/api" owner: team-petclinic system: pet-clinics description: "example"

The workload must include the apis.apps.tanzu.vmware.com/register-api: "true" label to activate this function.

For more details about API auto registration, see Use API Auto Registration.

config-writer (git or registry)

The config-writer resource is responsible for performing the last mile of the supply chain: persisting in an external system (registry or Git repository) the Kubernetes configuration generated throughout the supply chain.

There are three methods:

• Publishing the configuration to a container image registry
• Publishing the configuration to a Git repository by using the push of a commit
• Publishing the configuration to a Git repository by pushing a commit and opening a pull request

For more information about the different modes of operation, see Use GitOps or RegistryOps with Supply Chain Choreographer.

deliverable

The deliverable resource creates a deliverable object that represents the intention of delivering to the cluster the configurations that are produced by the supply chain.

Parameters:

Parameter name	Meaning	Example
serviceAccount	The name of the serviceaccount (in the same namespace as the deliverable) to use for providing the necessary permissions to create the children objects for deploying the objects created by the supply chain to the cluster.	- name: serviceAccount value: default

The --service-account flag sets the spec.serviceAccountName key in the workload object. To configure the serviceAccount parameter, use --param serviceAccount=SERVICE-ACCOUNT.

On build clusters where a corresponding ClusterDelivery doesn't exist, the deliverable takes no effect (similarly to a workload without a SupplyChain, no action is taken).

Deliverable Parameters Reference

The deliverable object applies the configuration produced by the resources defined by a ClusterSupplyChain to a Kubernetes cluster.

This section describes the deliverable.spec.params parameters that can be configured in the deliverable object. The following section describes the two resources defined in the ClusterDelivery resources section. These are part of the ootb-delivery-basic package:

List of Cluster Delivery Resources for Deliverable Object

Cluster Delivery Resource	Output Type	Purpose
source provider	Source	Fetches the Kubernetes configuration file from Git repository or image registry
app deployer	Source	Applies configuration produced by a supply chain to the cluster

For information about the ClusterDelivery shipped with ootb-delivery-basic, and the templates used by it, see:

• Out of the Box Delivery Basic
• Out of the Templates

For information about the use of the deliverable object in a multicluster environment, see Getting started with multicluster Tanzu Application Platform.

For reference information about deliverable, see Deliverable and Delivery custom resources in the Cartographer documentation.

source-provider

The source-provider resource in the basic ClusterDelivery creates objects that continuously fetch Kubernetes configuration files from a Git repository or container image registry so that it can apply those to the cluster.

Regardless of where it fetches that Kubernetes configuration from (Git repository or image registry), it exposes those files to further resources along the ClusterDelivery as a tarball.

GitRepository

A GitRepository object is instantiated when deliverable.spec.source.git is configured to continuously look for a Kubernetes configuration pushed to a Git repository, making it available for resources in the ClusterDelivery.

Parameters:

Parameter name	Meaning	Example
gitImplementation	VMware recommends that you use the underlying library for fetching the source code. go-git.	- name: gitImplementation value: go-git
gitops_ssh_secret	The name of the secret in the same namespace as the deliverable used for providing credentials for fetching Kubernetes configuration files from the Git repository pointed at. See Git authentication.	- name: gitops_ssh_secret value: git-credentials

For information about the features supported by each implementation, see git implementation in the Flux documentation.

For information about how to create a workload that uses a GitHub repository as the provider of source code, see Create a workload from GitHub repository.

For information about GitRepository objects, see GitRepository.

ImageRepository

An ImageRepository object is instantiated when deliverable.spec.source.image is configured to continuously look for Kubernetes configuration files pushed to a container image registry as opposed to a Git repository.

Parameters:

Parameter name	Meaning	Example
serviceAccount	The name of the service account, in the same namespace as the deliverable, you want to use to provide the necessary permissions for kapp-controller to deploy the objects to the cluster.	- name: serviceAccount value: default

The --service-account flag sets the spec.serviceAccountName key in the deliverable object. To configure the serviceAccount parameter, use --param serviceAccount=SERVICE-ACCOUNT.

For information about custom resource details, see the ImageRepository reference documentation.

app deployer

The app-deploy resource in the ClusterDelivery applies the Kubernetes configuration that is built by the supply chain, pushed to either a Git repository or image repository, and applied to the cluster.

App

Regardless of where the configuration comes from, an App object is instantiated to deploy the set of Kubernetes configuration files to the cluster.

Parameters:

Parameter name	Meaning	Example
serviceAccount	The name of the service account, in the same namespace as the deliverable, you want to use to provide the necessary privileges for App to apply the Kubernetes objects to the cluster.	- name: serviceAccount value: default
gitops_sub_path (deprecated)	The subdirectory within the configuration bundle used for looking up the files to apply to the Kubernetes cluster.	- name: gitops_sub_path value: ./config

The gitops_sub_path parameter is deprecated. Use deliverable.spec.source.subPath instead.

The --service-account flag sets the spec.serviceAccountName key in the deliverable object.

To configure the serviceAccount parameter, use --param serviceAccount=SERVICE-ACCOUNT.

For details about RBAC and how kapp-controller uses the ServiceAccount provided to it using the serviceAccount parameter in the deliverable object, see kapp-controller's Security Model in the Carvel documentation.