Make the Application Connector documentation more clear #836
Conversation
lszymik
requested review from
akgalwas,
Szymongib,
janmedrek,
Maladie,
klaudiagrz,
kazydek and
a user
| This is a global service that works in the context of a given Remote Environment. | ||
| - The **Gateway Service** proxies the API calls sent from Kyma to the connected external solution and handles OAuth2 tokens. A new instance of this service is deployed for every Remote Environment. | ||
| - The **Event Service** delivers the Events sent from a connected external solution to Kyma. A new instance of this service is deployed for every Remote Environment. | ||
| The Application Connector ensures that a connected system communicates with Kyma securely using the client certificate which can be acquired from the Connector service. A client certificate ensures that each connected system is separated. |
There was a problem hiding this comment.
instead of writing The Application Connector 5 times, better write it once with some good intro text and then mention all those features/advantages in a bullet point list
| All components of the Application Connector can be scaled independently to adjust to the need of the solution which is being built on the top of the Kyma. | ||
|
|
||
|
|
||
| ## Functionality |
There was a problem hiding this comment.
this section kind of duplicates previous paragraphs
example:
Deliver of events from the external system to Kyma Eventbus is duplicating The Application Connector provides a possibility to communicate with services and lambdas deployed in Kyma in an asynchronous matter using events. A system can send an event which triggers a subscribed service or lambda. Developers can benefit from the built-in monitoring and tracing which allow troubleshooting of the event delivery.
content is like code, it is better if you write less than more. there should be just one list of features/advantages
|
|
||
| The Remote Environment is creating a coherent entity from underlying Application Connector's components for a connected system and ensures a separation between different environments. | ||
|
|
||
| All Remote Environments are stored using Kubernetes Custom Resource Definition (CRD). You can find more details here [Remote Environment CRD](040-remote-environment-custom-resource.md) |
There was a problem hiding this comment.
link will not work in UI, please remove them
| @@ -0,0 +1,15 @@ | |||
| --- | |||
There was a problem hiding this comment.
arch doc with no diagram and no real explanation of the architecture
- where is the RE coming from?
- what is creating RE and EM Crs?
- as a result of such RE creation, what is happening in the system?
there is even nothing about service classes
There was a problem hiding this comment.
The file will be removed and RE description will be in the general architecture doc.
| * **Nginx Ingress Controller** | ||
| * **Connector Service** | ||
| * **Metadata Service** | ||
| * **Event Service** |
|
|
||
|  | ||
|
|
||
|
|
||
| ### Nginx Ingress Controller |
There was a problem hiding this comment.
don't do subsections here, you have separate docs for more details about each component, here focus on describing the diagram and architecture in overall
| @@ -5,11 +5,72 @@ type: Architecture | |||
|
|
|||
| The Application Connector consists of the following components: | |||
There was a problem hiding this comment.
do you really think you need it? it is in the diagram already
|
|
||
| Creating a new client certificate is the first step of configuring external system represented by Remote Environment. Kyma stores root certificate and serves in this case as a Certificate Authority. In order to make validation possible the Connector Service returns complete certificate chain: created client certificate along with the root certificate. | ||
|
|
||
| ## API |
There was a problem hiding this comment.
details about API are not part of the component architecture, API should be described as a separate doc type
https://github.com/kyma-project/community/blob/master/guidelines/content-guidelines/content-strategy.md#documentation-types
| @@ -0,0 +1,50 @@ | |||
| --- | |||
| title: Metadata Service | |||
| type: Details | |||
There was a problem hiding this comment.
why not arch?
also, API, same as with my other comment for connector
There was a problem hiding this comment.
Yes, the metadata of file was not updated. Tomek will handle it.
| - Creating a client certificate for specified CSR using Connector Service External API. | ||
|
|
||
| The following diagram illustrates the operation flow in details: | ||
|  |
There was a problem hiding this comment.
add SVG version of all diagrams otherwise the diagrams is not maintainable in future
| - Description | ||
| - Optional labels of your choice which are key-value pairs | ||
|
|
||
|  |
There was a problem hiding this comment.
Screenshots in this document are redundant. The described actions are simple and do not really require additional images.
The screenshots can become outdated with the next interface update.
Additionally, we treat them as a last resort. If there's no other easy way to explain stuff, then you use the screenshots.
In this case, you can easily describe what to do in the interface to achieve the desired outcome and you can achieve the same results using the CLI.
TL;DR:
Remove screenshots from this document.
There was a problem hiding this comment.
We have discussed it and please remove screenshots.
| - Select the **Remote Environments** from the **Integration** section. | ||
| - Click **Create Remote Environment**.. | ||
|
|
||
|  |
There was a problem hiding this comment.
TL;DR:
Remove screenshots from this document.
| - Choose the Remote Environment you want to delete. | ||
| - Click **Delete**. | ||
|
|
||
|  |
There was a problem hiding this comment.
TL;DR:
Remove screenshots from this document.
| @@ -3,47 +3,68 @@ title: RemoteEnvironment | |||
| type: Custom Resource | |||
| --- | |||
|
|
|||
| The `remoteenvironments.remoteenvironment.kyma.cx` Custom Resource Definition (CRD) is a detailed description of the kind of data and the format used to register a Remote Environment in Kyma. The RemoteEnvironment resource defines APIs that the Remote Environment offers. As a result, the RemoteEnvironment is mapped to ServiceClasses in the Service Catalog. To get the up-to-date CRD and show the output in the `yaml` format, run this command: | |||
| The `remoteenvironments.applicationconnector.kyma-project.io` Custom Resource Definition (CRD) is a detailed description of the kind of data and the format used to register a Remote Environment in Kyma. The RemoteEnvironment resource defines APIs that the Remote Environment offers. As a result, the RemoteEnvironment is mapped to ServiceClasses in the Service Catalog. To get the up-to-date CRD and show the output in the `yaml` format, run this command: | |||
There was a problem hiding this comment.
The remoteenvironments.applicationconnector.kyma-project.io Custom Resource Definition (CRD) is a detailed description of the kind of data and the format used to register a Remote Environment(RE) in Kyma. The RemoteEnvironment Custom Resource defines the APIs that the RE offers. After creating a new Custom Resource for a given RE, the RE is mapped to appropriate ServiceClasses in the Service Catalog. To get the up-to-date CRD and show the output in the yaml format, run this command:
|
|
||
| ``` | ||
| kubectl get crd remoteenvironments.remoteenvironment.kyma.cx -o yaml | ||
| kubectl get crd remoteenvironments.applicationconnector.kyma-project.io -o yaml | ||
| ``` | ||
|
|
||
| ## Sample custom resource | ||
|
|
||
| This is a sample resource that registers the `re-prod` Remote Environment which provides one service with the `ac031e8c-9aa4-4cb7-8999-0d358726ffaa` ID. |
There was a problem hiding this comment.
I wouldn't mention the service ID in this sentence. Instead:
This is a sample resource that registers the
re-prodRemote Environment which offers one service.
| curl -X PUT -d '{YOUR_NEW_JSON_BODY}' https://gateway.kyma.local:$NODE_PORT/ec-default/v1/metadata/services/{YOUR_SERVICE_ID} --cert {CERT_FILE_NAME}.crt --key {KEY_FILE_NAME}.key -k | ||
| ``` | ||
|
|
||
| ## Deleting a service |
| curl https://gateway.kyma.local:$NODE_PORT/ec-default/v1/metadata/services/{YOUR_SERVICE_ID} --cert {CERT_FILE_NAME}.crt --key {KEY_FILE_NAME}.key -k | ||
| ``` | ||
|
|
||
| ## Updating a service |
| } | ||
| ``` | ||
|
|
||
| ## Generating CSR and sending it to Kyma |
There was a problem hiding this comment.
Generate a CSR and send it to Kyma
|
|
||
| >**NOTE:** This token that is valid for a single CSR information call. If you need to get the configuration details once again, just follow above steps to fetch a new token. | ||
|
|
||
| ## Fetching CSR information from Kyma |
There was a problem hiding this comment.
Get the CSR details from Kyma
|
|
||
| After you've got your key you can proceed to the next step. | ||
|
|
||
| ## Retrieving token |
lszymik
added
the
area/application-connector
lszymik
added
kind/feature
|
|
|
|
||
| The Connector Service: | ||
| - Handles the exchange of client certificates for a given RE. | ||
| - Provides the Metadata Service and Event Service endpoints. |
There was a problem hiding this comment.
Connector Services allows to use Metadata Service and Event service in a secure manner (with authentication and encryption) bu I'm not convinced whether "Provides the Metadata Service and Event Service endpoints." is a correct statement.
|
|
||
| To connect a new external solution, you must install and set up a new Remote Environment. Every external solution connected to Kyma is a separate Remote Environment with a dedicated Gateway Service and a dedicated Event Service. See the **Set up a Remote Environment on local Kyma installation** getting started guide to learn how to connect an external solution to Kyma. | ||
| A Remote Environment (RE) represents an external solution connected to Kyma. It handles the security and integration with other components, such as the Service Catalog or the Event Bus. |
There was a problem hiding this comment.
I'm not convinced if the following statement : "It handles the security and integration" is correct. Remote Environment is a glue between components so the part about integration is correct but it is not responsible for security.
| type: Details | ||
| --- | ||
|
|
||
| The Remote Environment Controller is responsible for provisioning and deprovisioning Event and Proxy services. |
There was a problem hiding this comment.
Minor inconsistency : we use de-provisioning in docs/application-connector/docs/005-architecture-application-connector.md.
| type: Getting Started | ||
| --- | ||
|
|
||
| The Remote Environment Controller provisions and de-provisions the necessary deployments for the created Remote Environment (RE). |
There was a problem hiding this comment.
Minor inconsistency : we use deprovisioning in docs/application-connector/docs/007-architecture-remote-environment-controller.md.
|
|
||
| The controller listens for creating or deleting the RemoteEnvironment Custom Resources and acts accordingly, either provisioning or de-provisioning an instance of Proxy Service and Event Service for every Custom Resource. | ||
|
|
||
| >**NOTE:** Every RemoteEnvironment Custom Resource is constitutes a RE to which you can connect an external solution. |
There was a problem hiding this comment.
"is constitutes"->"constitutes" ?
|
|
||
| ## Implementation details | ||
|
|
||
| Remote Environment Controller's repository includes [this](https://kyma-project.io/) chart containing Event and Proxy Service. The chart is installed or uninstalled with Helm client. |
There was a problem hiding this comment.
The link points to https://kyma-project.io/) but the description promises a link to a chart.
There was a problem hiding this comment.
this is removed/re-done
|
|
||
| 1. A Lambda function calls the Access Service. The name of every Access Service follows this format: `re-{remote-environment-name}-gateway-{service-id}` | ||
| 2. The Access Service exposes the Proxy Service. | ||
| 3. The Proxy Service analyzes the request Host header to get the service ID. Using the service ID, the Proxy Service finds the respective RemoteEnvironment Custom Resource and obtains the information about the registered external API, such as the API URL and the OAuth server URL. |
There was a problem hiding this comment.
Proxy service extracts remote environment name and service id from the Access Service name. Proxy Service finds RE CRD by name and then uses service ID to find API and OAuth url. The description suggests that RE is selected using service iD.
| Generating a new client certificate is the first step in the process of configuring a Remote Environment (RE). Kyma stores the root certificate and serves as the Certificate Authority when you configure a new RE. When you generate a new client certificate, the Connector Service returns it along with the root certificate to allow validation. | ||
|
|
||
| This diagram illustrates the client certificate generation flow in details: | ||
|  |
There was a problem hiding this comment.
There is a diagram with numbered steps but we don't describe what each step means.
…ated in Getting Started guide
(cherry picked from commit b999d91)
Description
Changes proposed in this pull request:
Related issue(s)
Fixes #783