Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions docs/kusion/3-concepts/3-module/2-develop-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,73 @@ type Patcher struct {
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.
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.

### Implicit Resource Dependency

When you need to use an attribute of another resource as the value of a specific resource attribute, Kusion supports declaring the implicit resource dependencies with the `$kusion_path` prefix. You can concatenate the implicit resource dependency path with the resource `id`, attribute `name` and the `$kusion_path` prefix, for example:

```yaml
# Dependency path as an attribute value.
spec:
resources:
- id: v1:Service:test-ns:test-service
type: Kubernetes
attributes:
metadata:
annotations:
deployment-name: $kusion_path.v1:Deployment:test-ns:test-deployment.metadata.name
```

In addition, please note that:

- 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**:

```yaml
# Dependency path not in `attributes`.
spec:
resources:
- id: v1:Service:test:$kusion_path.apps/v1:Deployment:test-ns:test-deployment.metadata.name
```

```yaml
# Dependency path in the key, but not in the value.
spec:
resources:
- id: apps/v1:Deployment:test-ns:test-deployment
type: Kubernetes
attributes:
metadata:
annotations:
$kusion_path.v1:Service:test-ns:test-service.metadata.name: test-svc
```

- 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**:

```yaml
# Dependency path combined with other string.
spec:
resources:
- id: apps/v1:Deployment:test-ns:test-deployment
type: Kubernetes
attributes:
metadata:
annotations:
test-svc: $kusion_path.v1:Service:test-ns:test-service.metadata.name + "-test"
```

- The impliciy resource dependency path does not support accessing the value in an array, so the following is currently **invalid**:

```yaml
# Dependency path accessing the value in an array.
spec:
resources:
- id: apps/v1:Deployment:test-ns:test-deployment
type: Kubernetes
attributes:
metadata:
annotations:
test-svc: $kusion_path.v1:Service:test-ns:test-service.spec.ports[0].name
```

## Publish

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).
Expand Down
1 change: 0 additions & 1 deletion docs/kusion/3-concepts/3-module/3-app-dev-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@

To follow this guide, you will need:

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

## Workflow
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,73 @@ type Patcher struct {
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.
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.

### Implicit Resource Dependency

When you need to use an attribute of another resource as the value of a specific resource attribute, Kusion supports declaring the implicit resource dependencies with the `$kusion_path` prefix. You can concatenate the implicit resource dependency path with the resource `id`, attribute `name` and the `$kusion_path` prefix, for example:

```yaml
# Dependency path as an attribute value.
spec:
resources:
- id: v1:Service:test-ns:test-service
type: Kubernetes
attributes:
metadata:
annotations:
deployment-name: $kusion_path.v1:Deployment:test-ns:test-deployment.metadata.name
```

In addition, please note that:

- 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**:

```yaml
# Dependency path not in `attributes`.
spec:
resources:
- id: v1:Service:test:$kusion_path.apps/v1:Deployment:test-ns:test-deployment.metadata.name
```

```yaml
# Dependency path in the key, but not in the value.
spec:
resources:
- id: apps/v1:Deployment:test-ns:test-deployment
type: Kubernetes
attributes:
metadata:
annotations:
$kusion_path.v1:Service:test-ns:test-service.metadata.name: test-svc
```

- 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**:

```yaml
# Dependency path combined with other string.
spec:
resources:
- id: apps/v1:Deployment:test-ns:test-deployment
type: Kubernetes
attributes:
metadata:
annotations:
test-svc: $kusion_path.v1:Service:test-ns:test-service.metadata.name + "-test"
```

- The impliciy resource dependency path does not support accessing the value in an array, so the following is currently **invalid**:

```yaml
# Dependency path accessing the value in an array.
spec:
resources:
- id: apps/v1:Deployment:test-ns:test-deployment
type: Kubernetes
attributes:
metadata:
annotations:
test-svc: $kusion_path.v1:Service:test-ns:test-service.spec.ports[0].name
```

## Publish

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).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,11 @@

To follow this guide, you will need:

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

## Workflow

As a platform engineer, the workflow of developing a Kusion module looks like this:
As an application developer, the workflow of using a Kusion module looks like this:

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