Configure builds to run on Tanzu Platform

By default, when you build an application by running tanzu build, the application is built locally on the system on which you run the command. The built application is then deployed to its Project on Tanzu Platform. Running local builds requires a Docker daemon to be running on the local system, which is not always possible. Building applications locally can also introduce single points of failure, pose problems of scale, introduce inconsistencies between build environments, or be subject to security issues. Consequently, you can configure Projects so that running tanzu build builds the application directly in its Project on Tanzu Platform rather than on the local system. By building applications on Tanzu Platform rather than locally, you can provide a secure and consistent build environment that has more resources available to it than are available on the local system.

Building applications on Tanzu Platform rather than locally requires you to provide some additional configuration information, so that the build can access Tanzu Platform, your container registry, any service bindings that the application requires, and so on. You provide this configuration information in Kubernetes secrets that are referenced by a BuildConfiguration resource. You apply the BuildConfiguration YAML file to the Project by using kubectl. The BuildConfiguration is applied to all builds occur in the Project, regardless the system on which the tanzu build command is run. Application developers run tanzu build in the same way as for a local build.

Note

Builds that you run on Tanzu Platform always use the default ContainerAppBuildPlan. To use a customized ContainerAppBuildPlan, see Add custom tasks to a build.

Before you begin

• Install Tanzu CLI v1.4.0 or later. See Installing the Tanzu CLI in the Tanzu CLI documentation.

• If it is not present, install the Tanzu CLI app-developer plug-in group by running:

  tanzu plugin install --group vmware-tanzu/app-developer
  

  If the app-developer plug-in group is already installed, verify that you have the latest version of the build plug-in by running:

  tanzu plugin upgrade build
  

Apply a BuildConfiguration file to a project

You create a BuildConfiguration file manually and apply it to a Project by using kubectl.

1. Log in to Tanzu Platform with the Tanzu CLI:

   tanzu login
   

2. Set the Tanzu CLI to your Project context:

   tanzu project use [project_name]
   

3. Set KUBECONFIG:

   export KUBECONFIG=~/.config/tanzu/kube/config
   

4. Create Kubernetes secret resource YAML files for authentication with your container registry, service binding certificates, and authentication token for Tanzu Platform.

   See Example Kubernetes secret resources below for examples of how to create the required secret resource YAML files.

5. Create a BuildConfiguration YAML file that references the secrets you created in the preceding step.

   For example, create a file named my-buildconfiguration.yaml. See BuildConfiguration file specification below for information about how to create a BuildConfiguration file, and an example file.

6. Use kubectl to add all of the secrets to your project.

   kubectl apply -f my-secret1.yaml
   kubectl apply -f my-secret2.yaml
   

7. Use kubectl to add the custom BuildConfiguration to your project.

   kubectl apply -f my-buildconfiguration.yaml
   

8. Run tanzu build to build your application on Tanzu Platform.

   tanzu build
   

BuildConfiguration file specification

A BuildConfiguration file requires the following information:

Field Name	Required?	Data Type	Description
AvailabilityTarget	Required	string	The availability target to use for the build. See spec.availabilityTarget in the BuildConfiguration example.
ImageRepositoryTemplate	Required	string	A templated string that is used to generate the URL of the repository to which to push built images. For example, for a ContainerApp named foo with spec.contact.team: bar and imageRepositoryTemplate my-registry.io/{contact.team}/containerapp-{name}, the URL renders as my-registry.io/bar/containerapp-foo. See spec.imageRepositoryTemplate in the BuildConfiguration example.
ImageRepositorySecretRefs	Optional	array (string)	One or more Kubernetes secret resources. This field is required if the image registry implements authentication when storing build artifacts. The referenced secret stores the credentials for accessing the image registry. Secrets must be of either the kubernetes.io/dockercfg or kubernetes.io/dockerconfigjson types. Referenced secret resources must be created in the Project Space. See spec.imageRepositorySecretRefs in the BuildConfiguration example and Example secret to store image registry credentials.
BindingSecretRefs	Optional	array (string)	One or more Kubernetes secret resources. The referenced secrets must be Opaque secrets that contain data for any service bindings that the build requires, such as CA Certificates, Maven settings, and so on. Data must be provided as a base64-encoded string. See bindingSecretRefs in the BuildConfiguration example and Example CA Certificate used in BindingSecretRefs.
APICredentialSecretRef	Required	string	A Kubernetes secret that contains an OAuth token used for internal communications with Tanzu Platform cloud services. The referenced secret must be an Opaque secret. Provide the OAuth credential with a key named user_auth and a base64-encoded string as its value. Alternatively, provide OAuth credentials by using the client_id and client_secret keys. See spec.imageRepositorySecretRefs in the BuildConfiguration example, Example Secret with OAuth token user_token, and Example Secret with OAuth token client_id and client_secret.
EgressPointTemplate	Optional	see EgressPointSpec	Egress endpoints that the build needs to accesses. Optionally configure approved endpoints that the build can access to generate artifacts. If omitted, egress traffic during the build can access any endpoints. See spec.egressPointTemplate in the BuildConfiguration example.

