Skip to content

Commit 1937e87

Browse files
Catalin-Stratulat-Ericssonliamfallon
Catalin-Stratulat-Ericsson
and
liamfallon
authored
Adding Api Server Documentation (kptdev#441)
* Adding Api Server Documentation * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/_index.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/_index.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/_index.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/_index.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/functionality.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/_index.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/design.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/functionality.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/interactions.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/interactions.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/_index.md * Apply suggestion from @liamfallon * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/design.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/design.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/design.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/functionality.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/functionality.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/_index.md * Update docs/content/en/docs/5_architecture_and_components/porch-apiserver/_index.md * Apply suggestion from @liamfallon * Apply suggestion from @liamfallon --------- Co-authored-by: Liam Fallon <35595825+liamfallon@users.noreply.github.com>
1 parent 1f8bece commit 1937e87

4 files changed

Lines changed: 1070 additions & 0 deletions

File tree

‎docs/content/en/docs/5_architecture_and_components/porch-apiserver/_index.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: "Porch API Server"
3+
type: docs
4+
weight: 1
5+
description: |
6+
The Kubernetes extension API server that provides Porch's API resources.
7+
---
8+
9+
## What is the Porch API Server?
10+
11+
The **Porch API Server** is a Kubernetes extension API server that exposes Porch's aggregated API resources (PackageRevision, PackageRevisionResources, Package) and CRDs (Repository, PackageRev) through the Kubernetes API. It acts as the entry point for client interactions with Porch, translating Kubernetes API requests into operations on the underlying Engine and Cache.
12+
13+
> The PackageVaraint and PackageVariantSet CRDs are not controlled by the Porch API server. They are controlled by the [Porch Controllers](../controllers/_index.md)
14+
15+
The Porch API Server is responsible for:
16+
17+
- **API Resource Registration**: Registering Porch's Kubernetes resources with the Kubernetes API aggregation layer
18+
- **Request Handling**: Processing CRUD operations (Create, Read, Update, Delete) and Watch requests for those resources
19+
- **REST Storage Implementation**: Interacting with the Porch [Cad Engine](../engine/_index.md) to provide storage backends for each API resource type
20+
- **Validation and Admission**: Enforcing API validation rules and admission policies through strategies
21+
- **Authentication and Authorization**: Integrating with Kubernetes RBAC for access control
22+
- **Watch Stream Management**: Supporting real-time watch streams for resource changes
23+
- **Background Operations**: Running periodic repository synchronization and maintenance tasks
24+
25+
## Role in the Architecture
26+
27+
The Porch API Server sits at the top of the Porch architecture, serving as the interface between Kubernetes clients and Porch's internal components:
28+
29+
```
30+
┌────────────────────────────────────────────────────────────┐
31+
│ Porch API Server │
32+
│ │
33+
│ ┌──────────────────┐ ┌────────────────────────────┐ │
34+
│ │ API Groups │ │ REST Storage │ │
35+
│ │ │ ───> │ (Aggregated) │ │
36+
│ │ • porch.kpt.dev │ │ • PackageRevision │ │
37+
│ │ │ │ • PackageRevisionResources│ │
38+
│ │ │ │ • Package │ │
39+
│ └──────────────────┘ └────────────────────────────┘ │
40+
│ │ │ │
41+
│ │ │ │
42+
│ ┌──────────────────┐ │ │
43+
│ │ CRDs (etcd) │ │ │
44+
│ │ │ │ │
45+
│ │ • Repository │ │ │
46+
│ │ • PackageRev │ │ │
47+
│ └──────────────────┘ │ │
48+
│ │ │ │
49+
│ └────────┬────────────────┘ │
50+
│ ↓ │
51+
│ ┌──────────────────┐ ┌──────────────────┐ │
52+
│ │ Strategies │ │ Background │ │
53+
│ │ │ │ Jobs │ │
54+
│ │ • Validation │ │ │ │
55+
│ │ • Admission │ │ • Repo Sync │ │
56+
│ │ • Table Conv │ │ • Cleanup │ │
57+
│ └──────────────────┘ └──────────────────┘ │
58+
└────────────────────────────────────────────────────────────┘
59+
↓
60+
┌──────────────────────┐
61+
│ CaD Engine │
62+
│ (Orchestration) │
63+
└──────────────────────┘
64+
↓
65+
┌──────────────────────┐
66+
│ Package Cache │
67+
│ (Repository Data) │
68+
└──────────────────────┘
69+
```
70+
71+
**Key architectural responsibilities:**
72+
73+
1. **Kubernetes API Integration**: Extends Kubernetes API with Porch-specific resources using API aggregation
74+
2. **Request Translation**: Converts Kubernetes API requests into Engine operations (CreatePackageRevision, UpdatePackageRevision, etc.)
75+
3. **Storage Abstraction**: Implements Kubernetes storage interface (REST storage) that delegates to Engine rather than etcd
76+
4. **Strategy Pattern**: Uses Kubernetes strategy pattern for validation, admission control, and table conversion
77+
5. **Watch Support**: Provides real-time watch streams by integrating with Engine's WatcherManager
78+
6. **Background Processing**: Runs periodic tasks for repository synchronization and resource cleanup
79+
7. **Multi-Tenancy**: Enforces namespace isolation and RBAC policies for secure multi-tenant operation
80+
81+
The API Server is instantiated once during Porch startup and configured with Engine, Cache, and client connections through dependency injection.

‎docs/content/en/docs/5_architecture_and_components/porch-apiserver/design.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
---
2+
title: "Design"
3+
type: docs
4+
weight: 2
5+
description: |
6+
Design patterns and architecture of the Porch API server.
7+
---
8+
9+
## REST Storage Interface
10+
11+
See [Functionality](functionality.md#rest-storage-implementation) for detailed CRUD operations and storage implementations.
12+
13+
The Porch API Server implements Kubernetes' REST storage interface to provide custom storage backends for Porch resources. Unlike standard Kubernetes resources that store data in etcd, Porch resources delegate to the Engine which manages package data in Git repositories through the Cache.
14+
15+
**Storage interface characteristics:**
16+
- Implements standard Kubernetes storage.Interface
17+
- Provides CRUD operations (Create, Get, List, Update, Delete)
18+
- Supports Watch for real-time change notifications
19+
- Delegates all operations to CaD Engine
20+
- No direct etcd storage - packages stored in Git
21+
22+
**Storage implementations:**
23+
- **packageRevisions**: Manages PackageRevision resources
24+
- **packageRevisionResources**: Manages PackageRevisionResources (package content)
25+
- **packages**: Manages Package resources
26+
27+
## Strategy Pattern
28+
29+
See [Functionality](functionality.md#validation-strategies) for detailed validation rules and processes.
30+
31+
The API Server uses Kubernetes' strategy pattern to customize resource behavior:
32+
33+
### Validation Strategy
34+
35+
**Purpose**: Validates resource specifications before persistence
36+
37+
**Validation types:**
38+
- **Create validation**: Ensures required fields present, lifecycle constraints enforced
39+
- **Update validation**: Validates resource version, lifecycle transitions, immutability rules
40+
- **Status validation**: Validates status subresource updates
41+
42+
### Admission Strategy
43+
44+
**Purpose**: Applies admission control policies and defaults
45+
46+
**Admission operations:**
47+
- **PrepareForCreate**: Sets defaults, generates names, initializes status
48+
- **PrepareForUpdate**: Validates resource version, enforces immutability
49+
- **Canonicalize**: Normalizes resource representation
50+
51+
### Table Conversion Strategy
52+
53+
**Purpose**: Converts resources to table format for kubectl display
54+
55+
**Table conversion:**
56+
- Defines columns for kubectl output (Name, Package, Workspace, Revision, Lifecycle)
57+
- Extracts values from resource specifications
58+
- Formats data for human-readable display
59+
- Supports both list and individual resource views
60+
61+
## API Groups
62+
63+
The Porch API Server registers two API groups with Kubernetes:
64+
65+
### porch.kpt.dev API Group (Aggregated API)
66+
67+
**Resources:**
68+
- **PackageRevision**: Represents a specific revision of a package
69+
- **PackageRevisionResources**: Contains the actual resource content of a package revision
70+
- **Package**: Represents a package across all its revisions
71+
72+
**Versions:**
73+
- v1alpha1: Current version with all resources
74+
75+
**Characteristics:**
76+
- Primary API group for package management
77+
- All resources namespaced
78+
- Served via Kubernetes API aggregation (not CRDs)
79+
- Supports full CRUD and Watch operations
80+
- Integrates with Engine for all operations
81+
- Uses custom REST storage (Git-backed, not etcd)
82+
83+
### config.porch.kpt.dev API Group (CRDs)
84+
85+
**Resources:**
86+
- **Repository**: Configures Git repositories for package storage
87+
- **PackageRev**: Internal metadata resource for tracking package revisions
88+
89+
**Versions:**
90+
- v1alpha1: Current version for all resources
91+
92+
**Characteristics:**
93+
- Configuration API group for repository management
94+
- All resources are namespaced
95+
- Implemented as standard Kubernetes CRDs
96+
- Managed by separate controllers, not directly by API server
97+
- Stored in etcd (standard Kubernetes CRD storage)
98+
- PackageRev is an internal resource used for metadata tracking
99+
100+
## Background Operations
101+
102+
See [Functionality](functionality.md#background-operations) for detailed implementation of background operations including repository synchronization and resource cleanup.
103+
104+
## Design Decisions
105+
106+
### REST Storage vs etcd
107+
108+
**Decision**: Implement custom REST storage that delegates to Engine instead of using etcd.
109+
110+
**Rationale:**
111+
- Package data naturally lives in Git repositories
112+
- etcd not suitable for large package content
113+
- Engine provides necessary abstraction over Git
114+
- Enables draft-commit workflow for package modifications
115+
116+
**Alternatives considered:**
117+
- **Store in etcd**: Would require duplicating package content, large storage overhead
118+
- **Hybrid approach**: Metadata in etcd, content in Git - adds complexity
119+
120+
**Trade-offs:**
121+
- Custom storage more complex than standard etcd
122+
- Enables Git-native package management
123+
- Better scalability for large packages
124+
125+
### Strategy-Based Validation
126+
127+
**Decision**: Use Kubernetes strategy pattern for validation and admission control.
128+
129+
**Rationale:**
130+
- Follows Kubernetes conventions
131+
- Separates validation logic from storage logic
132+
- Enables reuse across different storage implementations
133+
- Provides consistent validation behavior
134+
135+
**Alternatives considered:**
136+
- **Validation in Engine**: Would duplicate validation logic
137+
- **Webhook-based validation**: Adds network overhead and complexity
138+
139+
**Trade-offs:**
140+
- Strategy pattern adds abstraction layer
141+
- Provides clean separation of concerns
142+
- Enables testing validation independently
143+
144+
### Watch via WatcherManager
145+
146+
**Decision**: Implement watch streams using Engine's WatcherManager.
147+
148+
**Rationale:**
149+
- Engine knows when package revisions change
150+
- WatcherManager provides efficient fan-out to multiple watchers
151+
- Avoids polling or etcd watch overhead
152+
- Enables real-time notifications
153+
154+
**Alternatives considered:**
155+
- **etcd watch**: Would require storing all data in etcd
156+
- **Polling**: Inefficient and high latency
157+
158+
**Trade-offs:**
159+
- Custom watch implementation more complex
160+
- Provides efficient real-time updates
161+
- Scales to many concurrent watchers
162+
163+
### Background Job Pattern
164+
165+
**Decision**: Run repository synchronization and cleanup as background goroutines.
166+
167+
**Rationale:**
168+
- Sync operations are long-running and periodic
169+
- Should not block API requests
170+
- Enables concurrent sync of multiple repositories
171+
- Provides automatic cache refresh
172+
173+
**Alternatives considered:**
174+
- **Sync on demand**: Would add latency to API requests
175+
- **External controller**: Adds deployment complexity
176+
177+
**Trade-offs:**
178+
- Background jobs add complexity to server lifecycle
179+
- Provides better user experience (no sync delays)
180+
- Enables automatic cache consistency
181+
182+
### Dependency Injection
183+
184+
**Decision**: Configure Engine, Cache, and clients through dependency injection.
185+
186+
**Rationale:**
187+
- Enables testing with mock implementations
188+
- Provides flexible configuration
189+
- Separates construction from usage
190+
- Supports different deployment scenarios
191+
192+
**Alternatives considered:**
193+
- **Global singletons**: Hard to test and configure
194+
- **Service locator**: Hides dependencies
195+
196+
**Trade-offs:**
197+
- Requires explicit wiring during initialization
198+
- Provides clear dependency graph
199+
- Enables flexible testing and configuration

0 commit comments

Comments
 (0)