From 8600bda01253386c0e0c1bf415e5a15c42da342a Mon Sep 17 00:00:00 2001 From: void404 Date: Fri, 28 Apr 2023 12:43:40 +0200 Subject: [PATCH 1/4] Add descriptions to AC fields --- ...applications.applicationconnector.crd.yaml | 49 ++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/installation/resources/crds/application-connector/applications.applicationconnector.crd.yaml b/installation/resources/crds/application-connector/applications.applicationconnector.crd.yaml index 1a7b6518af71..e132fee024ca 100644 --- a/installation/resources/crds/application-connector/applications.applicationconnector.crd.yaml +++ b/installation/resources/crds/application-connector/applications.applicationconnector.crd.yaml @@ -38,15 +38,19 @@ spec: maxLength: 63 pattern: '^([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]$' description: + description: 'Describes the connected Application.' type: string skipInstallation: type: boolean skipVerify: + description: 'Determines whether to skip TLS certificate verification for the Application.' type: boolean encodeUrl: + description: 'Allows for URL encoding. If set to `false`, your URL segments stay intact.' type: boolean default: true labels: + description: 'Defines the labels of the Application.' nullable: true additionalProperties: type: string @@ -57,7 +61,7 @@ spec: type: string tags: nullable: true - description: New fields used by V2 version + description: New fields used by V2 version. items: type: string type: array @@ -68,6 +72,7 @@ spec: longDescription: type: string services: + description: 'Contains all services that the Application provides.' type: array items: type: object @@ -80,12 +85,23 @@ spec: - "entries" properties: id: + description: 'Identifies the service that the Application provides.' type: string name: + description: > + Represents a unique name of the service. + Used for proxying in Application Gateway. type: string identifier: + description: > + Represents an additional identifier unique in the Application scope. + Allows the external system to provide its own identifier. type: string labels: + description: > + Specifies additional labels for the service offered by the Application. + In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. + In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. nullable: true additionalProperties: type: string @@ -98,11 +114,19 @@ spec: longDescription: type: string providerDisplayName: + description: > + Specifies a human-readable name of the Application service provider. + In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. + In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. type: string authCreateParameterSchema: description: New fields used by V2 version type: string entries: + description: > + Contains the information about the APIs and events that the service offered by the Application provides. + In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. + In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. type: array items: type: object @@ -112,6 +136,10 @@ spec: apiType: type: string type: + description: > + Specifies the entry type: `API` or `Events`. + In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. + In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. type: string enum: - "API" @@ -119,12 +147,26 @@ spec: gatewayUrl: type: string centralGatewayUrl: + description: > + Specifies the URL of Application Gateway. + Internal address resolvable only within the cluster. + This field is required for the API entry type. + In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. + In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. type: string accessLabel: + description: > + Specifies the label used in Istio rules in Application Connector. + This field is required for the API entry type. type: string maxLength: 63 pattern: '^([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]$' targetUrl: + description: > + Specifies the URL of a given API. + This field is required for the API entry type. + In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. + In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. type: string id: type: string @@ -155,6 +197,11 @@ spec: tokenEndpointURL: type: string tags: + description: > + Specifies additional tags used for better documentation of the available APIs. + In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), + it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), + you have to provide it yourself. type: array items: type: string From b06ff4bd883d18dd66916335a5336b4ca0613732 Mon Sep 17 00:00:00 2001 From: void404 Date: Fri, 28 Apr 2023 12:43:56 +0200 Subject: [PATCH 2/4] Prepare docs for generated table --- .../00-custom-resources/ac-01-application.md | 36 ++++++------------- 1 file changed, 10 insertions(+), 26 deletions(-) diff --git a/docs/05-technical-reference/00-custom-resources/ac-01-application.md b/docs/05-technical-reference/00-custom-resources/ac-01-application.md index f748b6dcdd1f..00d0c05d864a 100644 --- a/docs/05-technical-reference/00-custom-resources/ac-01-application.md +++ b/docs/05-technical-reference/00-custom-resources/ac-01-application.md @@ -36,34 +36,18 @@ spec: This table lists all the possible parameters of a given resource together with their descriptions: -| Parameter | Required | Description | -|----------|:-------------:|------| -| **metadata.name** | Yes | Specifies the name of the CR. | -| **spec.description** | No | Describes the connected Application. | -| **spec.skipVerify** | No | Determines whether to skip TLS certificate verification for the Application. | -| **spec.encodeUrl** | No | Allows for URL encoding. If set to 'false', your URL segments stay intact. | -| **spec.labels** | No | Defines the labels of the Application. | -| **spec.services** | No | Contains all services that the Application provides. | -| **spec.services.id** | Yes | Identifies the service that the Application provides. | -| **spec.services.identifier** | No | Represents an additional identifier unique in the Application scope. Allows the external system to provide its own identifier. | -| **spec.services.name** | No | Represents a unique name of the service. Used for proxying in Application Gateway. | -| **spec.services.providerDisplayName** | Yes | Specifies a human-readable name of the Application service provider. In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. | -| **spec.services.tags** | No | Specifies additional tags used for better documentation of the available APIs. In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. | -| **spec.services.labels** | No | Specifies additional labels for the service offered by the Application. In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. | -| **spec.services.entries** | Yes | Contains the information about the APIs and events that the service offered by the Application provides. In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. | -| **spec.services.entries.type** | Yes | Specifies the entry type: `API` or `Events`. In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. | -| **spec.services.entries.centralGatewayUrl** | No | Specifies the URL of Application Gateway. Internal address resolvable only within the cluster. This field is required for the API entry type. In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. | -| **spec.services.entries.accessLabel** | No | Specifies the label used in Istio rules in Application Connector. This field is required for the API entry type. | -| **spec.services.entries.targetUrl** | No | Specifies the URL of a given API. This field is required for the API entry type. In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. | -| **spec.services.entries.oauthUrl** | No | Specifies the URL used to authorize with a given API. This field is required for the API entry type. In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. | -| **spec.services.entries.credentialsSecretName** | No | Specifies the name of the Secret which allows you to call a given API. This field is required if **spec.services.entries.oauthUrl** is specified. In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. | + + + + + ## Related resources and components These components use this CR: -| Component | Description | -|-----------|-------------| -| Application Gateway | Reads the API metadata in order to connect to the external system. | -| Application Connectivity Validator (in the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md)) | Validates requests and events from the external system against the respective Application CR. | -| Runtime Agent (in the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md)) | Saves the metadata of the connected external system in the Application CR, synchronizes the metadata stored in Compass with the state in the cluster stored in the Application CR. | +| Component | Description | +|-----------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Application Gateway | Reads the API metadata in order to connect to the external system. | +| Application Connectivity Validator (in the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md)) | Validates requests and events from the external system against the respective Application CR. | +| Runtime Agent (in the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md)) | Saves the metadata of the connected external system in the Application CR, synchronizes the metadata stored in Compass with the state in the cluster stored in the Application CR. | From 7d226eeadd3ce37ada556a4bf751b242ccbf5816 Mon Sep 17 00:00:00 2001 From: void404 Date: Fri, 28 Apr 2023 12:48:33 +0200 Subject: [PATCH 3/4] Update makefile --- hack/table-gen/Makefile | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/hack/table-gen/Makefile b/hack/table-gen/Makefile index 4f5726843a4f..a5e9ae0e8871 100644 --- a/hack/table-gen/Makefile +++ b/hack/table-gen/Makefile @@ -13,5 +13,9 @@ telemetry-logparser: .PHONY: telemetry-docs telemetry-docs: telemetry-tracepipeline telemetry-logparser telemetry-logpipeline +.PHONY: application-connector-docs +application-connector-docs: + go run table-gen.go --crd-filename ../../installation/resources/crds/application-connector/applications.applicationconnector.crd.yaml --md-filename ../../docs/05-technical-reference/00-custom-resources/ac-01-application.md + .PHONY: generate -generate: telemetry-docs +generate: telemetry-docs application-connector-docs From fd90c8fffb7b5dcea62ba9b6eae653d2aaeda273 Mon Sep 17 00:00:00 2001 From: void404 Date: Fri, 28 Apr 2023 12:48:41 +0200 Subject: [PATCH 4/4] Generate docs --- .../00-custom-resources/ac-01-application.md | 61 ++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-) diff --git a/docs/05-technical-reference/00-custom-resources/ac-01-application.md b/docs/05-technical-reference/00-custom-resources/ac-01-application.md index 00d0c05d864a..b8f9de330333 100644 --- a/docs/05-technical-reference/00-custom-resources/ac-01-application.md +++ b/docs/05-technical-reference/00-custom-resources/ac-01-application.md @@ -39,7 +39,66 @@ This table lists all the possible parameters of a given resource together with t - + + +| Parameter | Description | +| ---------------------------------------- | ---------| +| **spec.accessLabel** | | +| **spec.compassMetadata** | | +| **spec.compassMetadata.applicationId** | | +| **spec.compassMetadata.authentication** | | +| **spec.compassMetadata.authentication.clientIds** | | +| **spec.description** | Describes the connected Application. | +| **spec.displayName** | | +| **spec.encodeUrl** | Allows for URL encoding. If set to `false`, your URL segments stay intact. | +| **spec.group** | | +| **spec.labels** | Defines the labels of the Application. | +| **spec.longDescription** | | +| **spec.providerDisplayName** | | +| **spec.services** | Contains all services that the Application provides. | +| **spec.services.authCreateParameterSchema** | New fields used by V2 version | +| **spec.services.description** | | +| **spec.services.displayName** | | +| **spec.services.entries** | Contains the information about the APIs and events that the service offered by the Application provides. In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. + | +| **spec.services.entries.accessLabel** | Specifies the label used in Istio rules in Application Connector. This field is required for the API entry type. + | +| **spec.services.entries.apiType** | | +| **spec.services.entries.centralGatewayUrl** | Specifies the URL of Application Gateway. Internal address resolvable only within the cluster. This field is required for the API entry type. In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. + | +| **spec.services.entries.credentials** | | +| **spec.services.entries.credentials.authenticationUrl** | | +| **spec.services.entries.credentials.csrfInfo** | | +| **spec.services.entries.credentials.csrfInfo.tokenEndpointURL** | | +| **spec.services.entries.credentials.secretName** | | +| **spec.services.entries.credentials.type** | | +| **spec.services.entries.gatewayUrl** | | +| **spec.services.entries.id** | | +| **spec.services.entries.name** | New fields used by V2 version | +| **spec.services.entries.requestParametersSecretName** | | +| **spec.services.entries.specificationUrl** | | +| **spec.services.entries.targetUrl** | Specifies the URL of a given API. This field is required for the API entry type. In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. + | +| **spec.services.entries.type** | Specifies the entry type: `API` or `Events`. In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. + | +| **spec.services.id** | Identifies the service that the Application provides. | +| **spec.services.identifier** | Represents an additional identifier unique in the Application scope. Allows the external system to provide its own identifier. + | +| **spec.services.labels** | Deprecated | +| **spec.services.longDescription** | | +| **spec.services.name** | Represents a unique name of the service. Used for proxying in Application Gateway. + | +| **spec.services.providerDisplayName** | Specifies a human-readable name of the Application service provider. In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. + | +| **spec.services.tags** | Specifies additional tags used for better documentation of the available APIs. In the [Compass mode](../../01-overview/main-areas/application-connectivity/README.md), it's provided by Runtime Agent. In the [standalone mode](../../01-overview/main-areas/application-connectivity/README.md), you have to provide it yourself. + | +| **spec.skipInstallation** | | +| **spec.skipVerify** | Determines whether to skip TLS certificate verification for the Application. | +| **spec.tags** | New fields used by V2 version. | +| **spec.tenant** | | +| **status.installationStatus** | Represents the status of Application release installation | +| **status.installationStatus.description** | | +| **status.installationStatus.status** | | ## Related resources and components