Skip to content

Latest commit

 

History

History
216 lines (161 loc) · 8.68 KB

carvel-package-supply-chain.hbs.md

File metadata and controls

216 lines (161 loc) · 8.68 KB

Carvel Package Supply Chains (alpha)

The Out of the Box Basic Supply Chain package introduces a variation of the OOTB Basic supply chains that outputs Carvel Packages. The Carvel Package Supply Chains enable users to deliver applications to multiple production environments with configuration for each environment.

This topic explains what the Carvel Package Supply Chains do, how they work, how operators can enable them, and how to create a Workload that uses them.

Overview of the Carvel Package Supply Chains

The traditional Out of the Box Supply Chain Basic Supply Chains outputs a Deliverable object. These Deliverables 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 FluxCD and ArgoCD can deploy the Packages onto multiple environments.

Note The underlying Kubernetes resources created for your server Workload are the same for source-to-url or basic-image-to-url, with the addition of a networking.k8s.io/v1 Ingress resource. For example, Deployment. The Carvel Package wraps these resources.

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. It 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> defaults 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: {}

The Carvel Package generated by the Supply Chain has three configurable parameters:

  • 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. Default is example.com.
  • port: Port for the networking.k8s.io/v1 Ingress. Default is 8080.

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 FluxCD or ArgoCD. See Deploy Carvel Packages using FluxCD 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 package with the following parameters:

  1. (Required) Enable the Carvel Package workflow.

    ootb_supply_chain_basic:
  carvel_package:
    workflow_enabled: true

  2. (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

  3. (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

  4. Configure the Out of the Box Basic Supply Chain package with your GitOps parameters. See GitOps versus RegistryOps.

  5. Install the Out of the Box Basic Supply Chain package.

Verifying the Carvel Package Supply Chains are Installed

  1. Run kubectl get ClusterSupplyChains.
  2. 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.

Creating 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.

  1. 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 IMAGE

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: IMAGE
  1. (Optional) You can override parameters set by the operator. Set a GitOps subpath. This verifies the path in your GitOps repository to which Carvel Packages are written. Defaults to "". See Template referemce.

Set this parameter by modifying workload.spec.params.carvel_package_gitops_subpath. With the Tanzu CLI, you can do so by using the --param carvel_package_gitops_subpath=path/to/my/dir flag.

  1. (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. With the Tanzu CLI, you can do so by using the --param carvel_package_name_suffix=vmware.com flag.

  1. (Optional) You can override GitOps parameters. See GitOps versus RegistryOps.

Verify the Carvel Package was Created

You now 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.

Next Steps

You can deploy the Carvel Package using tools such as FluxCD or ArgoCD. See Deploy Carvel Packages using FluxCD Kustomization.