From dde76b345b6e8d52c8bd233e5b80e244237d3dad Mon Sep 17 00:00:00 2001 From: siyul-park Date: Tue, 8 Oct 2024 07:19:30 -0400 Subject: [PATCH] docs: add document --- docs/getting_started.md | 96 +++++++++++++++++------------- docs/getting_started_kr.md | 76 +++++++++++++---------- docs/key_concepts.md | 119 ++++++++++++++++++++++++------------- docs/key_concepts_kr.md | 35 +++++++++++ pkg/runtime/runtime.go | 3 + 5 files changed, 217 insertions(+), 112 deletions(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index 5a640ade..b78cb1f4 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -1,134 +1,150 @@ # πŸš€ Getting Started -This guide provides detailed instructions on installing, configuring, and managing workflows using the [Command Line Interface (CLI)](../cmd/README.md). It covers the entire process from installation to workflow control and configuration. +This guide will walk you through installing, configuring, and managing workflows using the [Command Line Interface (CLI)](../cmd/README.md). It covers the full process, from installation to controlling and configuring workflows. ## Installing from Source -To begin, set up the [CLI](../cmd/README.md) along with the [built-in extensions](../ext/README.md). Before starting the installation, ensure that [Go 1.23](https://go.dev/doc/install) or higher is installed on your system. +First, set up the [CLI](../cmd/README.md) along with the [core extensions](../ext/README.md). Make sure your system has [Go 1.23](https://go.dev/doc/install) or a later version installed. -### Cloning the Repository +### Clone the Repository -To clone the source code, run: +To download the source code, run the following command in your terminal: ```sh git clone https://github.com/siyul-park/uniflow ``` -Navigate to the cloned directory: +Navigate to the downloaded folder: ```sh cd uniflow ``` -### Installing Dependencies and Building +### Install Dependencies and Build -To install dependencies and build the project, execute: +To install the required dependencies and build the project, run the following commands: ```sh make init make build ``` -Once the build is complete, the executable will be located in the `dist` folder. +After the build completes, the executable files will be available in the `dist` folder. ### Configuration -You can modify settings flexibly via the `.uniflow.toml` file or system environment variables. Key configuration options include: +Settings can be modified using the `.uniflow.toml` file or system environment variables. The key configuration options are: -| TOML Key | Environment Variable Key | Example | -|-----------------------|----------------------------|----------------------------| -| `database.url` | `DATABASE.URL` | `mem://` or `mongodb://` | -| `database.name` | `DATABASE.NAME` | - | -| `collection.nodes` | `COLLECTION.NODES` | `nodes` | -| `collection.secrets` | `COLLECTION.SECRETS` | `secrets` | +| TOML Key | Environment Variable Key | Example | +|----------------------|--------------------------|-----------------------------| +| `database.url` | `DATABASE.URL` | `mem://` or `mongodb://` | +| `database.name` | `DATABASE.NAME` | - | +| `collection.nodes` | `COLLECTION.NODES` | `nodes` | +| `collection.secrets` | `COLLECTION.SECRETS` | `secrets` | -If using [MongoDB](https://www.mongodb.com/), enable [Change Streams](https://www.mongodb.com/docs/manual/changeStreams/) to allow the engine to track node specifications and secret changes. This requires setting up a [Replica Set](https://www.mongodb.com/docs/manual/replication/). +If you are using [MongoDB](https://www.mongodb.com/), enable [Change Streams](https://www.mongodb.com/docs/manual/changeStreams/) to track resource changes in real time. This requires setting up a [replica set](https://www.mongodb.com/docs/manual/replication/). -## Uniflow +## Using Uniflow -`uniflow` is primarily used to start and manage runtime environments. +`uniflow` is primarily used to start and manage the runtime environment. -### Start +### Start Command -The `start` command initiates the runtime with node specifications for a specific namespace. Basic usage is as follows: +The `start` command executes all node specifications in the specified namespace. If no namespace is provided, the default namespace (`default`) is used. ```sh ./dist/uniflow start --namespace default ``` -If the namespace is empty, you can provide initial node specifications using the `--from-nodes` flag: +If the namespace is empty, you can provide an initial node specification using the `--from-nodes` flag: ```sh ./dist/uniflow start --namespace default --from-nodes examples/nodes.yaml ``` -To provide initial secrets, use the `--from-secrets` flag: +You can specify an initial secrets file with the `--from-secrets` flag: ```sh ./dist/uniflow start --namespace default --from-secrets examples/secrets.yaml ``` -This command executes all node specifications for the specified namespace. If no namespace is specified, the `default` namespace is used. +Charts can be initialized using the `--from-charts` flag: -## Uniflowctl +```sh +./dist/uniflow start --namespace default --from-charts examples/charts.yaml +``` + +## Using Uniflowctl -`uniflowctl` is used to manage node specifications and secrets within a namespace. +`uniflowctl` is a command used to manage resources within a namespace. -### Apply +### Apply Command -The `apply` command adds or updates node specifications or secrets in a namespace. Usage examples are: +The `apply` command applies the contents of a specified file to the namespace. If no namespace is specified, the `default` namespace is used. ```sh ./dist/uniflowctl apply nodes --namespace default --filename examples/nodes.yaml ``` -or +To apply secrets: ```sh ./dist/uniflowctl apply secrets --namespace default --filename examples/secrets.yaml ``` -This command applies the contents of the specified file to the namespace. If no namespace is specified, the `default` namespace is used by default. +To apply charts: + +```sh +./dist/uniflowctl apply charts --namespace default --filename examples/charts.yaml +``` -### Delete +### Delete Command -The `delete` command removes node specifications or secrets from a namespace. Usage examples are: +The `delete` command removes all resources defined in the specified file. If no namespace is specified, the `default` namespace is used. ```sh ./dist/uniflowctl delete nodes --namespace default --filename examples/nodes.yaml ``` -or +To delete secrets: ```sh ./dist/uniflowctl delete secrets --namespace default --filename examples/secrets.yaml ``` -This command removes all node specifications or secrets defined in the specified file. If no namespace is specified, the `default` namespace is used. +To delete charts: -### Get +```sh +./dist/uniflowctl delete charts --namespace default --filename examples/charts.yaml +``` + +### Get Command -The `get` command retrieves node specifications or secrets from a namespace. Usage examples are: +The `get` command retrieves all resources in the specified namespace. If no namespace is specified, the `default` namespace is used. ```sh ./dist/uniflowctl get nodes --namespace default ``` -or +To retrieve secrets: ```sh ./dist/uniflowctl get secrets --namespace default ``` -This command displays all node specifications or secrets for the specified namespace. If no namespace is specified, the `default` namespace is used. +To retrieve charts: + +```sh +./dist/uniflowctl get charts --namespace default +``` -## HTTP API Integration +## Integrating HTTP API -To modify node specifications through the HTTP API, set up a workflow that exposes this functionality. You can use the `native` node included in the [basic extensions](../ext/README.md): +To modify node specifications via the HTTP API, set up workflows accordingly. You can use the `native` node provided in the [core extensions](../ext/README.md): ```yaml kind: native opcode: nodes.create # or nodes.read, nodes.update, nodes.delete ``` -To get started, refer to the [workflow example](../examples/system.yaml). You may need to add authentication and authorization processes to this workflow as needed. Typically, such runtime control workflows are defined in the `system` namespace. +Refer to the [workflow examples](../examples/system.yaml) to get started. If needed, you can add authentication and authorization processes. These runtime control workflows are typically defined in the `system` namespace. diff --git a/docs/getting_started_kr.md b/docs/getting_started_kr.md index 103cbf1a..ef5f3c0a 100644 --- a/docs/getting_started_kr.md +++ b/docs/getting_started_kr.md @@ -1,20 +1,20 @@ # πŸš€ μ‹œμž‘ν•˜κΈ° -이 μ•ˆλ‚΄μ„œλŠ” [λͺ…령쀄 μΈν„°νŽ˜μ΄μŠ€(CLI)](../cmd/README_kr.md)λ₯Ό μ„€μΉ˜ν•˜κ³  κ΅¬μ„±ν•˜λ©° μ›Œν¬ν”Œλ‘œμš°λ₯Ό κ΄€λ¦¬ν•˜λŠ” 방법을 μžμ„Ένžˆ μ„€λͺ…ν•©λ‹ˆλ‹€. μ„€μΉ˜λΆ€ν„° μ›Œν¬ν”Œλ‘œμš° μ œμ–΄ 및 μ„€μ •κΉŒμ§€μ˜ μ „λ°˜μ μΈ 과정을 λ‹€λ£Ήλ‹ˆλ‹€. +이 κ°€μ΄λ“œλŠ” [λͺ…령쀄 μΈν„°νŽ˜μ΄μŠ€(CLI)](../cmd/README_kr.md)의 μ„€μΉ˜, μ„€μ •, 그리고 μ›Œν¬ν”Œλ‘œμš° 관리 방법을 μ‰½κ²Œ 따라 ν•  수 μžˆλ„λ‘ μ„€λͺ…ν•©λ‹ˆλ‹€. μ„€μΉ˜ κ³Όμ •λΆ€ν„° μ›Œν¬ν”Œλ‘œμš°μ˜ μ œμ–΄ 및 μ„€μ • λ°©λ²•κΉŒμ§€, ν•„μš”ν•œ λͺ¨λ“  단계λ₯Ό λ‹€λ£Ήλ‹ˆλ‹€. ## μ†ŒμŠ€μ—μ„œ μ„€μΉ˜ν•˜κΈ° -λ¨Όμ € [κΈ°λ³Έ ν™•μž₯ κΈ°λŠ₯](../ext/README_kr.md)κ³Ό ν•¨κ»˜ μ œκ³΅λ˜λŠ” [CLI](../cmd/README_kr.md)λ₯Ό μ„€μ •ν•΄μ•Ό ν•©λ‹ˆλ‹€. μ„€μΉ˜λ₯Ό μ‹œμž‘ν•˜κΈ° 전에 μ‹œμŠ€ν…œμ— [Go 1.23](https://go.dev/doc/install) 이상이 μ„€μΉ˜λ˜μ–΄ μžˆλŠ”μ§€ ν™•μΈν•˜μ„Έμš”. +λ¨Όμ € [κΈ°λ³Έ ν™•μž₯ κΈ°λŠ₯](../ext/README_kr.md)κ³Ό ν•¨κ»˜ μ œκ³΅λ˜λŠ” [CLI](../cmd/README_kr.md)λ₯Ό μ„€μ •ν•΄μ•Ό ν•©λ‹ˆλ‹€. μ‹œμž‘ν•˜κΈ° 전에, μ‹œμŠ€ν…œμ— [Go 1.23](https://go.dev/doc/install) μ΄μƒμ˜ 버전이 μ„€μΉ˜λ˜μ–΄ μžˆλŠ”μ§€ ν™•μΈν•˜μ„Έμš”. ### 리포지토리 클둠 -μ†ŒμŠ€ μ½”λ“œλ₯Ό ν΄λ‘ ν•˜λ €λ©΄ λ‹€μŒ λͺ…λ Ήμ–΄λ₯Ό μ‹€ν–‰ν•©λ‹ˆλ‹€: +μ†ŒμŠ€ μ½”λ“œλ₯Ό λ‹€μš΄λ‘œλ“œν•˜λ €λ©΄, ν„°λ―Έλ„μ—μ„œ μ•„λž˜ λͺ…λ Ήμ–΄λ₯Ό μž…λ ₯ν•˜μ„Έμš”: ```sh git clone https://github.com/siyul-park/uniflow ``` -ν΄λ‘ ν•œ λ””λ ‰ν† λ¦¬λ‘œ μ΄λ™ν•©λ‹ˆλ‹€: +λ‹€μš΄λ‘œλ“œν•œ ν΄λ”λ‘œ μ΄λ™ν•©λ‹ˆλ‹€: ```sh cd uniflow @@ -22,7 +22,7 @@ cd uniflow ### μ˜μ‘΄μ„± μ„€μΉ˜ 및 λΉŒλ“œ -μ˜μ‘΄μ„±μ„ μ„€μΉ˜ν•˜κ³  ν”„λ‘œμ νŠΈλ₯Ό λΉŒλ“œν•˜λ €λ©΄ λ‹€μŒ λͺ…λ Ήμ–΄λ₯Ό μ‹€ν–‰ν•©λ‹ˆλ‹€: +ν•„μš”ν•œ μ˜μ‘΄μ„±μ„ μ„€μΉ˜ν•˜κ³  ν”„λ‘œμ νŠΈλ₯Ό λΉŒλ“œν•˜λ €λ©΄, μ•„λž˜ λͺ…λ Ήμ–΄λ₯Ό μ‹€ν–‰ν•˜μ„Έμš”: ```sh make init @@ -33,7 +33,7 @@ make build ### μ„€μ • -`.uniflow.toml` νŒŒμΌμ΄λ‚˜ μ‹œμŠ€ν…œ ν™˜κ²½ λ³€μˆ˜λ₯Ό 톡해 섀정을 μœ μ—°ν•˜κ²Œ λ³€κ²½ν•  수 μžˆμŠ΅λ‹ˆλ‹€. μ£Όμš” ꡬ성 μ˜΅μ…˜μ€ λ‹€μŒκ³Ό κ°™μŠ΅λ‹ˆλ‹€: +섀정은 `.uniflow.toml` νŒŒμΌμ΄λ‚˜ μ‹œμŠ€ν…œ ν™˜κ²½ λ³€μˆ˜λ₯Ό μ‚¬μš©ν•΄ μœ μ—°ν•˜κ²Œ λ³€κ²½ν•  수 μžˆμŠ΅λ‹ˆλ‹€. μ£Όμš” μ„€μ • ν•­λͺ©μ€ λ‹€μŒκ³Ό κ°™μŠ΅λ‹ˆλ‹€: | TOML ν‚€ | ν™˜κ²½ λ³€μˆ˜ ν‚€ | μ˜ˆμ‹œ | |----------------------|-------------------------|----------------------------| @@ -42,93 +42,109 @@ make build | `collection.nodes` | `COLLECTION.NODES` | `nodes` | | `collection.secrets` | `COLLECTION.SECRETS` | `secrets` | -[MongoDB](https://www.mongodb.com/)λ₯Ό μ‚¬μš©ν•˜λŠ” 경우, 엔진이 λ…Έλ“œ λͺ…μ„Έ 및 μ‹œν¬λ¦Ώ 변경을 좔적할 수 μžˆλ„λ‘ [λ³€κ²½ 슀트림](https://www.mongodb.com/docs/manual/changeStreams/)을 ν™œμ„±ν™”ν•΄μ•Ό ν•©λ‹ˆλ‹€. 이λ₯Ό μœ„ν•΄ [볡제 μ„ΈνŠΈ](https://www.mongodb.com/docs/manual/replication/) 섀정이 ν•„μš”ν•©λ‹ˆλ‹€. +λ§Œμ•½ [MongoDB](https://www.mongodb.com/)λ₯Ό μ‚¬μš©ν•œλ‹€λ©΄, λ¦¬μ†ŒμŠ€μ˜ λ³€κ²½ 사항을 μ‹€μ‹œκ°„μœΌλ‘œ μΆ”μ ν•˜κΈ° μœ„ν•΄ [λ³€κ²½ 슀트림](https://www.mongodb.com/docs/manual/changeStreams/)을 ν™œμ„±ν™”ν•΄μ•Ό ν•©λ‹ˆλ‹€. 이λ₯Ό μœ„ν•΄μ„œλŠ” [볡제 μ„ΈνŠΈ](https://www.mongodb.com/docs/manual/replication/) 섀정이 ν•„μš”ν•©λ‹ˆλ‹€. -## Uniflow +## Uniflow μ‚¬μš©ν•˜κΈ° -`uniflow`λŠ” 주둜 λŸ°νƒ€μž„ ν™˜κ²½μ„ μ‹œμž‘ν•˜κ³  κ΄€λ¦¬ν•˜λŠ” 데 μ‚¬μš©λ©λ‹ˆλ‹€. +`uniflow`λŠ” 주둜 λŸ°νƒ€μž„ ν™˜κ²½μ„ μ‹œμž‘ν•˜κ³  κ΄€λ¦¬ν•˜λŠ” λͺ…λ Ήμ–΄μž…λ‹ˆλ‹€. -### Start +### Start λͺ…λ Ήμ–΄ -`start` λͺ…λ Ήμ–΄λŠ” νŠΉμ • λ„€μž„μŠ€νŽ˜μ΄μŠ€μ˜ λ…Έλ“œ λͺ…μ„Έλ‘œ λŸ°νƒ€μž„μ„ μ‹œμž‘ν•©λ‹ˆλ‹€. κΈ°λ³Έ μ‚¬μš©λ²•μ€ λ‹€μŒκ³Ό κ°™μŠ΅λ‹ˆλ‹€: +`start` λͺ…λ Ήμ–΄λŠ” μ§€μ •λœ λ„€μž„μŠ€νŽ˜μ΄μŠ€ λ‚΄μ˜ λͺ¨λ“  λ…Έλ“œ λͺ…μ„Έλ₯Ό μ‹€ν–‰ν•©λ‹ˆλ‹€. λ„€μž„μŠ€νŽ˜μ΄μŠ€κ°€ μ§€μ •λ˜μ§€ μ•ŠμœΌλ©΄ 기본적으둜 `default` λ„€μž„μŠ€νŽ˜μ΄μŠ€κ°€ μ‚¬μš©λ©λ‹ˆλ‹€. ```sh ./dist/uniflow start --namespace default ``` -λ„€μž„μŠ€νŽ˜μ΄μŠ€κ°€ λΉ„μ–΄ μžˆλŠ” 경우, `--from-nodes` ν”Œλž˜κ·Έλ₯Ό μ‚¬μš©ν•˜μ—¬ 초기 λ…Έλ“œ λͺ…μ„Έλ₯Ό μ œκ³΅ν•  수 μžˆμŠ΅λ‹ˆλ‹€: +λ„€μž„μŠ€νŽ˜μ΄μŠ€κ°€ λΉ„μ–΄ μžˆμ„ 경우, 초기 λ…Έλ“œ λͺ…μ„Έλ₯Ό `--from-nodes` ν”Œλž˜κ·Έλ‘œ μ œκ³΅ν•  수 μžˆμŠ΅λ‹ˆλ‹€: ```sh ./dist/uniflow start --namespace default --from-nodes examples/nodes.yaml ``` -초기 μ‹œν¬λ¦Ώμ„ μ œκ³΅ν•˜λ €λ©΄ `--from-secrets` ν”Œλž˜κ·Έλ₯Ό μ‚¬μš©ν•  수 μžˆμŠ΅λ‹ˆλ‹€: +초기 μ‹œν¬λ¦Ώ νŒŒμΌμ€ `--from-secrets` ν”Œλž˜κ·Έλ‘œ μ„€μ •ν•  수 μžˆμŠ΅λ‹ˆλ‹€: ```sh ./dist/uniflow start --namespace default --from-secrets examples/secrets.yaml ``` -이 λͺ…λ Ήμ–΄λŠ” μ§€μ •λœ λ„€μž„μŠ€νŽ˜μ΄μŠ€μ˜ λͺ¨λ“  λ…Έλ“œ λͺ…μ„Έλ₯Ό μ‹€ν–‰ν•©λ‹ˆλ‹€. λ„€μž„μŠ€νŽ˜μ΄μŠ€λ₯Ό μ§€μ •ν•˜μ§€ μ•ŠμœΌλ©΄ `default` λ„€μž„μŠ€νŽ˜μ΄μŠ€κ°€ μ‚¬μš©λ©λ‹ˆλ‹€. +초기 차트 νŒŒμΌμ€ `--from-charts` ν”Œλž˜κ·Έλ‘œ μ œκ³΅ν•  수 μžˆμŠ΅λ‹ˆλ‹€: -## Uniflowctl +```sh +./dist/uniflow start --namespace default --from-charts examples/charts.yaml +``` + +## Uniflowctl μ‚¬μš©ν•˜κΈ° -`uniflowctl`λŠ” λ„€μž„μŠ€νŽ˜μ΄μŠ€ λ‚΄μ—μ„œ λ…Έλ“œ λͺ…세와 μ‹œν¬λ¦Ώμ„ κ΄€λ¦¬ν•˜λŠ” 데 μ‚¬μš©λ©λ‹ˆλ‹€. +`uniflowctl`λŠ” λ„€μž„μŠ€νŽ˜μ΄μŠ€ λ‚΄μ—μ„œ λ¦¬μ†ŒμŠ€λ₯Ό κ΄€λ¦¬ν•˜λŠ” λͺ…λ Ήμ–΄μž…λ‹ˆλ‹€. -### Apply +### Apply λͺ…λ Ήμ–΄ -`apply` λͺ…λ Ήμ–΄λŠ” λ„€μž„μŠ€νŽ˜μ΄μŠ€μ— λ…Έλ“œ λͺ…μ„Έ λ˜λŠ” μ‹œν¬λ¦Ώμ„ μΆ”κ°€ν•˜κ±°λ‚˜ μ—…λ°μ΄νŠΈν•©λ‹ˆλ‹€. μ‚¬μš© μ˜ˆμ‹œλŠ” λ‹€μŒκ³Ό κ°™μŠ΅λ‹ˆλ‹€: +`apply` λͺ…λ Ήμ–΄λŠ” μ§€μ •λœ 파일 λ‚΄μš©μ„ λ„€μž„μŠ€νŽ˜μ΄μŠ€μ— μ μš©ν•©λ‹ˆλ‹€. λ„€μž„μŠ€νŽ˜μ΄μŠ€λ₯Ό μ§€μ •ν•˜μ§€ μ•ŠμœΌλ©΄ 기본적으둜 `default` λ„€μž„μŠ€νŽ˜μ΄μŠ€κ°€ μ‚¬μš©λ©λ‹ˆλ‹€. ```sh ./dist/uniflowctl apply nodes --namespace default --filename examples/nodes.yaml ``` -λ˜λŠ” +μ‹œν¬λ¦Ώμ„ μ μš©ν•˜λ €λ©΄: ```sh ./dist/uniflowctl apply secrets --namespace default --filename examples/secrets.yaml ``` -이 λͺ…λ Ήμ–΄λŠ” μ§€μ •λœ 파일의 λ‚΄μš©μ„ λ„€μž„μŠ€νŽ˜μ΄μŠ€μ— μ μš©ν•©λ‹ˆλ‹€. λ„€μž„μŠ€νŽ˜μ΄μŠ€λ₯Ό μ§€μ •ν•˜μ§€ μ•ŠμœΌλ©΄ 기본적으둜 `default` λ„€μž„μŠ€νŽ˜μ΄μŠ€κ°€ μ‚¬μš©λ©λ‹ˆλ‹€. +차트λ₯Ό μ μš©ν•˜λ €λ©΄: + +```sh +./dist/uniflowctl apply charts --namespace default --filename examples/charts.yaml +``` -### Delete +### Delete λͺ…λ Ήμ–΄ -`delete` λͺ…λ Ήμ–΄λŠ” λ„€μž„μŠ€νŽ˜μ΄μŠ€μ—μ„œ λ…Έλ“œ λͺ…μ„Έ λ˜λŠ” μ‹œν¬λ¦Ώμ„ μ œκ±°ν•©λ‹ˆλ‹€. μ‚¬μš© μ˜ˆμ‹œλŠ” λ‹€μŒκ³Ό κ°™μŠ΅λ‹ˆλ‹€: +`delete` λͺ…λ Ήμ–΄λŠ” μ§€μ •λœ νŒŒμΌμ— μ •μ˜λœ λͺ¨λ“  λ¦¬μ†ŒμŠ€λ₯Ό μ‚­μ œν•©λ‹ˆλ‹€. λ„€μž„μŠ€νŽ˜μ΄μŠ€λ₯Ό μ§€μ •ν•˜μ§€ μ•ŠμœΌλ©΄ 기본적으둜 `default` λ„€μž„μŠ€νŽ˜μ΄μŠ€κ°€ μ‚¬μš©λ©λ‹ˆλ‹€. ```sh ./dist/uniflowctl delete nodes --namespace default --filename examples/nodes.yaml ``` -λ˜λŠ” +μ‹œν¬λ¦Ώμ„ μ‚­μ œν•˜λ €λ©΄: ```sh ./dist/uniflowctl delete secrets --namespace default --filename examples/secrets.yaml ``` -이 λͺ…λ Ήμ–΄λŠ” μ§€μ •λœ νŒŒμΌμ— μ •μ˜λœ λͺ¨λ“  λ…Έλ“œ λͺ…μ„Έ λ˜λŠ” μ‹œν¬λ¦Ώμ„ μ œκ±°ν•©λ‹ˆλ‹€. λ„€μž„μŠ€νŽ˜μ΄μŠ€λ₯Ό μ§€μ •ν•˜μ§€ μ•ŠμœΌλ©΄ `default` λ„€μž„μŠ€νŽ˜μ΄μŠ€κ°€ μ‚¬μš©λ©λ‹ˆλ‹€. +차트λ₯Ό μ‚­μ œν•˜λ €λ©΄: -### Get +```sh +./dist/uniflowctl delete charts --namespace default --filename examples/charts.yaml +``` + +### Get λͺ…λ Ήμ–΄ -`get` λͺ…λ Ήμ–΄λŠ” λ„€μž„μŠ€νŽ˜μ΄μŠ€μ—μ„œ λ…Έλ“œ λͺ…μ„Έ λ˜λŠ” μ‹œν¬λ¦Ώμ„ μ‘°νšŒν•©λ‹ˆλ‹€. μ‚¬μš© μ˜ˆμ‹œλŠ” λ‹€μŒκ³Ό κ°™μŠ΅λ‹ˆλ‹€: +`get` λͺ…λ Ήμ–΄λŠ” μ§€μ •λœ λ„€μž„μŠ€νŽ˜μ΄μŠ€ λ‚΄ λͺ¨λ“  λ¦¬μ†ŒμŠ€λ₯Ό μ‘°νšŒν•©λ‹ˆλ‹€. λ„€μž„μŠ€νŽ˜μ΄μŠ€κ°€ μ§€μ •λ˜μ§€ μ•ŠμœΌλ©΄ 기본적으둜 `default` λ„€μž„μŠ€νŽ˜μ΄μŠ€κ°€ μ‚¬μš©λ©λ‹ˆλ‹€. ```sh ./dist/uniflowctl get nodes --namespace default ``` -λ˜λŠ” +μ‹œν¬λ¦Ώμ„ μ‘°νšŒν•˜λ €λ©΄: ```sh ./dist/uniflowctl get secrets --namespace default ``` -이 λͺ…λ Ήμ–΄λŠ” μ§€μ •λœ λ„€μž„μŠ€νŽ˜μ΄μŠ€μ˜ λͺ¨λ“  λ…Έλ“œ λͺ…μ„Έ λ˜λŠ” μ‹œν¬λ¦Ώμ„ ν‘œμ‹œν•©λ‹ˆλ‹€. λ„€μž„μŠ€νŽ˜μ΄μŠ€λ₯Ό μ§€μ •ν•˜μ§€ μ•ŠμœΌλ©΄ `default` λ„€μž„μŠ€νŽ˜μ΄μŠ€κ°€ μ‚¬μš©λ©λ‹ˆλ‹€. +차트λ₯Ό μ‘°νšŒν•˜λ €λ©΄: + +```sh +./dist/uniflowctl get charts --namespace default +``` ## HTTP API 톡합 -HTTP APIλ₯Ό 톡해 λ…Έλ“œ λͺ…μ„Έλ₯Ό μˆ˜μ •ν•˜λ €λ©΄ ν•΄λ‹Ή κΈ°λŠ₯을 λ…ΈμΆœν•˜λŠ” μ›Œν¬ν”Œλ‘œμš°λ₯Ό μ„€μ •ν•΄μ•Ό ν•©λ‹ˆλ‹€. 이λ₯Ό μœ„ν•΄ [κΈ°λ³Έ ν™•μž₯](../ext/README_kr.md)에 ν¬ν•¨λœ `native` λ…Έλ“œλ₯Ό ν™œμš©ν•  수 μžˆμŠ΅λ‹ˆλ‹€: +HTTP APIλ₯Ό 톡해 λ…Έλ“œ λͺ…μ„Έλ₯Ό μˆ˜μ •ν•˜λ €λ©΄, κ΄€λ ¨ μ›Œν¬ν”Œλ‘œμš°λ₯Ό μ„€μ •ν•΄μ•Ό ν•©λ‹ˆλ‹€. 이λ₯Ό μœ„ν•΄ [κΈ°λ³Έ ν™•μž₯](../ext/README_kr.md)에 ν¬ν•¨λœ `native` λ…Έλ“œλ₯Ό μ‚¬μš©ν•  수 μžˆμŠ΅λ‹ˆλ‹€: ```yaml kind: native opcode: nodes.create # λ˜λŠ” nodes.read, nodes.update, nodes.delete ``` -μ‹œμž‘ν•˜λ €λ©΄ [μ›Œν¬ν”Œλ‘œμš° 예제](../examples/system.yaml)λ₯Ό μ°Έκ³ ν•˜μ„Έμš”. ν•„μš”μ— 따라 이 μ›Œν¬ν”Œλ‘œμš°μ— 인증 및 κΆŒν•œ λΆ€μ—¬ ν”„λ‘œμ„ΈμŠ€λ₯Ό μΆ”κ°€ν•  수 μžˆμŠ΅λ‹ˆλ‹€. 일반적으둜 μ΄λŸ¬ν•œ λŸ°νƒ€μž„ μ œμ–΄ μ›Œν¬ν”Œλ‘œμš°λŠ” `system` λ„€μž„μŠ€νŽ˜μ΄μŠ€μ— μ •μ˜λ©λ‹ˆλ‹€. +μ‹œμž‘ν•˜λ €λ©΄ [μ›Œν¬ν”Œλ‘œμš° 예제](../examples/system.yaml)λ₯Ό μ°Έκ³ ν•˜μ„Έμš”. ν•„μš”ν•œ 경우, 인증 및 κΆŒν•œ 관리 ν”„λ‘œμ„ΈμŠ€λ₯Ό μΆ”κ°€ν•  수 μžˆμŠ΅λ‹ˆλ‹€. μ΄λŸ¬ν•œ λŸ°νƒ€μž„ μ œμ–΄ μ›Œν¬ν”Œλ‘œμš°λŠ” 보톡 `system` λ„€μž„μŠ€νŽ˜μ΄μŠ€μ— μ •μ˜λ©λ‹ˆλ‹€. diff --git a/docs/key_concepts.md b/docs/key_concepts.md index c661d905..94b6d5bb 100644 --- a/docs/key_concepts.md +++ b/docs/key_concepts.md @@ -1,10 +1,10 @@ # πŸ“š Key Concepts -This guide provides detailed explanations of the key terms and concepts used in the system. +This guide provides a detailed explanation of the key terms and concepts used within the system. ## Node Specification -A node specification declaratively defines the behavior and connections of each node. The engine compiles this specification into executable nodes. +A node specification declaratively define how each node operates and connects. The engine compiles these specifications into executable nodes. ```yaml id: 01908c74-8b22-7cbf-a475-6b6bc871b01a @@ -27,18 +27,18 @@ env: ``` - `id`: A unique identifier in UUID format. UUID V7 is recommended. -- `kind`: Specifies the type of node. This example is a `listener`. Additional fields may vary based on the node type. -- `namespace`: The namespace to which the node belongs; the default is `default`. -- `name`: The name of the node, which must be unique within the namespace. -- `annotations`: Additional metadata about the node, including user-defined key-value pairs like description and version. -- `protocol`: Specifies the protocol used by the listener. This field is required for `listener` nodes. -- `port`: Specifies the port used by the listener. This field is required for `listener` nodes. -- `ports`: Defines the connection scheme of ports. `out` defines an output port named `proxy`, which connects to the `in` port of another node. -- `env`: Specifies environment variables needed by the node. Here, `PORT` is dynamically set from a secret. +- `kind`: Specifies the type of the node. Additional fields may vary based on the node type. +- `namespace`: Specifies the namespace to which the node belongs, defaulting to `default`. +- `name`: Specifies the name of the node, which must be unique within the same namespace. +- `annotations`: Additional metadata for the node, including user-defined key-value pairs such as description and version. +- `protocol`: Specifies the protocol used by the listener. This is an additional required field for nodes of the `listener` type. +- `port`: Specifies the port used by the listener. This is an additional required field for nodes of the `listener` type. +- `ports`: Defines how the ports are connected. `out` defines an output port named `proxy`, which connects to the `in` port of another node. +- `env`: Specifies the environment variables required by the node. In this case, `PORT` is dynamically set from a secret. ## Secret -A secret securely stores sensitive information needed by nodes, such as passwords and API keys. +A secret securely store sensitive information needed by nodes, such as passwords and API keys. ```yaml id: 01908c74-8b22-7cbf-a475-6b6bc871b01b @@ -51,65 +51,100 @@ data: ``` - `id`: A unique identifier in UUID format. UUID V7 is recommended. -- `namespace`: The namespace to which the secret belongs; the default is `default`. -- `name`: The name of the secret, which must be unique within the namespace. -- `annotations`: Additional metadata about the secret, including user-defined key-value pairs like description and version. -- `data`: Contains the secret data in key-value pairs. +- `namespace`: Specifies the namespace to which the secret belongs, defaulting to `default`. +- `name`: Specifies the name of the secret, which must be unique within the same namespace. +- `annotations`: Additional metadata for the secret, including user-defined key-value pairs such as description and version. +- `data`: Contains the secret data structured as key-value pairs. + +## Chart + +A chart defines a node that combines multiple node specifications to perform more complex operations. Charts are used to set up interactions between nodes. + +```yaml +id: 01908c74-8b22-7cbf-a475-6b6bc871b01b +namespace: default +name: sqlite +annotations: + version: "v1.0.0" +specs: + - kind: sql + name: sql + driver: sqlite3 + source: file::{{ .FILENAME }}:?cache=shared +ports: + in: + - name: sql + port: in + out: + - name: sql + port: out +env: + FILENAME: + value: "{{ .filename }}" +``` + +- `id`: A unique identifier in UUID format. UUID V7 is recommended. +- `namespace`: Specifies the namespace to which the chart belongs, defaulting to `default`. +- `name`: Specifies the name of the chart, which must be unique within the same namespace. This name becomes the type of the node specification. +- `annotations`: Additional metadata for the chart, including user-defined key-value pairs such as description and version. +- `specs`: Defines the node specifications that make up the chart. +- `ports`: Defines how the chart's ports connect. It specifies how external ports should connect to internal nodes. +- `env`: Specifies the environment variables required by the chart. If `id` and `name` are empty, this is used as an argument for node specifications that utilize this chart. ## Node -A node is an entity that processes data, exchanging packets through connected ports to execute workflows. Each node has an independent processing loop and communicates asynchronously with other nodes. +A node is an object that processes data, executing workflows by sending and receiving packets through connected ports. Each node has its own independent processing loop and communicates asynchronously with other nodes. -Nodes are classified based on their packet processing methods: -- `ZeroToOne`: Generates initial packets to start a workflow. -- `OneToOne`: Receives a packet from an input port, processes it, and sends it to an output port. -- `OneToMany`: Receives a packet from an input port and sends it to multiple output ports. -- `ManyToOne`: Receives packets from multiple input ports and sends a single packet to an output port. -- `Other`: Includes nodes that manage state and interactions beyond simple packet forwarding. +Nodes are classified based on how they process packets: +- `ZeroToOne`: A node that generates an initial packet to start the workflow. +- `OneToOne`: A node that receives packets from an input port, processes them, and sends them to an output port. +- `OneToMany`: A node that receives packets from an input port and sends them to multiple output ports. +- `ManyToOne`: A node that receives packets from multiple input ports and sends them to a single output port. +- `Other`: A node that includes state management and interaction beyond simple packet forwarding. ## Port -Ports are connection points for exchanging packets between nodes. There are two types of ports: `InPort` and `OutPort`. Packets sent to a port are delivered to all connected ports. +Ports are connection points for sending and receiving packets between nodes. There are two types of ports: `InPort` and `OutPort`, and packets are transmitted by connecting them. A packet sent to one port is forwarded to all connected ports. -Common port names include: -- `init`: A special port used to initialize a node. When the node becomes available, workflows connected to the `init` port are executed. -- `io`: Processes and immediately returns packets. -- `in`: Receives packets for processing and sends results to `out` or `error`. If `out` or `error` ports are not connected, the result is returned directly. -- `out`: Sends processed packets. The results can be sent back to another `in` port. -- `error`: Sends packets containing error information. Error handling results can be sent back to an `in` port. +Commonly used port names include: +- `init`: A special port used to initialize nodes. When the node becomes available, the workflow connected to the `init` port executes. +- `io`: Processes packets and returns them immediately. +- `in`: Receives packets for processing and sends the results to `out` or `error`. If there are no connected `out` or `error` ports, the result is returned directly. +- `out`: Sends processed packets. The transmitted result can be sent to other `in` ports. +- `error`: Sends errors encountered during packet processing. Error handling results can be sent back to an `in` port. -When multiple ports with the same role are needed, they can be expressed as `in[0]`, `in[1]`, `out[0]`, `out[1]`, etc. +When multiple ports with the same role are needed, they are expressed as `in[0]`, `in[1]`, `out[0]`, `out[1]`, etc. ## Packet -A packet is a unit of data exchanged between ports. Each packet contains a payload, which nodes process and transmit. +A packet is a unit of data exchanged between ports. Each packet includes a payload, which the node processes before transmission. -Nodes must return response packets in the order of received request packets. When connected to multiple ports, all response packets are collected and returned as a new response packet. +Nodes must return response packets in the order of the request packets. If connected to multiple ports, all response packets are gathered and returned as a single new response packet. -A special `None` packet indicates no response, simply acknowledging the packet's acceptance. +A special `None` packet indicates that there is no response, merely indicating that the packet was accepted. ## Process -A process is the fundamental unit of execution, managed independently. Processes can have parent processes, and when a parent process terminates, its child processes also terminate. +A process is the basic unit of execution, managed independently. A process may have a parent process, and when the parent terminates, the child process also terminates. -Processes have their own storage to retain values that are difficult to transmit via packets. This storage operates using a Copy-On-Write (COW) mechanism to efficiently share data from parent processes. +Processes maintain their own storage to store values that are difficult to transmit as packets. This storage operates on a Copy-On-Write (COW) basis, efficiently sharing data from the parent process. -A new workflow begins by creating a process. When a process ends, all resources used by it are released. +A new workflow is initiated by creating a process. When the process terminates, all resources used are released. -Processes can have multiple root packets, but root packets must originate from the same node. If they come from different nodes, a new child process must be created to handle them. +Processes can have two or more root packets, but the root packets must be generated by the same node. If generated by different nodes, a new child process must be created to handle them. ## Workflow -A workflow is defined as a directed graph with multiple interconnected nodes. Each node processes data, and packets flow between nodes. +A workflow is defined as a directed graph, a structure where multiple nodes are interconnected. In this graph, each node is responsible for data processing, and packets are transmitted between nodes. -Workflows consist of multiple stages, with data processed and transmitted according to defined rules at each stage. Data can be processed sequentially or in parallel during this process. +Workflows consist of multiple stages, where data is processed and passed according to defined rules. In this process, data can be processed sequentially or in parallel. -For example, given initial data, it is processed by the first node and then forwarded to the next node. Each node receives input, processes it, and sends the processed result to the next stage. +For example, given initial data, it is processed by the first node before being passed to the next node. Each node receives input, processes it, and sends the result to the next stage. ## Namespace -A namespace manages workflows in isolation, providing an independent execution environment. Each namespace can contain multiple workflows, and nodes within a namespace cannot reference nodes from another namespace. Each namespace independently manages its data and resources. +A namespace serves to isolate and manage workflows, offering independent execution environments. It can house multiple workflows, ensuring that nodes within a namespace cannot reference nodes from other namespaces. Each namespace independently manages its own data and resources, allowing for streamlined operations and clear boundaries between workflows. ## Runtime Environment -A runtime environment is an independent space where each namespace is executed. The engine loads all nodes within the namespace to build the environment and execute workflows. This prevents conflicts during workflow execution and ensures a stable execution environment. +The runtime environment provides an independent execution context for each namespace, ensuring that workflows within namespaces operate without interference. This environment includes the necessary resources and configurations for the execution of nodes and processes, facilitating the smooth operation of workflows within the system. diff --git a/docs/key_concepts_kr.md b/docs/key_concepts_kr.md index 5380e595..1080849c 100644 --- a/docs/key_concepts_kr.md +++ b/docs/key_concepts_kr.md @@ -56,6 +56,41 @@ data: - `annotations`: μ‹œν¬λ¦Ώμ— λŒ€ν•œ μΆ”κ°€ λ©”νƒ€λ°μ΄ν„°μž…λ‹ˆλ‹€. μ„€λͺ…, 버전 λ“± μ‚¬μš©μž μ •μ˜ ν‚€-κ°’ μŒμ„ 포함할 수 μžˆμŠ΅λ‹ˆλ‹€. - `data`: ν‚€-κ°’ 쌍으둜 κ΅¬μ„±λœ μ‹œν¬λ¦Ώ 데이터λ₯Ό ν¬ν•¨ν•©λ‹ˆλ‹€. +## 차트 + +μ°¨νŠΈλŠ” μ—¬λŸ¬ 개의 λ…Έλ“œ λͺ…μ„Έλ₯Ό κ²°ν•©ν•˜μ—¬ 더 λ³΅μž‘ν•œ λ™μž‘μ„ μˆ˜ν–‰ν•˜λŠ” λ…Έλ“œλ₯Ό μ •μ˜ν•©λ‹ˆλ‹€. μ°¨νŠΈλŠ” λ…Έλ“œλ“€ κ°„μ˜ μƒν˜Έ μž‘μš©μ„ μ„€μ •ν•˜λŠ” 데 μ‚¬μš©λ©λ‹ˆλ‹€. + +```yaml +id: 01908c74-8b22-7cbf-a475-6b6bc871b01b +namespace: default +name: sqlite +annotations: + version: "v1.0.0" +specs: + - kind: sql + name: sql + driver: sqlite3 + source: file::{{ .FILENAME }}:?cache=shared +ports: + in: + - name: sql + port: in + out: + - name: sql + port: out +env: + FILENAME: + value: "{{ .filename }}" +``` + +- `id`: UUID ν˜•μ‹μ˜ 고유 μ‹λ³„μžμž…λ‹ˆλ‹€. UUID V7을 ꢌμž₯ν•©λ‹ˆλ‹€. +- `namespace`: μ°¨νŠΈκ°€ μ†ν•œ λ„€μž„μŠ€νŽ˜μ΄μŠ€λ₯Ό μ§€μ •ν•˜λ©°, 기본값은 `default`μž…λ‹ˆλ‹€. +- `name`: 차트의 이름을 μ§€μ •ν•˜λ©°, λ™μΌν•œ λ„€μž„μŠ€νŽ˜μ΄μŠ€ λ‚΄μ—μ„œ κ³ μœ ν•΄μ•Ό ν•©λ‹ˆλ‹€. 이 이름이 λ…Έλ“œ λͺ…μ„Έμ˜ μœ ν˜•μ΄ λ©λ‹ˆλ‹€. +- `annotations`: μ°¨νŠΈμ— λŒ€ν•œ μΆ”κ°€ λ©”νƒ€λ°μ΄ν„°μž…λ‹ˆλ‹€. μ„€λͺ…, 버전 λ“± μ‚¬μš©μž μ •μ˜ ν‚€-κ°’ μŒμ„ 포함할 수 μžˆμŠ΅λ‹ˆλ‹€. +- `specs`: 차트λ₯Ό κ΅¬μ„±ν•˜λŠ” λ…Έλ“œ λͺ…μ„Έλ₯Ό μ •μ˜ν•©λ‹ˆλ‹€. +- `ports`: 차트의 μ—°κ²° 방식을 μ •μ˜ν•©λ‹ˆλ‹€. μ™ΈλΆ€λ‘œ λ…ΈμΆœλ  ν¬νŠΈκ°€ λ‚΄λΆ€μ˜ μ–΄λ–€ λ…Έλ“œμ™€ μ—°κ²°λ˜μ–΄μ•Ό ν•˜λŠ”μ§€ μ •μ˜ν•©λ‹ˆλ‹€. +- `env`: μ°¨νŠΈμ— ν•„μš”ν•œ ν™˜κ²½ λ³€μˆ˜λ₯Ό μ§€μ •ν•©λ‹ˆλ‹€. `id`와 `name`이 λΉ„μ–΄μ Έ μžˆλ‹€λ©΄ 이 차트λ₯Ό ν™œμš©ν•˜λŠ” λ…Έλ“œ λͺ…μ„Έκ°€ 값을 ν‰κ°€ν•˜κΈ° μœ„ν•œ 인자둜 μ‚¬μš©λ©λ‹ˆλ‹€. + ## λ…Έλ“œ λ…Έλ“œλŠ” 데이터λ₯Ό μ²˜λ¦¬ν•˜λŠ” 객체둜, μ„œλ‘œ μ—°κ²°λœ 포트λ₯Ό 톡해 νŒ¨ν‚·μ„ μ£Όκ³ λ°›μœΌλ©° μ›Œν¬ν”Œλ‘œμš°λ₯Ό μ‹€ν–‰ν•©λ‹ˆλ‹€. 각 λ…Έλ“œλŠ” 독립적인 처리 루프λ₯Ό 가지며, λΉ„λ™κΈ°μ μœΌλ‘œ λ‹€λ₯Έ λ…Έλ“œμ™€ ν†΅μ‹ ν•©λ‹ˆλ‹€. diff --git a/pkg/runtime/runtime.go b/pkg/runtime/runtime.go index 5ff1cd87..2ba125e9 100644 --- a/pkg/runtime/runtime.go +++ b/pkg/runtime/runtime.go @@ -111,6 +111,9 @@ func New(config Config) *Runtime { // Load loads symbols from the spec store into the symbol table. func (r *Runtime) Load(ctx context.Context) error { + if err := r.chartLoader.Load(ctx, &chart.Chart{Namespace: r.namespace}); err != nil { + return err + } return r.symbolLoader.Load(ctx, &spec.Meta{Namespace: r.namespace}) }