Skip to content

Commit 3ad8336

Browse files
ffforestffforest
committed
feat: add kusion server design doc first draft
1 parent 6b9c2cd commit 3ad8336

File tree

4 files changed

+379
-0
lines changed

4 files changed

+379
-0
lines changed

‎docs/design/kusion_server/domain_models.png

93 KB
Loading

‎docs/design/kusion_server/kusion_server.md

+379
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,379 @@
1+
# Kusion Server Design Doc
2+
3+
# Table of Content
4+
- [Abstract](#abstract)
5+
- [Background](#background)
6+
- [Goals and Non-Goals](#goals-and-non-goals)
7+
- [Goals](#goals)
8+
- [Non-goals](#non-goals)
9+
- [Concepts](#concepts)
10+
= [Core Domain Models](#core-domain-models)
11+
- [Model Hierarchy](#model-hierarchy)
12+
- [Separation of Application Resources and Platform Resources](#separation-of-application-resources-and-platform-resources)
13+
- [Core Capabilities and APIs](#core-capabilities-and-apis)
14+
- [Organization Management](#organization-management)
15+
- [Organizations](#organizations)
16+
- [Roles and Assignments](#roles-and-assignments)
17+
- [Application Management](#application-management)
18+
- [Projects](#project)
19+
- [Stacks](#stack)
20+
- [Platform Configuration](#platform-configuration)
21+
- [Backends](#backend)
22+
- [Workspaces](#workspace)
23+
- [Variable Sets (Optional)](#variable-sets-optional)
24+
- [Matching Rules (Optional)](#matching-rules-optional)
25+
- [GitOps Management](#gitops-management)
26+
- [Source](#source)
27+
- [Resource Management](#resource-management)
28+
- [Resource](#resource)
29+
- [Modules Management (Coming Soon)](#modules-management-coming-soon)
30+
- [Workflow Management (Coming Soon)](#workflow-management-coming-soon)
31+
- [Policy Management (Coming Soon)](#policy-management-coming-soon)
32+
33+
34+
# Abstract
35+
36+
This document captures the design details for Kusion 2.0, a.k.a Kusion with a Control Plane, or Kusion Server.
37+
38+
# Background
39+
40+
KusionStack is a Platform Engineering tech stack that is set to enable platform owners to build their tailored IDPs.
41+
42+
Kusion today serves as a Command Line Interface (CLI) tool that functions as an Intent-Driven Platform Orchestrator. Kusion proposes a protocol-driven collaboration paradigm which includes the platform owners and application developers to each do their jobs separately, and then have Kusion perform the orchestration work to dynamically match and generate the final and infrastructure-facing specification (in Kusion's term, this is called a `spec`), which eventually gets applied by Kusion.
43+
44+
However, this form of Kusion is limited in its ability to provider service at scale, where users are facing issues such credentials management, resource visibility, complexity in managing permissions, and effort to integrate with other systems etc.
45+
46+
With that background, we are proposing Kusion 2.0 which is a form of Kusion that runs as a long-running service and exposes REST service endpoints.
47+
48+
# Goals and Non-Goals
49+
50+
## Goals
51+
52+
- Kusion server is primarily targeting collaboration scenario (between application dev and platform engineers) at scale
53+
- Kusion server should provide universal APIs that covers the entire lifecycle of an application delivery and operations
54+
- Kusion server should provide RBAC based on identities, which includes user identities and system identities
55+
- Kusion server should primarily recommend and use the GitOps-driven workflow
56+
- Kusion server should expand the domain models in Kusion CLI to provide value-add capabilities such as the ability to persist resource status and construct a topological graph to which the application is deployed
57+
- Kusion server should follow the same design principles of Kusion, which will be elaborated in the next section
58+
59+
## Non-goals
60+
61+
- Kusion server is not a resource manager in a sense that it should not directly manipulate resources. Instead, it relies on users to update configuration files (either application or platform configurations).
62+
- Kusion server does not provide configuration management capabilities, a.k.a the ability to modify intent or spec files. The management of such files should be the responsibility of the users at the moment.
63+
- Kusion server does not consider procedure operations such as "restarting a pod", or "scale up my database", etc. as part its scope at the moment.
64+
65+
# Concepts
66+
67+
- Platform Orchestrator: According to [internaldeveloperplatform.org](https://internaldeveloperplatform.org/platform-orchestrators/), a Platform Orchestrator is defined as "a new generation of tools that go beyond the traditional platform-as-a-service (PaaS) model and offer published contracts between developers and platform teams. The contract might involve provisioning cloud environments, databases, monitoring, authentication and more in a different environment. These tools enforce organizational standards while granting developers self-service access to variations through configuration". In the context of Kusion, it follows several stages while achieving that: Read -> Match -> Create -> Deploy -> Day-2 Operations.
68+
69+
For other Kusion-native concepts, please refer to the [Kusion Concept Doc](https://www.kusionstack.io/docs/concepts/project/overview).
70+
71+
# Core Domain Models
72+
## Model Hierarchy
73+
![domain_models](domain_models.png)
74+
75+
## Separation of Application Resources and Platform Resources
76+
![resource models](resource_models.png)
77+
78+
# Core Capabilities and APIs
79+
## Organization Management
80+
- `Organization` represents a virtual entity that contains a collection of Projects that belongs together logically
81+
- Usually this maps to a real software engineering organization, such as teams, departments, business units or business groups, etc.
82+
- Deleting an organization deletes all projects in that organization
83+
- Authorizing to a subject to an organization grants it permission to all projects in that organization
84+
85+
### Organizations
86+
#### Proposed Organizations APIs
87+
```
88+
# CRUDL
89+
POST /api/v1/orgs # Create an org
90+
GET /api/v1/orgs/{orgID} # Read an org
91+
PUT /api/v1/orgs/{orgID} # Update an org
92+
DELETE /api/v1/orgs/{orgID} # Delete an org
93+
GET /api/v1/orgs # List all orgs
94+
```
95+
96+
#### Parameters
97+
98+
| Parameters | Required | Unique Key | Description |
99+
| -------- | ------- | -------- | ------- |
100+
| Name | true | true | organization name |
101+
| Description | false | false | organization description |
102+
| Labels | false | false | organization labels |
103+
| Owners | false | false | organization owners |
104+
105+
#### Sample Payload:
106+
```
107+
{
108+
"name": "ffforest-org",
109+
"owners": ["forest"]
110+
}
111+
```
112+
113+
### Roles and Assignments
114+
- Organization owners shoud be responsible for managing roles and role assignments in its org
115+
- Detailed API design coming soon
116+
117+
## Application Management
118+
### Project
119+
- `Project` generally represents an application that serves a business purpose. It may encapsulates one or more micro-services.
120+
- The purpose of the project is to bundle application configurations there are relevant. Specifically, it organizes configurations for internal components that orchestrate the application
121+
- A `Project` must belong to an `Organization`
122+
- A `Project` must have a `Source` that points to where its configurations are stored
123+
124+
#### Proposed Project APIs
125+
```
126+
# CRUDL
127+
POST /api/v1/project # Create a project
128+
GET /api/v1/project/{projectID} # Read a project
129+
PUT /api/v1/project/{projectID} # Update a project
130+
DELETE /api/v1/project/{projectID} # Delete a project
131+
GET /api/v1/project # List all projects
132+
GET /api/v1/project?org=xxx # List all projects in an org
133+
```
134+
135+
#### Parameters
136+
137+
| Parameters | Required | Unique Key | Description |
138+
| -------- | ------- | -------- | ------- |
139+
| Name | true | true | project name |
140+
| SourceID | true | false | source ID where project configuration is stored |
141+
| OrganizationID | true | false | organization ID where project belongs to |
142+
| Path | true | false | project path in the source |
143+
| Description | false | false | project description |
144+
| Labels | false | false | project labels |
145+
| Owners | false | false | project owners |
146+
| TemplateID(?) | false | false | project template ID |
147+
148+
#### Sample Payload
149+
```
150+
{
151+
"name": "forest-simple-service-4",
152+
"path": "simple-service-4",
153+
"organizationID": "1",
154+
"sourceID": "1"
155+
}
156+
```
157+
158+
### Stack
159+
- `Stack` is a configuration instance of an project. It represents a way to distinctly manage different configurations in the same project
160+
- The recommended way is to use the abstract concept of an `environment` to name stacks, such as `dev`, `stage`, `prod`, etc., because _generally_ there are some configuration differences in each `environment`, such as environment variables
161+
- However if ther are not, you can absolutely store all of them in one stack (such as `base`)
162+
- One stack can be deployed to multiple `environments`, or in Kusion's term, `workspaces`
163+
- A `Stack` DOES NOT necessarily represent the application instance in a given environment. It only represents a set of different application configuration
164+
- `Environment` or `Workspace` is a deploy-time concept, whereas `stack` is a config-time concept
165+
- A `Stack` must belong to a `Project`
166+
- A `Stack` does not equal to `a project in a workspace`
167+
- A `Stack` is a minimum unit of operation to write (Create+Update+Delete) or execute (Preview+Apply+Destroy)
168+
169+
#### Proposed Stack APIs
170+
```
171+
# CRUDL
172+
POST /api/v1/stack # Create a stack
173+
GET /api/v1/stack/{stackID} # Read a stack
174+
PUT /api/v1/stack/{stackID} # Update a stack
175+
DELETE /api/v1/stack/{stackID} # Delete a stack
176+
GET /api/v1/stack # List all stacks
177+
GET /api/v1/stack?project=xxx # List all stacks in a project
178+
GET /api/v1/stack?org=xxx&project=xxx # List all stacks in a project in an org
179+
180+
# Execute
181+
POST /api/v1/stack/{stackID}/generate # Generate specs for a stack
182+
POST /api/v1/stack/{stackID}/preview # Preview changes for a stack
183+
POST /api/v1/stack/{stackID}/apply # Apply resources for a stack
184+
POST /api/v1/stack/{stackID}/destroy # Destroy resources for a stack
185+
POST /api/v1/stack/{stackID}/generate?cell=xxx&aig=xxx # Generate
186+
187+
# Release
188+
GET /api/v1/stack/{stackID}/release # List all releases for this stack
189+
GET /api/v1/stack/{stackID}/release?workspace=dev # List all release for this stack in dev workspace
190+
POST /api/v1/stack/{stackID}/rollback
191+
```
192+
193+
#### Parameters
194+
195+
| Parameters | Required | Unique Key | Description |
196+
| -------- | ------- | -------- | ------- |
197+
| Name | true | true | stack name |
198+
| ProjectID | true | false | project ID where stack belongs to |
199+
| Path | true | false | stack path in the source |
200+
| Description | false | false | stack description |
201+
| Labels | false | false | stack labels |
202+
| Owners | false | false | stack owners |
203+
| TemplateID(?) | false | false | stack template ID |
204+
205+
#### Sample Payload
206+
```
207+
{
208+
"name": "forest-simple-service-dev-2",
209+
"path": "simple-service/dev-4",
210+
"desiredVersion": "latest",
211+
"projectID": "5"
212+
}
213+
```
214+
215+
#### Sample Request
216+
```
217+
curl http://localhost:8888/api/v1/stack/1/generate?workspace=dev # this generates a new spec for dev workspace
218+
curl http://localhost:8888/api/v1/stack/{stackID}/rollback?workspace=dev&releaseID=xxx # this rolls back a stack to one of its previous release
219+
```
220+
221+
## Platform Configuration
222+
223+
### Backend
224+
- A `Backend` represents a storage backend for Kusion server to store structured data, such as workspace configurations (in the form of `workspace.yaml`) or releases (including `spec` and `state`)
225+
- Supports AWS S3, AliCloud OSS and local storage currently
226+
227+
#### Proposed Backend APIs
228+
```
229+
# CRUDL
230+
POST /api/v1/backend # Create a backend
231+
GET /api/v1/backend/{backendID} # Read a backend
232+
PUT /api/v1/backend/{backendID} # Update a backend
233+
DELETE /api/v1/backend/{backendID} # Delete a backend
234+
GET /api/v1/backend # List all backends
235+
```
236+
237+
#### Parameters
238+
| Parameters | Required | Unique Key | Description |
239+
| -------- | ------- | -------- | ------- |
240+
| Name | true | true | backend name |
241+
| BackendConfig | true | false | backend configurations including AccessKey and SecretKey |
242+
| Description | false | false | workspace description |
243+
| Labels | false | false | workspace labels |
244+
| Owners | false | false | workspace owners |
245+
246+
#### Sample Payload
247+
```
248+
{
249+
"name": "oss-backend-7",
250+
"description": "oss backend 7",
251+
"backendConfig": {
252+
"type": "oss",
253+
"configs": {
254+
"accessKey": "ak7",
255+
"secretKey": "sk7"
256+
}
257+
}
258+
}
259+
```
260+
261+
### Workspace
262+
- A `Workspace` represents a specific landing zone. It is a deploy-time concept, as opposed to `stack` being a config-time concept
263+
- It is a logical concept that maps to an actual target environment to deploy a stack to. In today's context, this usually represents a Kubernetes cluster for the application workload and an optional cloud account to provision infrastructure resources that the workload depends on (A database, for example)
264+
- Aside from the deployment destination, workspaces are also designed to be associated with a series of platform configurations that are used by all the stacks deployed to said workspace
265+
- Workspaces should be managed by Platform Engineers, and selected by developers (or whoever is in charge of the app delivery)
266+
267+
![workspace](workspace.png)
268+
269+
#### Proposed Workspace APIs
270+
```
271+
# CRUDL
272+
POST /api/v1/workspace # Create a workspace
273+
GET /api/v1/workspace/{workspaceID} # Read a workspace
274+
PUT /api/v1/workspace/{workspaceID} # Update a workspace
275+
DELETE /api/v1/workspace/{workspaceID} # Delete a workspace
276+
GET /api/v1/workspace # List all workspaces
277+
```
278+
279+
#### Parameters
280+
281+
| Parameters | Required | Unique Key | Description |
282+
| -------- | ------- | -------- | ------- |
283+
| Name | true | true | workspace name |
284+
| BackendID | true | false | backend ID to store workspace configuration and releases |
285+
| Description | false | false | workspace description |
286+
| Labels | false | false | workspace labels |
287+
| Owners | false | false | workspace owners |
288+
289+
#### Sample Payload
290+
291+
```
292+
{
293+
"name": "aws-us-east-1-prod",
294+
"backendID": "7",
295+
"owners": ["forest"]
296+
}
297+
```
298+
299+
### Variable Sets (Optional)
300+
- Variable Sets are places to store variables used as part of the `kusion` workflow
301+
- This provides an alternative way to store platform configurations
302+
- It is also responsible for managing secrets and credentials, especially those that are on the platform level
303+
- Detailed API design coming soon
304+
305+
### Matching Rules (Optional)
306+
- Matching Rule provides an alternative approach to "select" stacks based on rules configured on the workspace level
307+
- The purpose is to lower developers' burden to be aware of the concept of workspaces
308+
- Matching Rules can centrally manage all the matching logic between application configuration and platform configuration
309+
310+
## GitOps Management
311+
312+
### Source
313+
314+
#### Proposed Source API
315+
```
316+
# CRUDL
317+
POST /api/v1/source # Create a source
318+
GET /api/v1/source/{sourceID} # Read a source
319+
PUT /api/v1/source/{sourceID} # Update a source
320+
DELETE /api/v1/source/{sourceID} # Delete a source
321+
GET /api/v1/source # List all sources
322+
```
323+
324+
#### Parameters
325+
326+
| Parameters | Required | Unique Key | Description |
327+
| -------- | ------- | -------- | ------- |
328+
| SourceProvider | true | true | source provider type, supports git and oci |
329+
| Remote | true | true | source remote, usually an url |
330+
| Description | false | false | source description |
331+
| Labels | false | false | source labels |
332+
| Owners | false | false | source owners |
333+
334+
#### Sample Payload
335+
```
336+
{
337+
"name": "ffforest-github",
338+
"sourceProvider": "git",
339+
"remote": "https://github.com/ffforest/kcp-samples.git",
340+
"description": "KCP samples in ffforest github"
341+
}
342+
```
343+
344+
## Resource Management
345+
346+
### Resource
347+
- `Resource` here represents the actual resources that are applied via Kusion server
348+
- Kusion server should record its status **at apply time, after it has succeeded**, but NOT to serve as a proxy to cloud provider APIs afterwards to get real-time status in Day-2
349+
- The purpose is to persist resources that are managed under a given org, project, stack (or smaller granularities), in order to generate a topological view to which an application has been deployed
350+
- This application resource graph can also be used for IAM authorization purposes if need be
351+
- Kusion server should produce a mapping between Kusion resource ID and infrastructure resource ID, including cloud resource identifiers (such as ARNs) or Kubernetes resource identifiers (GVK+namespace+name)
352+
- Kusion server should be able to import existing cloud resources so that it can manage infrastructures that already exists. This is done by passing the cloud resource ID into a field in the `extension` in Kusion specs
353+
354+
#### Proposed Resource APIs
355+
```
356+
# Resource RL
357+
GET /api/v1/resource/{resourceID} # Read a resource
358+
GET /api/v1/resource # List all resources
359+
GET /api/v1/resource?moduleinstance=xxx # List all resources in a module
360+
GET /api/v1/resource?appconfig=xxx # List all resources in an appconfig
361+
GET /api/v1/resource?stack=xxx # List all resources in a stack
362+
```
363+
364+
## Modules Management (Coming Soon)
365+
- A Kusion Module is a reusable building block designed by platform engineers to standardize application deployments and enable app developers to self-service
366+
- Kusion server provide basic APIs for managing Kusion Modules that can be used by Kusion server
367+
- This should include the ability to publish and register Kusion Modules
368+
369+
## Workflow Management (Coming Soon)
370+
- This provides workflow execution records which are necessary for audits
371+
- Kusion server should have built-in approval and notifications mechanism
372+
373+
### Release
374+
- Release are automatically generated after a successful apply, with a combination of `Spec` and `State`
375+
- Detailed API design coming soon
376+
377+
## Policy Management (Coming Soon)
378+
- This should include render-time policy (during `kusion generate`) and apply-time policy (during `kusion apply`)
379+
- Policy should have an effective range: which orgs/projects/stacks does this policy set apply to?

‎docs/design/kusion_server/resource_models.png

165 KB
Loading

‎docs/design/kusion_server/workspace.png

149 KB
Loading

0 commit comments

Comments
 (0)