Skip to content

Commit 7da6c31

Browse files
committed
feat: update kusion module develop guide
1 parent 2095ba2 commit 7da6c31

File tree

4 files changed

+116
-4
lines changed

4 files changed

+116
-4
lines changed

docs/kusion/3-concepts/3-module/2-develop-guide.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,63 @@ type Patcher struct {
141141
The `GeneratorRequest` contains the application developer's config, platform engineer's config, workload config and related metadata a module could need to generate infrastructure resources.
142142
In the `GeneratorResponse`, there are two fields, `Resources` and `Patchers`. The `Resource` represents resources that should operated by Kusion and they will be appended into the [Spec](../spec). The `Patchers` are used to patch the workload and other resources.
143143

144+
### Implicit Resource Dependency
145+
146+
When you need to use an attribute of another resource as the value of a specific resource, Kusion supports declaring the implicit resource dependencies through `$kusion_path`. You can call the `modules.KusionPathDependency` method of the `kusionstack.io/kusion` package, passing in the resource `id` and the `name` of the attribute you want to reference, and this method will return the corresponding implicit resource dependency path.
147+
148+
In addition, please note that:
149+
150+
- You can concatenate the implicit resource dependency path with the resource `id`, attribute `name` and the `$kusion_path` prefix yourself. And the attribute name can be any number, for example `$kusion_path.v1:Service:test-ns:test-service.metadata.name`
151+
152+
- The implicit resource dependency path can only be used to replace the value in `Attributes` field of the `Resource`, but not the key. For example, the following `Spec` is invalid:
153+
154+
```yaml
155+
# Dependency path not in `attributes`.
156+
spec:
157+
resources:
158+
- id: v1:Service:test:$kusion_path.apps/v1:Deployment:test-ns:test-deployment.metadata.name
159+
```
160+
161+
```yaml
162+
# Dependency path in the key, but not in the value.
163+
spec:
164+
resources:
165+
- id: apps/v1:Deployment:test-ns:test-deployment
166+
type: Kubernetes
167+
attributes:
168+
metadata:
169+
annotations:
170+
$kusion_path.v1:Service:test-ns:test-service.metadata.name: test-svc
171+
```
172+
173+
- The implicit resource dependency path can only be used as a standalone value and cannot be combined with other string. For example, the following `Spec` is invalid:
174+
175+
```yaml
176+
# Dependency path combined with other string.
177+
spec:
178+
resources:
179+
- id: apps/v1:Deployment:test-ns:test-deployment
180+
type: Kubernetes
181+
attributes:
182+
metadata:
183+
annotations:
184+
test-svc: $kusion_path.v1:Service:test-ns:test-service.metadata.name + "-test"
185+
```
186+
187+
- The impliciy resource dependency path does not support accessing the value in an array, so the following is currently invalid:
188+
189+
```yaml
190+
# Dependency path accessing the value in an array.
191+
spec:
192+
resources:
193+
- id: apps/v1:Deployment:test-ns:test-deployment
194+
type: Kubernetes
195+
attributes:
196+
metadata:
197+
annotations:
198+
test-svc: $kusion_path.v1:Service:test-ns:test-service.spec.ports[0].name
199+
```
200+
144201
## Publish
145202

146203
Publish the Kusion module to an OCI registry with the command `kusion mod push`. If your module is open to the public, we **welcome and highly encourage** you to contribute it to the module registry [catalog](https://github.com/KusionStack/catalog), so that more people can benefit from the module. Submit a pull request to this repository, once it is merged, it will be published to the [KusionStack GitHub container registry](https://github.com/orgs/KusionStack/packages).

docs/kusion/3-concepts/3-module/3-app-dev-guide.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,11 @@
44

55
To follow this guide, you will need:
66

7-
- Go 1.22 or higher installed and configured
87
- Kusion v0.12 or higher installed locally
98

109
## Workflow
1110

12-
As a platform engineer, the workflow of developing a Kusion module looks like this:
11+
As a developer, the workflow of developing a Kusion module looks like this:
1312

1413
1. Browse available modules registered by platform engineers in the workspace
1514
2. Add modules you need to your Stack

docs_versioned_docs/version-v0.12/3-concepts/3-module/2-develop-guide.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,63 @@ type Patcher struct {
141141
The `GeneratorRequest` contains the application developer's config, platform engineer's config, workload config and related metadata a module could need to generate infrastructure resources.
142142
In the `GeneratorResponse`, there are two fields, `Resources` and `Patchers`. The `Resource` represents resources that should operated by Kusion and they will be appended into the [Spec](../spec). The `Patchers` are used to patch the workload and other resources.
143143

144+
### Implicit Resource Dependency
145+
146+
When you need to use an attribute of another resource as the value of a specific resource, Kusion supports declaring the implicit resource dependencies through `$kusion_path`. You can call the `modules.KusionPathDependency` method of the `kusionstack.io/kusion` package, passing in the resource `id` and the `name` of the attribute you want to reference, and this method will return the corresponding implicit resource dependency path.
147+
148+
In addition, please note that:
149+
150+
- You can concatenate the implicit resource dependency path with the resource `id`, attribute `name` and the `$kusion_path` prefix yourself. And the attribute name can be any number, for example `$kusion_path.v1:Service:test-ns:test-service.metadata.name`
151+
152+
- The implicit resource dependency path can only be used to replace the value in `Attributes` field of the `Resource`, but not the key. For example, the following `Spec` is invalid:
153+
154+
```yaml
155+
# Dependency path not in `attributes`.
156+
spec:
157+
resources:
158+
- id: v1:Service:test:$kusion_path.apps/v1:Deployment:test-ns:test-deployment.metadata.name
159+
```
160+
161+
```yaml
162+
# Dependency path in the key, but not in the value.
163+
spec:
164+
resources:
165+
- id: apps/v1:Deployment:test-ns:test-deployment
166+
type: Kubernetes
167+
attributes:
168+
metadata:
169+
annotations:
170+
$kusion_path.v1:Service:test-ns:test-service.metadata.name: test-svc
171+
```
172+
173+
- The implicit resource dependency path can only be used as a standalone value and cannot be combined with other string. For example, the following `Spec` is invalid:
174+
175+
```yaml
176+
# Dependency path combined with other string.
177+
spec:
178+
resources:
179+
- id: apps/v1:Deployment:test-ns:test-deployment
180+
type: Kubernetes
181+
attributes:
182+
metadata:
183+
annotations:
184+
test-svc: $kusion_path.v1:Service:test-ns:test-service.metadata.name + "-test"
185+
```
186+
187+
- The impliciy resource dependency path does not support accessing the value in an array, so the following is currently invalid:
188+
189+
```yaml
190+
# Dependency path accessing the value in an array.
191+
spec:
192+
resources:
193+
- id: apps/v1:Deployment:test-ns:test-deployment
194+
type: Kubernetes
195+
attributes:
196+
metadata:
197+
annotations:
198+
test-svc: $kusion_path.v1:Service:test-ns:test-service.spec.ports[0].name
199+
```
200+
144201
## Publish
145202

146203
Publish the Kusion module to an OCI registry with the command `kusion mod push`. If your module is open to the public, we **welcome and highly encourage** you to contribute it to the module registry [catalog](https://github.com/KusionStack/catalog), so that more people can benefit from the module. Submit a pull request to this repository, once it is merged, it will be published to the [KusionStack GitHub container registry](https://github.com/orgs/KusionStack/packages).

docs_versioned_docs/version-v0.12/3-concepts/3-module/3-app-dev-guide.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,11 @@
44

55
To follow this guide, you will need:
66

7-
- Go 1.22 or higher installed and configured
87
- Kusion v0.12 or higher installed locally
98

109
## Workflow
1110

12-
As a platform engineer, the workflow of developing a Kusion module looks like this:
11+
As a developer, the workflow of developing a Kusion module looks like this:
1312

1413
1. Browse available modules registered by platform engineers in the workspace
1514
2. Add modules you need to your Stack

0 commit comments

Comments
 (0)