|
1 | 1 | --- |
2 | | -title: "Concepts" |
| 2 | +title: "Porch Concepts" |
3 | 3 | type: docs |
4 | | -weight: 1 |
| 4 | +weight: 2 |
| 5 | +description: | |
| 6 | + The fundamental topics necessary to understand Porch as "package orchestration" on a conceptual level. |
5 | 7 | --- |
6 | 8 |
|
7 | | -The Concepts section helps you learn about the abstractions Porch uses to store and orchestrate your kpt packages, with |
8 | | -high-level descriptions of the repository management, package orchestration, and package revision lifecycle management |
9 | | -use cases. |
| 9 | +## Core Concepts |
| 10 | + |
| 11 | +This section introduces some core concepts of Porch's package orchestration: |
| 12 | + |
| 13 | +* ***[Package]({{% relref "package" %}})***: A Porch **Package** encapsulates the orchestration of a single [kpt package](https://kpt.dev/book/03-packages/), |
| 14 | + stored in a Git repository. A package may be orchestrated many times, resulting in the creation of many revisions of the |
| 15 | + package, each of which is modelled as a **package revision**. Packages are stored in Git repositories. When you interact |
| 16 | + with Porch via `porchctl` or `kubectl`, you orchestrate revisions of packages, thus working with `PackageRevision` resources |
| 17 | + and not directly with packages. |
| 18 | + |
| 19 | +* ***[Repository]({{% relref "repositories" %}})***: This is a version-control repository used to store package file |
| 20 | +* contents. For example, a [Git](https://git-scm.org/) or (experimentally) [OCI](https://github.com/opencontainers/image-spec/blob/main/spec.md) |
| 21 | + repository. |
| 22 | + |
| 23 | +* ***[Package Revision]({{% relref "package-revisions" %}})***: This is a single version of a package. Many versions of |
| 24 | + a package may exist because Porch allows users to perform multiple orchestrations on a single package. A **Package Revision** |
| 25 | + represents a particular version of a package and tracks the state of its orchestration. |
| 26 | + |
| 27 | +* ***[Lifecycle]({{% relref "package-revision-lifecycle" %}})***: The orchestration of a package revision in Porch has |
| 28 | + a **lifecycle**. The package revision passes through a number of lifecycle stages in its journey towards publication as |
| 29 | + a published package revision (as illustrated below): |
| 30 | + * ***Draft*** - the package revision is being authored (created or edited). The package revision contents can be modified, |
| 31 | + but the package revision is not ready to be used/deployed. |
| 32 | + * ***Proposed*** - the package revision's author has completed the preparation of the package revision and its files and |
| 33 | + has proposed that the package revision be published. |
| 34 | + * ***Published*** - the package revision has been approved and is ready to be used. Published package revisions may be |
| 35 | + deployed. A published package revision may be copied to create a new package revision of the same package, in which |
| 36 | + development of the package may continue. A published package revision may also be cloned to create the first package |
| 37 | + revision of an entirely new package. |
| 38 | + * ***DeletionProposed*** - a user has proposed that this package revision be deleted from the repository. A package revision |
| 39 | + must be proposed for deletion before it can be deleted from Porch. |
| 40 | +  |
| 41 | + |
| 42 | +* ***[Workspace]({{% relref "workspace" %}})***: A **workspace** is the *unique identifier* of a package revision *within* |
| 43 | + a package. It is specified either by the user (when creating a new package revision by initialisation, cloning, or editing) |
| 44 | + or by Porch (when discovering a package revision in a Git repository). For the workspace name, the following rules apply: |
| 45 | + * you can use whatever string you like (e.g., "cell1", "district", "add-a-feature", "delete-me") |
| 46 | + * as long as it is [compliant with DNS name conventions](https://kubernetes.io/docs/concepts/overview/working-with-objects/names#dns-label-names). |
| 47 | + * the workspace name must be unique in its own package |
| 48 | + * the same workspace name can be used on workspaces on other packages, so for two packages called `ran-package` and |
| 49 | + `ev-battery-package` it is legal for both to have a workspace called `cell1` |
| 50 | + * the workspace only has scope within a package, so if the same workspace name appears in two packages, Porch treats |
| 51 | + these as two completely independent package revisions completely independently |
| 52 | + * hence the two `cell1` workspaces above have no intrinsic relationship whatever |
| 53 | + * when Porch discovers package revisions in Git repositories, it takes the branch, tag or SHA, from which it read the |
| 54 | + package revision, as a workspace name for the package revision |
| 55 | + |
| 56 | + The workspace name of a package revision never changes once it is specified, and persists through all lifecycle transitions, |
| 57 | + even when the package revision is approved and is assigned a revision number. |
| 58 | + |
| 59 | +* ***[Revision numbering]({{% relref "package-revisions#published-package-revision-numbering" %}})***: A **Revision** |
| 60 | + number on a package revision identifies the order in which package revisions of a package were published. When a |
| 61 | + PackageRevision is approved and moves to the Published lifecycle stage, it is assigned a Revision one higher than the |
| 62 | + highest existing Revision. |
| 63 | + |
| 64 | + The following rules apply: |
| 65 | + * a package revision in the Published or DeletionProposed lifecycle stage has a Revision > `0` |
| 66 | + * a package revision in the Draft or Proposed lifecycle stage has a Revision == `0` |
| 67 | + * for discovered package revisions in Git, Porch uses naming conventions to determine the appropriate Revision. If |
| 68 | + Porch cannot determine the Revision of an upstream package revision, it sets the Revision to `-1` |
| 69 | + * *placeholder package revisions* (see below) have a revision of `-1` |
| 70 | + |
| 71 | + Notes: |
| 72 | + * Porch uses the workspace name and not the Revision of a package revision to uniquely identify the package revision |
| 73 | + * the Revision of a package revision is not unique because all Draft package revisions have a Revision of `0` |
| 74 | + * there is no relationship between the workspace name and the Revision of a package revision. For example, even if a |
| 75 | + package revision is created with its workspace name given a value of "V2", it could very well end up with a Revision |
| 76 | + of `4` once published |
| 77 | + |
| 78 | +* ***Placeholder package revision***: A dummy package revision reference that points at a package's latest package revision. |
| 79 | + The placeholder package revision is created by Porch simultaneously with the first package revision for a particular |
| 80 | + package. Each time a new package revision is published on the package, the placeholder package revision is updated (actually |
| 81 | + deleted and recreated). |
| 82 | + |
| 83 | + The following rules apply: |
| 84 | + * there is always at most one placeholder package revision for a package |
| 85 | + * it always has a revision number of `-1` |
| 86 | + * its workspace name is always the branch in the Git repository on which the package revision exists - usually (though |
| 87 | + not always) `main` |
| 88 | + * its naming comvention is `{repository-name}.{package-name}.{branch-name}`, where {branch-name} is the branch in Git |
| 89 | + on which the package revision exists |
| 90 | + |
| 91 | +* ***[Upstream and Downstream]({{% relref "upstream-downstream" %}})***: source-and-derivation relationships between |
| 92 | + package revisions. When a package revision is cloned, it becomes the **upstream** (source) in its relationship to the |
| 93 | + newly-created **downstream** (derived) package revision(s). Downstream package revisions maintain a link to their upstream |
| 94 | + source package revision and can be upgraded when new versions of the upstream package revision are published. |
| 95 | + |
| 96 | +* ***[Functions]({{% relref "functions" %}})***: Specifically, [KRM functions](https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md). |
| 97 | + Functions can be added to a package's [kptfile pipeline](https://kpt.dev/book/04-using-functions/#declarative-function-execution) |
| 98 | + in the course of modifying a package revision in *Draft* state. When a user updates or proposes a package revision, Porch |
| 99 | + automatically calls kpt to run the pipeline on the package contents, mutating and validating the KRM resource files. |
| 100 | + |
| 101 | +* ***[Package Variant]({{% relref "package-variant" %}})*** and ***Package Variant Set***: These Kubernetes objects represent |
| 102 | + higher levels of package revision automation. Package variants can be used to automatically track an upstream package |
| 103 | + revision and manage cloning it to one or several downstream package revisions, as well as preparing new downstream package |
| 104 | + revisions when a new revision of the upstream package revision is published. Package variant sets enable the same behaviour |
| 105 | + for package variants themselves. |
| 106 | + |
| 107 | +## Additional Terms |
| 108 | + |
| 109 | +* ***Configuration as Data (CaD)***: The architectural approach that Porch implements. [CaD](https://cloud.google.com/blog/products/containers-kubernetes/understanding-configuration-as-data-in-kubernetes) |
| 110 | + treats configuration with the same rigour as application code: configuration data is the source of truth (stored separately |
| 111 | + from live state), uses a uniform serialisable data model (KRM YAML), separates data from code that acts on it (functions |
| 112 | + transform, controllers apply), and abstracts storage from operations (clients use APIs, not direct Git/OCI access). Key |
| 113 | + principles include decoupling abstractions from data, separating actuation from processing, and preferring transformation |
| 114 | + over generation. |
| 115 | + |
| 116 | +* ***Deployment repository***: A repository can be designated as a deployment repository (via `spec.deployment: true`). |
| 117 | + Package revisions in *Published* state in a deployment repository are considered deployment-ready and can be consumed |
| 118 | + by GitOps tools like Flux or Config Sync. See [Repositories]({{% relref "repositories#deployment-vs-blueprint-repositories" %}}) |
| 119 | + for details. |
0 commit comments