Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[WIP] Add descriptions to AC's CRD's fields #17432

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

[WIP] Add descriptions to AC's CRD's fields #17432

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8600bda
Add descriptions to AC fields
VOID404 Apr 28, 2023
b06ff4b
Prepare docs for generated table
VOID404 Apr 28, 2023
7d226ee
Update makefile
VOID404 Apr 28, 2023
fd90c8f
Generate docs
VOID404 Apr 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 69 additions & 26 deletions docs/05-technical-reference/00-custom-resources/ac-01-application.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,34 +36,77 @@ 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. |
<!-- The table below was generated automatically -->
<!-- Some special tags (html comments) are at the end of lines due to markdown requirements. -->
<!-- The content between "TABLE-START" and "TABLE-END" will be replaced -->
<!-- TABLE-START -->
<!-- Application v1alpha1 applicationconnector.kyma-project.io -->
| Parameter | Description |
| ---------------------------------------- | ---------|
| **spec.accessLabel** | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

accessLabel was used for Service Catalog integration, and is no longer relevant. I think we can get rid of that.

| **spec.compassMetadata** | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

compassMetadata is set by the Compass Runtime Agent. If the property is non-nil it means that the Application was created from Compass Application. If the field is empty, we can assume that Application was created manually, and is not controlled by the Compass Runtime Agent.

| **spec.compassMetadata.applicationId** | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ApplicationID of the source Compass Application that was used to create Kyma Application

| **spec.compassMetadata.authentication** | |
| **spec.compassMetadata.authentication.clientIds** | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

clientIds contains an identifier fetched from Compass that is used for authentication. This field is set by Compass Runtime Agent when Application is created, and used by the Connectivity Validator to determine whether incoming request should be authorised or not. Connectivity Validator expects that the CNAME of the client certificate matches clientId

| **spec.description** | Describes the connected Application. |
| **spec.displayName** | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

displayName is left empty by the Compass Runtime Agent, so that I would assume it is deprecated.

| **spec.encodeUrl** | Allows for URL encoding. If set to `false`, your URL segments stay intact. |
| **spec.group** | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

group is deprecated, we should remove that.

| **spec.labels** | Defines the labels of the Application. |
| **spec.longDescription** | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think longDescription was used for Service Catalog integration. It's deprecated we should remove that.

| **spec.providerDisplayName** | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

providerDisplayName is still set by the Compass Runtime Agent, but I suppose it could be removed. Needs some short investigation.

| **spec.services** | Contains all services that the Application provides. |
| **spec.services.authCreateParameterSchema** | New fields used by V2 version |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AuthCreateParameterSchema is still set by the Compass Runtime Agent, but I suppose it was used by the Application Broker (Service Catalog integration), so that we should get rid of it.

| **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** | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could link the tutorials, but I think we should also describe those fields one by one.

| **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 |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New fields used by V2 version conveys zero information. Entry.name allows to support API Bundles functionality provided by Compass. APIBundle is a set of APIs that share the same credentials. The API Bundle have both name and identifier that are used by the Compass Runtime Agent to set spec.services.name field. Each API in the bundle has name that is used by the Compass Runtime Agent to set spec.services.entries.name.

| **spec.services.entries.requestParametersSecretName** | |
| **spec.services.entries.specificationUrl** | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is deprecated.

| **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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is deprecated, and should be removed.

|
| **spec.skipInstallation** | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

skipInstallation is a deprecated field used by the Application Operator. We should remove that.

| **spec.skipVerify** | Determines whether to skip TLS certificate verification for the Application. |
| **spec.tags** | New fields used by V2 version. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe it is deprecated, and we should remove it.

| **spec.tenant** | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tenant is deprecated, we should remove that.

| **status.installationStatus** | Represents the status of Application release installation |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should remove that as Application Operator was deprecated, and removed long time ago.

| **status.installationStatus.description** | |
| **status.installationStatus.status** | |<!-- TABLE-END -->


## 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. |
6 changes: 5 additions & 1 deletion hack/table-gen/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
49 changes: 48 additions & 1 deletion installation/resources/crds/application-connector/applications.applicationconnector.crd.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -68,6 +72,7 @@ spec:
longDescription:
type: string
services:
description: 'Contains all services that the Application provides.'
type: array
items:
type: object
Expand All @@ -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
Expand All @@ -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
Expand All @@ -112,19 +136,37 @@ 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"
- "Events"
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
Expand Down Expand Up @@ -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
Expand Down