API Reference

API reference documentation for Porch resources

Packages

porch.kpt.dev/v1alpha1

Condition

Appears in:

Field Description Default Validation
type string
status ConditionStatus
reason string
message string

ConditionStatus

Appears in:

Field Description
True
False
Unknown

Field

Field references a field in a resource

Appears in:

Field Description Default Validation
path string Path is the field path. This field is required.
currentValue string CurrentValue is the current field value
proposedValue string ProposedValue is the proposed value of the field to fix an issue.

File

File references a file containing a resource

Appears in:

Field Description Default Validation
path string Path is relative path to the file containing the resource.
This field is required.
index integer Index is the index into the file containing the resource
(i.e. if there are multiple resources in a single file)

GitLock

GitLock is the resolved locator for a package on Git.

Appears in:

Field Description Default Validation
repo string Repo is the git repository that was fetched.
e.g. ‘ https://github.com/kubernetes/examples.git'
directory string Directory is the sub directory of the git repository that was fetched.
e.g. ‘staging/cockroachdb’
ref string Ref can be a Git branch, tag, or a commit SHA-1 that was fetched.
e.g. ‘master’
commit string Commit is the SHA-1 for the last fetch of the package.
This is set by kpt for bookkeeping purposes.

GitPackage

Appears in:

Field Description Default Validation
repo string Address of the Git repository, for example:
https://github.com/GoogleCloudPlatform/blueprints.git
ref string Ref is the git ref containing the package. Ref can be a branch, tag, or commit SHA.
directory string Directory within the Git repository where the packages are stored. A subdirectory of this directory containing a Kptfile is considered a package.
secretRef SecretRef Reference to secret containing authentication credentials. Optional.

Locator

Locator is a resolved locator for the last fetch of the package.

Appears in:

Field Description Default Validation
type OriginType Type is the type of origin.
git GitLock Git is the resolved locator for a package on Git.

NameMeta

NameMeta contains name information.

Appears in:

Field Description Default Validation
name string Name is the metadata.name field of a Resource
namespace string Namespace is the metadata.namespace field of a Resource

OriginType

Appears in:

PackageCloneTaskSpec

Appears in:

Field Description Default Validation
upstreamRef UpstreamPackage Upstream is the reference to the upstream package to clone.

PackageEditTaskSpec

Appears in:

Field Description Default Validation
sourceRef PackageRevisionRef

PackageInitTaskSpec

PackageInitTaskSpec defines the package initialization task.

Appears in:

Field Description Default Validation
subpackage string Subpackage is a directory path to a subpackage to initialize. If unspecified, the main package will be initialized.
description string Description is a short description of the package.
keywords string array Keywords is a list of keywords describing the package.
site string Site is a link to page with information about the package.

PackageMergeStrategy

Appears in:

Field Description
resource-merge
fast-forward
force-delete-replace
copy-merge

PackageMetadata

Appears in:

Field Description Default Validation
labels object (keys:string, values:string)
annotations object (keys:string, values:string)

PackageRevision

PackageRevision

Appears in:

Field Description Default Validation
spec PackageRevisionSpec
status PackageRevisionStatus

PackageRevisionLifecycle

Appears in:

Field Description
Draft
Proposed
Published
DeletionProposed

PackageRevisionRef

PackageRevisionRef is a reference to a package revision.

Appears in:

Field Description Default Validation
name string Name is the name of the referenced PackageRevision resource.

PackageRevisionResources

PackageRevisionResources

Appears in:

Field Description Default Validation
spec PackageRevisionResourcesSpec
status PackageRevisionResourcesStatus

PackageRevisionResourcesSpec

PackageRevisionResourcesSpec represents resources (as ResourceList serialized as yaml string) of the PackageRevision.

Appears in:

Field Description Default Validation
packageName string PackageName identifies the package in the repository.
workspaceName string WorkspaceName identifies the workspace of the package.
revision integer Revision identifies the version of the package.
repository string RepositoryName is the name of the Repository object containing this package.
resources object (keys:string, values:string) Resources are the content of the package.

PackageRevisionResourcesStatus

PackageRevisionResourcesStatus represents state of the rendered package resources.

Appears in:

Field Description Default Validation
renderStatus RenderStatus RenderStatus contains the result of rendering the package resources.

PackageRevisionSpec

PackageRevisionSpec defines the desired state of PackageRevision

Appears in:

Field Description Default Validation
packageName string PackageName identifies the package in the repository.
repository string RepositoryName is the name of the Repository object containing this package.
workspaceName string WorkspaceName is a short, unique description of the changes contained in this package revision.
revision integer Revision identifies the version of the package.
parent ParentReference Deprecated. Parent references a package that provides resources to us
lifecycle PackageRevisionLifecycle
tasks Task array The task slice holds zero or more tasks that describe the operations
performed on the packagerevision. The are essentially a replayable history
of the packagerevision,
Packagerevisions that were not created in Porch may have an
empty task list.
Packagerevisions created and managed through Porch will always
have either an Init, Edit, or a Clone task as the first entry in their
task list. This represent packagerevisions created from scratch, based
a copy of a different revision in the same package, or a packagerevision
cloned from another package.
Each change to the packagerevision will result in a correspondig
task being added to the list of tasks. It will describe the operation
performed and will have a corresponding entry (commit or layer) in git
or oci.
The task slice describes the history of the packagerevision, so it
is an append only list (We might introduce some kind of compaction in the
future to keep the number of tasks at a reasonable number).
readinessGates ReadinessGate array
packageMetadata PackageMetadata

PackageRevisionStatus

PackageRevisionStatus defines the observed state of PackageRevision

Appears in:

Field Description Default Validation
upstreamLock Locator UpstreamLock identifies the upstream data for this package.
selfLock Locator SelfLock identifies the location of the current package’s data
publishedBy string PublishedBy is the identity of the user who approved the packagerevision.
publishTimestamp Time PublishedAt is the time when the packagerevision were approved.
deployment boolean Deployment is true if this is a deployment package (in a deployment repository).
conditions Condition array

PackageSpec

PackageSpec defines the desired state of Package

Appears in:

Field Description Default Validation
packageName string PackageName identifies the package in the repository.
repository string RepositoryName is the name of the Repository object containing this package.

PackageStatus

PackageStatus defines the observed state of Package

Appears in:

Field Description Default Validation
latestRevision integer LatestRevision identifies the package revision that is the latest
published package revision belonging to this package. Latest is determined by comparing
packages that have valid semantic version as their revision. In case of git backend, branch tracking
revisions like “main” and in case of oci backend, revisions tracking “latest” are not considered during
selection of the latest revision.

PackageUpgradeTaskSpec

Appears in:

Field Description Default Validation
oldUpstreamRef PackageRevisionRef OldUpstream is the reference to the original upstream package revision that is
the common ancestor of the local package and the new upstream package revision.
newUpstreamRef PackageRevisionRef NewUpstream is the reference to the new upstream package revision that the
local package will be upgraded to.
localPackageRevisionRef PackageRevisionRef LocalPackageRevisionRef is the reference to the local package revision that
contains all the local changes on top of the OldUpstream package revision.
strategy PackageMergeStrategy 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.
* fast-forward: Fail without updating if the local package was modified
since it was fetched.
* force-delete-replace: Wipe all the local changes to the package and replace
it with the remote version.
* copy-merge: Copy all the remote changes to the local package.

ParentReference

Deprecated. ParentReference is a reference to a parent package

Appears in:

Field Description Default Validation
name string Name is the name of the parent PackageRevision

PorchPackage

Package

Appears in:

Field Description Default Validation
spec PackageSpec
status PackageStatus

ReadinessGate

Appears in:

Field Description Default Validation
conditionType string

RenderStatus

RenderStatus represents the result of performing render operation on a package resources.

Appears in:

Field Description Default Validation
result ResultList
error string

RepositoryType

Appears in:

Field Description
git
oci

ResourceIdentifier

ResourceIdentifier contains the information needed to uniquely identify a resource in a cluster.

Appears in:

Field Description Default Validation
name string Name is the metadata.name field of a Resource
namespace string Namespace is the metadata.namespace field of a Resource

Result

Result contains the structured result from an individual function

Appears in:

Field Description Default Validation
image string Image is the full name of the image that generates this result
Image and Exec are mutually exclusive
exec string ExecPath is the the absolute os-specific path to the executable file
If user provides an executable file with commands, ExecPath should
contain the entire input string.
stderr string Enable this once test harness supports filepath based assertions.
Pkg is OS specific Absolute path to the package.
Pkg string yaml:"pkg,omitempty"
Stderr is the content in function stderr
exitCode integer ExitCode is the exit code from running the function
results ResultItem array Results is the list of results for the function

ResultItem

ResultItem defines a validation result

Appears in:

Field Description Default Validation
message string Message is a human readable message. This field is required.
severity string Severity is the severity of this result
resourceRef ResourceIdentifier ResourceRef is a reference to a resource.
Required fields: apiVersion, kind, name.
field Field Field is a reference to the field in a resource this result refers to
file File File references a file containing the resource this result refers to
tags object (keys:string, values:string) Tags is an unstructured key value map stored with a result that may be set
by external tools to store and retrieve arbitrary metadata

ResultList

ResultList contains aggregated results from multiple functions

Appears in:

Field Description Default Validation
exitCode integer ExitCode is the exit code of kpt command
items Result array Items contain a list of function result

SecretRef

Appears in:

Field Description Default Validation
name string Name of the secret. The secret is expected to be located in the same namespace as the resource containing the reference.

Task

Appears in:

Field Description Default Validation
type TaskType
init PackageInitTaskSpec
clone PackageCloneTaskSpec
edit PackageEditTaskSpec
upgrade PackageUpgradeTaskSpec

TaskType

Appears in:

Field Description
init
clone
edit
upgrade
render
push
``

UpstreamPackage

UpstreamRepository repository may be specified directly or by referencing another Repository resource.

Appears in:

Field Description Default Validation
type RepositoryType Type of the repository (i.e. git). If empty, upstreamRef will be used.
git GitPackage Git upstream package specification. Required if type is git. Must be unspecified if type is not git.
upstreamRef PackageRevisionRef UpstreamRef is the reference to the package from a registered repository rather than external package.