Example BuildConfiguration with an egress point specification

apiVersion: build.tanzu.vmware.com/v1
kind: BuildConfiguration
metadata:
  annotations: {}
  name: dev-project-bld-cfg
  namespace: default
spec:
  apiCredentialSecretRef:
    name: api-creds
  availabilityTarget: all-regions.tanzu.broadcom.com
  bindingSecretRefs:
    - name: ca-cert
    - name: maven-settings
  imageRepositorySecretRefs:
    - name: reg-cred
    - name: builder-image-reg-cred
  imageRepositoryTemplate: my-registry.io/containerapp-{name}
  egressPointTemplate:
    targets:
    - hosts:
      - my-registry.io
      port:
        number: 443
        protocol: HTTPS

Example Kubernetes secret resources

The example BuildConfiguration file above references the following example Kubernetes secret resources.

Example secret to store image registry credentials

apiVersion: v1
data:
  .dockerconfigjson: eyJhdXRocyI6eyJteS1yZWdpc3RyeS5pbyI6eyJ1c2VybmFtZSI6Im15LXJlZy11c2VyIiwicGFzc3dvcmQiOiJteS1yZWctcHdkIiwiZW1haWwiOiJ0ZXN0QGJyb2FkY29tLmNvbSIsImF1dGgiOiJiWGt0Y21WbkxYVnpaWEk2YlhrdGNtVm5MWEIzWkE9PSJ9fX0=
kind: Secret
metadata:
  name: reg-cred
  namespace: default
type: kubernetes.io/dockerconfigjson

Example CA Certificate used in BindingSecretRefs

apiVersion: v1
data:
  cert.pem: LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQ0lqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FnOEFNSUlDQ2dLQ0FnRUFsUnVSblRoVWpVOC9wcndZeGJ0eQpXUFQ5cFVSSTNsYnNLTWlCNkZuL1ZIT0tFMTNwNEQ4eGdPQ0FEcGRSYWdkVDZuNGV0cjlhdHpES1VTdnBNdFIzCkNQNW5vTmM5N1dpTkNnZ0JqVldoczdzekVlOHVneXFGMjNYd3BIUTZ1VjFMS0g1MG05Mk1iT1dmQ3RqVTlwL3gKcWhOcFFRMUFaaHFOeTVHZXZhcDVrOFh6Um1qU2xkTkFGWk1ZN1l2M0dpK255Q3dHd3BWdEJVd2h1THpnTkZLLwp5RHR3MldjV21VVTdOdUM4UTZNV3ZQZWJ4VnRDZlZwL2lRVTZxNjB5eXQ2YUdPQmtoQVgwTHBLQUVoS2lkaXhZCm5QOVBOVkJ2eGd1M1haNFAzNmdaVjYrdW1tS2RCVm5jM05xd0JMdTUrQ2NkUmR1c21IUEhkNXBIZjQvMzhaMy8KNnFVMmEvZlB2V3pjZVZURWdaNDdRakZNVENUbUN3TnQyOWN2aTd6WmVRemp0d1FnbjRpcE45TmliUkgvQXgvcQpUYkl6SGZySjF4YTJSdGVXU2RGand0eGk5QzIwSFVralhTZUk0WWx6UU1IMGZQWDZLQ0U3YVZlUFRPbkI2OUkvCmE5L3E5NkRpWFphandscHEzd0ZjdHJzMW9YcUJwNURWckNJajhoVTJ3TmdCN0x0UTFtQ3RzWXovL2hlYWkwSzkKUGhFNFg2aGlFMFltZUFaalIwdUhsOE0vNWFXOXhDb0o3MisxMmtLcFdBYTBTRlJXTHk2RmVqTllDWXBrdXBWSgp5ZWNMay80TDFXMGw2alFRWm5XRXJYWlllMFBORmNtd0dYeTFSZXA4M2tmQlJOS1J5NXR2b2NhbExsd1hMZFVrCkFJVSsyR0tqeVQzaU11elp4eEZ4UEZNQ0F3RUFBUT09Ci0tLS0tRU5EIFBVQkxJQyBLRVktLS0tLQ==
  type: Y2EtY2VydGlmaWNhdGVz
