vcf-services

Authoring Supervisor Services

Supervisor Services are powered by the Carvel packaging standard. To support automated reconciliation, Supervisor Services must be packaged using the Carvel toolset. This guide defines the technical “contract” your service must meet to be compatible with the Supervisor platform.

The Final Deliverable

To submit a service, you must provide a single YAML document and a pushed OCI bundle.

• OCI Bundle – A registry-hosted OCI bundle containing all manifests and image references.
• Single YAML document – One manifest containing both PackageMetadata (catalog data: name, display name, description, categories) and Package (installer data: version, bundle reference, and configuration schema).

Step 1: Create the imgpkg Bundle

An imgpkg bundle is an OCI image that holds your configuration files. The Supervisor uses this to ensure “What You Push is What You Deploy.”

Expected Bundle Layout

While you can customize your internal directory names, the following is the standard convention:

.
├── .imgpkg/
│   └── images.yml          # REQUIRED: Generated by kbld
└── config/                 # Your Kubernetes manifests & ytt templates

Key Requirement: The Lockfile

The Supervisor requires an immutable deployment. You must include a .imgpkg/images.yml file. This ensures that even if a mutable tag (like :latest) is updated in the registry, your service remains pinned to the specific digest you tested.

Tooling tip: Use kbld to generate this automatically. Refer to the imgpkg Basic Workflow for command-line examples.

---

Step 2: Define the Package Metadata

The PackageMetadata resource defines how your service appears in the Supervisor Service catalog.

• metadata.name – The main service identifier: a stable, unique, fully qualified name for the service (e.g. my-service.example.com). It must match the spec.refName of every Package that ships a version of this service, and it is what admins see referenced in the Service Catalog and APIs.
• spec.displayName – The human-readable name shown in the Service Catalog (e.g. "My Service").
• spec.shortDescription – A one-line summary used in catalog listings.
• spec.longDescription – A longer description shown on the service detail page.
• spec.providerName – The organization that publishes the service (e.g. "Example Inc.").
• spec.categories – Optional list of category tags used for filtering in the catalog.

For the full PackageMetadata CR specification, see the Carvel packaging docs.

---

Step 3: Define the Package (The Installer)

The Package resource tells the Supervisor how to actually deploy your code.

The Fetch & Template Contract

Your Package must define a template section that follows this flow:

1. Fetch – Pulls your imgpkg bundle.
2. Template – Processes your manifests using ytt and resolves image digests using kbld.
3. Deploy – Applies the result via kapp.

Simplified snippet of the contract:

template:
  spec:
    fetch:
      - imgpkgBundle:
          image: <your-registry-url>/bundle@sha256:...
    template:
      - ytt:
          paths: ["config/"]
      - kbld:
          paths: ["-", ".imgpkg/images.yml"]
    deploy:
      - kapp: {}

For the full Package CR specification, see the Carvel packaging docs.

---

References

• Carvel – ytt, kbld, imgpkg, kapp
• Carvel packaging (Package & PackageMetadata)
• imgpkg Basic Workflow

This site is open source. Improve this page.