feat(carvel): emit cross-deployment consumes on runtime config addon job (#666)

## Summary

- Extends the \`job-spec-overlay\` sidecar format with two optional
fields: \`from\` and \`deployment\`
- When set on a \`boshLinkConsumer\` entry, \`generateRuntimeConfigs()\`
now includes the link in the \`registry-data\` addon job's \`consumes:\`
map using the BOSH cross-deployment link resolution schema
- Extracts a \`readJobSpecOverlays()\` helper so overlay-reading is
shared between \`generateBoshReleaseDir()\` and
\`generateRuntimeConfigs()\` rather than duplicated

## Motivation

Tile authors currently have to post-process the built \`.pivotal\` to
inject a \`consumes:\` block into the runtime config addon job after
\`kiln carvel bake\`. This change makes it possible to declare
cross-deployment link resolution natively in the sidecar files,
eliminating the need for that patch step.

## Example overlay

```yaml
consumes:
- name: nats-tls
  type: nats-tls
  optional: false
  from: nats-tls
  deployment: "(( ..cf.deployment_name ))"
- name: binding_cache
  type: binding_cache
  optional: true
  from: binding_cache
  deployment: "(( ..cf.deployment_name ))"
```

Generated runtime config addon job will include:

```yaml
consumes:
  nats-tls:
    from: nats-tls
    deployment: (( ..cf.deployment_name ))
  binding_cache:
    from: binding_cache
    deployment: (( ..cf.deployment_name ))
```

## Test plan

- [ ] \`go test ./internal/carvel/...\` passes (unit + integration
tests)
- [ ] New unit tests: \`jobSpecOverlay\` parses \`from\`/\`deployment\`
fields correctly, including partial presence (only \`from\` set, only
\`deployment\` set)
- [ ] Updated integration test:
\`addon.Jobs[0].Consumes["binding_cache"]\` has expected
\`From\`/\`Deployment\` values in the generated runtime config
- [ ] Entries without \`from\`/\`deployment\` are unaffected (no
\`consumes:\` key emitted)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: drich10

internal/carvel/baker.go

@@ -257,7 +257,7 @@ func (b *baker) progress(message string) {
 
 // deduplicateConsumes removes duplicate BOSH link consumer entries by name.
 // Identical duplicates are dropped silently. If two entries share a name but
-// differ in type or optional, the first is kept and a WARNING is emitted —
+// differ in any field, the first is kept and a WARNING is emitted —
 // BOSH rejects duplicate link names in job.MF, so the second is always ignored.
 func (b *baker) deduplicateConsumes(consumes []boshLinkConsumer) []boshLinkConsumer {
 	seen := make(map[string]boshLinkConsumer)
@@ -272,19 +272,59 @@ func (b *baker) deduplicateConsumes(consumes []boshLinkConsumer) []boshLinkConsu
 		if existing != c {
 			b.progress(fmt.Sprintf(
 				"WARNING: duplicate BOSH link consumer name %q found across packageinstalls.\n"+
-					"  Keeping:  {type: %s, optional: %v}\n"+
-					"  Ignoring: {type: %s, optional: %v}\n"+
+					"  Keeping:  {type: %s, optional: %v, from: %s, deployment: %s}\n"+
+					"  Ignoring: {type: %s, optional: %v, from: %s, deployment: %s}\n"+
 					"  Ensure all packageinstalls agree on the link definition.",
-				c.Name, existing.Type, existing.Optional, c.Type, c.Optional,
+				c.Name,
+				existing.Type, existing.Optional, existing.From, existing.Deployment,
+				c.Type, c.Optional, c.From, c.Deployment,
 			))
 		}
 	}
 	return deduped
 }
 
+// readJobSpecOverlays reads all *.job-spec-overlay.yml sidecars for the tile's
+// package installs and returns the merged slice of boshLinkConsumer entries.
+func (b *baker) readJobSpecOverlays() ([]boshLinkConsumer, error) {
+	var all []boshLinkConsumer
+	for _, entry := range b.metadata.PackageInstalls {
+		entry = strings.Trim(entry, "$() ")
+		entry = strings.TrimPrefix(entry, "package")
+		entry = strings.Trim(entry, `"' `)
+
+		overlayPath := path.Join(b.source, "packageinstalls", entry+".job-spec-overlay.yml")
+		data, err := os.ReadFile(overlayPath)
+		if errors.Is(err, os.ErrNotExist) {
+			continue
+		}
+		if err != nil {
+			return nil, fmt.Errorf("reading %s: %w", overlayPath, err)
+		}
+		var overlay jobSpecOverlay
+		if err := yaml.Unmarshal(data, &overlay); err != nil {
+			return nil, fmt.Errorf("parsing %s: %w", overlayPath, err)
+		}
+		all = append(all, overlay.Consumes...)
+	}
+	return all, nil
+}
+
 // boshLinkConsumer declares a BOSH link the registry-data job should consume.
 // Populated from per-packageinstall *.job-spec-overlay.yml sidecar files.
