kptdev · liamfallon · May 13, 2026 · May 7, 2026 · May 7, 2026 · May 7, 2026
diff --git a/api/generated/openapi/zz_generated.openapi.go b/api/generated/openapi/zz_generated.openapi.go
diff --git a/api/porch/types.go b/api/porch/types.go
@@ -209,6 +209,10 @@ type PackageInitTaskSpec struct {
 type PackageCloneTaskSpec struct {
 	// `Upstream` is the reference to the upstream package to clone.
 	Upstream UpstreamPackage `json:"upstreamRef,omitempty"`
+
+	// `SubpackageDir` is the path to a subdirectory in an existing package revision
+	// into which `Upstream` will be cloned as an independent subpackage.
+	SubpackageDir string `json:"subpackageDir,omitempty"`
 }
 
 type PackageMergeStrategy string
@@ -226,6 +230,10 @@ type PackageUpgradeTaskSpec struct {
 	// contains all the local changes on top of the `OldUpstream` package revision.
 	LocalPackageRevisionRef PackageRevisionRef `json:"localPackageRevisionRef,omitempty"`
 
+	// `SubpackageDir` is the path to a subdirectory that contains an independent
+	// subpackage that is to be upgraded.
+	SubpackageDir string `json:"subpackageDir,omitempty"`
+
 	// 	Defines which strategy should be used to update the package. It defaults to 'resource-merge'.
 	//  * resource-merge: Perform a structural comparison of the original /
 	//    updated resources, and merge the changes into the local package.

diff --git a/api/porch/v1alpha1/types.go b/api/porch/v1alpha1/types.go
@@ -209,6 +209,10 @@ type PackageInitTaskSpec struct {
 type PackageCloneTaskSpec struct {
 	// `Upstream` is the reference to the upstream package to clone.
 	Upstream UpstreamPackage `json:"upstreamRef,omitempty"`
+
+	// `SubpackageDir` is the path to a subdirectory in an existing package revision
+	// into which `Upstream` will be cloned as an independent subpackage.
+	SubpackageDir string `json:"subpackageDir,omitempty"`
 }
 
 type PackageMergeStrategy string
@@ -226,6 +230,10 @@ type PackageUpgradeTaskSpec struct {
 	// contains all the local changes on top of the `OldUpstream` package revision.
 	LocalPackageRevisionRef PackageRevisionRef `json:"localPackageRevisionRef,omitempty"`
 
+	// `SubpackageDir` is the path to a subdirectory in the package revision that contains
+	// an independent subpackage that is to be upgraded.
+	SubpackageDir string `json:"subpackageDir,omitempty"`
+
 	// 	Defines which strategy should be used to update the package. It defaults to 'resource-merge'.
 	//  * resource-merge: Perform a structural comparison of the original /
 	//    updated resources, and merge the changes into the local package.

diff --git a/api/porch/v1alpha1/zz_generated.conversion.go b/api/porch/v1alpha1/zz_generated.conversion.go
diff --git a/api/porch/v1alpha2/packagerevision_types.go b/api/porch/v1alpha2/packagerevision_types.go
@@ -204,16 +204,19 @@ type PackageRevisionStatus struct {
 
 // PackageSource specifies how a package was created.
 // Exactly one field must be set.
-// +kubebuilder:validation:XValidation:rule="[has(self.init), has(self.cloneFrom), has(self.copyFrom), has(self.upgrade)].filter(x, x).size() == 1",message="exactly one of init, cloneFrom, copyFrom, or upgrade must be set"
+// +kubebuilder:validation:XValidation:rule="[has(self.init), has(self.clone), has(self.copy), has(self.upgrade)].filter(x, x).size() == 1",message="exactly one of init, clone, copy, or upgrade must be set"
+// +kubebuilder:validation:XValidation:rule="!has(self.clone) || has(self.clone.cloneFrom)",message="clone.cloneFrom must be set when clone is specified"
+// +kubebuilder:validation:XValidation:rule="!has(self.clone) || has(self.clone.cloneFrom.upstreamRef) || has(self.clone.cloneFrom.git)",message="clone.cloneFrom must specify either upstreamRef or git when clone is specified"
+// +kubebuilder:validation:XValidation:rule="!has(self.clone) || (has(self.clone.cloneFrom.upstreamRef) && !has(self.clone.cloneFrom.git)) || (!has(self.clone.cloneFrom.upstreamRef) && has(self.clone.cloneFrom.git))",message="clone.cloneFrom must specify exactly one of upstreamRef or git when clone is specified"
 type PackageSource struct {
 	// Init creates a brand new package from scratch.
 	Init *PackageInitSpec `json:"init,omitempty"`
 
-	// CloneFrom copies a package from an upstream source (first time).
-	CloneFrom *UpstreamPackage `json:"cloneFrom,omitempty"`
+	// Clone copies a package from an upstream source (first time).
+	Clone *PackageCloneSpec `json:"clone,omitempty"`
 
-	// CopyFrom creates a new revision from an existing package in the same repository.
-	CopyFrom *PackageRevisionRef `json:"copyFrom,omitempty"`
+	// Copy creates a new revision from an existing package in the same repository.
+	Copy *PackageRevisionRef `json:"copy,omitempty"`
 
 	// Upgrade merges changes from a new upstream version into a local package.
 	Upgrade *PackageUpgradeSpec `json:"upgrade,omitempty"`

diff --git a/api/porch/v1alpha2/porch.kpt.dev_packagerevisions.yaml b/api/porch/v1alpha2/porch.kpt.dev_packagerevisions.yaml
@@ -126,60 +126,69 @@ spec:
                   For packages discovered from git (existed before Porch), Source will be nil.
                   This field is immutable after creation.
                 properties:
-                  cloneFrom:
-                    description: CloneFrom copies a package from an upstream source
-                      (first time).
+                  clone:
+                    description: Clone copies a package from an upstream source (first
+                      time).
                     properties:
-                      git:
-                        description: Git upstream package specification. Required
-                          if type is git.
+                      cloneFrom:
+                        description: '`cloneFrom` is the upstream package to clone.'
                         properties:
-                          directory:
-                            description: Directory within the Git repository where
-                              the packages are stored.
-                            type: string
-                          ref:
-                            description: Ref is the git ref containing the package.
-                              Ref can be a branch, tag, or commit SHA.
-                            type: string
-                          repo:
-                            description: |-
-                              Repo is the address of the Git repository, for example:
-                              https://github.com/GoogleCloudPlatform/blueprints.git
+                          git:
+                            description: Git upstream package specification. Required
+                              if type is git.
+                            properties:
+                              directory:
+                                description: Directory within the Git repository where
+                                  the packages are stored.
+                                type: string
+                              ref:
+                                description: Ref is the git ref containing the package.
+                                  Ref can be a branch, tag, or commit SHA.
+                                type: string
+                              repo:
+                                description: |-
+                                  Repo is the address of the Git repository, for example:
+                                  https://github.com/GoogleCloudPlatform/blueprints.git
+                                type: string
+                              secretRef:
+                                description: SecretRef is a reference to secret containing
+                                  authentication credentials.
+                                properties:
+                                  name:
+                                    type: string
+                                required:
+                                - name
+                                type: object
+                            required:
+                            - directory
+                            - ref
+                            - repo
+                            type: object
+                          type:
+                            description: Type of the repository (i.e. git). If empty,
+                              upstreamRef will be used.
+                            enum:
+                            - git
                             type: string
-                          secretRef:
-                            description: SecretRef is a reference to secret containing
-                              authentication credentials.
+                          upstreamRef:
+                            description: UpstreamRef is the reference to the package
+                              from a registered repository.
                             properties:
                               name:
                                 type: string
                             required:
                             - name
                             type: object
-                        required:
-                        - directory
-                        - ref
-                        - repo
                         type: object
-                      type:
-                        description: Type of the repository (i.e. git). If empty,
-                          upstreamRef will be used.
-                        enum:
-                        - git
+                      subpackageDir:
+                        description: |-
+                          `SubpackageDir` is the path to a subdirectory in an existing package revision
+                          into which `CloneFrom` will be cloned as an independent subpackage.
                         type: string
-                      upstreamRef:
-                        description: UpstreamRef is the reference to the package from
-                          a registered repository.
-                        properties:
-                          name:
-                            type: string
-                        required:
-                        - name
-                        type: object
                     type: object
-                  copyFrom:
-                    description: CopyFrom creates a new revision from an existing
-                      package in the same repository.
+                  copy:
+                    description: Copy creates a new revision from an existing package
+                      in the same repository.
                     properties:
                       name:
                         type: string
@@ -253,13 +262,28 @@ spec:
                         - force-delete-replace
                         - copy-merge
                         type: string
+                      subpackageDir:
+                        description: |-
+                          `SubpackageDir` is the path to a subdirectory that contains an independent
+                          subpackage that is to be upgraded.
+                        type: string
                     type: object
                 type: object
                 x-kubernetes-validations:
-                - message: exactly one of init, cloneFrom, copyFrom, or upgrade must
-                    be set
-                  rule: '[has(self.init), has(self.cloneFrom), has(self.copyFrom),
-                    has(self.upgrade)].filter(x, x).size() == 1'
+                - message: exactly one of init, clone, copy, or upgrade must be set
+                  rule: '[has(self.init), has(self.clone), has(self.copy), has(self.upgrade)].filter(x,
+                    x).size() == 1'
+                - message: clone.cloneFrom must be set when clone is specified
+                  rule: '!has(self.clone) || has(self.clone.cloneFrom)'
+                - message: clone.cloneFrom must specify either upstreamRef or git
+                    when clone is specified
+                  rule: '!has(self.clone) || has(self.clone.cloneFrom.upstreamRef)
+                    || has(self.clone.cloneFrom.git)'
+                - message: clone.cloneFrom must specify exactly one of upstreamRef
+                    or git when clone is specified
+                  rule: '!has(self.clone) || (has(self.clone.cloneFrom.upstreamRef)
+                    && !has(self.clone.cloneFrom.git)) || (!has(self.clone.cloneFrom.upstreamRef)
+                    && has(self.clone.cloneFrom.git))'
               workspaceName:
                 description: WorkspaceName is a short, unique description of the changes
                   contained in this package revision.

diff --git a/api/porch/v1alpha2/source_types.go b/api/porch/v1alpha2/source_types.go
@@ -15,8 +15,8 @@
 package v1alpha2
 
 // Package creation source specifications.
-// In v1alpha2, the creation source is specified directly via PackageSource fields.
-// Exactly one of Init, CloneFrom, CopyFrom, or Upgrade must be set when creating a PackageRevision.
+// In v1alpha2, the creation source is specified directly using PackageSource fields.
+// Exactly one of Init, Clone, Copy, or Upgrade must be set when creating a PackageRevision.
 // These fields are immutable after creation.
 
 // PackageInitSpec defines the package initialization parameters.
@@ -30,6 +30,17 @@ type PackageInitSpec struct {
 	Site string `json:"site,omitempty"`
 }
 
+// PackageCloneSpec defines the package clone parameters.
+// Used when creating a new package by cloning it from an existing package revision.
+type PackageCloneSpec struct {
+	// `cloneFrom` is the upstream package to clone.
+	CloneFrom *UpstreamPackage `json:"cloneFrom,omitempty"`
+
+	// `SubpackageDir` is the path to a subdirectory in an existing package revision
+	// into which `CloneFrom` will be cloned as an independent subpackage.
+	SubpackageDir string `json:"subpackageDir,omitempty"`
+}
+
 // PackageUpgradeSpec defines the package upgrade parameters.
 // Used when merging changes from a new upstream version into a local package.
 type PackageUpgradeSpec struct {
@@ -45,6 +56,10 @@ type PackageUpgradeSpec struct {
 	// contains all the local changes on top of the OldUpstream package revision.
 	CurrentPackage PackageRevisionRef `json:"currentPackage,omitempty"`
 
+	// `SubpackageDir` is the path to a subdirectory that contains an independent
+	// subpackage that is to be upgraded.
+	SubpackageDir string `json:"subpackageDir,omitempty"`
+
 	// Strategy defines which strategy should be used to update the package. It defaults to 'resource-merge'.
 	//  * resource-merge: Perform a structural comparison of the original /
 	//    updated resources, and merge the changes into the local package.

diff --git a/api/porch/v1alpha2/util.go b/api/porch/v1alpha2/util.go
@@ -48,5 +48,5 @@ func IsPackageCreation(pkgRev *PackageRevision) bool {
 	if pkgRev.Spec.Source == nil {
 		return false
 	}
-	return pkgRev.Spec.Source.Init != nil || pkgRev.Spec.Source.CloneFrom != nil
+	return pkgRev.Spec.Source.Init != nil || pkgRev.Spec.Source.Clone != nil
 }
diff --git a/api/porch/v1alpha2/util_test.go b/api/porch/v1alpha2/util_test.go
@@ -120,8 +120,8 @@ func TestIsPackageCreation(t *testing.T) {
 	}{
 		{name: "nil source", source: nil, expected: false},
 		{name: "init", source: &PackageSource{Init: &PackageInitSpec{}}, expected: true},
-		{name: "clone", source: &PackageSource{CloneFrom: &UpstreamPackage{}}, expected: true},
-		{name: "copy", source: &PackageSource{CopyFrom: &PackageRevisionRef{}}, expected: false},
+		{name: "clone", source: &PackageSource{Clone: &PackageCloneSpec{}}, expected: true},
+		{name: "copy", source: &PackageSource{Copy: &PackageRevisionRef{}}, expected: false},
 		{name: "upgrade", source: &PackageSource{Upgrade: &PackageUpgradeSpec{}}, expected: false},
 	}
 

diff --git a/api/porch/v1alpha2/zz_generated.deepcopy.go b/api/porch/v1alpha2/zz_generated.deepcopy.go