From 659f761a117fbc2cab2812bff063e96def28fb52 Mon Sep 17 00:00:00 2001 From: seal90 <578935869@qq.com> Date: Sat, 6 Dec 2025 03:21:46 +0000 Subject: [PATCH 1/2] add structformat doc Signed-off-by: seal90 <578935869@qq.com> --- .../nr-structformat.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-structformat.md diff --git a/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-structformat.md b/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-structformat.md new file mode 100644 index 00000000000..f76de822d3a --- /dev/null +++ b/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-structformat.md @@ -0,0 +1,84 @@ +--- +type: docs +title: "StructuredFormat" +linkTitle: "StructuredFormat" +description: Detailed information on the StructuredFormat name resolution component +--- + + +The Structured Format name resolver provides a flexible way to resolve service names using predefined JSON or YAML format templates. It is particularly useful in scenarios where no dedicated service registry is available. + +## Configuration + +Name resolution is configured via the [Dapr Configuration]({{< ref configuration-overview.md >}}). + +Within the configuration YAML, set the `spec.nameResolution.component` property to `"structuredformat"`, then pass configuration options in the `spec.nameResolution.configuration` dictionary. + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: appconfig +spec: + nameResolution: + component: "structuredformat" + configuration: + structuredType: "jsonString" + stringValue: '{"appInstances":{"myapp":[{"domain":"","ipv4":"127.0.0.1","ipv6":"","port":4433,"extendedInfo":{"hello":"world"}}]}}' +``` + +## Spec configuration fields + +| Field | Required | Details | Example | +|---------|----------|---------|---------| +| structuredType | Y | Structured type: jsonString, yamlString, jsonFile, yamlFile. | jsonString | +| stringValue | N | This field must be configured when structuredType is set to jsonString or yamlString. | {"appInstances":{"myapp":[{"domain":"","ipv4":"127.0.0.1","ipv6":"","port":4433,"extendedInfo":{"hello":"world"}}]}} | +| filePath | N | This field must be configured when structuredType is set to jsonFile or yamlFile. | /path/to/yamlfile.yaml | + +## Examples + +Service ID "myapp" → "127.0.0.1:4433" + +- By jsonString +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: appconfig +spec: + nameResolution: + component: "structuredformat" + configuration: + structuredType: "jsonString" + stringValue: '{"appInstances":{"myapp":[{"domain":"","ipv4":"127.0.0.1","ipv6":"","port":4433,"extendedInfo":{"hello":"world"}}]}}' +``` + +- By yamlString + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: appconfig +spec: + nameResolution: + component: "structuredformat" + configuration: + structuredType: "yamlString" + stringValue: | + appInstances: + myapp: + - domain: "" + ipv4: "127.0.0.1" + ipv6: "" + port: 4433 + extendedInfo: + hello: world +``` + +## Notes + +- Empty service IDs are not allowed and will result in an error +- Accessing a non-existent service will also result in an error +- The structured format string must be provided in the configuration +- The program selects the first available address according to the priority order: domain → IPv4 → IPv6, and appends the port to form the final target address From 0b599d8c6bfd1eabbd13751f07dc72a1eccf1b00 Mon Sep 17 00:00:00 2001 From: seal90 <578935869@qq.com> Date: Sat, 13 Dec 2025 03:56:09 +0000 Subject: [PATCH 2/2] optimize structuredformat docs Signed-off-by: seal90 <578935869@qq.com> --- .../nr-structformat.md | 84 ------------- .../nr-structuredformat.md | 113 ++++++++++++++++++ 2 files changed, 113 insertions(+), 84 deletions(-) delete mode 100644 daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-structformat.md create mode 100644 daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-structuredformat.md diff --git a/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-structformat.md b/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-structformat.md deleted file mode 100644 index f76de822d3a..00000000000 --- a/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-structformat.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -type: docs -title: "StructuredFormat" -linkTitle: "StructuredFormat" -description: Detailed information on the StructuredFormat name resolution component ---- - - -The Structured Format name resolver provides a flexible way to resolve service names using predefined JSON or YAML format templates. It is particularly useful in scenarios where no dedicated service registry is available. - -## Configuration - -Name resolution is configured via the [Dapr Configuration]({{< ref configuration-overview.md >}}). - -Within the configuration YAML, set the `spec.nameResolution.component` property to `"structuredformat"`, then pass configuration options in the `spec.nameResolution.configuration` dictionary. - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Configuration -metadata: - name: appconfig -spec: - nameResolution: - component: "structuredformat" - configuration: - structuredType: "jsonString" - stringValue: '{"appInstances":{"myapp":[{"domain":"","ipv4":"127.0.0.1","ipv6":"","port":4433,"extendedInfo":{"hello":"world"}}]}}' -``` - -## Spec configuration fields - -| Field | Required | Details | Example | -|---------|----------|---------|---------| -| structuredType | Y | Structured type: jsonString, yamlString, jsonFile, yamlFile. | jsonString | -| stringValue | N | This field must be configured when structuredType is set to jsonString or yamlString. | {"appInstances":{"myapp":[{"domain":"","ipv4":"127.0.0.1","ipv6":"","port":4433,"extendedInfo":{"hello":"world"}}]}} | -| filePath | N | This field must be configured when structuredType is set to jsonFile or yamlFile. | /path/to/yamlfile.yaml | - -## Examples - -Service ID "myapp" → "127.0.0.1:4433" - -- By jsonString -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Configuration -metadata: - name: appconfig -spec: - nameResolution: - component: "structuredformat" - configuration: - structuredType: "jsonString" - stringValue: '{"appInstances":{"myapp":[{"domain":"","ipv4":"127.0.0.1","ipv6":"","port":4433,"extendedInfo":{"hello":"world"}}]}}' -``` - -- By yamlString - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Configuration -metadata: - name: appconfig -spec: - nameResolution: - component: "structuredformat" - configuration: - structuredType: "yamlString" - stringValue: | - appInstances: - myapp: - - domain: "" - ipv4: "127.0.0.1" - ipv6: "" - port: 4433 - extendedInfo: - hello: world -``` - -## Notes - -- Empty service IDs are not allowed and will result in an error -- Accessing a non-existent service will also result in an error -- The structured format string must be provided in the configuration -- The program selects the first available address according to the priority order: domain → IPv4 → IPv6, and appends the port to form the final target address diff --git a/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-structuredformat.md b/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-structuredformat.md new file mode 100644 index 00000000000..b122727ba7d --- /dev/null +++ b/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-structuredformat.md @@ -0,0 +1,113 @@ +--- +type: docs +title: "StructuredFormat" +linkTitle: "StructuredFormat" +description: Detailed information on the StructuredFormat name resolution component +--- + + +The **Structured Format** name resolver enables you to explicitly define service instances using structured configuration in **JSON or YAML**, either as inline strings or external files. It is designed for scenarios where service topology is **static and known in advance**, such as: + +- Local development and testing +- Integration or end-to-end test environments +- Edge deployments + +## Configuration format + +Name resolution is configured via the [Dapr Configuration]({{< ref configuration-overview.md >}}). + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: appconfig +spec: + nameResolution: + component: "structuredformat" + configuration: + structuredType: "json" # or "yaml", "jsonFile", "yamlFile" + stringValue: '{"appInstances":{"myapp":[{"ipv4":"127.0.0.1","port":4433}]}}' +``` + +## Spec configuration fields + +| Field | Required? | Description | Example | +|------------------|-----------|-----------------------------------------------------------------------------|---------| +| `structuredType` | Yes | Format and source type. Must be one of: `json`, `yaml`, `jsonFile`, `yamlFile` | `json` | +| `stringValue` | Conditional | Required when `structuredType` is `json` or `yaml` | `{"appInstances":{"myapp":[{"ipv4":"127.0.0.1","port":4433}]}}` | +| `filePath` | Conditional | Required when `structuredType` is `jsonFile` or `yamlFile` | `/etc/dapr/services.yaml` | + +> **Important**: Only one of `stringValue` or `filePath` should be provided, based on `structuredType`. + +## `appInstances` Schema + +The configuration must contain a top-level `appInstances` object that maps **service IDs** to **lists of address instances**. + +### Supported Address Fields + +| Field | Type | Required? | Description | +|----------|--------|-----------|-------------| +| `domain` | string | No | Hostname or FQDN (e.g., `"api.example.com"`). Highest priority. | +| `ipv4` | string | No | IPv4 address in dotted-decimal format (e.g., `"192.168.1.10"`). | +| `ipv6` | string | No | Unbracketed IPv6 address (e.g., `"::1"`, `"2001:db8::1"`). | +| `port` | int | **Yes** | TCP port number (**must be 1–65535**). | + +> **Notes**: +> - Service IDs must be non-empty strings. +> - **At least one** of `domain`, `ipv4`, or `ipv6` must be non-empty per instance. +> - Invalid or missing ports will cause initialization to fail. + +## Address Selection Logic + +For each instance, the resolver selects the **first non-empty address** in this priority order: + +1. `domain` → e.g., `github.com` +2. `ipv4` → e.g., `192.168.1.10` +3. `ipv6` → e.g., `::1` + +The final target address is formatted as: + +- `host:port` for domain/IPv4 +- `[ipv6]:port` for IPv6 (automatically bracketed) + +If a service has **multiple instances**, one is selected **uniformly at random** on each call. + +## Examples + +### Inline JSON +```yaml +configuration: + structuredType: "json" + stringValue: '{"appInstances":{"myapp":[{"ipv4":"127.0.0.1","port":4433}]}}' +``` +→ Resolves `"myapp"` to `127.0.0.1:4433` + +### Inline YAML (multi-line) +```yaml +configuration: + structuredType: "yaml" + stringValue: | + appInstances: + myapp: + - domain: "example.com" + port: 80 + - ipv6: "::1" + port: 8080 +``` +→ Possible results: `example.com:80` or `[::1]:8080` (chosen randomly) + +### From External File +```yaml +configuration: + structuredType: "yamlFile" + filePath: "/etc/dapr/services.yaml" +``` + +With `/etc/dapr/services.yaml`: +```yaml +appInstances: + backend: + - ipv4: "10.0.0.5" + port: 3000 +``` +→ Resolves `"backend"` to `10.0.0.5:3000`