+// When From or Deployment is set, kiln also emits a cross-deployment consumes
+// entry for the link in the runtime config addon job.
 type boshLinkConsumer struct {
+	Name       string `yaml:"name"`
+	Type       string `yaml:"type"`
+	Optional   bool   `yaml:"optional"`
+	From       string `yaml:"from,omitempty"`
+	Deployment string `yaml:"deployment,omitempty"`
+}
+
+// boshConsumes is the BOSH job spec consumes schema: name, type, and optional only.
+// From/Deployment are runtime-config-only and must not appear in the job spec.
+type boshConsumes struct {
 	Name     string `yaml:"name"`
 	Type     string `yaml:"type"`
 	Optional bool   `yaml:"optional"`
@@ -293,6 +333,8 @@ type boshLinkConsumer struct {
 // jobSpecOverlay is the schema for <entry>.job-spec-overlay.yml sidecar files.
 // kiln reads these from packageinstalls/ and merges the consumes entries into
 // the generated registry-data job.MF alongside the hardcoded cluster-info link.
+// Entries that set from or deployment are also emitted as cross-deployment
+// consumes on the runtime config addon job.
 type jobSpecOverlay struct {
 	Consumes []boshLinkConsumer `yaml:"consumes"`
 }
@@ -355,7 +397,6 @@ files:
 
 	registryDataTemplates := ""
 	registryDataProperties := ""
-	var allConsumes []boshLinkConsumer
 
 	b.progress("  Configuring package installs")
 	for _, entry := range b.metadata.PackageInstalls {
@@ -416,21 +457,6 @@ files:
 			overlayContent = string(overlayData)
 		}
 
-		// Read optional job-spec-overlay sidecar to discover additional BOSH link consumptions.
-		jobSpecOverlayPath := path.Join(b.source, "packageinstalls", entry+".job-spec-overlay.yml")
-		overlayData, overlayErr = os.ReadFile(jobSpecOverlayPath)
-		if overlayErr != nil {
-			if !errors.Is(overlayErr, os.ErrNotExist) {
-				return overlayErr
-			}
-		} else {
-			var overlay jobSpecOverlay
-			if parseErr := yaml.Unmarshal(overlayData, &overlay); parseErr != nil {
-				return fmt.Errorf("parsing %s: %w", jobSpecOverlayPath, parseErr)
-			}
-			allConsumes = append(allConsumes, overlay.Consumes...)
-		}
-
 		manifestTemplate := generateManifestTemplate(entry, overlayContent)
 
 		err = os.WriteFile(
@@ -443,9 +469,17 @@ files:
 		}
 	}
 
+	allConsumes, err := b.readJobSpecOverlays()
+	if err != nil {
+		return err
+	}
 	deduped := b.deduplicateConsumes(allConsumes)
 
-	registryDataSpec, err := buildRegistryDataSpec(registryDataTemplates, registryDataProperties, deduped)
+	boshLinks := make([]boshConsumes, len(deduped))
+	for i, c := range deduped {
+		boshLinks[i] = boshConsumes{Name: c.Name, Type: c.Type, Optional: c.Optional}
+	}
+	registryDataSpec, err := buildRegistryDataSpec(registryDataTemplates, registryDataProperties, boshLinks)
 	if err != nil {
 		return err
 	}
@@ -461,7 +495,7 @@ files:
 // buildRegistryDataSpec constructs the job.MF content for the registry-data BOSH job.
 // It always includes the hardcoded cluster-info link and appends any additional links
 // collected from *.job-spec-overlay.yml sidecars in the packageinstalls/ directory.
-func buildRegistryDataSpec(templates, properties string, additionalLinks []boshLinkConsumer) (string, error) {
+func buildRegistryDataSpec(templates, properties string, additionalLinks []boshConsumes) (string, error) {
 	extraLinks := ""
 	if len(additionalLinks) > 0 {
 		data, err := yaml.Marshal(additionalLinks)
@@ -717,11 +751,30 @@ func (b *baker) generateRuntimeConfigs() error {
 		}
 	}
 
+	allConsumes, err := b.readJobSpecOverlays()
+	if err != nil {
+		return err
+	}
+	deduped := b.deduplicateConsumes(allConsumes)
+
+	consumesMap := make(map[string]models.JobConsumes)
+	for _, c := range deduped {
+		if c.From != "" || c.Deployment != "" {
+			consumesMap[c.Name] = models.JobConsumes{
+				From:       c.From,
+				Deployment: c.Deployment,
+			}
+		}
+	}
+
 	registryDataJob := models.Job{
 		Name:       "registry-data",
 		Release:    b.metadata.Name,
 		Properties: registryDataProps,
 	}
+	if len(consumesMap) > 0 {
+		registryDataJob.Consumes = consumesMap
+	}
 
 	inner := models.RuntimeConfigInner{
 		Releases: []string{

internal/carvel/baker_test.go

@@ -124,7 +124,7 @@ var _ = Describe("Carvel Baker", func() {
 
 	Context("buildRegistryDataSpec", func() {
 		It("includes user-declared additional links after cluster-info", func() {
-			links := []boshLinkConsumer{
+			links := []boshConsumes{
 				{Name: "binding_cache", Type: "binding_cache", Optional: false},
 			}
 			spec, err := buildRegistryDataSpec("", "", links)
@@ -136,7 +136,7 @@ var _ = Describe("Carvel Baker", func() {
 		})
 
 		It("marks optional links correctly", func() {
-			links := []boshLinkConsumer{
+			links := []boshConsumes{
 				{Name: "optional-link", Type: "some-type", Optional: true},
 			}
 			spec, err := buildRegistryDataSpec("", "", links)
@@ -154,7 +154,7 @@ var _ = Describe("Carvel Baker", func() {
 		It("safely encodes link names containing YAML-special characters", func() {
 			// yaml.Marshal quotes/blocks the value so it cannot inject extra YAML keys.
 			// The real type field ("legit-type") must still appear at the correct level.
-			links := []boshLinkConsumer{
+			links := []boshConsumes{
 				{Name: "name: injected\ntype: evil", Type: "legit-type", Optional: false},
 			}
 			spec, err := buildRegistryDataSpec("", "", links)
@@ -163,7 +163,7 @@ var _ = Describe("Carvel Baker", func() {
 		})
 
 		It("emits each unique link name only once given pre-deduplicated input", func() {
-			links := []boshLinkConsumer{
+			links := []boshConsumes{
 				{Name: "binding_cache", Type: "binding_cache", Optional: false},
 			}
 			spec, err := buildRegistryDataSpec("", "", links)
@@ -280,6 +280,55 @@ consumes:
 			err := yaml.Unmarshal([]byte("consumes: [\ninvalid"), &overlay)
 			Expect(err).To(HaveOccurred())
 		})
+
+		It("parses an entry with only from set (no deployment)", func() {
+			content := `
+consumes:
+- name: nats-tls
+  type: nats-tls
+  optional: false
+  from: nats-tls
+`
+			var overlay jobSpecOverlay
+			err := yaml.Unmarshal([]byte(content), &overlay)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(overlay.Consumes[0].From).To(Equal("nats-tls"))
+			Expect(overlay.Consumes[0].Deployment).To(BeEmpty())
+		})
+
+		It("parses an entry with only deployment set (no from)", func() {
+			content := `
+consumes:
+- name: nats-tls
+  type: nats-tls
+  optional: false
+  deployment: "(( ..cf.deployment_name ))"
+`
+			var overlay jobSpecOverlay
+			err := yaml.Unmarshal([]byte(content), &overlay)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(overlay.Consumes[0].From).To(BeEmpty())
+			Expect(overlay.Consumes[0].Deployment).To(Equal("(( ..cf.deployment_name ))"))
+		})
+
+		It("parses from and deployment fields for cross-deployment link resolution", func() {
+			content := `
+consumes:
+- name: nats-tls
+  type: nats-tls
+  optional: false
+  from: nats-tls
+  deployment: "(( ..cf.deployment_name ))"
+`
+			var overlay jobSpecOverlay
+			err := yaml.Unmarshal([]byte(content), &overlay)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(overlay.Consumes).To(HaveLen(1))
+			c := overlay.Consumes[0]
+			Expect(c.Name).To(Equal("nats-tls"))
+			Expect(c.From).To(Equal("nats-tls"))
+			Expect(c.Deployment).To(Equal("(( ..cf.deployment_name ))"))
+		})
 	})
 
 	Context("Bake", func() {
@@ -455,6 +504,12 @@ consumes:
 					props := addon.Jobs[0].Properties["test-install"]
 					Expect(props.Name).To(Equal("something-test.tanzu.vmware.com"))
 					Expect(props.Version).To(Equal("0.1.5"))
+
+					By("emitting cross-deployment consumes from job-spec-overlay from/deployment fields")
+					Expect(addon.Jobs[0].Consumes).To(HaveKey("binding_cache"))
+					bc := addon.Jobs[0].Consumes["binding_cache"]
+					Expect(bc.From).To(Equal("binding_cache"))
+					Expect(bc.Deployment).To(Equal("(( ..cf.deployment_name ))"))
 				})
 				It("can be kiln baked", func() {
 					if !kilnInstalled() {

internal/carvel/models/job.go

@@ -3,5 +3,14 @@ package models
 type Job struct {
 	Name       string                         `yaml:"name"`
 	Release    string                         `yaml:"release"`
+	Consumes   map[string]JobConsumes         `yaml:"consumes,omitempty"`
 	Properties map[string]PackageInstallProps `yaml:"properties,omitempty"`
 }
+
+// JobConsumes declares cross-deployment link resolution for a runtime config addon job.
+// When a job-spec-overlay entry sets from or deployment, kiln includes it in the
+// addon job's consumes map in the generated metadata.
+type JobConsumes struct {
+	From       string `yaml:"from,omitempty"`
+	Deployment string `yaml:"deployment,omitempty"`
+}

internal/carvel/testdata/sample-tile/packageinstalls/test-install.job-spec-overlay.yml

@@ -2,3 +2,5 @@ consumes:
 - name: binding_cache
   type: binding_cache
   optional: false
+  from: binding_cache
+  deployment: "(( ..cf.deployment_name ))"