kind: Secret
metadata:
  name: ca-cert
type: Opaque

Example Secret with OAuth token user_token

apiVersion: v1
data:
  user_token: aGtzZGpoZmtzZGpoJTQyNzZlaGg4NzYK==
kind: Secret
metadata:
  name: api-creds
type: Opaque

Example Secret with OAuth token client_id and client_secret

apiVersion: v1
data:
  client_id: OTg3M2luZmt3ZHNuYnZrc2Q2djlzNnY5c3l2c252a3NmdmtqZGh2OTc2OTQzNzVvMzRqcmozNGw1dTM0MDU3MDM0dXJvMzRqNXAzNGk4NzM0ODUzNDg1LTk0My05NTM0LTkwNTM0OTUtMzQ5NS05Mi0tOTUtODI0LTU4LTM0ODUtMzQ4NS0zOC1oa2tma3NqaGZ5ZjhzN2N5dmljc2h2a3Nrdm5ia2NqaHZrZmh2Cg==
  cliend_secret: YTF2ZDgwV0VPOHgrMFBMdDB2REFBM3BGc0xmbER4TVZOcUZXVW5KNHRiZnRkYnZSaFZuWGxsamJIejJiXG5MYkhpRm5uN2lXSVBTVFV3MUR1ZE90dkVEUHk1NzlkZ1RNTjdodTZGdVVST2ZVbzlGSWhRZjFzUnkwNTVBWDdwXG4zQ2I1SUYzTDYwd2pING0ybU50L080SXZNTUQxNkZZa1ZwdmdZZElsWkc4U1ZoZVMvckwwZHJWTWUwNlVjcWhsXG56ZEtxeStYc2pIUGtCMHNiaXdpMVcybHdJVTBUbGV4Y25rVTQxV1Nzc1hRY3JheFI2anF3MitGVlErUXVSU01OXG45T1lGY2lCdWxlUUNQVUoxUW5YUFpadVdScFltWXVVOVc3SjNWTldmcTNVdlJaVm1VZWZOS2crZUhsVExhekJyXG5peXRJMjF0MUFnTUJBQUVDZ2dFQUNJUExyWXgxR2l5OGlnYVNYRk1CNmtrc1ZOWUdMYkpNNUdlQTdsQTVhRnFXXG5HZFl1VjhmME10SEM0YmZaMlBKanl0bFVSTllrYU1KZ0VVaGNvMlcxVTQreG5GVDcxbzNoaXdaUlA5SUVoSmM2XG4yTVVVQTdMbGVYbm1ua25nd2hEa2RCTDZrVFNzNzZFdGRHbXFJM3RhTS9ydmpyR2RoMVFTbHY2a3RFNU1qYXdZXG5OWXBzMldSSnJTTGRzV1lGK0MzekgvR0VRMGJDU3piWnhmb3hUUFlCRUV2U2FmTlpnK1VtMmlEWWdJMnV6bEE4XG5pclRRaEdBTm1ia2hwSWJkdVRLUTZrVmVQQkx0Z0E3SWlIOHVMS043MkZFdm1sMTFnODJzejVheldqQndZdXFSXG5BWUJWYTQwQkVHdUhMTVVnZHhzNFh6ZHVaRTZORmU1UFMyTTNtWUdZRVFLQmdRRDJCVjlUNGdwT05hNjArUzhkXG45M05KSGRBbEM5NWFlV2loanVvWWVLejJsdlNXRVAvQS9hZ0ZWZXpJWjR3TlNFaVBXUGNzTzJuWHNCN1QvMTdzCgo=
kind: Secret
metadata:
  name: api-creds
type: Opaque