/
Porch Documentation Refactoring

Porch Documentation Refactoring

See https://github.com/nephio-project/nephio/issues/902

Suggested Layout & Changes Required

The Kubernetes documentation follows a table of contents detailed in the below section. taking this template and adapting it to the porch code base/documentation we get the following.

  1. The different sections required to be covered following the Kubernetes documentation.

  2. The currently available documentation relating to this section available now on https://docs.nephio.org/docs/porch/.

  3. The gaps/missing sections not found in the current documentation but required in the rework.

Sections marked as [Section in Green] means they have been reviewed and marked as necessary to be included in the new documentation.

Sections marked as [Section in Red] means they have not been reviewed but could still be placed in the docs in the given location once they are. TLDR its a topic of interest to be looked at just not signed off on yet as as a mandatory addition.

Table of Contents

  1. Overview

  2. Concepts

  3. Getting Started

  4. Tutorials & How‑to's

  5. Architecture & Components

  6. Configuration & Deployment

  7. CLI / API / Reference

  8. Best Practices & Patterns

  9. Troubleshooting & FAQ

  10. Security & Compliance

  11. Glossary

  12. Contributing

  13. Release Notes / Change-log

1. Overview

Section Must Contain:

  • What is Porch
      • Short description (“Porch = package orchestration, opinionated package management …”) (Porch already has this under Overview). (https://docs.nephio.org/docs/porch/ )

  • Goals & scope (what Porch intends to do, what it does not do)

  • Audiences: which users should care (operators, GitOps engineers, developers, integrators, etc.)

  • Prerequisites / compatibility (Kubernetes versions, environments, permissions, dependencies)

Currently Available Resources:

Gaps / additions Required:

  • Statement of goals & scope (what Porch intends to do / NOT do).

  • Target audiences (operators, developers, integrators).

  • Supported environments / prerequisites summary.

  • CONTENT HERE PENDING

  • CLARIFY WHAT PORCH IS!

  • ORCHESTRATION SERVICE FOR KPT PACKAGES

  • I WOULD SUGGEST SOMEONE WHO KNOWS THINGS VERY LOW LEVEL AND SOMEONE TO SUMMARIZE IT

  • ITS USED TO COMPOSE / CUSTOMIZE AND DEPLOY KPT PACKAGES INTO WORKLOADS FROM KPT PACKAGES, CUSTOMIZE THOSE WORKLOADS, AND DEPLOY THOSE WORKLOADS

  • THERE WOULD LIKELY BE LINKS TO KPT SECTIONS!

2. Concepts

Section Must Contain:

  • Key terminology (package, variant, mutation pipeline, function runner, etc.)

  • Core models/entities: what Porch works with (packages, modules, variants, pipelines).

  • High‑level flow / lifecycle: how a package moves through Porch (creation → mutation → deployment or consumption)

  • Relationships to other Nephio components / external systems (Git repos, registries, etc.)

Currently Available Resources:

Gaps / additions Required:

  • Central glossary of key terms

  • Visual lifecycle diagram of a package

  • Mapping of Porch functions vs Nephio components

  • [PACKAGE-ORCHESTRATION] https://docs.nephio.org/docs/porch/package-orchestration/ ← A LOT OF GREAT REUSABLE CONTENT HERE FOR THIS SECTION. THIS SECTION CAN BE OUR HIGH LEVEL INTRODUCTION OF THE ENTIRE PROJECT BEFORE DIVING DEEPER INTO THE DETAILS IN THE LATER SECTIONS BELOW.

  • [MODIFYING-PORCH-PACKAGES] MUTATORS VS VALIDATORS

  • [REVISION/VERSION] Explain what the revision of a package revision is.

  • [LIFECYCLE] DRAFT PROPOSED PUBLISHED PROPOSED-DELETE Explain what the lifecycle of a package is.

  • [LATEST] Explain the "latest" field works, and how it relates to the "latest" annotation

  • [REPOSITORIES] GIT repo short hand explanation.
    [WORKSPACE/(REVISION IDENTIFIER)] Explain what a workspace is****, see https://github.com/nephio-project/nephio/issues/831

  • [UPSTREAM VS DOWNSTREAM] VS Explain the behavior of packages which contain embedded packages https://github.com/nephio-project/nephio/discussions/917 (LIKELY KPT CONCEPT LINK)

  • [EXPLAIN UPSTREAM AT A HIGH LEVEL HERE BEFORE GOING IN DETAIL]

  • [UPGRADE AT A HIGH LEVEL] PORCH SUPPORTS UPGRADE ALLOWING A USER TO CHANGE WORKLOADS AND HAS VARIOUS STRATEGIES FOR ACHIEVING THIS.

  • [porch pkg which is a kpt pkg ] likely with pointer to kpt docs

  • [link to a kpt file defenition because link kpt docs]

  • potentially a shared element to stop from context switching

3. Getting Started

Section Must Contain:

  • Install Porch: requirements, supported platforms/environments, step‑by‑step install. Porch already has Installing Porch.

  • Environment preparation: what users need locally, or on a cluster. (Porch has Preparing the Environment.)

  • First example / quick start: minimal working example (e.g. a package, mutate, deploy)

  • Using the Porch CLI / basic commands. Porch has Using the Porch CLI tool.

Currently Available Resources:

Gaps / additions Required:

  • End-to-end quickstart walkthrough

  • Output examples (logs/screenshots)

  • Supported platforms/environment matrix

PENDING CONTENT HERE

  • Requirements page likely needed kubectl, kind, (for porch to function)

  • Then after prerequisites can just run a script Installing Porch needs quick version e.g. script containing (./scripts/setup-dev-env.sh + make run-in-kind) ideally.

  • as part of the documentation someone should put together a script containing a deployment of porch. (find a willing participant who knows k8s but not porch to try follow the install script way of deployment) partly done here https://docs.nephio.org/docs/porch/contributors-guide/environment-setup/

  • simple tutorial describing first use of porch at high level e.g. init a pkg , pull it down, add a simple kpt mutator to it → push it → propose and approve it.

  • use the tutorial to explain in one sentance what an init does what a pull does etc and use it to also show how to do that command e.g. https://docs.nephio.org/docs/porch/contributors-guide/environment-setup/

4. Tutorials & How‑to's

Section Must Contain:

  • Common tasks with step‑by‑step instructions:

    • Authenticating with remote Git repositories.

    • Using private registries.

    • Running Porch in different environments (cloud, on‑prem, VMs).

  • Advanced how‑tos: customizing the mutation pipeline, variant selection, function runner templating, etc.

Currently Available Resources:

  • Authenticating with remote Git

  • Using authenticated private registries

  • Running Porch on GKE

  • Mutation pipeline & function runner content (under Concepts)

Gaps / additions Required:

  • Complete end-to-end sample with full mutation + deployment

  • Real-world examples (multi-repo setups)

  • CI/CD testing integration

  • [EXPECT EXAMPLE SCRIPT HAVING DEPLOYED PORCH FOR THEM AS A FIRST TIME USER] e.g. ./scripts/setup-dev-env.sh + make run-in-kind

  • in the tutorials there will need to be clarity of the changes in git that are happening.

  • [STEP 1: SETUP PORCH REPOSITORIES RESOURCE] LIKELY FIRST STEP FROM A DEPLOYMENT OF PORCH TO USE IT

  • [FLOWCHART EXPLAINING FLOW E2E] init → pull → locally do changes → push → proposed → approved/rejected → if rejected changes required then re proposed → if approved → becomes published/latest → A good flowchart of the different states of packages would be good possibly using https://graphviz.org/gallery/ to use diagrams as code as to make them more update-able (BIGGEST ISSUE WITH DIAGRAMS IN DOCS IS KEEPING THEM UPDATED) [diagrams as code could alleviate this a bit]

  • [CREATING FIRST PACKAGE] INIT HOLLOW PKG -> PULL PKG LOCALLY FROM REPO -> MODIFY LOCALLY -> PUSH TO UPSTREAM -> PROPOSE FOR APPROVAL -> APPROVE TO UPSTREAM REPO.

  • [GET/LIST EXAMPLES] [FOR EACH: PORCHCTL EXAMPLE + KUBECTL ALTERNATIVE]

    • [LIST ALL PACKAGE REVISIONS]

    • [GET SPECIFIC PACKAGE REVISION]

    • [LIST WITH FILTER]

      • [LABEL SELECTOR] --selector

      • [FIELD SELECTOR] --field-selector

  • WE WILL NEED TEST PACKAGES FOR THESE USE CASES (possibly leverage test packages from kpt examples)

  • [cloning an upstream package] deploy without any changes

    • [cloning an upstream] with changes.

    • ADD & Delete type changes at both file level(lines in a file getting added and removed) and also package level(files getting added and removed)

  • [copy examples]

    • detailed different examples here

  • [UPGRADE EXAMPLES] [ALL THE DIFF SCENARIOS] [THIS IS THE MOST COMPLEX PART] [IT NEEDS TO BE VERY SPECIFIC ON WHAT DO/DONT WE SUPPORT] []

    • [CREATE A GENERIC PACKAGE AND RUN IT THROUGH THE DIFFERENT UPGRADES TO SHOW HOW THEY WORK AND CHANGE]

    • in upgrade scenario we expect that we have NEW BLUEPRINT IS PUBLISHED → DEPLOYMENT PACKAGE CAN BE UPGRADED IF IT WAS BASED ON THAT BLUEPRINT (AKA THE UPSTREAM OF THIS PACKAGE POINTS AT THAT BLUEPRINT). assuming 2 repositories

    • [RESOURCE MERGE] IS A STRUCTURAL 3 WAY MERGE → HAS CONTEXT OF THE STRUCTURE OF THE FILES ->

    • [COPY MERGE] IS A FILE REPLACEMENT STRATEGY → USEFUL WHEN YOU DONT NEED PORCH TO BE AWARE OF THE CONTENT OF THE FILES ESPECIALLY IF THERE IS CONTENT INSIDE THE FILES THAT DO NOT COMPLY WITH KUSTOMIZE.

      • [OTHER STRATEGIES] …

5. Architecture & Components

Section Must Contain:

  • Overall architecture diagram

  • Main components/modules of Porch (controllers, function runner, variant controller, etc.)

  • Data flow and interaction: how packages move through system, lifecycle events, error paths, etc.

  • Dependencies: e.g. what external services Porch relies on (Git, registry, Kubernetes APIs)

Currently Available Resources:

  • Porch in the Nephio Architecture

  • Individual component pages: Function Runner, Variant Controller, etc.

Gaps / additions Required:

  • Single consolidated diagram of Porch system

  • Component interaction maps

  • Package lifecycle description and flow diagram

  • [PORCH-SERVER] PORCH SERVER SPECIFIC MAIN CHUNK FOR DETAIL HERE

    • [AGGREGATED API SERVER] HOW CERTAIN PORCH RESOURCES ARE SERVED AND HANDLED AKA NOT THROUGH CRDS BUT AGGR API

    • [REPO SYNC] ENSURES LOCAL DB/CR CACHE AND UPSTREAM REPO’S ARE KEPT IN SYNC

  • [ENGINE] MAIN BRAIN/LOGIC USED IN PROCESSING PACKAGES

    • [CACHE SYSTEM]

      • [DB-CACHE] EXPLAIN DIFFERENCE IN OPERATION COMPARED TO OTHER (E.G. DB DOESNT PUSH TO REPO UNTIL APPROVED)

      • [CR-CACHE] EXPLAIN DIFFERENCE IN OPERATION COMPARED TO OTHER

  • [FUNCTION-RUNNER] MAIN CHUNK OF DETAIL REGARDING THIS HERE

  • [CONTROLLERS] MAIN CHUNK OF DETAIL REGARDING THIS HERE

  • [GIT-REPO] MAIN CHUNK OF DETAIL REGARDING THIS HERE

    • [DEPLOYMENT VS NON DEPLOYMENT REPO] EXPLAIN WHAT THAT MEANS

      • [4 WAYS PKG REV COMES INTO EXISTENCE], [UPSTREAM IS THE SOURCE OF THE CLONE]

      • [CREATED USING RPKG INIT/API] , [IN THE CASE THERE IS NO UPSTREAM]

      • [COPY FROM ANOTHER REV IN THE SAME PKG] ,[NO UPSTREAM?]

      • [CAN BE CLONED FROM ANOTHER PKG REV A NEW] [HAS UPSTREAM]

      • [CAN BE LOADED FROM GIT] [DEPENDS ON WEATHER IT HAD A HAD A CLONE SOURCE OR NOT AT THE TIME]

    • [UPSTREAM] EXPLAIN PORCH INTERACTION WITH UPSTREAM REPO'S

    • [DOWNSTREAM] EXPLAIN PORCH INTERACTION WITH DOWNSTREAM REPO'S

  • [PORCH-SPECIFIC-RESOURCES] SUMMARY OF MAIN RESOURCES E.G. PACKAGE-REVISIONS.

    • [PACKAGE-REVISION] MORE DETAIL HERE (have a more in depth analysis)

    • [PACKAGE-REVISION-RESOURCES] this resource is a representation of the content of the files inside the porch package revision.

    • [PACKAGE-REV] core of the cr cache where a packagereivison’s metadata in a kubernetes custom resource for caching purposes. check with kushal/liam

    • [REPOSITORIES] A repository acts as a link between the porch server and the git repository(or oci) and acts as a representation of the repository for porch to use. what porch uses to know where to do its operations towards.

      • [GIT VS OCI] PORCH SUPPORTS THE CONCEPT OF MULTIPLE REPOS OCI IS EXPERIMENTAL. AN EXERNAL REPO IS AN IMPLEMENTATION OF PORCH REPOSTIORY INTERFACE WHICH STORES PKG REVISION ON AN EXTERNAL SYSTEM. TODAY THERE ARE 2 EXTERNAL REPO IMPLEMENTATIONS. THEY ARE GIT(FULLY SUPPORTED) & OCI(EXPERIMENTALLY). DEVELOPERS ARE FREE TO DESIGN AND IMPLEMENT NEW EXTERNAL REPOS TYPES IF THEY WISH E.G. DB INTERFACE

  • [PACKAGE-VARIANTS/-SETS] MORE DETAIL HERE https://docs.nephio.org/docs/porch/package-variant/#core-concepts

6. Configuration & Deployment

Section Must Contain:

  • Configuration options (config as data, configuration schema) — key settings, environment variables, flags. Porch has Configuration as Data.

  • Deployment modes: how Porch can be deployed (cluster, single VM, etc.)

  • Versioning and upgrades

  • Authentication, authorization configuration (connecting to Git, registries)

Currently Available Resources:

  • Configuration as Data

  • Git & Registry Auth (under How-Tos)

  • GKE Deployment Guide

Gaps / additions Required:

  • Config file schema and field definitions

  • Supported deployment topologies

  • Upgrade instructions / versioning policy

7. CLI / API / Reference

Section Must Contain:

  • CLI tool reference: all commands, flags, examples

  • APIs / CRDs / Resources: full spec for Porch‑specific Kubernetes resources, with fields, validation, defaulting

  • Schema definitions or API versioning

  • Configuration schema reference, file formats etc.

Currently Available Resources:

Gaps / additions Required:

  • Full CLI command reference (flags, subcommands)

  • CRD reference (e.g., PackageVariant, Repository)

  • YAML schema definitions and validation docs

8. Best Practices

Section Must Contain:

  • Recommendations for structuring packages, versions & variants

  • How to design reusable templates/functions

  • Performance / scaling tips (e.g. for large numbers of packages or functions)

  • Operational guidance: monitoring, logging, health checks

Currently Available Resources:

  • Not directly addressed

Gaps / additions Required:

  • Package/variant organization patterns

  • Best practices for reusable mutations/functions

  • Monitoring/logging guides

FOR REPOSITORIES

  • PORCH SUPPORTS MULTIPLE PORCH REPOS ON A SINGLE GIT REPO BUT ONLY FOR /////

  • THE USAGE OF MULTIPLE PORCH REPOS ON A SINGLE GIT REPO IS NOT RECOMMENDED FOR PORCH REPOS THAT PORCH WRITES PACKAGE REVISIONS TO AND SHOULD ONLY BE USED FOR READ ONLY UPSTREAM REPOS. THIS WILL BE SLOWER AND TAKE A PERFORMANCE HIT.

  • THE OPTIMAL USE CASE IS A SINGLE PORCH REPO PER GIT REPO FOR EFFICIENCY SAKE.

 

9. Troubleshooting & FAQ

Section Must Contain:

  • Common problems & their solutions

  • Error messages & diagnostic steps

  • Debugging tips / tools

  • FAQ: questions new users often ask

Currently Available Resources:

  • None found

Gaps / additions Required:

  • FAQ page

  • Error resolution page

  • CLI diagnostic/debugging guide

10. Security & Compliance

Section Must Contain:

  • Authentication & authorization: how Porch ensures secure access

  • Secrets / credentials handling (for Git, registries, etc.)

  • Security considerations for function runner / templates / untrusted code

  • TLS, encryption in transit / at rest if applicable

Currently Available Resources:

  • Git & Registry authentication (under How-Tos)

Gaps / additions Required:

  • Security model for untrusted functions

  • Secrets handling / rotation model

  • RBAC requirements and guidance

  • [TLS IN CONTAINER REG'S]

  • [GIT REG AUTH IN PORCH REPOSITORIES RESOURCES]

  • [SELF SIGNED TLS IN PORCH SERVER]

  • [WEBHOOKS AND RBAC]

11. Glossary

Section Must Contain:

  • Define domain‑specific or technical terms used throughout the docs (variant, package orchestration, mutation, etc.)

Currently Available Resources:

Gaps / additions Required:

  • Term definitions + cross-links

[IT IS PRESENT BUT DEFINITELY OUT OF DATE]

12. Contributing

Section Must Contain:

  • How to contribute (code, documentation)

  • Developer setup (how to build and run Porch locally) — Porch has Setting up a local environment.

  • Process for submitting changes, code review, governance

Currently Available Resources:

Gaps / additions Required: