Skip to content

Seed code for FOCOM REST NBI (Provisioning)#1091

Merged
nephio-prow[bot] merged 1 commit into
nephio-project:mainfrom
saulgillEST:focom-nbi
Apr 20, 2026
Merged

Seed code for FOCOM REST NBI (Provisioning)#1091
nephio-prow[bot] merged 1 commit into
nephio-project:mainfrom
saulgillEST:focom-nbi

Conversation

@saulgillEST
Copy link
Copy Markdown
Contributor

@saulgillEST saulgillEST commented Apr 14, 2026

Add REST NBI with Porch storage, schema validation, and GitOps deployment

Description

This PR introduces the FOCOM North Bound Interface (NBI) REST API layer, Porch-based GitOps storage, FPR template parameter schema validation, and supporting infrastructure for the focom-operator.

What changed

REST NBI API (internal/nbi/)

A complete REST API layer built with Gin, implementing the draft → validate → approve → publish lifecycle for three resource types: OCloud, TemplateInfo, and FocomProvisioningRequest. The API follows the OpenAPI spec at api/openapi/focom-nbi-api.yaml.

  • handlers/ — HTTP handlers for all three resource types with full CRUD, draft management, revision history, and lifecycle operations (validate, approve, reject)
  • services/ — Business logic layer with dependency validation, state machine enforcement, and schema validation orchestration
  • models/ — Internal data models with JSON serialization, ID generation, and structured error types
  • validation/ — Validation framework with JSON Schema validation (gojsonschema), business rule validation, dependency validation, and schema metavalidation
  • storage/ — Storage abstraction with two implementations:
    • inmemory.go — In-memory storage for testing
    • porch.go — Production storage using Nephio Porch PackageRevisions via Kubernetes REST API, with full draft/revision lifecycle mapped to Porch's Draft/Proposed/Published states
  • integration/ — Operator integration layer for mapping NBI resources to Kubernetes CRs
  • config/ — Runtime configuration with environment variable support

FPR Template Parameter Schema Validation

Validates FPR templateParameters against the templateParameterSchema defined in the referenced TemplateInfo:

  • Schema validation runs during ValidateDraft (always) and optionally during CreateDraft/UpdateDraft when FOCOM_EARLY_SCHEMA_VALIDATION=true
  • TemplateInfo schema metavalidation ensures templateParameterSchema is a valid JSON Schema before approval
  • Structured error reporting with field path, constraint type, and human-readable description
  • Property-based tests (using gopter) verify schema validation conformance, error structure completeness, metavalidation correctness, and error serialization round-trip

Porch Storage Implementation

Full implementation of the storage layer using Nephio Porch as a GitOps backend:

  • Maps NBI draft/validate/approve lifecycle to Porch PackageRevision Draft/Proposed/Published states
  • Stores resources as Kubernetes-style YAML inside Porch packages
  • Supports kubeconfig-based and token-based authentication
  • Handles revision management, draft-from-revision creation, and resource listing with state mapping

GitOps Deployment (ConfigSync & Flux)

  • ConfigSync integration via config/configsync/ for automatic Git → Kubernetes sync
  • Flux integration via config/flux/ as an alternative GitOps engine with webhook support for instant sync
  • Makefile targets: deploy, deploy-with-flux, deploy-with-flux-webhook, undeploy, undeploy-flux

Testing

  • Unit tests for models, validation, services, storage, and controller
  • Property-based tests (gopter, 100 iterations each) for schema validation correctness
  • Integration test framework with smoke, integration, and stability test tiers against live Porch clusters
  • Postman collection (api/postman/) for manual API testing
  • Makefile targets: unit-tests, ci-tests, test-smoke, test-integration, test-stability

Documentation

  • Architecture overview (docs/ARCHITECTURE.md)
  • Deployment guide (docs/DEPLOYMENT.md)
  • Porch setup guide (docs/PORCH_SETUP.md)
  • Troubleshooting guide (docs/TROUBLESHOOTING.md)
  • Flux deployment docs (docs/flux/)
  • kpt deployment docs (docs/kpt/)
  • OpenAPI specification (api/openapi/focom-nbi-api.yaml)

Environment Variables

Variable Description Default
FOCOM_NAMESPACE Default namespace for resources focom-system
FOCOM_EARLY_SCHEMA_VALIDATION Enable schema validation on create/update false
NBI_STORAGE_BACKEND Storage backend (inmemory or porch) porch
PORCH_NAMESPACE Porch PackageRevision namespace default
PORCH_REPOSITORY Porch repository name focom-resources

