EPIC: Release a hard revision of the Porch APIs

[liamfallon]

This EPIC covers the activities required to release a hard revision of the Porch APIs.

Porch API rules

1. These rules comply with Kubernetes Versions in CustomResourceDefinitions rules
2. These rules follow the direction set in the Kubernetes document Changing the API
3. The Porch versioning will follow the semantic versioning convention vx. Porch alpha and beta releases will follow the semantic versioning convention vx-alpha.n and vx-beta.n. The first full version would be v1, a beta would v1-beta.24
4. The latest version of the API will always be the "stored" version.
5. The Porch codebase will always import the latest version of the API (Check this, use the unversioned type?)
6. The Porch code that is not webhook code or specific API version code should not import specific versions of the API
7. Supported versions will be served using webhook conversion, that is they will be translated from the "served" version to the "stored" version 'client-->server' and from the "stored" version to the "served" version "server->client"
8. Each time a Kind in either the porch.kpt.dev group is changed, the version of the porch.kpt.dev will be stepped. The Porch API server Kinds are in this group.
9. Each time a Kind in either the config.porch.kpt.dev group is changed, the version of the config.porch.kpt.dev will be stepped. Note that the Repository, PackageVariant, PackageVariantSet, and PackageRev kinds are all in this group.
10. Unversioned API calls are not supported.

Porch APIs

Porch currently has five published APIs.

The Porch API

Group Name: porch.kpt.dev

Types:

• PorchPackage
• PorchPackageList
• PackageRevision
• PackageRevisionList
• PackageRevisionResources
• PackageRevisionResourcesList

Stored in api/porch

Versions:

• v1alpha1: stored and served

Porch Repository CRD

Group Name: config.porch.kpt.dev

Types:

• Repository

Stored in api/porchconfig

Versions:

• v1alpha1: stored and served

PackageVariant CRD

Group Name: config.porch.kpt.dev

Types:

• PackageVariant

Stored in controllers/packagevariants

Versions:

• v1alpha1: stored and served

PackageVariantSet CRD

Group Name: config.porch.kpt.dev

Types:

• PackageVariantSet

Stored in controllers/packagevariantsets

Versions:

• v1alpha1: not stored and not served
• v1alpha2: stored and served

PackageRev CRD

Group Name: config.porch.kpt.dev

Types:

• PackageRev

Stored in internal/api/porchinternal

Versions:

• v1alpha1: stored and served

Tasks

The tasks to achieve this are as follows

• Document that Porch will use Kubernetes processes for API handling such as
• Kubernetes API deprecation Policy
• Deprecated API Migration Guide
• Kubernetes API health endpoints
• Review the current APIs and clean them in a backwardly compatible way, removing parts that are not used
• Document the current APIs, see [BUG]: Nephio Docs do not show PackageRevision and PackageRevisionResources APIs #735
• Release the APIs with a hard version
• Update the code to use the new API version

Subtasks will be created for the task list above if tasks are substantial enough to merit their own subtask.

See also Discussion Cleaning up porch API to move to v1