User Guide / TargetSource Docs

.gitignore

@@ -33,4 +33,5 @@ notes/
 docs/public
 docs/resources/_gen/
 docs/.hugo_build.lock
+test/integration/clab-*
 test/integration/**/clab-*

docs/content/docs/Apis/DefaultApi.md

@@ -0,0 +1,2 @@
+# DefaultApi
+

docs/content/docs/advanced/openapi-generator-config.yaml

@@ -0,0 +1,9 @@
+# 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/internal/apiserver/openapi.yaml
+outputDir: /local/docs/content/docs/advanced/rest-api-documentation
+templateDir: /local/docs/content/docs/advanced/openapi-templates
+files:
+  README.mustache:
+    destinationFilename: _index.md

docs/content/docs/advanced/openapi-templates/_index.mustache

@@ -0,0 +1,69 @@
+---
+title: "REST API interface"
+linkTitle: "REST API interface"
+weight: 3
+description: >
+  This document describes the REST API exposed by the gNMIc Operator, including the available endpoints, request formats, and usage examples.
+---
+
+{{#generateApiDocs}}
+<a name="documentation-for-api-endpoints"></a>
+## Documentation for API Endpoints
+
+All URIs are relative to *{{{basePath}}}:8082*
+
+| Class | Method | HTTP request | Description |
+|------------ | ------------- | ------------- | -------------|
+{{#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}}
+
+{{#generateModelDocs}}
+<a name="documentation-for-models"></a>
+## Documentation for Models
+
+{{#modelPackage}}
+{{#models}}{{#model}} - [{{#lambda.lowercase}}{{{classname}}}{{/lambda.lowercase}}](/docs/advanced/rest-api-documentation/models/{{#lambda.lowercase}}{{{classFilename}}}{{/lambda.lowercase}}/)
+{{/model}}{{/models}}
+{{/modelPackage}}
+{{^modelPackage}}
+No model defined in this package
+{{/modelPackage}}
+{{/generateModelDocs}}
+
+<a name="documentation-for-authorization"></a>{{! 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}}
+{{#authMethods}}
+{{#last}}
+    Authentication schemes defined for the API:
+{{/last}}
+{{/authMethods}}
+{{#authMethods}}
+<a name="{{name}}"></a>
+### {{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}}

docs/content/docs/advanced/openapi-templates/apis.mustache

@@ -0,0 +1,50 @@
+---
+title: "Routes"
+linkTitle: "Routes"
+weight: 4
+description: >
+  Available HTTP routes on the gNMIc Operator API interface.
+---
+
+# {{#lambda.lowercase}}{{classname}}{{/lambda.lowercase}}{{#description}}
+    {{.}}{{/description}}
+
+All URIs are relative to *{{basePath}}:8082*
+
+| Method | HTTP request | Description |
+|------------- | ------------- | -------------|
+{{#operations}}{{#operation}}| **{{operationId}}** | **{{httpMethod}}** {{path}} | {{summary}} |
+{{/operation}}{{/operations}}
+
+{{#operations}}
+{{#operation}}
+<a name="{{operationId}}"></a>
+# **{{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}}**](/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/models/{{#lambda.lowercase}}{{returnBaseType}}{{/lambda.lowercase}}/){{/generateModelDocs}}{{^generateModelDocs}}**{{returnType}}**{{/generateModelDocs}}{{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}null (empty response body){{/returnType}}
+
+### Authorization
+
+{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{name}}](/docs/advanced/rest-api-documentation/#{{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}}

docs/content/docs/advanced/openapi-templates/models.mustache

@@ -0,0 +1,29 @@
+---
+title: "Model"
+linkTitle: "Model"
+weight: 4
+description: >
+  Documentation for OpenAPI models and their schema-defined properties.
+---
+
+{{#models}}
+{{#model}}
+# {{#lambda}}{{{classname}}}{{/lambda}}
+{{#description}}
+{{{description}}}
+{{/description}}
+
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+{{#parent}}
+{{#parentVars}}
+| **{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}} | {{{description}}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}} |
+{{/parentVars}}
+{{/parent}}
+{{#vars}}| **{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}} | {{{description}}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}} |
+{{/vars}}
+
+    {{/model}}
+{{/models}}

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.
+---
+
+<a name="documentation-for-api-endpoints"></a>
+## 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. |
+
+
+<a name="documentation-for-models"></a>
+## Documentation for Models
+
+ - [Target](../Models/Target.md)
+
+
+<a name="documentation-for-authorization"></a>
+## Documentation for Authorization
+
+<a name="bearerAuth"></a>
+### bearerAuth
+
+- **Type**: HTTP Bearer Token authentication
+

docs/content/docs/advanced/rest-api-documentation/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 | 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. |
+
+
+<a name="applyTargets"></a>
+# **applyTargets**
+> List applyTargets(Target)
+
+Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator.
+
+### Parameters
+
+|Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **Target** | [**List**](../Models/Target.md)| Target must be passed as a list, multiple targets possible. | |
+
+### Return type
+
+[**List**](../Models/Target.md)
+
+### Authorization
+
+[signature](../README.md#signature), [bearerAuth](../README.md#bearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: application/json
+- **Accept**: application/json
+
+<a name="getClusterPlan"></a>
+# **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
+

docs/content/docs/advanced/rest-api-documentation/Models/Target.md

@@ -0,0 +1,14 @@
+# Target
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **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) | Labels must be map[string]string. For example vendor:nokia. | [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]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

docs/content/docs/advanced/rest-api-documentation/_index.md

@@ -0,0 +1,34 @@
+# Documentation for gNMIc Operator REST API
+
+<a name="documentation-for-api-endpoints"></a>
+## 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. |
+
+
+<a name="documentation-for-models"></a>
+## Documentation for Models
+
+ - [Target](./Models/Target.md)
+
+
+<a name="documentation-for-authorization"></a>
+## Documentation for Authorization
+
+<a name="bearerAuth"></a>
+### bearerAuth
+
+- **Type**: HTTP Bearer Token authentication
+
+<a name="signature"></a>
+### signature
+
+- **Type**: API key
+- **API key parameter name**: X-Hook-Signature
+- **Location**: HTTP header
+