Testing

cd focom-operator
make unit-tests    # Unit tests only
make test-smoke    # Smoke tests against live Porch (requires cluster)

@nephio-prow nephio-prow Bot requested review from efiacor and liamfallon April 14, 2026 10:42
@linux-foundation-easycla
Copy link
Copy Markdown

linux-foundation-easycla Bot commented Apr 14, 2026 •
edited
Loading

CLA Signed

The committers listed above are authorized under a signed CLA.

  • ✅ login: saulgillEST / name: saul.gill (c73fb51)

@nephio-prow
Copy link
Copy Markdown
Contributor

nephio-prow Bot commented Apr 14, 2026

Hi @saulgillEST. Thanks for your PR.

I'm waiting for a nephio-project member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

@saulgillEST
Copy link
Copy Markdown
Contributor Author

saulgillEST commented Apr 14, 2026

This work refers to user story #1066

@saulgillEST
Copy link
Copy Markdown
Contributor Author

saulgillEST commented Apr 14, 2026

See also API Proposal nephio-project/api#71

@nephio-prow nephio-prow Bot added the approved label Apr 15, 2026
@liamfallon
Copy link
Copy Markdown
Member

liamfallon commented Apr 15, 2026

/approve
/lgtm

@nephio-prow nephio-prow Bot added the lgtm label Apr 15, 2026
@nephio-prow nephio-prow Bot removed the lgtm label Apr 15, 2026
@saulgillEST
Copy link
Copy Markdown
Contributor Author

saulgillEST commented Apr 15, 2026

/retest

@nephio-prow
Copy link
Copy Markdown
Contributor

nephio-prow Bot commented Apr 15, 2026

@saulgillEST: Cannot trigger testing until a trusted user reviews the PR and leaves an /ok-to-test message.

Details

In response to this:

/retest

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

@saulgillEST saulgillEST changed the title Add REST NBI API with Porch storage and schema validatiion Seed code for FOCOM REST NBI (Provisioning) Apr 16, 2026
@saulgillEST
Add REST NBI API with Porch storage and schema validatiion
c73fb51 
- Add REST NBI API (Gin) for OCloud, TemplateInfo, and FPR resources
- Implement draft/validate/approve/reject lifecycle for all resource types
- Add Porch storage backend mapping to PackageRevision lifecycle states
- Add in-memory storage backend for testing
- Add FPR templateParameters validation against TemplateInfo JSON Schema
- Add TemplateInfo schema metavalidation (verify schema is valid JSON Schema)
- Add structured schema error reporting with field path and constraint info
- Add optional early validation mode via FOCOM_EARLY_SCHEMA_VALIDATION env var
- Add FOCOM_NAMESPACE env var for configurable default namespace
- Add ConfigSync and Flux GitOps deployment support
- Add OpenAPI 3.0 specification for the NBI API
- Add property-based tests (gopter) for schema validation correctness
- Add unit tests for models, validation, services, storage, and controller
- Add integration test framework with smoke, integration, and stability tiers
- Add Postman collection for manual API testing
- Add documentation for architecture, deployment, Porch setup, and troubleshooting
- Comply with linting, gosec, docker and other nephio make commands
- Support docker.io by default but also support private github registries for testing
- Support kpt deploy undeploy through makefile

Signed-off-by: saul.gill <saul.gill@est.tech>
@efiacor
Copy link
Copy Markdown
Collaborator

efiacor commented Apr 17, 2026

/ok-to-test

@liamfallon
Copy link
Copy Markdown
Member

liamfallon commented Apr 20, 2026

/approve
/lgtm

@nephio-prow nephio-prow Bot added the lgtm label Apr 20, 2026
@nephio-prow
Copy link
Copy Markdown
Contributor

nephio-prow Bot commented Apr 20, 2026

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: liamfallon

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@nephio-prow nephio-prow Bot merged commit a076755 into nephio-project:main Apr 20, 2026
14 checks passed
@saulgillEST saulgillEST deleted the focom-nbi branch April 20, 2026 09:37
@saulgillEST saulgillEST mentioned this pull request Apr 20, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@liamfallon liamfallon liamfallon approved these changes

@efiacor efiacor Awaiting requested review from efiacor

Assignees

@liamfallon liamfallon

Labels

approved lgtm ok-to-test

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@saulgillEST @liamfallon @efiacor