From 9c848c714dfce0dbb95895232fc48db735601a85 Mon Sep 17 00:00:00 2001 From: liuhaoming Date: Tue, 2 Jul 2024 14:18:59 +0800 Subject: [PATCH 1/2] feat: update kusion module develop guide --- .../3-concepts/3-module/2-develop-guide.md | 57 +++++++++++++++++++ .../3-concepts/3-module/3-app-dev-guide.md | 1 - .../3-concepts/3-module/2-develop-guide.md | 57 +++++++++++++++++++ .../3-concepts/3-module/3-app-dev-guide.md | 3 +- 4 files changed, 115 insertions(+), 3 deletions(-) diff --git a/docs/kusion/3-concepts/3-module/2-develop-guide.md b/docs/kusion/3-concepts/3-module/2-develop-guide.md index 3e885968..d753a884 100644 --- a/docs/kusion/3-concepts/3-module/2-develop-guide.md +++ b/docs/kusion/3-concepts/3-module/2-develop-guide.md @@ -141,6 +141,63 @@ 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, 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. + +In addition, please note that: + +- 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` + +- 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). diff --git a/docs/kusion/3-concepts/3-module/3-app-dev-guide.md b/docs/kusion/3-concepts/3-module/3-app-dev-guide.md index abf6b3b4..3169c67c 100644 --- a/docs/kusion/3-concepts/3-module/3-app-dev-guide.md +++ b/docs/kusion/3-concepts/3-module/3-app-dev-guide.md @@ -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 diff --git a/docs_versioned_docs/version-v0.12/3-concepts/3-module/2-develop-guide.md b/docs_versioned_docs/version-v0.12/3-concepts/3-module/2-develop-guide.md index 3e885968..d753a884 100644 --- a/docs_versioned_docs/version-v0.12/3-concepts/3-module/2-develop-guide.md +++ b/docs_versioned_docs/version-v0.12/3-concepts/3-module/2-develop-guide.md @@ -141,6 +141,63 @@ 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, 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. + +In addition, please note that: + +- 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` + +- 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). diff --git a/docs_versioned_docs/version-v0.12/3-concepts/3-module/3-app-dev-guide.md b/docs_versioned_docs/version-v0.12/3-concepts/3-module/3-app-dev-guide.md index c1eef5b1..f362c2c1 100644 --- a/docs_versioned_docs/version-v0.12/3-concepts/3-module/3-app-dev-guide.md +++ b/docs_versioned_docs/version-v0.12/3-concepts/3-module/3-app-dev-guide.md @@ -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 a developer, the workflow of developing 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 From e0ef0637fa9c151f3fbba9a890486e89a13f9d54 Mon Sep 17 00:00:00 2001 From: liuhaoming Date: Wed, 3 Jul 2024 11:47:09 +0800 Subject: [PATCH 2/2] fix: kusion module develop guide docs --- .../3-concepts/3-module/2-develop-guide.md | 22 ++++++++++++++----- .../3-concepts/3-module/2-develop-guide.md | 22 ++++++++++++++----- .../3-concepts/3-module/3-app-dev-guide.md | 2 +- 3 files changed, 33 insertions(+), 13 deletions(-) diff --git a/docs/kusion/3-concepts/3-module/2-develop-guide.md b/docs/kusion/3-concepts/3-module/2-develop-guide.md index d753a884..977d9457 100644 --- a/docs/kusion/3-concepts/3-module/2-develop-guide.md +++ b/docs/kusion/3-concepts/3-module/2-develop-guide.md @@ -143,13 +143,23 @@ In the `GeneratorResponse`, there are two fields, `Resources` and `Patchers`. Th ### Implicit Resource Dependency -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. +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: -In addition, please note that: +```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 +``` -- 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` +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: +- 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`. @@ -170,7 +180,7 @@ spec: $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: +- 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. @@ -184,7 +194,7 @@ spec: 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: +- 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. diff --git a/docs_versioned_docs/version-v0.12/3-concepts/3-module/2-develop-guide.md b/docs_versioned_docs/version-v0.12/3-concepts/3-module/2-develop-guide.md index d753a884..977d9457 100644 --- a/docs_versioned_docs/version-v0.12/3-concepts/3-module/2-develop-guide.md +++ b/docs_versioned_docs/version-v0.12/3-concepts/3-module/2-develop-guide.md @@ -143,13 +143,23 @@ In the `GeneratorResponse`, there are two fields, `Resources` and `Patchers`. Th ### Implicit Resource Dependency -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. +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: -In addition, please note that: +```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 +``` -- 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` +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: +- 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`. @@ -170,7 +180,7 @@ spec: $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: +- 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. @@ -184,7 +194,7 @@ spec: 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: +- 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. diff --git a/docs_versioned_docs/version-v0.12/3-concepts/3-module/3-app-dev-guide.md b/docs_versioned_docs/version-v0.12/3-concepts/3-module/3-app-dev-guide.md index f362c2c1..3169c67c 100644 --- a/docs_versioned_docs/version-v0.12/3-concepts/3-module/3-app-dev-guide.md +++ b/docs_versioned_docs/version-v0.12/3-concepts/3-module/3-app-dev-guide.md @@ -8,7 +8,7 @@ To follow this guide, you will need: ## Workflow -As a developer, 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