From 7adee4bd2c11c3161b3fc143a6729eb24b00418b Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Thu, 21 May 2026 13:51:37 +0200 Subject: [PATCH 01/17] add acceptPush --- .../docs/user-guide/targetsource/http.md | 52 ++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/docs/content/docs/user-guide/targetsource/http.md b/docs/content/docs/user-guide/targetsource/http.md index b5ff3d02..041bd1bc 100644 --- a/docs/content/docs/user-guide/targetsource/http.md +++ b/docs/content/docs/user-guide/targetsource/http.md @@ -20,7 +20,7 @@ spec: | Field | Type | Required | Description | |-------|------|----------|-------------| | `url` | string | Yes | URL pointing to the inventory server | -| `acceptPush` | bool | No | Enable webhook-based target updates. Defaults to `false`. | +| `acceptPush` | bool | No | Enable webhook-based target updates. Defaults to `false`. See _acceptPush_ section.| | `authorization` | object | No | Credentials used to access the HTTP endpoint. See _Authorization_ section. | | `pollInterval` | duration | No | Polling interval used to fetch targets from the endpoint. Defaults to `30s`. | | `timeout` | duration | No | Timeout for HTTP requests. Defaults to `10s`. | @@ -222,3 +222,53 @@ spec: | `port` | string | No | JSONPath expression extracting the gNMI port | | `targetProfile` | string | No | JSONPath expression extracting the `TargetProfile` | | `labels` | map[string]string | No | JSONPath expressions extracting target labels | + +## AcceptPush + +Setting acceptPush `True` to true, will enable an REST API endpoint. This allows real-time target updates from a Webhook (or any other application that can send HTTP requests) using `HTTP POST` requests. The API is defined as an openAPI contract. + +### URL + +The URL is `http://:8082/api/v1//target-source//createTargets`. + +- _clusterAddress_: Address of the kubernetes cluster. +- _namespace_: namespace the gNMIc Operator runs in +- _name_: name of the targetSource provider, often `http` . + +### Header + +These header options are mandatory: + +- `-H "Content-Type: application/json"` +- `H "Authorization: Bearer fEPGF5qwV...` + +If acceptPush is enabled, a Kubernetes secret `gnmic-api-auth` is created. It must be passed along in the authorization header, otherwise the POST request is rejected. + +Get `gnmic-api-auth `secret with `kubectl get secret -n gnmic-system gnmic-api-auth -o jsonpath="{.data.bearer-token}" | base64 --decode`. + +#### TLS + +In production, it is highly recommended to use `TLS` and `HTTPS`! For this it is recommended to use a ingress-router/load-balancer that terminates the TLS connection at the Kubernetes edge. + +### Body + +Can we use swagger docs here?! See example below + +#### Example POST request + +``` +curl -X POST "http://localhost:8082/api/v1/default/target-source/http-discovery/createTargets" \ + -H "Authorization: Bearer fEPGF5qwVfM7vvEw2vYuaPojcda/a78aOtqmW4oEFYZUJF67yXluSjDoTKmey5zU" \ + -H "Content-Type: application/json" \ + -d '[ + { + "address": "1.1.1.1:123", + "name": "Router1", + "operation": "created", + "profile": "defaultProfile", + "labels": [ + { "key": "tags", "value": "tag1, tag2" } + ] + } + ]' +``` \ No newline at end of file From 00555b4458bd81484a6a4787f41d78610aa1fccc Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Mon, 8 Jun 2026 11:31:35 +0200 Subject: [PATCH 02/17] generate docs --- .../docs/advanced/.openapi-generator-ignore | 23 ++++++ .../docs/advanced/.openapi-generator/FILES | 4 + .../docs/advanced/.openapi-generator/VERSION | 1 + docs/content/docs/advanced/Apis/DefaultApi.md | 57 +++++++++++++ docs/content/docs/advanced/Models/Target.md | 14 ++++ docs/content/docs/advanced/README.md | 27 ++++++ docs/content/docs/advanced/openapi.yaml | 82 +++++++++++++++++++ 7 files changed, 208 insertions(+) create mode 100644 docs/content/docs/advanced/.openapi-generator-ignore create mode 100644 docs/content/docs/advanced/.openapi-generator/FILES create mode 100644 docs/content/docs/advanced/.openapi-generator/VERSION create mode 100644 docs/content/docs/advanced/Apis/DefaultApi.md create mode 100644 docs/content/docs/advanced/Models/Target.md create mode 100644 docs/content/docs/advanced/README.md create mode 100644 docs/content/docs/advanced/openapi.yaml diff --git a/docs/content/docs/advanced/.openapi-generator-ignore b/docs/content/docs/advanced/.openapi-generator-ignore new file mode 100644 index 00000000..7484ee59 --- /dev/null +++ b/docs/content/docs/advanced/.openapi-generator-ignore @@ -0,0 +1,23 @@ +# OpenAPI Generator Ignore +# Generated by openapi-generator https://github.com/openapitools/openapi-generator + +# Use this file to prevent files from being overwritten by the generator. +# The patterns follow closely to .gitignore or .dockerignore. + +# As an example, the C# client generator defines ApiClient.cs. +# You can make changes and tell OpenAPI Generator to ignore just this file by uncommenting the following line: +#ApiClient.cs + +# You can match any string of characters against a directory, file or extension with a single asterisk (*): +#foo/*/qux +# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux + +# You can recursively match patterns against a directory, file or extension with a double asterisk (**): +#foo/**/qux +# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux + +# You can also negate patterns with an exclamation (!). +# For example, you can ignore all files in a docs folder with the file extension .md: +#docs/*.md +# Then explicitly reverse the ignore rule for a single file: +#!docs/README.md diff --git a/docs/content/docs/advanced/.openapi-generator/FILES b/docs/content/docs/advanced/.openapi-generator/FILES new file mode 100644 index 00000000..dd678403 --- /dev/null +++ b/docs/content/docs/advanced/.openapi-generator/FILES @@ -0,0 +1,4 @@ +.openapi-generator-ignore +Apis/DefaultApi.md +Models/Target.md +README.md diff --git a/docs/content/docs/advanced/.openapi-generator/VERSION b/docs/content/docs/advanced/.openapi-generator/VERSION new file mode 100644 index 00000000..ca7bf6e4 --- /dev/null +++ b/docs/content/docs/advanced/.openapi-generator/VERSION @@ -0,0 +1 @@ +7.23.0-SNAPSHOT diff --git a/docs/content/docs/advanced/Apis/DefaultApi.md b/docs/content/docs/advanced/Apis/DefaultApi.md new file mode 100644 index 00000000..a69288cd --- /dev/null +++ b/docs/content/docs/advanced/Apis/DefaultApi.md @@ -0,0 +1,57 @@ +# DefaultApi + +All URIs are relative to *http://localhost* + +| Method | HTTP request | Description | +|------------- | ------------- | -------------| +| [**applyTargets**](DefaultApi.md#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Targets received are applied in gNMIc Operator. | +| [**getClusterPlan**](DefaultApi.md#getClusterPlan) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | + + + +# **applyTargets** +> List applyTargets(Target) + +Targets received are applied in gNMIc Operator. + +### Parameters + +|Name | Type | Description | Notes | +|------------- | ------------- | ------------- | -------------| +| **Target** | [**List**](../Models/Target.md)| | | + +### Return type + +[**List**](../Models/Target.md) + +### Authorization + +[bearerAuth](../README.md#bearerAuth) + +### HTTP request headers + +- **Content-Type**: application/json +- **Accept**: application/json + + +# **getClusterPlan** +> getClusterPlan() + +Get cluster plan. + +### Parameters +This endpoint does not need any parameter. + +### Return type + +null (empty response body) + +### Authorization + +No authorization required + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: Not defined + diff --git a/docs/content/docs/advanced/Models/Target.md b/docs/content/docs/advanced/Models/Target.md new file mode 100644 index 00000000..5f784eba --- /dev/null +++ b/docs/content/docs/advanced/Models/Target.md @@ -0,0 +1,14 @@ +# Target +## Properties + +| Name | Type | Description | Notes | +|------------ | ------------- | ------------- | -------------| +| **name** | **String** | Routername | [default to null] | +| **address** | **String** | IPv4 or IPv6 | [optional] [default to null] | +| **port** | **Integer** | gNMIc port | [optional] [default to null] | +| **targetProfile** | **String** | TargetProfile applied to specific router | [optional] [default to null] | +| **labels** | [**List**](map.md) | Input of labels through key:value pair | [optional] [default to null] | +| **operation** | **String** | Either created, updated or deleted. created and updated internally is the same operation (apply) | [default to null] | + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + diff --git a/docs/content/docs/advanced/README.md b/docs/content/docs/advanced/README.md new file mode 100644 index 00000000..4a0ddd35 --- /dev/null +++ b/docs/content/docs/advanced/README.md @@ -0,0 +1,27 @@ +# Documentation for gNMIc Operator REST API + + +## Documentation for API Endpoints + +All URIs are relative to *http://localhost* + +| Class | Method | HTTP request | Description | +|------------ | ------------- | ------------- | -------------| +| *DefaultApi* | [**applyTargets**](Apis/DefaultApi.md#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Targets received are applied in gNMIc Operator. | +*DefaultApi* | [**getClusterPlan**](Apis/DefaultApi.md#getClusterPlan) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | + + + +## Documentation for Models + + - [Target](./Models/Target.md) + + + +## Documentation for Authorization + + +### bearerAuth + +- **Type**: HTTP Bearer Token authentication + diff --git a/docs/content/docs/advanced/openapi.yaml b/docs/content/docs/advanced/openapi.yaml new file mode 100644 index 00000000..b26e69de --- /dev/null +++ b/docs/content/docs/advanced/openapi.yaml @@ -0,0 +1,82 @@ +openapi: 3.0.3 +info: + title: "gNMIc Operator REST API" + version: "0.0.1" +paths: + /clusters/:namespace/:name/plan: + get: + summary: "Get cluster plan." + operationId: "getClusterPlan" + responses: + '200': + description: "ClusterPlan returned" + /api/v1/:namespace/target-source/:name/applyTargets: + post: + summary: "Targets received are applied in gNMIc Operator." + operationId: "applyTargets" + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Targets' + responses: + '201': + description: "Targets applied successfully" + content: + application/json: + schema: + $ref: '#/components/schemas/Targets' + '401': + description: Access token is missing or invalid + +components: + schemas: + Targets: + type: array + items: + $ref: '#/components/schemas/Target' + Label: + description: TBD + type: object + additionalProperties: + description: Label must be passed as key:value pair. Multiple values per key possible + type: string + Target: + type: object + required: + - name + - ip + - operation + properties: + name: + type: string + description: Routername + address: + type: string + description: IPv4 or IPv6 + port: + type: integer + description: gNMIc port + targetProfile: + type: string + description: TargetProfile applied to specific router + labels: + type: array + description: Input of labels through key:value pair + items: + $ref: '#/components/schemas/Label' + operation: + type: string + enum: + - created + - updated + - deleted + description: Either created, updated or deleted. created and updated internally is the same operation (apply) + securitySchemes: + bearerAuth: + type: http + scheme: bearer + \ No newline at end of file From ad2b377b95b3a84c424c8745b2b2d7e360c6f2b4 Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Mon, 8 Jun 2026 11:39:20 +0200 Subject: [PATCH 03/17] add header to generated md --- docs/content/docs/advanced/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/content/docs/advanced/README.md b/docs/content/docs/advanced/README.md index 4a0ddd35..1985a6e5 100644 --- a/docs/content/docs/advanced/README.md +++ b/docs/content/docs/advanced/README.md @@ -1,3 +1,11 @@ +--- +title: "Documentation for gNMIc Operator REST API" +linkTitle: "REST API interface" +weight: 3 +description: > + Documentation of REST API interface according to openAPI standard. +--- + # Documentation for gNMIc Operator REST API From 3a0f5c8a13ab939b1042c050aca33898cf861b36 Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Mon, 8 Jun 2026 13:34:08 +0200 Subject: [PATCH 04/17] tests with markdown templates --- docs/content/docs/advanced/Apis/DefaultApi.md | 6 +- docs/content/docs/advanced/Models/Target.md | 24 ++++--- .../advanced/openapi-generator-config.yaml | 7 ++ .../markdown-documentation/README.mustache | 67 +++++++++++++++++++ .../markdown-documentation/api.mustache | 42 ++++++++++++ .../markdown-documentation/model.mustache | 27 ++++++++ docs/content/docs/advanced/openapi.yaml | 19 +++--- .../docs/advanced/rest-api-documentation.md | 33 +++++++++ 8 files changed, 205 insertions(+), 20 deletions(-) create mode 100644 docs/content/docs/advanced/openapi-generator-config.yaml create mode 100644 docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache create mode 100644 docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache create mode 100644 docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache create mode 100644 docs/content/docs/advanced/rest-api-documentation.md diff --git a/docs/content/docs/advanced/Apis/DefaultApi.md b/docs/content/docs/advanced/Apis/DefaultApi.md index a69288cd..aeb9cdbd 100644 --- a/docs/content/docs/advanced/Apis/DefaultApi.md +++ b/docs/content/docs/advanced/Apis/DefaultApi.md @@ -4,7 +4,7 @@ All URIs are relative to *http://localhost* | Method | HTTP request | Description | |------------- | ------------- | -------------| -| [**applyTargets**](DefaultApi.md#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Targets received are applied in gNMIc Operator. | +| [**applyTargets**](DefaultApi.md#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | | [**getClusterPlan**](DefaultApi.md#getClusterPlan) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | @@ -12,7 +12,7 @@ All URIs are relative to *http://localhost* # **applyTargets** > List applyTargets(Target) -Targets received are applied in gNMIc Operator. +Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. ### Parameters @@ -26,7 +26,7 @@ Targets received are applied in gNMIc Operator. ### Authorization -[bearerAuth](../README.md#bearerAuth) +[bearerAuth](../rest-api-documentation.md#bearerAuth) ### HTTP request headers diff --git a/docs/content/docs/advanced/Models/Target.md b/docs/content/docs/advanced/Models/Target.md index 5f784eba..f3e5de65 100644 --- a/docs/content/docs/advanced/Models/Target.md +++ b/docs/content/docs/advanced/Models/Target.md @@ -1,14 +1,22 @@ +--- +title: "Model" +linkTitle: "Model" +weight: 4 +description: > + Todo +--- + # Target ## Properties | Name | Type | Description | Notes | |------------ | ------------- | ------------- | -------------| -| **name** | **String** | Routername | [default to null] | -| **address** | **String** | IPv4 or IPv6 | [optional] [default to null] | -| **port** | **Integer** | gNMIc port | [optional] [default to null] | -| **targetProfile** | **String** | TargetProfile applied to specific router | [optional] [default to null] | -| **labels** | [**List**](map.md) | Input of labels through key:value pair | [optional] [default to null] | -| **operation** | **String** | Either created, updated or deleted. created and updated internally is the same operation (apply) | [default to null] | - -[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) +| **name** | **String** | Name of device to be monitored. | [default to null] | +| **address** | **String** | IPv4/IPv6 address or hostname. | [default to null] | +| **port** | **Integer** | gNMIc port. | [optional] [default to null] | +| **targetProfile** | **String** | TargetProfile applied to apply to this router. | [optional] [default to null] | +| **labels** | [**List**](map.md) | Input of labels as key:value pair. | [optional] [default to null] | +| **operation** | **String** | Either `created`, `updated` or `deleted`. `created` and `updated` are identical and both apply the target. | [default to null] | + +[[Back to Model list]](../rest-api-documentation.md#documentation-for-models) [[Back to API list]](../rest-api-documentation.md#documentation-for-api-endpoints) [[Back to README]](../rest-api-documentation.md) diff --git a/docs/content/docs/advanced/openapi-generator-config.yaml b/docs/content/docs/advanced/openapi-generator-config.yaml new file mode 100644 index 00000000..20fa9d53 --- /dev/null +++ b/docs/content/docs/advanced/openapi-generator-config.yaml @@ -0,0 +1,7 @@ +generatorName: markdown +inputSpec: /local/docs/content/docs/advanced/openapi.yaml +outputDir: /local/docs/content/docs/advanced +templateDir: /local/docs/content/docs/advanced/openapi-templates/markdown-documentation +files: + README.mustache: + destinationFilename: rest-api-documentation.md \ No newline at end of file diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache new file mode 100644 index 00000000..f231ec03 --- /dev/null +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache @@ -0,0 +1,67 @@ +--- +title: "Documentation for gNMIc Operator REST API" +linkTitle: "REST API interface" +weight: 3 +description: > + Documentation of REST API interface according to openAPI standard. +--- + +{{#generateApiDocs}} + +## Documentation for API Endpoints + +All URIs are relative to *{{{basePath}}}* + +| Class | Method | HTTP request | Description | +|------------ | ------------- | ------------- | -------------| +{{#apiInfo}}{{#apis}}{{#operations}}| {{#operation}}*{{classname}}* | [**{{operationId}}**](Apis/{{apiDocPath}}{{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{{summary}}}{{^summary}}{{{notes}}}{{/summary}} | +{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}} +{{/generateApiDocs}} + +{{#generateModelDocs}} + +## Documentation for Models + +{{#modelPackage}} +{{#models}}{{#model}} - [{{{classname}}}](./{{{modelPackage}}}/{{modelDocPath}}{{{classFilename}}}.md) +{{/model}}{{/models}} +{{/modelPackage}} +{{^modelPackage}} +No model defined in this package +{{/modelPackage}} +{{/generateModelDocs}} + +{{! TODO: optional documentation for authorization? }} +## Documentation for Authorization + +{{^authMethods}} +All endpoints do not require authorization. +{{/authMethods}} +{{#authMethods}} +{{#last}} + Authentication schemes defined for the API: +{{/last}} +{{/authMethods}} +{{#authMethods}} + +### {{name}} + +{{#isApiKey}}- **Type**: API key +- **API key parameter name**: {{keyParamName}} +- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}} +{{/isApiKey}} +{{#isBasicBasic}}- **Type**: HTTP basic authentication +{{/isBasicBasic}} +{{#isBasicBearer}}- **Type**: HTTP Bearer Token authentication{{#bearerFormat}} ({{{.}}}){{/bearerFormat}} +{{/isBasicBearer}} +{{#isHttpSignature}}- **Type**: HTTP signature authentication +{{/isHttpSignature}} +{{#isOAuth}}- **Type**: OAuth +- **Flow**: {{flow}} +- **Authorization URL**: {{authorizationUrl}} +- **Scopes**: {{^scopes}}N/A{{/scopes}} +{{#scopes}} - {{scope}}: {{description}} +{{/scopes}} +{{/isOAuth}} + +{{/authMethods}} \ No newline at end of file diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache new file mode 100644 index 00000000..cbb8d19e --- /dev/null +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache @@ -0,0 +1,42 @@ +# {{classname}}{{#description}} + {{.}}{{/description}} + +All URIs are relative to *{{basePath}}* + +| Method | HTTP request | Description | +|------------- | ------------- | -------------| +{{#operations}}{{#operation}}| [**{{operationId}}**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{summary}} | +{{/operation}}{{/operations}} + +{{#operations}} +{{#operation}} + +# **{{operationId}}** +> {{#returnType}}{{.}} {{/returnType}}{{operationId}}({{#allParams}}{{{paramName}}}{{^-last}}, {{/-last}}{{/allParams}}) + +{{summary}}{{#notes}} + + {{.}}{{/notes}} + +### Parameters +{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}} +|Name | Type | Description | Notes | +|------------- | ------------- | ------------- | -------------|{{/-last}}{{/allParams}} +{{#allParams}}| **{{paramName}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{#isFile}}**{{dataType}}**{{/isFile}}{{^isFile}}{{#generateModelDocs}}[**{{dataType}}**](../{{modelPackage}}/{{baseType}}.md){{/generateModelDocs}}{{^generateModelDocs}}**{{dataType}}**{{/generateModelDocs}}{{/isFile}}{{/isPrimitiveType}}| {{description}} |{{^required}} [optional]{{/required}}{{#defaultValue}} [default to {{.}}]{{/defaultValue}}{{#allowableValues}} [enum: {{#values}}{{{.}}}{{^-last}}, {{/-last}}{{/values}}]{{/allowableValues}} | +{{/allParams}} + +### Return type + +{{#returnType}}{{#returnTypeIsPrimitive}}**{{returnType}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}{{#generateModelDocs}}[**{{returnType}}**](../{{modelPackage}}/{{returnBaseType}}.md){{/generateModelDocs}}{{^generateModelDocs}}**{{returnType}}**{{/generateModelDocs}}{{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}null (empty response body){{/returnType}} + +### Authorization + +{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{name}}](../rest-api-documentation.md#{{name}}){{^-last}}, {{/-last}}{{/authMethods}} + +### HTTP request headers + +- **Content-Type**: {{#consumes}}{{{mediaType}}}{{^-last}}, {{/-last}}{{/consumes}}{{^consumes}}Not defined{{/consumes}} +- **Accept**: {{#produces}}{{{mediaType}}}{{^-last}}, {{/-last}}{{/produces}}{{^produces}}Not defined{{/produces}} + +{{/operation}} +{{/operations}} \ No newline at end of file diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache new file mode 100644 index 00000000..a5b5e851 --- /dev/null +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache @@ -0,0 +1,27 @@ +--- +title: "Model" +linkTitle: "Model" +weight: 4 +description: > + Todo +--- + +{{#models}} +{{#model}} +# {{{classname}}} +## Properties + +| Name | Type | Description | Notes | +|------------ | ------------- | ------------- | -------------| +{{#parent}} +{{#parentVars}} +| **{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{complexType}}.md){{/isPrimitiveType}} | {{{description}}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}} | +{{/parentVars}} +{{/parent}} +{{#vars}}| **{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{complexType}}.md){{/isPrimitiveType}} | {{{description}}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}} | +{{/vars}} + +[[Back to Model list]](../rest-api-documentation.md#documentation-for-models) [[Back to API list]](../rest-api-documentation.md#documentation-for-api-endpoints) [[Back to README]](../rest-api-documentation.md) + + {{/model}} +{{/models}} \ No newline at end of file diff --git a/docs/content/docs/advanced/openapi.yaml b/docs/content/docs/advanced/openapi.yaml index b26e69de..3883f465 100644 --- a/docs/content/docs/advanced/openapi.yaml +++ b/docs/content/docs/advanced/openapi.yaml @@ -12,7 +12,7 @@ paths: description: "ClusterPlan returned" /api/v1/:namespace/target-source/:name/applyTargets: post: - summary: "Targets received are applied in gNMIc Operator." + summary: "Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator." operationId: "applyTargets" security: - bearerAuth: [] @@ -42,30 +42,31 @@ components: description: TBD type: object additionalProperties: - description: Label must be passed as key:value pair. Multiple values per key possible + description: Label must be passed as key:value pair, multiple values per key possible. type: string Target: + description: Network device to be monitored. Properties not marked as optional must be in JSON body. type: object required: - name - - ip + - address - operation properties: name: type: string - description: Routername + description: Name of device to be monitored. address: type: string - description: IPv4 or IPv6 + description: IPv4/IPv6 address or hostname. port: type: integer - description: gNMIc port + description: gNMIc port. targetProfile: type: string - description: TargetProfile applied to specific router + description: TargetProfile applied to apply to this router. labels: type: array - description: Input of labels through key:value pair + description: Input of labels as key:value pair. items: $ref: '#/components/schemas/Label' operation: @@ -74,7 +75,7 @@ components: - created - updated - deleted - description: Either created, updated or deleted. created and updated internally is the same operation (apply) + description: "Either `created`, `updated` or `deleted`. `created` and `updated` are identical and both apply the target." securitySchemes: bearerAuth: type: http diff --git a/docs/content/docs/advanced/rest-api-documentation.md b/docs/content/docs/advanced/rest-api-documentation.md new file mode 100644 index 00000000..ddc20bfb --- /dev/null +++ b/docs/content/docs/advanced/rest-api-documentation.md @@ -0,0 +1,33 @@ +--- +title: "Documentation for gNMIc Operator REST API" +linkTitle: "REST API interface" +weight: 3 +description: > + Documentation of REST API interface according to openAPI standard. +--- + + +## Documentation for API Endpoints + +All URIs are relative to *http://localhost* + +| Class | Method | HTTP request | Description | +|------------ | ------------- | ------------- | -------------| +| *DefaultApi* | [**applyTargets**](Apis/DefaultApi.md#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | +*DefaultApi* | [**getClusterPlan**](Apis/DefaultApi.md#getClusterPlan) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | + + + +## Documentation for Models + + - [Target](./Models/Target.md) + + + +## Documentation for Authorization + + +### bearerAuth + +- **Type**: HTTP Bearer Token authentication + From 131d838a8f39ac337f52cedc513a9530f0baf91a Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Mon, 8 Jun 2026 13:41:03 +0200 Subject: [PATCH 05/17] fix links --- docs/content/docs/advanced/README.md | 35 ------------------- .../markdown-documentation/README.mustache | 4 +-- .../docs/advanced/rest-api-documentation.md | 6 ++-- 3 files changed, 5 insertions(+), 40 deletions(-) delete mode 100644 docs/content/docs/advanced/README.md diff --git a/docs/content/docs/advanced/README.md b/docs/content/docs/advanced/README.md deleted file mode 100644 index 1985a6e5..00000000 --- a/docs/content/docs/advanced/README.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "Documentation for gNMIc Operator REST API" -linkTitle: "REST API interface" -weight: 3 -description: > - Documentation of REST API interface according to openAPI standard. ---- - -# Documentation for gNMIc Operator REST API - - -## Documentation for API Endpoints - -All URIs are relative to *http://localhost* - -| Class | Method | HTTP request | Description | -|------------ | ------------- | ------------- | -------------| -| *DefaultApi* | [**applyTargets**](Apis/DefaultApi.md#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Targets received are applied in gNMIc Operator. | -*DefaultApi* | [**getClusterPlan**](Apis/DefaultApi.md#getClusterPlan) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | - - - -## Documentation for Models - - - [Target](./Models/Target.md) - - - -## Documentation for Authorization - - -### bearerAuth - -- **Type**: HTTP Bearer Token authentication - diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache index f231ec03..70619729 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache @@ -14,7 +14,7 @@ All URIs are relative to *{{{basePath}}}* | Class | Method | HTTP request | Description | |------------ | ------------- | ------------- | -------------| -{{#apiInfo}}{{#apis}}{{#operations}}| {{#operation}}*{{classname}}* | [**{{operationId}}**](Apis/{{apiDocPath}}{{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{{summary}}}{{^summary}}{{{notes}}}{{/summary}} | +{{#apiInfo}}{{#apis}}{{#operations}}| {{#operation}}*{{classname}}* | [**{{operationId}}**](../Apis/{{apiDocPath}}{{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{{summary}}}{{^summary}}{{{notes}}}{{/summary}} | {{/operation}}{{/operations}}{{/apis}}{{/apiInfo}} {{/generateApiDocs}} @@ -23,7 +23,7 @@ All URIs are relative to *{{{basePath}}}* ## Documentation for Models {{#modelPackage}} -{{#models}}{{#model}} - [{{{classname}}}](./{{{modelPackage}}}/{{modelDocPath}}{{{classFilename}}}.md) +{{#models}}{{#model}} - [{{{classname}}}](../{{{modelPackage}}}/{{modelDocPath}}{{{classFilename}}}.md) {{/model}}{{/models}} {{/modelPackage}} {{^modelPackage}} diff --git a/docs/content/docs/advanced/rest-api-documentation.md b/docs/content/docs/advanced/rest-api-documentation.md index ddc20bfb..edba35f0 100644 --- a/docs/content/docs/advanced/rest-api-documentation.md +++ b/docs/content/docs/advanced/rest-api-documentation.md @@ -13,14 +13,14 @@ All URIs are relative to *http://localhost* | Class | Method | HTTP request | Description | |------------ | ------------- | ------------- | -------------| -| *DefaultApi* | [**applyTargets**](Apis/DefaultApi.md#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | -*DefaultApi* | [**getClusterPlan**](Apis/DefaultApi.md#getClusterPlan) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | +| *DefaultApi* | [**applyTargets**](../Apis/DefaultApi.md#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | +*DefaultApi* | [**getClusterPlan**](../Apis/DefaultApi.md#getClusterPlan) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | ## Documentation for Models - - [Target](./Models/Target.md) + - [Target](../Models/Target.md) From a7c632111091f6476f69cbaef7e87dc12b87e1cf Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Mon, 8 Jun 2026 13:56:54 +0200 Subject: [PATCH 06/17] udpate folder structure --- .gitignore | 4 ++- .../docs/advanced/.openapi-generator/FILES | 4 --- .../docs/advanced/.openapi-generator/VERSION | 1 - .../advanced/openapi-generator-config.yaml | 4 +-- .../markdown-documentation/README.mustache | 4 +-- .../markdown-documentation/api.mustache | 10 +++++- .../markdown-documentation/model.mustache | 2 +- .../Apis/DefaultApi.md | 10 +++++- .../Models/Target.md | 2 +- .../advanced/rest-api-documentation/_index.md | 33 +++++++++++++++++++ 10 files changed, 60 insertions(+), 14 deletions(-) delete mode 100644 docs/content/docs/advanced/.openapi-generator/FILES delete mode 100644 docs/content/docs/advanced/.openapi-generator/VERSION rename docs/content/docs/advanced/{ => rest-api-documentation}/Apis/DefaultApi.md (87%) rename docs/content/docs/advanced/{ => rest-api-documentation}/Models/Target.md (79%) create mode 100644 docs/content/docs/advanced/rest-api-documentation/_index.md diff --git a/.gitignore b/.gitignore index 29d31af3..743dab8a 100644 --- a/.gitignore +++ b/.gitignore @@ -33,4 +33,6 @@ notes/ docs/public docs/resources/_gen/ docs/.hugo_build.lock -test/integration/clab-* \ No newline at end of file +test/integration/clab-* +docs/content/docs/advanced/rest-api-documentation/.openapi-generator +docs/content/docs/advanced/rest-api-documentation/.openapi-generator-ignore diff --git a/docs/content/docs/advanced/.openapi-generator/FILES b/docs/content/docs/advanced/.openapi-generator/FILES deleted file mode 100644 index dd678403..00000000 --- a/docs/content/docs/advanced/.openapi-generator/FILES +++ /dev/null @@ -1,4 +0,0 @@ -.openapi-generator-ignore -Apis/DefaultApi.md -Models/Target.md -README.md diff --git a/docs/content/docs/advanced/.openapi-generator/VERSION b/docs/content/docs/advanced/.openapi-generator/VERSION deleted file mode 100644 index ca7bf6e4..00000000 --- a/docs/content/docs/advanced/.openapi-generator/VERSION +++ /dev/null @@ -1 +0,0 @@ -7.23.0-SNAPSHOT diff --git a/docs/content/docs/advanced/openapi-generator-config.yaml b/docs/content/docs/advanced/openapi-generator-config.yaml index 20fa9d53..9ab8481d 100644 --- a/docs/content/docs/advanced/openapi-generator-config.yaml +++ b/docs/content/docs/advanced/openapi-generator-config.yaml @@ -1,7 +1,7 @@ generatorName: markdown inputSpec: /local/docs/content/docs/advanced/openapi.yaml -outputDir: /local/docs/content/docs/advanced +outputDir: /local/docs/content/docs/advanced/rest-api-documentation templateDir: /local/docs/content/docs/advanced/openapi-templates/markdown-documentation files: README.mustache: - destinationFilename: rest-api-documentation.md \ No newline at end of file + destinationFilename: _index.md \ No newline at end of file diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache index 70619729..f231ec03 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache @@ -14,7 +14,7 @@ All URIs are relative to *{{{basePath}}}* | Class | Method | HTTP request | Description | |------------ | ------------- | ------------- | -------------| -{{#apiInfo}}{{#apis}}{{#operations}}| {{#operation}}*{{classname}}* | [**{{operationId}}**](../Apis/{{apiDocPath}}{{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{{summary}}}{{^summary}}{{{notes}}}{{/summary}} | +{{#apiInfo}}{{#apis}}{{#operations}}| {{#operation}}*{{classname}}* | [**{{operationId}}**](Apis/{{apiDocPath}}{{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{{summary}}}{{^summary}}{{{notes}}}{{/summary}} | {{/operation}}{{/operations}}{{/apis}}{{/apiInfo}} {{/generateApiDocs}} @@ -23,7 +23,7 @@ All URIs are relative to *{{{basePath}}}* ## Documentation for Models {{#modelPackage}} -{{#models}}{{#model}} - [{{{classname}}}](../{{{modelPackage}}}/{{modelDocPath}}{{{classFilename}}}.md) +{{#models}}{{#model}} - [{{{classname}}}](./{{{modelPackage}}}/{{modelDocPath}}{{{classFilename}}}.md) {{/model}}{{/models}} {{/modelPackage}} {{^modelPackage}} diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache index cbb8d19e..f8b29ef5 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache @@ -1,3 +1,11 @@ +--- +title: "REST API definition" +linkTitle: "REST API definition" +weight: 4 +description: > + Gives REST API definition with available options. +--- + # {{classname}}{{#description}} {{.}}{{/description}} @@ -31,7 +39,7 @@ All URIs are relative to *{{basePath}}* ### Authorization -{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{name}}](../rest-api-documentation.md#{{name}}){{^-last}}, {{/-last}}{{/authMethods}} +{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{name}}](../_index.md#{{name}}){{^-last}}, {{/-last}}{{/authMethods}} ### HTTP request headers diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache index a5b5e851..844cde03 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache @@ -21,7 +21,7 @@ description: > {{#vars}}| **{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{complexType}}.md){{/isPrimitiveType}} | {{{description}}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}} | {{/vars}} -[[Back to Model list]](../rest-api-documentation.md#documentation-for-models) [[Back to API list]](../rest-api-documentation.md#documentation-for-api-endpoints) [[Back to README]](../rest-api-documentation.md) +[[Back to Model list]](../_index.md#documentation-for-models) [[Back to API list]](../_index.md#documentation-for-api-endpoints) [[Back to README]](../_index.md) {{/model}} {{/models}} \ No newline at end of file diff --git a/docs/content/docs/advanced/Apis/DefaultApi.md b/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md similarity index 87% rename from docs/content/docs/advanced/Apis/DefaultApi.md rename to docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md index aeb9cdbd..2432fc73 100644 --- a/docs/content/docs/advanced/Apis/DefaultApi.md +++ b/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md @@ -1,3 +1,11 @@ +--- +title: "REST API definition" +linkTitle: "REST API definition" +weight: 4 +description: > + Gives REST API definition with available options. +--- + # DefaultApi All URIs are relative to *http://localhost* @@ -26,7 +34,7 @@ Interface for real-time target updates, usually using a webhook. Targets are app ### Authorization -[bearerAuth](../rest-api-documentation.md#bearerAuth) +[bearerAuth](../_index.md#bearerAuth) ### HTTP request headers diff --git a/docs/content/docs/advanced/Models/Target.md b/docs/content/docs/advanced/rest-api-documentation/Models/Target.md similarity index 79% rename from docs/content/docs/advanced/Models/Target.md rename to docs/content/docs/advanced/rest-api-documentation/Models/Target.md index f3e5de65..106dea2c 100644 --- a/docs/content/docs/advanced/Models/Target.md +++ b/docs/content/docs/advanced/rest-api-documentation/Models/Target.md @@ -18,5 +18,5 @@ description: > | **labels** | [**List**](map.md) | Input of labels as key:value pair. | [optional] [default to null] | | **operation** | **String** | Either `created`, `updated` or `deleted`. `created` and `updated` are identical and both apply the target. | [default to null] | -[[Back to Model list]](../rest-api-documentation.md#documentation-for-models) [[Back to API list]](../rest-api-documentation.md#documentation-for-api-endpoints) [[Back to README]](../rest-api-documentation.md) +[[Back to Model list]](../_index.md#documentation-for-models) [[Back to API list]](../_index.md#documentation-for-api-endpoints) [[Back to README]](../_index.md) diff --git a/docs/content/docs/advanced/rest-api-documentation/_index.md b/docs/content/docs/advanced/rest-api-documentation/_index.md new file mode 100644 index 00000000..ddc20bfb --- /dev/null +++ b/docs/content/docs/advanced/rest-api-documentation/_index.md @@ -0,0 +1,33 @@ +--- +title: "Documentation for gNMIc Operator REST API" +linkTitle: "REST API interface" +weight: 3 +description: > + Documentation of REST API interface according to openAPI standard. +--- + + +## Documentation for API Endpoints + +All URIs are relative to *http://localhost* + +| Class | Method | HTTP request | Description | +|------------ | ------------- | ------------- | -------------| +| *DefaultApi* | [**applyTargets**](Apis/DefaultApi.md#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | +*DefaultApi* | [**getClusterPlan**](Apis/DefaultApi.md#getClusterPlan) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | + + + +## Documentation for Models + + - [Target](./Models/Target.md) + + + +## Documentation for Authorization + + +### bearerAuth + +- **Type**: HTTP Bearer Token authentication + From 7aec4c2c0cf5afb6031646e751141f56e04925c2 Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Mon, 8 Jun 2026 14:10:31 +0200 Subject: [PATCH 07/17] fix links, cleanup some text --- .../markdown-documentation/README.mustache | 10 +++++----- .../markdown-documentation/api.mustache | 6 +++--- .../markdown-documentation/model.mustache | 8 ++++++-- .../rest-api-documentation/Apis/DefaultApi.md | 6 +++--- .../advanced/rest-api-documentation/Models/Target.md | 6 ++++-- .../docs/advanced/rest-api-documentation/_index.md | 12 ++++++------ 6 files changed, 27 insertions(+), 21 deletions(-) diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache index f231ec03..6ecbdb00 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache @@ -1,20 +1,20 @@ --- -title: "Documentation for gNMIc Operator REST API" +title: "REST API interface" linkTitle: "REST API interface" weight: 3 description: > - Documentation of REST API interface according to openAPI standard. + The gNMIc Operator has a REST API endpoint. This documentation explains what routes are avaiable and how to use them. --- {{#generateApiDocs}} ## Documentation for API Endpoints -All URIs are relative to *{{{basePath}}}* +All URIs are relative to *{{{basePath}}}:8082* | Class | Method | HTTP request | Description | |------------ | ------------- | ------------- | -------------| -{{#apiInfo}}{{#apis}}{{#operations}}| {{#operation}}*{{classname}}* | [**{{operationId}}**](Apis/{{apiDocPath}}{{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{{summary}}}{{^summary}}{{{notes}}}{{/summary}} | +{{#apiInfo}}{{#apis}}{{#operations}}| {{#operation}}*{{classname}}* | [**{{operationId}}**](/docs/advanced/rest-api-documentation/Apis/{{apiDocPath}}{{classname}}/#{{operationId}}) | **{{httpMethod}}** {{path}} | {{{summary}}}{{^summary}}{{{notes}}}{{/summary}} | {{/operation}}{{/operations}}{{/apis}}{{/apiInfo}} {{/generateApiDocs}} @@ -23,7 +23,7 @@ All URIs are relative to *{{{basePath}}}* ## Documentation for Models {{#modelPackage}} -{{#models}}{{#model}} - [{{{classname}}}](./{{{modelPackage}}}/{{modelDocPath}}{{{classFilename}}}.md) +{{#models}}{{#model}} - [{{{classname}}}](/docs/advanced/rest-api-documentation/{{{modelPackage}}}/{{modelDocPath}}{{{classFilename}}}/) {{/model}}{{/models}} {{/modelPackage}} {{^modelPackage}} diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache index f8b29ef5..9ac12fd6 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache @@ -30,16 +30,16 @@ All URIs are relative to *{{basePath}}* {{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}} |Name | Type | Description | Notes | |------------- | ------------- | ------------- | -------------|{{/-last}}{{/allParams}} -{{#allParams}}| **{{paramName}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{#isFile}}**{{dataType}}**{{/isFile}}{{^isFile}}{{#generateModelDocs}}[**{{dataType}}**](../{{modelPackage}}/{{baseType}}.md){{/generateModelDocs}}{{^generateModelDocs}}**{{dataType}}**{{/generateModelDocs}}{{/isFile}}{{/isPrimitiveType}}| {{description}} |{{^required}} [optional]{{/required}}{{#defaultValue}} [default to {{.}}]{{/defaultValue}}{{#allowableValues}} [enum: {{#values}}{{{.}}}{{^-last}}, {{/-last}}{{/values}}]{{/allowableValues}} | +{{#allParams}}| **{{paramName}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{#isFile}}**{{dataType}}**{{/isFile}}{{^isFile}}{{#generateModelDocs}}[**{{dataType}}**](/docs/advanced/rest-api-documentation/{{modelPackage}}/{{baseType}}/){{/generateModelDocs}}{{^generateModelDocs}}**{{dataType}}**{{/generateModelDocs}}{{/isFile}}{{/isPrimitiveType}}| {{description}} |{{^required}} [optional]{{/required}}{{#defaultValue}} [default to {{.}}]{{/defaultValue}}{{#allowableValues}} [enum: {{#values}}{{{.}}}{{^-last}}, {{/-last}}{{/values}}]{{/allowableValues}} | {{/allParams}} ### Return type -{{#returnType}}{{#returnTypeIsPrimitive}}**{{returnType}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}{{#generateModelDocs}}[**{{returnType}}**](../{{modelPackage}}/{{returnBaseType}}.md){{/generateModelDocs}}{{^generateModelDocs}}**{{returnType}}**{{/generateModelDocs}}{{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}null (empty response body){{/returnType}} +{{#returnType}}{{#returnTypeIsPrimitive}}**{{returnType}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}{{#generateModelDocs}}[**{{returnType}}**](/docs/advanced/rest-api-documentation/{{modelPackage}}/{{returnBaseType}}/){{/generateModelDocs}}{{^generateModelDocs}}**{{returnType}}**{{/generateModelDocs}}{{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}null (empty response body){{/returnType}} ### Authorization -{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{name}}](../_index.md#{{name}}){{^-last}}, {{/-last}}{{/authMethods}} +{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{name}}](/docs/advanced/rest-api-documentation/#{{name}}){{^-last}}, {{/-last}}{{/authMethods}} ### HTTP request headers diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache index 844cde03..d9a711c5 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache @@ -3,12 +3,16 @@ title: "Model" linkTitle: "Model" weight: 4 description: > - Todo + Documentation for OpenAPI models and their schema-defined properties. --- {{#models}} {{#model}} # {{{classname}}} +{{#description}} +{{{description}}} +{{/description}} + ## Properties | Name | Type | Description | Notes | @@ -21,7 +25,7 @@ description: > {{#vars}}| **{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{complexType}}.md){{/isPrimitiveType}} | {{{description}}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}} | {{/vars}} -[[Back to Model list]](../_index.md#documentation-for-models) [[Back to API list]](../_index.md#documentation-for-api-endpoints) [[Back to README]](../_index.md) +[[Back to Model list]](/docs/advanced/rest-api-documentation/#documentation-for-models) [[Back to API list]](/docs/advanced/rest-api-documentation/#documentation-for-api-endpoints) [[Back to README]](/docs/advanced/rest-api-documentation/) {{/model}} {{/models}} \ No newline at end of file diff --git a/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md b/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md index 2432fc73..bf27be18 100644 --- a/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md +++ b/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md @@ -26,15 +26,15 @@ Interface for real-time target updates, usually using a webhook. Targets are app |Name | Type | Description | Notes | |------------- | ------------- | ------------- | -------------| -| **Target** | [**List**](../Models/Target.md)| | | +| **Target** | [**List**](/docs/advanced/rest-api-documentation/Models/Target/)| | | ### Return type -[**List**](../Models/Target.md) +[**List**](/docs/advanced/rest-api-documentation/Models/Target/) ### Authorization -[bearerAuth](../_index.md#bearerAuth) +[bearerAuth](/docs/advanced/rest-api-documentation/#bearerAuth) ### HTTP request headers diff --git a/docs/content/docs/advanced/rest-api-documentation/Models/Target.md b/docs/content/docs/advanced/rest-api-documentation/Models/Target.md index 106dea2c..4292d45c 100644 --- a/docs/content/docs/advanced/rest-api-documentation/Models/Target.md +++ b/docs/content/docs/advanced/rest-api-documentation/Models/Target.md @@ -3,10 +3,12 @@ title: "Model" linkTitle: "Model" weight: 4 description: > - Todo + Documentation for OpenAPI models and their schema-defined properties. --- # Target +Network device to be monitored. Properties not marked as optional must be in JSON body. + ## Properties | Name | Type | Description | Notes | @@ -18,5 +20,5 @@ description: > | **labels** | [**List**](map.md) | Input of labels as key:value pair. | [optional] [default to null] | | **operation** | **String** | Either `created`, `updated` or `deleted`. `created` and `updated` are identical and both apply the target. | [default to null] | -[[Back to Model list]](../_index.md#documentation-for-models) [[Back to API list]](../_index.md#documentation-for-api-endpoints) [[Back to README]](../_index.md) +[[Back to Model list]](/docs/advanced/rest-api-documentation/#documentation-for-models) [[Back to API list]](/docs/advanced/rest-api-documentation/#documentation-for-api-endpoints) [[Back to README]](/docs/advanced/rest-api-documentation/) diff --git a/docs/content/docs/advanced/rest-api-documentation/_index.md b/docs/content/docs/advanced/rest-api-documentation/_index.md index ddc20bfb..379f851c 100644 --- a/docs/content/docs/advanced/rest-api-documentation/_index.md +++ b/docs/content/docs/advanced/rest-api-documentation/_index.md @@ -1,26 +1,26 @@ --- -title: "Documentation for gNMIc Operator REST API" +title: "REST API interface" linkTitle: "REST API interface" weight: 3 description: > - Documentation of REST API interface according to openAPI standard. + The gNMIc Operator has a REST API endpoint. This documentation explains what routes are avaiable and how to use them. --- ## Documentation for API Endpoints -All URIs are relative to *http://localhost* +All URIs are relative to *http://localhost:8082* | Class | Method | HTTP request | Description | |------------ | ------------- | ------------- | -------------| -| *DefaultApi* | [**applyTargets**](Apis/DefaultApi.md#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | -*DefaultApi* | [**getClusterPlan**](Apis/DefaultApi.md#getClusterPlan) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | +| *DefaultApi* | [**applyTargets**](/docs/advanced/rest-api-documentation/Apis/DefaultApi/#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | +*DefaultApi* | [**getClusterPlan**](/docs/advanced/rest-api-documentation/Apis/DefaultApi/#getClusterPlan) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | ## Documentation for Models - - [Target](./Models/Target.md) + - [Target](/docs/advanced/rest-api-documentation/Models/Target/) From 7732cb4db8422363e388c6de3fd6b1129d2f7b8a Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Mon, 8 Jun 2026 14:19:47 +0200 Subject: [PATCH 08/17] update inline md links --- .../markdown-documentation/README.mustache | 4 ++-- .../openapi-templates/markdown-documentation/api.mustache | 8 ++++---- .../advanced/rest-api-documentation/Apis/DefaultApi.md | 8 ++++---- .../docs/advanced/rest-api-documentation/_index.md | 6 +++--- 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache index 6ecbdb00..38ee13ca 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache @@ -3,7 +3,7 @@ title: "REST API interface" linkTitle: "REST API interface" weight: 3 description: > - The gNMIc Operator has a REST API endpoint. This documentation explains what routes are avaiable and how to use them. + The gNMIc Operator has a REST API endpoint. This documentation explains what routes are available and how to use them. --- {{#generateApiDocs}} @@ -14,7 +14,7 @@ All URIs are relative to *{{{basePath}}}:8082* | Class | Method | HTTP request | Description | |------------ | ------------- | ------------- | -------------| -{{#apiInfo}}{{#apis}}{{#operations}}| {{#operation}}*{{classname}}* | [**{{operationId}}**](/docs/advanced/rest-api-documentation/Apis/{{apiDocPath}}{{classname}}/#{{operationId}}) | **{{httpMethod}}** {{path}} | {{{summary}}}{{^summary}}{{{notes}}}{{/summary}} | +{{#apiInfo}}{{#apis}}{{#operations}}| {{#operation}}*{{classname}}* | [**{{operationId}}**](/docs/advanced/rest-api-documentation/{{apiDocPath}}{{classname}}) | **{{httpMethod}}** {{path}} | {{{summary}}}{{^summary}}{{{notes}}}{{/summary}} | {{/operation}}{{/operations}}{{/apis}}{{/apiInfo}} {{/generateApiDocs}} diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache index 9ac12fd6..0935152a 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache @@ -1,15 +1,15 @@ --- -title: "REST API definition" -linkTitle: "REST API definition" +title: "Routes" +linkTitle: "Routes" weight: 4 description: > - Gives REST API definition with available options. + Available HTTP routes on the gNMIc Operator API interface. --- # {{classname}}{{#description}} {{.}}{{/description}} -All URIs are relative to *{{basePath}}* +All URIs are relative to *{{basePath}}:8082* | Method | HTTP request | Description | |------------- | ------------- | -------------| diff --git a/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md b/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md index bf27be18..5b43e25c 100644 --- a/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md +++ b/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md @@ -1,14 +1,14 @@ --- -title: "REST API definition" -linkTitle: "REST API definition" +title: "Routes" +linkTitle: "Routes" weight: 4 description: > - Gives REST API definition with available options. + Available HTTP routes on the gNMIc Operator API interface. --- # DefaultApi -All URIs are relative to *http://localhost* +All URIs are relative to *http://localhost:8082* | Method | HTTP request | Description | |------------- | ------------- | -------------| diff --git a/docs/content/docs/advanced/rest-api-documentation/_index.md b/docs/content/docs/advanced/rest-api-documentation/_index.md index 379f851c..b47a39d6 100644 --- a/docs/content/docs/advanced/rest-api-documentation/_index.md +++ b/docs/content/docs/advanced/rest-api-documentation/_index.md @@ -3,7 +3,7 @@ title: "REST API interface" linkTitle: "REST API interface" weight: 3 description: > - The gNMIc Operator has a REST API endpoint. This documentation explains what routes are avaiable and how to use them. + The gNMIc Operator has a REST API endpoint. This documentation explains what routes are available and how to use them. --- @@ -13,8 +13,8 @@ All URIs are relative to *http://localhost:8082* | Class | Method | HTTP request | Description | |------------ | ------------- | ------------- | -------------| -| *DefaultApi* | [**applyTargets**](/docs/advanced/rest-api-documentation/Apis/DefaultApi/#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | -*DefaultApi* | [**getClusterPlan**](/docs/advanced/rest-api-documentation/Apis/DefaultApi/#getClusterPlan) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | +| *DefaultApi* | [**applyTargets**](/docs/advanced/rest-api-documentation/DefaultApi) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | +*DefaultApi* | [**getClusterPlan**](/docs/advanced/rest-api-documentation/DefaultApi) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | From 6d6c7209e24095de42cd7e9fef5df78ec1449d68 Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Mon, 8 Jun 2026 14:41:22 +0200 Subject: [PATCH 09/17] add signature --- docs/content/docs/Apis/DefaultApi.md | 2 ++ .../markdown-documentation/README.mustache | 4 ++-- docs/content/docs/advanced/openapi.yaml | 7 +++++++ .../rest-api-documentation/Apis/DefaultApi.md | 2 +- .../docs/advanced/rest-api-documentation/_index.md | 13 ++++++++++--- 5 files changed, 22 insertions(+), 6 deletions(-) create mode 100644 docs/content/docs/Apis/DefaultApi.md diff --git a/docs/content/docs/Apis/DefaultApi.md b/docs/content/docs/Apis/DefaultApi.md new file mode 100644 index 00000000..513f6da6 --- /dev/null +++ b/docs/content/docs/Apis/DefaultApi.md @@ -0,0 +1,2 @@ +# DefaultApi + diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache index 38ee13ca..70ef54a6 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache @@ -3,7 +3,7 @@ title: "REST API interface" linkTitle: "REST API interface" weight: 3 description: > - The gNMIc Operator has a REST API endpoint. This documentation explains what routes are available and how to use them. + This document describes the REST API exposed by the gNMIc Operator, including the available endpoints, request formats, and usage examples. --- {{#generateApiDocs}} @@ -14,7 +14,7 @@ All URIs are relative to *{{{basePath}}}:8082* | Class | Method | HTTP request | Description | |------------ | ------------- | ------------- | -------------| -{{#apiInfo}}{{#apis}}{{#operations}}| {{#operation}}*{{classname}}* | [**{{operationId}}**](/docs/advanced/rest-api-documentation/{{apiDocPath}}{{classname}}) | **{{httpMethod}}** {{path}} | {{{summary}}}{{^summary}}{{{notes}}}{{/summary}} | +{{#apiInfo}}{{#apis}}{{#operations}}| {{#operation}}*{{classname}}* | [**{{operationId}}**](/docs/advanced/rest-api-documentation/apis/{{apiDocPath}}{{classname}}) | **{{httpMethod}}** {{path}} | {{{summary}}}{{^summary}}{{{notes}}}{{/summary}} | {{/operation}}{{/operations}}{{/apis}}{{/apiInfo}} {{/generateApiDocs}} diff --git a/docs/content/docs/advanced/openapi.yaml b/docs/content/docs/advanced/openapi.yaml index 3883f465..5f6ea35b 100644 --- a/docs/content/docs/advanced/openapi.yaml +++ b/docs/content/docs/advanced/openapi.yaml @@ -16,6 +16,7 @@ paths: operationId: "applyTargets" security: - bearerAuth: [] + signature: [] requestBody: required: true content: @@ -80,4 +81,10 @@ components: bearerAuth: type: http scheme: bearer + description: HTTP authentication using Bearer token + signature: + name: X-Hook-Signature + type: apiKey + in: header + description: HMAC signature of the request payload \ No newline at end of file diff --git a/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md b/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md index 5b43e25c..e0d65613 100644 --- a/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md +++ b/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md @@ -34,7 +34,7 @@ Interface for real-time target updates, usually using a webhook. Targets are app ### Authorization -[bearerAuth](/docs/advanced/rest-api-documentation/#bearerAuth) +[signature](/docs/advanced/rest-api-documentation/#signature), [bearerAuth](/docs/advanced/rest-api-documentation/#bearerAuth) ### HTTP request headers diff --git a/docs/content/docs/advanced/rest-api-documentation/_index.md b/docs/content/docs/advanced/rest-api-documentation/_index.md index b47a39d6..a47cb911 100644 --- a/docs/content/docs/advanced/rest-api-documentation/_index.md +++ b/docs/content/docs/advanced/rest-api-documentation/_index.md @@ -3,7 +3,7 @@ title: "REST API interface" linkTitle: "REST API interface" weight: 3 description: > - The gNMIc Operator has a REST API endpoint. This documentation explains what routes are available and how to use them. + This document describes the REST API exposed by the gNMIc Operator, including the available endpoints, request formats, and usage examples. --- @@ -13,8 +13,8 @@ All URIs are relative to *http://localhost:8082* | Class | Method | HTTP request | Description | |------------ | ------------- | ------------- | -------------| -| *DefaultApi* | [**applyTargets**](/docs/advanced/rest-api-documentation/DefaultApi) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | -*DefaultApi* | [**getClusterPlan**](/docs/advanced/rest-api-documentation/DefaultApi) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | +| *DefaultApi* | [**applyTargets**](/docs/advanced/rest-api-documentation/apis/DefaultApi) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | +*DefaultApi* | [**getClusterPlan**](/docs/advanced/rest-api-documentation/apis/DefaultApi) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | @@ -31,3 +31,10 @@ All URIs are relative to *http://localhost:8082* - **Type**: HTTP Bearer Token authentication + +### signature + +- **Type**: API key +- **API key parameter name**: X-Hook-Signature +- **Location**: HTTP header + From 04244041f31841970a3401a29d897cb36af1c3c9 Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Mon, 8 Jun 2026 15:00:39 +0200 Subject: [PATCH 10/17] paths again and small corrections --- .../markdown-documentation/README.mustache | 4 ++-- .../markdown-documentation/api.mustache | 8 ++++---- .../markdown-documentation/model.mustache | 6 +++--- docs/content/docs/advanced/openapi.yaml | 1 + .../advanced/rest-api-documentation/Apis/DefaultApi.md | 10 +++++----- .../advanced/rest-api-documentation/Models/Target.md | 2 +- .../docs/advanced/rest-api-documentation/_index.md | 6 +++--- 7 files changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache index 70ef54a6..9bf976ad 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache @@ -14,7 +14,7 @@ All URIs are relative to *{{{basePath}}}:8082* | Class | Method | HTTP request | Description | |------------ | ------------- | ------------- | -------------| -{{#apiInfo}}{{#apis}}{{#operations}}| {{#operation}}*{{classname}}* | [**{{operationId}}**](/docs/advanced/rest-api-documentation/apis/{{apiDocPath}}{{classname}}) | **{{httpMethod}}** {{path}} | {{{summary}}}{{^summary}}{{{notes}}}{{/summary}} | +{{#apiInfo}}{{#apis}}{{#operations}}| {{#operation}}*{{#lambda.lowercase}}{{classname}}{{/lambda.lowercase}}* | [**{{operationId}}**](/docs/advanced/rest-api-documentation/apis/{{#lambda.lowercase}}{{classname}}{{/lambda.lowercase}}) | **{{httpMethod}}** {{path}} | {{{summary}}}{{^summary}}{{{notes}}}{{/summary}} | {{/operation}}{{/operations}}{{/apis}}{{/apiInfo}} {{/generateApiDocs}} @@ -23,7 +23,7 @@ All URIs are relative to *{{{basePath}}}:8082* ## Documentation for Models {{#modelPackage}} -{{#models}}{{#model}} - [{{{classname}}}](/docs/advanced/rest-api-documentation/{{{modelPackage}}}/{{modelDocPath}}{{{classFilename}}}/) +{{#models}}{{#model}} - [{{#lambda.lowercase}}{{{classname}}}{{/lambda.lowercase}}](/docs/advanced/rest-api-documentation/models/{{#lambda.lowercase}}{{{classFilename}}}{{/lambda.lowercase}}/) {{/model}}{{/models}} {{/modelPackage}} {{^modelPackage}} diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache index 0935152a..5fb1b8e1 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache @@ -6,14 +6,14 @@ description: > Available HTTP routes on the gNMIc Operator API interface. --- -# {{classname}}{{#description}} +# {{#lambda.lowercase}}{{classname}}{{/lambda.lowercase}}{{#description}} {{.}}{{/description}} All URIs are relative to *{{basePath}}:8082* | Method | HTTP request | Description | |------------- | ------------- | -------------| -{{#operations}}{{#operation}}| [**{{operationId}}**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{summary}} | +{{#operations}}{{#operation}}| [**{{operationId}}**]({{#lambda.lowercase}}{{classname}}{{/lambda.lowercase}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{summary}} | {{/operation}}{{/operations}} {{#operations}} @@ -30,12 +30,12 @@ All URIs are relative to *{{basePath}}:8082* {{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}} |Name | Type | Description | Notes | |------------- | ------------- | ------------- | -------------|{{/-last}}{{/allParams}} -{{#allParams}}| **{{paramName}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{#isFile}}**{{dataType}}**{{/isFile}}{{^isFile}}{{#generateModelDocs}}[**{{dataType}}**](/docs/advanced/rest-api-documentation/{{modelPackage}}/{{baseType}}/){{/generateModelDocs}}{{^generateModelDocs}}**{{dataType}}**{{/generateModelDocs}}{{/isFile}}{{/isPrimitiveType}}| {{description}} |{{^required}} [optional]{{/required}}{{#defaultValue}} [default to {{.}}]{{/defaultValue}}{{#allowableValues}} [enum: {{#values}}{{{.}}}{{^-last}}, {{/-last}}{{/values}}]{{/allowableValues}} | +{{#allParams}}| **{{paramName}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{#isFile}}**{{dataType}}**{{/isFile}}{{^isFile}}{{#generateModelDocs}}[**{{dataType}}**](/docs/advanced/rest-api-documentation/models/{{#lambda.lowercase}}{{baseType}}{{/lambda.lowercase}}/){{/generateModelDocs}}{{^generateModelDocs}}**{{dataType}}**{{/generateModelDocs}}{{/isFile}}{{/isPrimitiveType}}| {{description}} |{{^required}} [optional]{{/required}}{{#defaultValue}} [default to {{.}}]{{/defaultValue}}{{#allowableValues}} [enum: {{#values}}{{{.}}}{{^-last}}, {{/-last}}{{/values}}]{{/allowableValues}} | {{/allParams}} ### Return type -{{#returnType}}{{#returnTypeIsPrimitive}}**{{returnType}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}{{#generateModelDocs}}[**{{returnType}}**](/docs/advanced/rest-api-documentation/{{modelPackage}}/{{returnBaseType}}/){{/generateModelDocs}}{{^generateModelDocs}}**{{returnType}}**{{/generateModelDocs}}{{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}null (empty response body){{/returnType}} +{{#returnType}}{{#returnTypeIsPrimitive}}**{{returnType}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}{{#generateModelDocs}}[**{{returnType}}**](/docs/advanced/rest-api-documentation/models/{{#lambda.lowercase}}{{returnBaseType}}{{/lambda.lowercase}}/){{/generateModelDocs}}{{^generateModelDocs}}**{{returnType}}**{{/generateModelDocs}}{{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}null (empty response body){{/returnType}} ### Authorization diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache index d9a711c5..1905a91e 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache @@ -8,7 +8,7 @@ description: > {{#models}} {{#model}} -# {{{classname}}} +# {{#lambda.lowercase}}{{{classname}}}{{/lambda.lowercase}} {{#description}} {{{description}}} {{/description}} @@ -19,10 +19,10 @@ description: > |------------ | ------------- | ------------- | -------------| {{#parent}} {{#parentVars}} -| **{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{complexType}}.md){{/isPrimitiveType}} | {{{description}}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}} | +| **{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{#lambda.lowercase}}{{complexType}}{{/lambda.lowercase}}.md){{/isPrimitiveType}} | {{{description}}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}} | {{/parentVars}} {{/parent}} -{{#vars}}| **{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{complexType}}.md){{/isPrimitiveType}} | {{{description}}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}} | +{{#vars}}| **{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{#lambda.lowercase}}{{complexType}}{{/lambda.lowercase}}.md){{/isPrimitiveType}} | {{{description}}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}} | {{/vars}} [[Back to Model list]](/docs/advanced/rest-api-documentation/#documentation-for-models) [[Back to API list]](/docs/advanced/rest-api-documentation/#documentation-for-api-endpoints) [[Back to README]](/docs/advanced/rest-api-documentation/) diff --git a/docs/content/docs/advanced/openapi.yaml b/docs/content/docs/advanced/openapi.yaml index 5f6ea35b..7dfbc24b 100644 --- a/docs/content/docs/advanced/openapi.yaml +++ b/docs/content/docs/advanced/openapi.yaml @@ -19,6 +19,7 @@ paths: signature: [] requestBody: required: true + description: Target must be passed as a list, multiple targets possible. content: application/json: schema: diff --git a/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md b/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md index e0d65613..2415c558 100644 --- a/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md +++ b/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md @@ -6,14 +6,14 @@ description: > Available HTTP routes on the gNMIc Operator API interface. --- -# DefaultApi +# defaultapi All URIs are relative to *http://localhost:8082* | Method | HTTP request | Description | |------------- | ------------- | -------------| -| [**applyTargets**](DefaultApi.md#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | -| [**getClusterPlan**](DefaultApi.md#getClusterPlan) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | +| [**applyTargets**](defaultapi.md#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | +| [**getClusterPlan**](defaultapi.md#getClusterPlan) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | @@ -26,11 +26,11 @@ Interface for real-time target updates, usually using a webhook. Targets are app |Name | Type | Description | Notes | |------------- | ------------- | ------------- | -------------| -| **Target** | [**List**](/docs/advanced/rest-api-documentation/Models/Target/)| | | +| **Target** | [**List**](/docs/advanced/rest-api-documentation/models/target/)| Target must be passed as a list, multiple targets possible. | | ### Return type -[**List**](/docs/advanced/rest-api-documentation/Models/Target/) +[**List**](/docs/advanced/rest-api-documentation/models/target/) ### Authorization diff --git a/docs/content/docs/advanced/rest-api-documentation/Models/Target.md b/docs/content/docs/advanced/rest-api-documentation/Models/Target.md index 4292d45c..17967253 100644 --- a/docs/content/docs/advanced/rest-api-documentation/Models/Target.md +++ b/docs/content/docs/advanced/rest-api-documentation/Models/Target.md @@ -6,7 +6,7 @@ description: > Documentation for OpenAPI models and their schema-defined properties. --- -# Target +# target Network device to be monitored. Properties not marked as optional must be in JSON body. ## Properties diff --git a/docs/content/docs/advanced/rest-api-documentation/_index.md b/docs/content/docs/advanced/rest-api-documentation/_index.md index a47cb911..a0ad838b 100644 --- a/docs/content/docs/advanced/rest-api-documentation/_index.md +++ b/docs/content/docs/advanced/rest-api-documentation/_index.md @@ -13,14 +13,14 @@ All URIs are relative to *http://localhost:8082* | Class | Method | HTTP request | Description | |------------ | ------------- | ------------- | -------------| -| *DefaultApi* | [**applyTargets**](/docs/advanced/rest-api-documentation/apis/DefaultApi) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | -*DefaultApi* | [**getClusterPlan**](/docs/advanced/rest-api-documentation/apis/DefaultApi) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | +| *defaultapi* | [**applyTargets**](/docs/advanced/rest-api-documentation/apis/defaultapi) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | +*defaultapi* | [**getClusterPlan**](/docs/advanced/rest-api-documentation/apis/defaultapi) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | ## Documentation for Models - - [Target](/docs/advanced/rest-api-documentation/Models/Target/) + - [target](/docs/advanced/rest-api-documentation/models/target/) From ede85b6aeda3bde6f7dfcb864240e2add432d3c6 Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Mon, 8 Jun 2026 16:00:20 +0200 Subject: [PATCH 11/17] remove #section hyperlink --- .../openapi-templates/markdown-documentation/api.mustache | 2 +- .../openapi-templates/markdown-documentation/model.mustache | 2 -- .../docs/advanced/rest-api-documentation/Apis/DefaultApi.md | 4 ++-- .../docs/advanced/rest-api-documentation/Models/Target.md | 2 -- 4 files changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache index 5fb1b8e1..8a75a8a9 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache @@ -13,7 +13,7 @@ All URIs are relative to *{{basePath}}:8082* | Method | HTTP request | Description | |------------- | ------------- | -------------| -{{#operations}}{{#operation}}| [**{{operationId}}**]({{#lambda.lowercase}}{{classname}}{{/lambda.lowercase}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{summary}} | +{{#operations}}{{#operation}}| **{{operationId}}** | **{{httpMethod}}** {{path}} | {{summary}} | {{/operation}}{{/operations}} {{#operations}} diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache index 1905a91e..d5d3f74a 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache @@ -25,7 +25,5 @@ description: > {{#vars}}| **{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{#lambda.lowercase}}{{complexType}}{{/lambda.lowercase}}.md){{/isPrimitiveType}} | {{{description}}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}} | {{/vars}} -[[Back to Model list]](/docs/advanced/rest-api-documentation/#documentation-for-models) [[Back to API list]](/docs/advanced/rest-api-documentation/#documentation-for-api-endpoints) [[Back to README]](/docs/advanced/rest-api-documentation/) - {{/model}} {{/models}} \ No newline at end of file diff --git a/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md b/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md index 2415c558..ec3b4c08 100644 --- a/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md +++ b/docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md @@ -12,8 +12,8 @@ All URIs are relative to *http://localhost:8082* | Method | HTTP request | Description | |------------- | ------------- | -------------| -| [**applyTargets**](defaultapi.md#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | -| [**getClusterPlan**](defaultapi.md#getClusterPlan) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | +| **applyTargets** | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. | +| **getClusterPlan** | **GET** /clusters/:namespace/:name/plan | Get cluster plan. | diff --git a/docs/content/docs/advanced/rest-api-documentation/Models/Target.md b/docs/content/docs/advanced/rest-api-documentation/Models/Target.md index 17967253..ec4df149 100644 --- a/docs/content/docs/advanced/rest-api-documentation/Models/Target.md +++ b/docs/content/docs/advanced/rest-api-documentation/Models/Target.md @@ -20,5 +20,3 @@ Network device to be monitored. Properties not marked as optional must be in JSO | **labels** | [**List**](map.md) | Input of labels as key:value pair. | [optional] [default to null] | | **operation** | **String** | Either `created`, `updated` or `deleted`. `created` and `updated` are identical and both apply the target. | [default to null] | -[[Back to Model list]](/docs/advanced/rest-api-documentation/#documentation-for-models) [[Back to API list]](/docs/advanced/rest-api-documentation/#documentation-for-api-endpoints) [[Back to README]](/docs/advanced/rest-api-documentation/) - From 8e8e25189c139b6aea8cddee2dc1d636c834ba9f Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Mon, 8 Jun 2026 16:46:17 +0200 Subject: [PATCH 12/17] add push-interface document structure --- docs/content/docs/advanced/openapi-generator-config.yaml | 2 ++ docs/content/docs/examples/NetBox/webhook/_index.md | 9 +++++++++ .../docs/user-guide/targetsource/push-interface.md | 9 +++++++++ 3 files changed, 20 insertions(+) create mode 100644 docs/content/docs/examples/NetBox/webhook/_index.md create mode 100644 docs/content/docs/user-guide/targetsource/push-interface.md diff --git a/docs/content/docs/advanced/openapi-generator-config.yaml b/docs/content/docs/advanced/openapi-generator-config.yaml index 9ab8481d..fb047ff3 100644 --- a/docs/content/docs/advanced/openapi-generator-config.yaml +++ b/docs/content/docs/advanced/openapi-generator-config.yaml @@ -1,3 +1,5 @@ +# docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate -c /local/docs/content/docs/advanced/openapi-generator-config.yaml + generatorName: markdown inputSpec: /local/docs/content/docs/advanced/openapi.yaml outputDir: /local/docs/content/docs/advanced/rest-api-documentation diff --git a/docs/content/docs/examples/NetBox/webhook/_index.md b/docs/content/docs/examples/NetBox/webhook/_index.md new file mode 100644 index 00000000..1b58a1df --- /dev/null +++ b/docs/content/docs/examples/NetBox/webhook/_index.md @@ -0,0 +1,9 @@ +--- +title: "Real-time target udpate with webhook" +linkTitle: "Real-time target udpate with webhook" +weight: 2 +description: > + Configure a webhook in Netbox to update targets in the gNMIc Operator real-time. +--- + +## Implemented soon \ No newline at end of file diff --git a/docs/content/docs/user-guide/targetsource/push-interface.md b/docs/content/docs/user-guide/targetsource/push-interface.md new file mode 100644 index 00000000..a8a4f75e --- /dev/null +++ b/docs/content/docs/user-guide/targetsource/push-interface.md @@ -0,0 +1,9 @@ +--- +title: "Push-based interface" +linkTitle: "Push-based interface" +weight: 4 +description: > + Enables REST API interface that accepts real-time target updates. +--- + +# Titel 1 From 7bc8886d19acaa58edcc5bdb8388249bae8ff452 Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Mon, 8 Jun 2026 18:33:31 +0200 Subject: [PATCH 13/17] first version push --- .../docs/examples/NetBox/webhook/_index.md | 4 +- .../user-guide/targetsource/providers/http.md | 3 - .../user-guide/targetsource/push-interface.md | 9 -- .../docs/user-guide/targetsource/push.md | 105 ++++++++++++++++++ 4 files changed, 107 insertions(+), 14 deletions(-) delete mode 100644 docs/content/docs/user-guide/targetsource/push-interface.md create mode 100644 docs/content/docs/user-guide/targetsource/push.md diff --git a/docs/content/docs/examples/NetBox/webhook/_index.md b/docs/content/docs/examples/NetBox/webhook/_index.md index 1b58a1df..70cf240e 100644 --- a/docs/content/docs/examples/NetBox/webhook/_index.md +++ b/docs/content/docs/examples/NetBox/webhook/_index.md @@ -1,6 +1,6 @@ --- -title: "Real-time target udpate with webhook" -linkTitle: "Real-time target udpate with webhook" +title: "Real-time target update with webhook" +linkTitle: "Real-time target update with webhook" weight: 2 description: > Configure a webhook in Netbox to update targets in the gNMIc Operator real-time. diff --git a/docs/content/docs/user-guide/targetsource/providers/http.md b/docs/content/docs/user-guide/targetsource/providers/http.md index de0f3b6b..99bc1b2d 100644 --- a/docs/content/docs/user-guide/targetsource/providers/http.md +++ b/docs/content/docs/user-guide/targetsource/providers/http.md @@ -6,8 +6,6 @@ description: > The HTTP provider discovers targets from an HTTP endpoint returning JSON, or receives webhook-based updates when push mode is enabled. --- -The HTTP provider discovers targets from an HTTP endpoint returning JSON, or receives webhook-based updates when push mode is enabled. - ## Basic Configuration ```yaml @@ -16,7 +14,6 @@ kind: TargetSource metadata: name: targetsource-1 spec: - provider: provider: http: url: http://inventory-service:8080/targets diff --git a/docs/content/docs/user-guide/targetsource/push-interface.md b/docs/content/docs/user-guide/targetsource/push-interface.md deleted file mode 100644 index a8a4f75e..00000000 --- a/docs/content/docs/user-guide/targetsource/push-interface.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "Push-based interface" -linkTitle: "Push-based interface" -weight: 4 -description: > - Enables REST API interface that accepts real-time target updates. ---- - -# Titel 1 diff --git a/docs/content/docs/user-guide/targetsource/push.md b/docs/content/docs/user-guide/targetsource/push.md new file mode 100644 index 00000000..18199694 --- /dev/null +++ b/docs/content/docs/user-guide/targetsource/push.md @@ -0,0 +1,105 @@ +--- +title: "Push mode" +linkTitle: "Push mode" +weight: 4 +description: > + Enables REST API interface that accepts real-time target updates. +--- + +## Basic configuration + +This CR enables the push interface with no authentication. + +```yaml +apiVersion: operator.gnmic.dev/v1alpha1 +kind: TargetSource +metadata: + name: targetsource-1 +spec: + provider: + http: + push: + enabled: true +``` + +## Spec Fields + +| Field | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `push` | object | No | - | Push interface config | +| `enabled` | bool | Yes | False | Whether the push interface is active | +| `auth` | object | No | - | Bearer token authentication | +| `signature` | object | No | - | HTTP body verification using HMAC | +| `algorithm` | string | No | sha512 | Algorithm for signature verification(`sha256`or`sha512`) | + +## Address + +The REST API endpoint runs on `http://cluster-address:8082/api/v1/:namespace/target-source/:name/applyTargets`. + +- `cluster-address`: Adress of your cluster, localhost during development. +- `:namespace`: Namespace the gNMIc controller runs in. +- `:name`: Name of the TargetSource. + +See [real-time target update with webhook](/docs/examples/netbox/webhook) for an on how to configure the URI. + +## REST API + +Refer to the [REST API documentation](/docs/advanced/rest-api-documentation/) for the expected request schema and payload format. Any system or automation capable of sending HTTP POST requests can integrate with this interface. Compatibility has been validated using a [Netbox webhook](/docs/examples/netbox/webhook). + +## Security + +The API supports Bearer Token authentication and X-Hook-Signature, both are optional and turned off by default. They can be used in combination and are enabled by adding them to the specification. + +### Bearer Authentication + +Bearer authentication compares a token stored in Kubernetes with the one sent in the HTTP header. The Kubernetes secret is referenced as `tokenSecretRef`. + +```yaml +apiVersion: operator.gnmic.dev/v1alpha1 +kind: TargetSource +metadata: + name: targetsource-1 +spec: + provider: + http: + push: + enabled: true + auth: + bearer: + tokenSecretRef: + name: gnmic-api-auth # secret name + key: bearer-token # secret key +``` + +This requires the [creation](https://kubernetes.ltd/docs/reference/kubectl/generated/kubectl_create/kubectl_create_secret_generic/) of an Opaque Kuberentes secret: + +- Must be in the same namespace the gNMIc controller runs in. +- `name`: refers to the secret name +- `key`: key of the secret +- Example: `kubectl create secret generic gnmic-api-auth --from-literal=bearer-token=Secret...` + +#### Authorization Header + +HTTP request must contain the Bearer token in the header in the format: + +```yaml +Authorization: Bearer Secret... +``` + +### Signature + +Signature verification requires an Opaque Kubernetes secret that stores the shared key (see Bearer Authentication). For each request, the HMAC generated from the request body and shared key must be provided in the `X-Hook-Signature` header. Refer to the [Netbox webhook](/docs/examples/netbox/webhook) example for a configuration reference. + +```yaml +spec: + provider: + http: + push: + enabled: true + auth: + signature: + algorithm: sha512 + secretRef: + name: gnmic-signature + key: signature +``` From a4cdf035f9b43b010fc408f96ce44c21c259e0de Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Mon, 8 Jun 2026 23:10:07 +0200 Subject: [PATCH 14/17] add Netbox webhook example --- .../docs/examples/NetBox/webhook/_index.md | 120 +++++++++++++++++- .../docs/user-guide/targetsource/push.md | 6 +- 2 files changed, 124 insertions(+), 2 deletions(-) diff --git a/docs/content/docs/examples/NetBox/webhook/_index.md b/docs/content/docs/examples/NetBox/webhook/_index.md index 70cf240e..3e499d3b 100644 --- a/docs/content/docs/examples/NetBox/webhook/_index.md +++ b/docs/content/docs/examples/NetBox/webhook/_index.md @@ -6,4 +6,122 @@ description: > Configure a webhook in Netbox to update targets in the gNMIc Operator real-time. --- -## Implemented soon \ No newline at end of file +## Netbox Webhook Configuration + +This example will run you through the configuration of a webhook in Netbox. This allows for real-time target updates from Netbox into the gNMIc Operator. The configuration steps are: + +1. Apply TargetSource +2. Create Kubernetes Secrets +3. Configure Webhook +4. Create Event Rule +5. Verification + +### Prerequisites + +- Kubernetes cluster with gNMIc Operator installed +- kubectl access to your cluster +- Running Netbox instance +- Netbox can send HTTP requests to the gNMIc Operator + +### 1. Apply TargetSource + +Apply the targetSource with `kubectl apply -f netbox.yaml -n default`. + +- `enabled` set to `true`, otherwise target updates are rejected +- Bearer authentication and Signature activated + +```yaml +# netbox.yaml +apiVersion: operator.gnmic.dev/v1alpha1 +kind: TargetSource +metadata: + name: netbox +spec: + provider: + http: + push: + enabled: true + auth: + bearer: + tokenSecretRef: + name: gnmic-api-auth + key: bearer-token + signature: + secretRef: + name: gnmic-signature + key: signature + targetLabels: + integrationtest: http + targetProfile: default +``` + +### 2. Create Kubernetes Secrets + +Authentication and the signature both require a Kubernetes secret. These must: + +- Be in the same namespace as the TargetSource, in this case `default`. +- `Name` and `Key` align with the TargetSource spec. + +```bash +kubectl create secret generic gnmic-api-auth --from-literal=bearer-token=thisIsASecureToken -n default +kubectl create secret generic gnmic-signature --from-literal=signature=SecretSignature -n default +``` + +### 3. Configure Webhook + +Now we switch to Netbox and configure a webhook. The webhook gets triggered by events like `device update` and sends a HTTP POST request to the gNMIc Operator. + +Configure the Webhook under `Operations > Webhooks` and create a new Webhook with the following settings: + +- *Name*: GNMIc operator push +- *URL*: `http://gnmic-controller-manager-api.gnmic-system.svc.cluster.local:8082/api/v1/default/target-source/netbox/applyTargets` + - The cluster-address might be `http://localhost:8082/` or `http://servername:8082/`, depending on your setup. +- *HTTP method*: POST +- *HTTP content type*: application/json +- *SSL Verification*: true +- *Additional headers:* `Authorization: Bearer thisIsASecureToken` +- *Body Template*: + + ```json + [ + { + "name": "{{ data.name }}", + "address": "{{ data.primary_ip4.address.split('/')[0] }}", + "operation": "{{ event }}", + "targetProfile": "{{ data.custom_fields.target_profile | default('', true) }}", + "port": {{ data.custom_fields.gnmic_port | default(57400, true) }}, + "labels": [ + { + "key": "vendor", + "value": "{{ data.device_type.manufacturer.name }}" + } + ] + } + ] + ``` + +- *Secret*: `SecretSignature` + +### 4. Create Event Rule + +The webhook just created needs a trigger, which is created as an event rule under `Operations > Event Rules`. + +- *Name*: gNMIc Operator push target change +- *Object types*: DCIM > Device +- *Event types*: "Object Created", "Object Updated", "Object Deleted" +- *Action type*: Webhook +- *Webhook*: gNMIc Operator push + +### 5. Verification + +Updating a device in Netbox will now trigger the webhook, verify this with these commands: + +```bash +kubectl get targets +kubectl get targets -o yaml + +# Check logs of incoming POST requests: +kubectl logs -n gnmic-system deploy/gnmic-controller-manager -f +``` + +Every POST request received will write logs, even if rejected. If no POST request are being logged, the request is not received. diff --git a/docs/content/docs/user-guide/targetsource/push.md b/docs/content/docs/user-guide/targetsource/push.md index 18199694..5ed69e4a 100644 --- a/docs/content/docs/user-guide/targetsource/push.md +++ b/docs/content/docs/user-guide/targetsource/push.md @@ -37,7 +37,7 @@ spec: The REST API endpoint runs on `http://cluster-address:8082/api/v1/:namespace/target-source/:name/applyTargets`. - `cluster-address`: Adress of your cluster, localhost during development. -- `:namespace`: Namespace the gNMIc controller runs in. +- `:namespace`: Namespace the TargetSource is created in. - `:name`: Name of the TargetSource. See [real-time target update with webhook](/docs/examples/netbox/webhook) for an on how to configure the URI. @@ -86,6 +86,10 @@ HTTP request must contain the Bearer token in the header in the format: Authorization: Bearer Secret... ``` +#### Reverse Proxy + +Use one. + ### Signature Signature verification requires an Opaque Kubernetes secret that stores the shared key (see Bearer Authentication). For each request, the HMAC generated from the request body and shared key must be provided in the `X-Hook-Signature` header. Refer to the [Netbox webhook](/docs/examples/netbox/webhook) example for a configuration reference. From b17bf93ef606028be3fa102e8a52ff4041791032 Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Tue, 9 Jun 2026 00:07:13 +0200 Subject: [PATCH 15/17] small grammar changes --- .../markdown-documentation/README.mustache | 2 + .../markdown-documentation/model.mustache | 2 +- .../rest-api-documentation/Models/Target.md | 2 +- .../advanced/rest-api-documentation/_index.md | 2 + .../examples/NetBox/Export Template/_index.md | 12 ++--- .../docs/examples/NetBox/REST API/_index.md | 4 +- .../docs/examples/NetBox/webhook/_index.md | 45 +++++++++++-------- .../docs/user-guide/targetsource/push.md | 18 +++++--- 8 files changed, 51 insertions(+), 36 deletions(-) diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache index 9bf976ad..7b3df486 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache @@ -34,6 +34,8 @@ No model defined in this package {{! TODO: optional documentation for authorization? }} ## Documentation for Authorization +For a detailed explanation on how to configure the required secrets within the gNMIc Operator, refer to [TargetSource > Push mode](/docs/user-guide/targetsource/push/). + {{^authMethods}} All endpoints do not require authorization. {{/authMethods}} diff --git a/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache b/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache index d5d3f74a..3ee88fd2 100644 --- a/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache +++ b/docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache @@ -8,7 +8,7 @@ description: > {{#models}} {{#model}} -# {{#lambda.lowercase}}{{{classname}}}{{/lambda.lowercase}} +# {{#lambda}}{{{classname}}}{{/lambda}} {{#description}} {{{description}}} {{/description}} diff --git a/docs/content/docs/advanced/rest-api-documentation/Models/Target.md b/docs/content/docs/advanced/rest-api-documentation/Models/Target.md index ec4df149..58c08caa 100644 --- a/docs/content/docs/advanced/rest-api-documentation/Models/Target.md +++ b/docs/content/docs/advanced/rest-api-documentation/Models/Target.md @@ -6,7 +6,7 @@ description: > Documentation for OpenAPI models and their schema-defined properties. --- -# target +# Target Network device to be monitored. Properties not marked as optional must be in JSON body. ## Properties diff --git a/docs/content/docs/advanced/rest-api-documentation/_index.md b/docs/content/docs/advanced/rest-api-documentation/_index.md index a0ad838b..93b2d678 100644 --- a/docs/content/docs/advanced/rest-api-documentation/_index.md +++ b/docs/content/docs/advanced/rest-api-documentation/_index.md @@ -26,6 +26,8 @@ All URIs are relative to *http://localhost:8082* ## Documentation for Authorization +For a detailed explanation on how to configure the required secrets within the gNMIc Operator, refer to [TargetSource > Push mode](/docs/user-guide/targetsource/push/). + ### bearerAuth diff --git a/docs/content/docs/examples/NetBox/Export Template/_index.md b/docs/content/docs/examples/NetBox/Export Template/_index.md index 2cc48b3b..fd481841 100644 --- a/docs/content/docs/examples/NetBox/Export Template/_index.md +++ b/docs/content/docs/examples/NetBox/Export Template/_index.md @@ -1,6 +1,6 @@ --- -title: "NetBox (Export Template)" -linkTitle: "NetBox Export Template" +title: "Pull with Export Template" +linkTitle: "Pull with Export Template" weight: 1 description: > Discover targets from NetBox using HTTP provider with NetBox Export Template @@ -12,14 +12,14 @@ Export Templates offer powerful filtering, transformation, and formatting direct ## Overview -An **Export Template** is a Jinja2 template defined in NetBox that: +An **Export Template** is a Jinja2 template that: 1. **Queries** NetBox's internal database (devices, interfaces, etc.) 2. **Filters** results based on custom criteria -3. **Transforms** data into your desired output format (JSON, YAML, CSV, etc.) -4. **Returns** the formatted output via a custom REST API endpoint +3. **Transforms** data into your desired output format +4. **Returns** the formatted output via REST API endpoint -When used with gNMIc's HTTP provider, the operator simply fetches the rendered JSON template and parses the result — no additional gNMIc Operator transformation needed if done correctly. +When used with gNMIc's HTTP provider, the operator fetches the rendered JSON template and parses the result with no further transformation needed by the gNMIc Operator. --- diff --git a/docs/content/docs/examples/NetBox/REST API/_index.md b/docs/content/docs/examples/NetBox/REST API/_index.md index 18111d75..bb4be0e4 100644 --- a/docs/content/docs/examples/NetBox/REST API/_index.md +++ b/docs/content/docs/examples/NetBox/REST API/_index.md @@ -1,6 +1,6 @@ --- -title: "NetBox (REST API)" -linkTitle: "NetBox REST" +title: "Pull with REST API" +linkTitle: "Pull with REST API"" weight: 2 description: > Discover targets from NetBox using the HTTP provider and NetBox REST API diff --git a/docs/content/docs/examples/NetBox/webhook/_index.md b/docs/content/docs/examples/NetBox/webhook/_index.md index 3e499d3b..b8b11467 100644 --- a/docs/content/docs/examples/NetBox/webhook/_index.md +++ b/docs/content/docs/examples/NetBox/webhook/_index.md @@ -1,14 +1,14 @@ --- -title: "Real-time target update with webhook" -linkTitle: "Real-time target update with webhook" +title: "Push mode with webhook" +linkTitle: "Push mode with webhook" weight: 2 description: > - Configure a webhook in Netbox to update targets in the gNMIc Operator real-time. + Configure a webhook in NetBox to update targets in the gNMIc Operator in real time. --- ## Netbox Webhook Configuration -This example will run you through the configuration of a webhook in Netbox. This allows for real-time target updates from Netbox into the gNMIc Operator. The configuration steps are: +This tutorial walks through configuring a webhook in NetBox to push real-time target updates to the gNMIc Operator. The workflow includes the following steps: 1. Apply TargetSource 2. Create Kubernetes Secrets @@ -19,16 +19,18 @@ This example will run you through the configuration of a webhook in Netbox. This ### Prerequisites - Kubernetes cluster with gNMIc Operator installed -- kubectl access to your cluster -- Running Netbox instance -- Netbox can send HTTP requests to the gNMIc Operator +- `kubectl` access to your cluster +- Running NetBox instance +- Network connectivity from NetBox to the gNMIc Operator API endpoint + +--- ### 1. Apply TargetSource -Apply the targetSource with `kubectl apply -f netbox.yaml -n default`. +Apply the TargetSource manifest: `kubectl apply -f netbox.yaml -n default` -- `enabled` set to `true`, otherwise target updates are rejected -- Bearer authentication and Signature activated +- `enabled` must be set to `true`, otherwise updates are rejected. +- Bearer authentication and signature verification are enabled. ```yaml # netbox.yaml @@ -55,12 +57,14 @@ spec: targetProfile: default ``` +> Namespace is `default`, the name of the TargetSource is `netbox`. These values will be in the URL in step 3. + ### 2. Create Kubernetes Secrets -Authentication and the signature both require a Kubernetes secret. These must: +Bearer authentication and signature verification both require Kubernetes secrets. Ensure that the secrets: -- Be in the same namespace as the TargetSource, in this case `default`. -- `Name` and `Key` align with the TargetSource spec. +- Are created in the same namespace as the TargetSource (`default` in this example). +- Use `name` and `key` values that match the TargetSource spec. ```bash kubectl create secret generic gnmic-api-auth --from-literal=bearer-token=thisIsASecureToken -n default @@ -69,13 +73,14 @@ kubectl create secret generic gnmic-signature --from-literal=signature=SecretSig ### 3. Configure Webhook -Now we switch to Netbox and configure a webhook. The webhook gets triggered by events like `device update` and sends a HTTP POST request to the gNMIc Operator. +Next, configure a webhook in NetBox. The webhook is triggered by device events (for example, updates) and sends an HTTP POST request to the gNMIc Operator. -Configure the Webhook under `Operations > Webhooks` and create a new Webhook with the following settings: +In NetBox, go to `Operations > Webhooks` and create a webhook with the following settings: - *Name*: GNMIc operator push - *URL*: `http://gnmic-controller-manager-api.gnmic-system.svc.cluster.local:8082/api/v1/default/target-source/netbox/applyTargets` - - The cluster-address might be `http://localhost:8082/` or `http://servername:8082/`, depending on your setup. + - Depending on your environment, the cluster address may instead be `http://localhost:8082/` or `http://servername:8082/`. + - URL contains the namespace `default` and TargetSource name `netbox`. - *HTTP method*: POST - *HTTP content type*: application/json - *SSL Verification*: true @@ -104,7 +109,7 @@ Configure the Webhook under `Operations > Webhooks` and create a new Webhook wit ### 4. Create Event Rule -The webhook just created needs a trigger, which is created as an event rule under `Operations > Event Rules`. +The webhook requires a trigger, configured as an event rule under `Operations > Event Rules`. - *Name*: gNMIc Operator push target change - *Object types*: DCIM > Device @@ -112,9 +117,11 @@ The webhook just created needs a trigger, which is created as an event rule unde - *Action type*: Webhook - *Webhook*: gNMIc Operator push +--- + ### 5. Verification -Updating a device in Netbox will now trigger the webhook, verify this with these commands: +Updating a device in NetBox should now trigger the webhook. Verify this with the following commands: ```bash kubectl get targets @@ -124,4 +131,4 @@ kubectl get targets -o yaml kubectl logs -n gnmic-system deploy/gnmic-controller-manager -f ``` -Every POST request received will write logs, even if rejected. If no POST request are being logged, the request is not received. +Every incoming POST request is logged, including rejected requests. If no POST requests appear in the logs, the webhook request is not reaching the gNMIc Operator. diff --git a/docs/content/docs/user-guide/targetsource/push.md b/docs/content/docs/user-guide/targetsource/push.md index 5ed69e4a..9fa35fdf 100644 --- a/docs/content/docs/user-guide/targetsource/push.md +++ b/docs/content/docs/user-guide/targetsource/push.md @@ -40,16 +40,20 @@ The REST API endpoint runs on `http://cluster-address:8082/api/v1/:namespace/tar - `:namespace`: Namespace the TargetSource is created in. - `:name`: Name of the TargetSource. -See [real-time target update with webhook](/docs/examples/netbox/webhook) for an on how to configure the URI. +See [Push mode with webhook](/docs/examples/netbox/webhook) for an example on how to configure the URL. ## REST API -Refer to the [REST API documentation](/docs/advanced/rest-api-documentation/) for the expected request schema and payload format. Any system or automation capable of sending HTTP POST requests can integrate with this interface. Compatibility has been validated using a [Netbox webhook](/docs/examples/netbox/webhook). +Refer to the [REST API documentation](/docs/advanced/rest-api-documentation/) for the expected request schema and payload format. + +Any system or script capable of sending HTTP POST requests can integrate with this interface. ## Security The API supports Bearer Token authentication and X-Hook-Signature, both are optional and turned off by default. They can be used in combination and are enabled by adding them to the specification. +An example configuration of both is documented in the [Netbox webhook](/docs/examples/netbox/webhook) example. + ### Bearer Authentication Bearer authentication compares a token stored in Kubernetes with the one sent in the HTTP header. The Kubernetes secret is referenced as `tokenSecretRef`. @@ -86,13 +90,9 @@ HTTP request must contain the Bearer token in the header in the format: Authorization: Bearer Secret... ``` -#### Reverse Proxy - -Use one. - ### Signature -Signature verification requires an Opaque Kubernetes secret that stores the shared key (see Bearer Authentication). For each request, the HMAC generated from the request body and shared key must be provided in the `X-Hook-Signature` header. Refer to the [Netbox webhook](/docs/examples/netbox/webhook) example for a configuration reference. +Signature verification requires an Opaque Kubernetes secret that stores the shared key (see Bearer Authentication). For each request, the HMAC generated from the request body and shared key must be provided in the `X-Hook-Signature` header. ```yaml spec: @@ -107,3 +107,7 @@ spec: name: gnmic-signature key: signature ``` + +#### Reverse Proxy + +In order to have a secure setup, the HTTP post requests must be sent using TLS. The REST API interface does not support HTTPS, at least not directly. It is recommended to terminate the TLS connection at the reverse proxy and forward a plain HTTP request to the gNMIc Operator. From 5e5cca72d925fdfe0fdfe01bcd68cef2be894ac0 Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Tue, 9 Jun 2026 00:23:31 +0200 Subject: [PATCH 16/17] fix pages build --- docs/content/docs/examples/NetBox/REST API/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/docs/examples/NetBox/REST API/_index.md b/docs/content/docs/examples/NetBox/REST API/_index.md index bb4be0e4..fcbd990a 100644 --- a/docs/content/docs/examples/NetBox/REST API/_index.md +++ b/docs/content/docs/examples/NetBox/REST API/_index.md @@ -1,6 +1,6 @@ --- title: "Pull with REST API" -linkTitle: "Pull with REST API"" +linkTitle: "Pull with REST API" weight: 2 description: > Discover targets from NetBox using the HTTP provider and NetBox REST API From a9ad35f002a1a385d9d87473a7f3a9261ebc39c2 Mon Sep 17 00:00:00 2001 From: Roman Weber Date: Tue, 9 Jun 2026 00:29:03 +0200 Subject: [PATCH 17/17] remove unneeded files, cleanup --- .../docs/advanced/.openapi-generator-ignore | 23 ----- .../advanced/openapi-generator-config.yaml | 2 +- docs/content/docs/advanced/openapi.yaml | 91 ------------------- 3 files changed, 1 insertion(+), 115 deletions(-) delete mode 100644 docs/content/docs/advanced/.openapi-generator-ignore delete mode 100644 docs/content/docs/advanced/openapi.yaml diff --git a/docs/content/docs/advanced/.openapi-generator-ignore b/docs/content/docs/advanced/.openapi-generator-ignore deleted file mode 100644 index 7484ee59..00000000 --- a/docs/content/docs/advanced/.openapi-generator-ignore +++ /dev/null @@ -1,23 +0,0 @@ -# OpenAPI Generator Ignore -# Generated by openapi-generator https://github.com/openapitools/openapi-generator - -# Use this file to prevent files from being overwritten by the generator. -# The patterns follow closely to .gitignore or .dockerignore. - -# As an example, the C# client generator defines ApiClient.cs. -# You can make changes and tell OpenAPI Generator to ignore just this file by uncommenting the following line: -#ApiClient.cs - -# You can match any string of characters against a directory, file or extension with a single asterisk (*): -#foo/*/qux -# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux - -# You can recursively match patterns against a directory, file or extension with a double asterisk (**): -#foo/**/qux -# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux - -# You can also negate patterns with an exclamation (!). -# For example, you can ignore all files in a docs folder with the file extension .md: -#docs/*.md -# Then explicitly reverse the ignore rule for a single file: -#!docs/README.md diff --git a/docs/content/docs/advanced/openapi-generator-config.yaml b/docs/content/docs/advanced/openapi-generator-config.yaml index fb047ff3..5f041408 100644 --- a/docs/content/docs/advanced/openapi-generator-config.yaml +++ b/docs/content/docs/advanced/openapi-generator-config.yaml @@ -1,7 +1,7 @@ # docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate -c /local/docs/content/docs/advanced/openapi-generator-config.yaml generatorName: markdown -inputSpec: /local/docs/content/docs/advanced/openapi.yaml +inputSpec: /local/internal/apiserver/openapi.yaml outputDir: /local/docs/content/docs/advanced/rest-api-documentation templateDir: /local/docs/content/docs/advanced/openapi-templates/markdown-documentation files: diff --git a/docs/content/docs/advanced/openapi.yaml b/docs/content/docs/advanced/openapi.yaml deleted file mode 100644 index 7dfbc24b..00000000 --- a/docs/content/docs/advanced/openapi.yaml +++ /dev/null @@ -1,91 +0,0 @@ -openapi: 3.0.3 -info: - title: "gNMIc Operator REST API" - version: "0.0.1" -paths: - /clusters/:namespace/:name/plan: - get: - summary: "Get cluster plan." - operationId: "getClusterPlan" - responses: - '200': - description: "ClusterPlan returned" - /api/v1/:namespace/target-source/:name/applyTargets: - post: - summary: "Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator." - operationId: "applyTargets" - security: - - bearerAuth: [] - signature: [] - requestBody: - required: true - description: Target must be passed as a list, multiple targets possible. - content: - application/json: - schema: - $ref: '#/components/schemas/Targets' - responses: - '201': - description: "Targets applied successfully" - content: - application/json: - schema: - $ref: '#/components/schemas/Targets' - '401': - description: Access token is missing or invalid - -components: - schemas: - Targets: - type: array - items: - $ref: '#/components/schemas/Target' - Label: - description: TBD - type: object - additionalProperties: - description: Label must be passed as key:value pair, multiple values per key possible. - type: string - Target: - description: Network device to be monitored. Properties not marked as optional must be in JSON body. - type: object - required: - - name - - address - - operation - properties: - name: - type: string - description: Name of device to be monitored. - address: - type: string - description: IPv4/IPv6 address or hostname. - port: - type: integer - description: gNMIc port. - targetProfile: - type: string - description: TargetProfile applied to apply to this router. - labels: - type: array - description: Input of labels as key:value pair. - items: - $ref: '#/components/schemas/Label' - operation: - type: string - enum: - - created - - updated - - deleted - description: "Either `created`, `updated` or `deleted`. `created` and `updated` are identical and both apply the target." - securitySchemes: - bearerAuth: - type: http - scheme: bearer - description: HTTP authentication using Bearer token - signature: - name: X-Hook-Signature - type: apiKey - in: header - description: HMAC signature of the request payload - \ No newline at end of file