From b6ca5e68a90974e32cac4490fb330da97b91f37c Mon Sep 17 00:00:00 2001 From: grego952 Date: Mon, 25 Mar 2024 08:43:59 +0100 Subject: [PATCH] Apply markdowlint rules in the ACM repository --- .markdownlint.yaml | 28 ++ .markdownlintignore | 1 + docs/contributor/01-10-installation.md | 14 +- docs/contributor/03-10-scripts-dont-work.md | 2 +- docs/contributor/04-10-ci-cd.md | 2 +- docs/user/00-10-application-gateway.md | 4 +- docs/user/00-20-security.md | 2 +- docs/user/00-30-runtime-agent-overview.md | 25 +- ...-10-pass-access-token-in-request-header.md | 2 +- .../02-20-enable-kyma-with-runtime-agent.md | 4 +- docs/user/resources/06-10-application.md | 4 +- .../user/resources/06-20-compassconnection.md | 7 +- .../resources/06-30-application-connector.md | 46 +- .../04-10-application-connector-components.md | 5 +- .../04-20-application-gateway.md | 8 +- .../04-30-runtime-agent-workflow.md | 11 +- .../05-20-connection-with-compass.md | 2 +- .../07-10-application-gateway-details.md | 8 +- .../07-20-configuring-runtime.md | 8 +- docs/user/technical-reference/README.md | 2 +- .../tutorials/01-10-create-application.md | 54 +-- ...00-reconnect-runtime-agent-with-compass.md | 2 +- .../01-20-register-manage-services.md | 23 +- .../tutorials/01-30-register-secured-api.md | 405 +++++++++--------- ...01-40-call-registered-service-from-kyma.md | 7 +- ...50-disable-tls-certificate-verification.md | 6 +- ...stablish-secure-connection-with-compass.md | 10 +- ...maintain-secure-connection-with-compass.md | 10 +- .../01-80-revoke-client-certificate.md | 4 +- ...90-configure-runtime-agent-with-compass.md | 4 +- docs/user/tutorials/README.md | 2 +- markdown_heading_capitalization.js | 30 ++ 32 files changed, 408 insertions(+), 334 deletions(-) create mode 100644 .markdownlint.yaml create mode 100644 .markdownlintignore create mode 100644 markdown_heading_capitalization.js diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 00000000..06b40cec --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,28 @@ +# This is a configuration file for the markdownlint. You can use this file to overwrite the default settings. +# MD013 is set to false by default because many files include lines longer than the conventional 80 character limit +MD013: false +# Disable the Multiple headings with the same content rule +MD024: false +# MD029 is set to false because it generated some issues with longer lists +MD029: false +# Checks if there some inline HTML-elements +MD033: false +# MD044 is used to set capitalization for the particular words. You can determine whether it should be used also for code blocks and html elements +MD044: + code_blocks: false + html_elements: false + names: + - Kyma + - Kubernetes + - ConfigMap + - CronJob + - CustomResourceDefinition + - Ingress + - Node + - PodPreset + - Pod + - ProwJob + - Secret + - ServiceBinding + - ServiceClass + - ServiceInstance \ No newline at end of file diff --git a/.markdownlintignore b/.markdownlintignore new file mode 100644 index 00000000..578db9cb --- /dev/null +++ b/.markdownlintignore @@ -0,0 +1 @@ +_sidebar.md \ No newline at end of file diff --git a/docs/contributor/01-10-installation.md b/docs/contributor/01-10-installation.md index b279e611..90812f8b 100644 --- a/docs/contributor/01-10-installation.md +++ b/docs/contributor/01-10-installation.md @@ -1,4 +1,4 @@ -# Install Application Connector Manager +# Install Application Connector Manager - [Install Application Connector Manager](#install-application-connector-manager) - [Install Application Connector Manager from the Local Sources](#install-application-connector-manager-from-the-local-sources) @@ -9,7 +9,7 @@ Learn how to install the Application Connector module locally (on k3d) or on your remote cluster. -## Install Application Connector Manager from the Local Sources +## Install Application Connector Manager from the Local Sources ### Prerequisites @@ -34,7 +34,8 @@ Run the following commands to deploy Application Connector Manager in a target K 2. Set the Application Connector Manager image name. - > NOTE: You can use the local k3d registry or your Docker Hub account to push intermediate images. + > NOTE: You can use the local k3d registry or your Docker Hub account to push intermediate images. + ```bash export IMG=/custom-application-connector-manager:0.0.1 ``` @@ -44,11 +45,13 @@ Run the following commands to deploy Application Connector Manager in a target K ```bash make test ``` + 4. Build and push the image to the registry. ```bash make module-image ``` + 5. Create a target namespace. ```bash @@ -69,7 +72,7 @@ Run the following commands to deploy Application Connector Manager in a target K You should get a result similar to this example: - ``` + ```bash NAME READY UP-TO-DATE AVAILABLE AGE application-connector-controller-manager 1/1 1 1 20s ``` @@ -86,10 +89,11 @@ Thanks to that, you don't need to push the Application Connector module images t ```bash git clone https://github.com/kyma-project/application-connector-manager.git && cd application-connector-manager/ ``` + 2. Build the manager locally and run it in the k3d cluster. ```bash make -C hack/local run-without-lifecycle-manager ``` -3. If you want to clean up the k3d cluster, use the `make -C hack/local stop` make target. +3. If you want to clean up the k3d cluster, use the `make -C hack/local stop` make target. diff --git a/docs/contributor/03-10-scripts-dont-work.md b/docs/contributor/03-10-scripts-dont-work.md index bab3ce79..568eeaa2 100644 --- a/docs/contributor/03-10-scripts-dont-work.md +++ b/docs/contributor/03-10-scripts-dont-work.md @@ -16,4 +16,4 @@ Install [Kyma CLI manually](https://github.com/kyma-project/cli#installation) an ```bash export KYMA=$(which kyma) - ``` \ No newline at end of file + ``` diff --git a/docs/contributor/04-10-ci-cd.md b/docs/contributor/04-10-ci-cd.md index b22f8cf2..702118ff 100644 --- a/docs/contributor/04-10-ci-cd.md +++ b/docs/contributor/04-10-ci-cd.md @@ -9,7 +9,7 @@ The following CI jobs are part of the development cycle. They verify the functio | [`pre-application-connector-manager-build`](https://github.com/kyma-project/test-infra/blob/main/templates/data/generic_module_data.yaml#L1059) | true | prow | Builds Application Connector Manager's image and pushes it to the `dev` registry. | | [`pre-application-connector-manager-presubmit-scanner`](https://github.com/kyma-project/test-infra/blob/main/prow/jobs/kyma-project/test-infra/presubmit-scanner.yaml#L556) | true | prow | Runs the Gitleaks presubmit scanner to detect committed sensitive data for Application Connector Manager. | | [`pre-main-application-connector-manager-verify`](https://github.com/kyma-project/test-infra/blob/main/templates/data/generic_module_data.yaml#L1093) | true | prow | Installs Application Connector Manager, not using Lifecycle Manager, and applies the sample Application Connector CR in a k3d cluster. Executes smoke integration test of Application Connector. | -| [`golangci-lint `](https://github.com/kyma-project/application-connector-manager/blob/main/.github/workflows/golangci-lint.yaml) | true | GH Actions | Is responsible for linting and static code analysis. | +| [`golangci-lint`](https://github.com/kyma-project/application-connector-manager/blob/main/.github/workflows/golangci-lint.yaml) | true | GH Actions | Is responsible for linting and static code analysis. | | [`Run unit tests`](https://github.com/kyma-project/application-connector-manager/blob/main/.github/workflows/run-tests.yaml) | true | GH Actions | Executes basic create/update/delete functional tests of Application Connector Manager's reconciliation logic. | | [`Run integration tests`](https://github.com/kyma-project/application-connector-manager/blob/main/.github/workflows/run-validation.yaml) | true | GH Actions | Installs Application Connector Manager, not using Lifecycle Manager, and applies the sample Application Connector CR in a k3d cluster. Executes smoke integration test of Application Connector. | | [`Run vuln check`](https://github.com/kyma-project/application-connector-manager/blob/main/.github/workflows/run-vuln-check.yaml) | true | GH Actions | Executes the [govulncheck](https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck) tool on the Application Connector Manager code to detect known vulnerabilities. | diff --git a/docs/user/00-10-application-gateway.md b/docs/user/00-10-application-gateway.md index 986ef300..4839f69f 100644 --- a/docs/user/00-10-application-gateway.md +++ b/docs/user/00-10-application-gateway.md @@ -1,6 +1,6 @@ # Application Gateway -Application Gateway is an intermediary component between a Function or a microservice and an external API. +Application Gateway is an intermediary component between a Function or a microservice and an external API. It [proxies the requests](technical-reference/04-20-application-gateway.md) from Functions and microservices in Kyma to external APIs based on the configuration stored in Secrets. Application Gateway also supports redirects for the request flows in which the URL host remains unchanged. For more details, see [Response rewriting](technical-reference/07-10-application-gateway-details.md#response-rewriting). @@ -24,4 +24,4 @@ Application Gateway overrides the registered API's security type if it gets a re This mechanism is suited for implementations in which an external application handles user authentication. -See how to [pass an access token in a request header](02-10-pass-access-token-in-request-header.md). \ No newline at end of file +See how to [pass an access token in a request header](02-10-pass-access-token-in-request-header.md). diff --git a/docs/user/00-20-security.md b/docs/user/00-20-security.md index a20745a1..5fd55006 100644 --- a/docs/user/00-20-security.md +++ b/docs/user/00-20-security.md @@ -7,4 +7,4 @@ To provide maximum security, in the [Compass mode](README.md), Application Conne ### TLS Certificate Verification for External Systems By default, the TLS certificate verification is enabled when sending data and requests to every application. -You can [disable the TLS certificate verification](tutorials/01-50-disable-tls-certificate-verification.md) in the communication between Kyma and an application to allow Kyma to send requests and data to an unsecured application. Disabling the certificate verification can be useful in certain testing scenarios. \ No newline at end of file +You can [disable the TLS certificate verification](tutorials/01-50-disable-tls-certificate-verification.md) in the communication between Kyma and an application to allow Kyma to send requests and data to an unsecured application. Disabling the certificate verification can be useful in certain testing scenarios. diff --git a/docs/user/00-30-runtime-agent-overview.md b/docs/user/00-30-runtime-agent-overview.md index 79cbf688..b12ec41f 100644 --- a/docs/user/00-30-runtime-agent-overview.md +++ b/docs/user/00-30-runtime-agent-overview.md @@ -1,11 +1,12 @@ # Runtime Agent > [!WARNING] -> Runtime Agent is currently not integrated into the Application Connector module. Proceed with caution and consult the respective documentation for the Application Connector module's current configuration and functionality. +> Runtime Agent is currently not integrated into the Application Connector module. Proceed with caution and consult the respective documentation for the Application Connector module's current configuration and functionality. Runtime Agent is a Kyma component that connects to [Compass](https://github.com/kyma-incubator/compass). It is an integral part of every Kyma Runtime in the [Compass mode](README.md) and it fetches the latest configuration from Compass. It also provides Runtime-specific information that is displayed in the Compass UI, such as Runtime UI URL, and it provides Compass with Runtime configuration, such as Event Gateway URL, that should be passed to an Application. To learn more, read the section on [configuring the Runtime](technical-reference/07-20-configuring-runtime.md). The main responsibilities of the component are: + - Establishing a trusted connection between the Kyma Runtime and Compass - Renewing a trusted connection between the Kyma Runtime and Compass - Synchronizing with the [Director](https://github.com/kyma-incubator/compass/blob/master/docs/compass/02-01-components.md#director) by fetching new Applications from the Director and creating them in the Runtime, and removing from the Runtime Applications that no longer exist in the Director. @@ -16,19 +17,19 @@ If you're interested in learning more about Runtime Agent, follow these links to - Perform some simple and more advanced tasks: - - [Enable Kyma with Runtime Agent](02-20-enable-kyma-with-runtime-agent.md) - - [Establish a secure connection with Compass](tutorials/01-60-establish-secure-connection-with-compass.md) - - [Maintain a secure connection with Compass](tutorials/01-70-maintain-secure-connection-with-compass.md) - - [Revoke a client certificate (RA)](tutorials/01-80-revoke-client-certificate.md) - - [Configure Runtime Agent with Compass](tutorials/01-90-configure-runtime-agent-with-compass.md) - - [Reconnect Runtime Agent with Compass](tutorials/01-100-reconnect-runtime-agent-with-compass.md) - + - [Enable Kyma with Runtime Agent](02-20-enable-kyma-with-runtime-agent.md) + - [Establish a secure connection with Compass](tutorials/01-60-establish-secure-connection-with-compass.md) + - [Maintain a secure connection with Compass](tutorials/01-70-maintain-secure-connection-with-compass.md) + - [Revoke a client certificate (RA)](tutorials/01-80-revoke-client-certificate.md) + - [Configure Runtime Agent with Compass](tutorials/01-90-configure-runtime-agent-with-compass.md) + - [Reconnect Runtime Agent with Compass](tutorials/01-100-reconnect-runtime-agent-with-compass.md) + - Analyze Runtime Agent specification and configuration files: - - [Compass Connection](resources/06-20-compassconnection.md) custom resource (CR) - - [Connection with Compass](technical-reference/05-20-connection-with-compass.md) + - [Compass Connection](resources/06-20-compassconnection.md) custom resource (CR) + - [Connection with Compass](technical-reference/05-20-connection-with-compass.md) - Understand technicalities behind the Runtime Agent implementation: - - [Runtime Agent workflow](technical-reference/04-30-runtime-agent-workflow.md) - - [Configuring the Runtime](technical-reference/07-20-configuring-runtime.md) \ No newline at end of file + - [Runtime Agent workflow](technical-reference/04-30-runtime-agent-workflow.md) + - [Configuring the Runtime](technical-reference/07-20-configuring-runtime.md) diff --git a/docs/user/02-10-pass-access-token-in-request-header.md b/docs/user/02-10-pass-access-token-in-request-header.md index 5f5787fb..03501c47 100644 --- a/docs/user/02-10-pass-access-token-in-request-header.md +++ b/docs/user/02-10-pass-access-token-in-request-header.md @@ -4,4 +4,4 @@ The Application Gateway service supports passing the access token directly in th ## Passing the Access Token -If the user is already authenticated to the target API, the access token can be passed in a custom `Access-token` header. The header's value is of the `Bearer {TOKEN}` or `Basic {TOKEN}` form. If the Application Gateway service detects that the custom header is present, instead of performing authentication steps, it removes the `Access-token` header and passes the received value in the `Authorization` header. \ No newline at end of file +If the user is already authenticated to the target API, the access token can be passed in a custom `Access-token` header. The header's value is of the `Bearer {TOKEN}` or `Basic {TOKEN}` form. If the Application Gateway service detects that the custom header is present, instead of performing authentication steps, it removes the `Access-token` header and passes the received value in the `Authorization` header. diff --git a/docs/user/02-20-enable-kyma-with-runtime-agent.md b/docs/user/02-20-enable-kyma-with-runtime-agent.md index 52df3770..f700b640 100644 --- a/docs/user/02-20-enable-kyma-with-runtime-agent.md +++ b/docs/user/02-20-enable-kyma-with-runtime-agent.md @@ -3,5 +3,5 @@ > [!WARNING] > Runtime Agent is currently not integrated into the Application Connector module. Proceed with caution and consult the respective documentation for the Application Connector module's current configuration and functionality. -[Runtime Agent](00-30-runtime-agent-overview.md) is a part of the Application Connector module that is used in the [Compass mode](README.md) of Application Connectivity. -By default, Kyma uses the [standalone Application Connectivity mode](README.md), which does not support integration with Compass. \ No newline at end of file +[Runtime Agent](00-30-runtime-agent-overview.md) is a part of the Application Connector module that is used in the [Compass mode](README.md) of Application Connectivity. +By default, Kyma uses the [standalone Application Connectivity mode](README.md), which does not support integration with Compass. diff --git a/docs/user/resources/06-10-application.md b/docs/user/resources/06-10-application.md index cd9b5a6a..59b9086c 100644 --- a/docs/user/resources/06-10-application.md +++ b/docs/user/resources/06-10-application.md @@ -64,6 +64,6 @@ These components use this CR: | Component | Description | |-----------|-------------| -| Application Gateway | Reads the API metadata in order to connect to the external system. | +| Application Gateway | Reads the API metadata in order to connect to the external system. | | Application Connectivity Validator (in the [Compass mode](../README.md)) | Validates requests and events from the external system against the respective Application CR. | -| Runtime Agent (in the [Compass mode](../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. | \ No newline at end of file +| Runtime Agent (in the [Compass mode](../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. | diff --git a/docs/user/resources/06-20-compassconnection.md b/docs/user/resources/06-20-compassconnection.md index 1994b80c..ae2e11e8 100644 --- a/docs/user/resources/06-20-compassconnection.md +++ b/docs/user/resources/06-20-compassconnection.md @@ -3,9 +3,7 @@ > [!WARNING] > Runtime Agent is currently not integrated into the Application Connector module. Proceed with caution and consult the respective documentation for the Application Connector module's current configuration and functionality. -The `compassconnections.compass.kyma-project.io` CustomResourceDefinition (CRD) -is a detailed description of the kind of data and the format used to preserve -the status of the connection between the Runtime Agent and Compass. +The `compassconnections.compass.kyma-project.io` CustomResourceDefinition (CRD) is a detailed description of the kind of data and the format used to preserve the status of the connection between the Runtime Agent and Compass. The `CompassConnection` custom resource (CR) contains the connection statuses and Compass URLs. To get the up-to-date CRD and show the output in the `yaml` format, run this command: @@ -15,8 +13,7 @@ kubectl get crd compassconnections.compass.kyma-project.io -o yaml ## Sample Custom Resource -This is a sample resource that registers the `compass-agent-connection` CompassConnection, -which preserves the status of the connection between Runtime Agent and Compass. +This is a sample resource that registers the `compass-agent-connection` CompassConnection, which preserves the status of the connection between Runtime Agent and Compass. It also stores the URLs for the Connector and the Director. ```yaml diff --git a/docs/user/resources/06-30-application-connector.md b/docs/user/resources/06-30-application-connector.md index 6ebd0397..e76e6236 100644 --- a/docs/user/resources/06-30-application-connector.md +++ b/docs/user/resources/06-30-application-connector.md @@ -2,15 +2,15 @@ The `applicationconnectors.operator.kyma-project.io` CustomResourceDefinition (CRD) is a comprehensive specification that defines the structure and format used to manage the configuration and status of the Application Connector module within your Kyma environment. -# Purpose +## Purpose The CRD serves as the blueprint for creating custom resources (CRs) specific to Application Connector. These CRs encapsulate the configuration settings and real-time statuses of the Application Connector module, providing essential insights into the module's behavior in the Kubernetes cluster. To get the up-to-date CRD and show the output in the `yaml` format, run this command: -```bash -kubectl get crd applicationconnectors.operator.kyma-project.io -o yaml -``` + ```bash + kubectl get crd applicationconnectors.operator.kyma-project.io -o yaml + ``` ## Custom Resource Specification @@ -25,22 +25,22 @@ kubectl get crd applicationconnectors.operator.kyma-project.io -o yaml ## Sample Custom Resource -``` -apiVersion: operator.kyma-project.io/v1alpha1 -kind: ApplicationConnector -metadata: - namespace: kyma-system - labels: - app.kubernetes.io/name: applicationconnector - app.kubernetes.io/instance: applicationconnector-sample - name: applicationconnector-sample -spec: - domainName: "my.domain" - appConnValidator: - logLevel: "info" - logFormat: "json" - appGateway: - proxyTimeout: "10s" - requestTimeout: "10s" - logLevel: "info" -``` + ```bash + apiVersion: operator.kyma-project.io/v1alpha1 + kind: ApplicationConnector + metadata: + namespace: kyma-system + labels: + app.kubernetes.io/name: applicationconnector + app.kubernetes.io/instance: applicationconnector-sample + name: applicationconnector-sample + spec: + domainName: "my.domain" + appConnValidator: + logLevel: "info" + logFormat: "json" + appGateway: + proxyTimeout: "10s" + requestTimeout: "10s" + logLevel: "info" + ``` diff --git a/docs/user/technical-reference/04-10-application-connector-components.md b/docs/user/technical-reference/04-10-application-connector-components.md index 1b6a86cd..403bd6f9 100644 --- a/docs/user/technical-reference/04-10-application-connector-components.md +++ b/docs/user/technical-reference/04-10-application-connector-components.md @@ -18,7 +18,7 @@ An Application represents an external solution connected to Kyma. It handles the Using the components of Application Connector, the Application creates a coherent identity for a connected external solution and ensures its separation. All Applications are instances of the Application custom resource, which also stores all the relevant metadata. -> [!NOTE] +> [!NOTE] > Every Application custom resource corresponds to a single Application to which you can connect an external solution. ## Application Gateway @@ -35,7 +35,6 @@ Application Gateway can call services which are not secured, or are secured with Additionally, Application Gateway supports cross-site request forgery (CSRF) tokens as an optional layer of API protection. - ## Kubernetes Secret -The Kubernetes Secret is a Kubernetes object that stores sensitive data, such as OAuth credentials. \ No newline at end of file +The Kubernetes Secret is a Kubernetes object that stores sensitive data, such as OAuth credentials. diff --git a/docs/user/technical-reference/04-20-application-gateway.md b/docs/user/technical-reference/04-20-application-gateway.md index 0b8e332a..e45c9539 100644 --- a/docs/user/technical-reference/04-20-application-gateway.md +++ b/docs/user/technical-reference/04-20-application-gateway.md @@ -6,13 +6,13 @@ The following diagram illustrates how Application Gateway interacts with other m ![Application Gateway Diagram](../../assets/ac-architecture-proxy-service.svg) -> [!NOTE] +> [!NOTE] > See how the [Gateway URL differs](07-10-application-gateway-details.md#application-gateway-url) for the [Standalone and Compass modes](../README.md). -1. A Function calls Application Gateway. -2. Application Gateway extracts the Application name and the service name from the path. Using the extracted Application name, Application Gateway finds the respective Application custom resource and obtains the information about the registered external API, such as the API URL and security credentials. +1. A Function calls Application Gateway. +2. Application Gateway extracts the Application name and the service name from the path. Using the extracted Application name, Application Gateway finds the respective Application custom resource and obtains the information about the registered external API, such as the API URL and security credentials. 3. Application Gateway gets a token from the OAuth server. 4. Application Gateway gets a CSRF token from the endpoint exposed by the upstream service. This step is optional and is valid only for the API which was registered with a CSRF token enabled. 5. Application Gateway calls the target API. -To learn more, read about the [Application Gateway details](07-10-application-gateway-details.md). \ No newline at end of file +To learn more, read about the [Application Gateway details](07-10-application-gateway-details.md). diff --git a/docs/user/technical-reference/04-30-runtime-agent-workflow.md b/docs/user/technical-reference/04-30-runtime-agent-workflow.md index c778b02b..4d4469b9 100644 --- a/docs/user/technical-reference/04-30-runtime-agent-workflow.md +++ b/docs/user/technical-reference/04-30-runtime-agent-workflow.md @@ -3,8 +3,8 @@ > [!WARNING] > Runtime Agent is currently not integrated into the Application Connector module. Proceed with caution and consult the respective documentation for the Application Connector module's current configuration and functionality. -> [!WARNING] -> Runtime Agent is used in the [Compass mode](../README.md) of Application Connectivity. To learn how to install Compass and integrate with it, refer to the [Compass documentation](https://github.com/kyma-incubator/compass/blob/master/docs/compass/04-01-installation.md) or to the [Director GraphQL schema](https://github.com/kyma-incubator/compass/blob/master/components/director/pkg/graphql/schema.graphql) directly. +> [!WARNING] +> Runtime Agent is used in the [Compass mode](../README.md) of Application Connectivity. To learn how to install Compass and integrate with it, refer to the [Compass documentation](https://github.com/kyma-incubator/compass/blob/master/docs/compass/04-01-installation.md) or to the [Director GraphQL schema](https://github.com/kyma-incubator/compass/blob/master/components/director/pkg/graphql/schema.graphql) directly. This document presents the workflow of Runtime Agent. @@ -15,9 +15,10 @@ This document presents the workflow of Runtime Agent. 2. Runtime Agent stores the certificate and key for the Connector and the Director in the Secret. 3. Runtime Agent synchronizes the Runtime with the Director. It does so by: - - fetching new Applications from the Director and creating them in the Runtime - - removing from the Runtime the Applications that no longer exist in the Director. + +- fetching new Applications from the Director and creating them in the Runtime +- removing from the Runtime the Applications that no longer exist in the Director. 4. Runtime Agent labels the Runtime data in the Director with the Event Gateway URL and the Console URL of the Kyma cluster. These URLs are displayed in the Compass UI. -5. Runtime Agent renews the certificate for the Connector and the Director to maintain connection with Compass. This only happens if the remaining validity period for the certificate passes a certain threshold. \ No newline at end of file +5. Runtime Agent renews the certificate for the Connector and the Director to maintain connection with Compass. This only happens if the remaining validity period for the certificate passes a certain threshold. diff --git a/docs/user/technical-reference/05-20-connection-with-compass.md b/docs/user/technical-reference/05-20-connection-with-compass.md index 4beb6a17..93d88cdc 100644 --- a/docs/user/technical-reference/05-20-connection-with-compass.md +++ b/docs/user/technical-reference/05-20-connection-with-compass.md @@ -26,4 +26,4 @@ The connection status is preserved in the [CompassConnection](../resources/06-20 If the connection with Compass fails, Runtime Agent keeps trying to connect with the token from the Secret. If the connection is established successfully, Runtime Agent ignores the Secret until the connection is lost. -To see how to reconnect Runtime Agent with Compass, see the [tutorial](../tutorials/01-100-reconnect-runtime-agent-with-compass.md). \ No newline at end of file +To see how to reconnect Runtime Agent with Compass, see the [tutorial](../tutorials/01-100-reconnect-runtime-agent-with-compass.md). diff --git a/docs/user/technical-reference/07-10-application-gateway-details.md b/docs/user/technical-reference/07-10-application-gateway-details.md index bd54251d..9906f1b8 100644 --- a/docs/user/technical-reference/07-10-application-gateway-details.md +++ b/docs/user/technical-reference/07-10-application-gateway-details.md @@ -25,7 +25,7 @@ Application Gateway proxies requests from Functions and services in Kyma to exte For examples of configurations and Secrets, see the [tutorial on registering a secured API](../tutorials/01-30-register-secured-api.md). -> [!NOTE] +> [!NOTE] > All APIs defined in a single Secret use the same configuration - the same credentials, CSRF tokens, and request parameters. ## Caching @@ -47,10 +47,10 @@ In addition, the `User-Agent` header is set to an empty value not specified in t ## Response Rewriting Application Gateway performs response rewriting in situations when during a call to the external system, the target responds with a redirect (`3xx` status code) that points to the URL with the same host and a different path. -In such a case, the `Location` header is modified so that the original target path is replaced with the Application Gateway URL and port. The sub-path pointing to the called service remains attached at the end. +In such a case, the `Location` header is modified so that the original target path is replaced with the Application Gateway URL and port. The sub-path pointing to the called service remains attached at the end. The modified `Location` header has the following format: `{APP_GATEWAY_URL}:{APP_GATEWAY_PORT}/{APP_NAME}/{SERVICE_NAME}/{SUB-PATH}`. -This functionality makes the HTTP clients that originally called Application Gateway follow redirects through the Gateway, and not to the service directly. +This functionality makes the HTTP clients that originally called Application Gateway follow redirects through the Gateway, and not to the service directly. This allows for passing authorization, custom headers, URL parameters, and the body without an issue. -Application Gateway also rewrites all the `5xx` status codes to `502`. In such a case, the `Target-System-Status` header contains the original code returned by the target. \ No newline at end of file +Application Gateway also rewrites all the `5xx` status codes to `502`. In such a case, the `Target-System-Status` header contains the original code returned by the target. diff --git a/docs/user/technical-reference/07-20-configuring-runtime.md b/docs/user/technical-reference/07-20-configuring-runtime.md index 48f92f0c..ac261590 100644 --- a/docs/user/technical-reference/07-20-configuring-runtime.md +++ b/docs/user/technical-reference/07-20-configuring-runtime.md @@ -3,7 +3,7 @@ > [!WARNING] > Runtime Agent is currently not integrated into the Application Connector module. Proceed with caution and consult the respective documentation for the Application Connector module's current configuration and functionality. -> [!NOTE] +> [!NOTE] > To represent API and Event Definitions of the Applications connected to a Runtime, we recommend that you use the Open Service Broker API. Runtime Agent periodically requests for the configuration of its Runtime from Compass. @@ -11,16 +11,16 @@ Changes in the configuration for the Runtime are applied by Runtime Agent on the To fetch the Runtime configuration, Runtime Agent calls the [`applicationsForRuntime`](https://github.com/kyma-incubator/compass/blob/master/components/director/pkg/graphql/schema.graphql) query offered by the Compass component called Director. The response for the query contains Applications assigned for the Runtime. -Each Application contains only credentials that are valid for the Runtime that called the query. Runtime Agent uses the credentials to create Secrets used by Application Gateway. +Each Application contains only credentials that are valid for the Runtime that called the query. Runtime Agent uses the credentials to create Secrets used by Application Gateway. Each Runtime Agent can fetch the configurations for Runtimes that belong to its tenant. Runtime Agent reports back to the Director the Runtime-specific [LabelDefinitions](https://github.com/kyma-incubator/compass/blob/master/docs/compass/03-04-labels.md#labeldefinitions), which represent Runtime configuration, together with their values. Runtime-specific LabelDefinitions are Event Gateway URL and Runtime Console URL. -The data mapping between Director and Kyma looks as follows: +The data mapping between Director and Kyma looks as follows: | **Director (Compass)** | **Kyma** | |---------------------------|-------------------------------| | Application | Application CR | | API Bundle | Service in the Application CR | -| API Definition | Entry under the service | \ No newline at end of file +| API Definition | Entry under the service | diff --git a/docs/user/technical-reference/README.md b/docs/user/technical-reference/README.md index 1fdf104b..14f029d1 100644 --- a/docs/user/technical-reference/README.md +++ b/docs/user/technical-reference/README.md @@ -1,3 +1,3 @@ # Technical Reference -In this section, you'll find the architecture documents, the configuration parameters, and other useful references. \ No newline at end of file +In this section, you'll find the architecture documents, the configuration parameters, and other useful references. diff --git a/docs/user/tutorials/01-10-create-application.md b/docs/user/tutorials/01-10-create-application.md index 489a1f18..965f334e 100644 --- a/docs/user/tutorials/01-10-create-application.md +++ b/docs/user/tutorials/01-10-create-application.md @@ -1,6 +1,6 @@ # Create a New Application -> [!NOTE] +> [!NOTE] > An Application represents a single connected external solution. ## Prerequisites @@ -11,7 +11,7 @@ Before you start, export the name of your application as an environment variable export APP_NAME={YOUR_APP_NAME} ``` -> [!NOTE] +> [!NOTE] > Read about the [Purpose and Benefits of Istio Sidecars](https://kyma-project.io/#/istio/user/00-30-overview-istio-sidecars). Then, check how to [Enable Automatic Istio Sidecar Proxy Injection](https://kyma-project.io/#/istio/user/operation-guides/02-20-enable-sidecar-injection). For more details, see [Default Istio Setup](https://kyma-project.io/#/istio/user/00-40-overview-istio-setup) in Kyma. ## Create an Application @@ -35,33 +35,34 @@ EOF ## Get the Application Data To get the data of the created Application and show the output in the `yaml` format, run this command: -```bash -kubectl get app $APP_NAME -o yaml -``` -A successful response returns the Application custom resource with the specified name. + ```bash + kubectl get app $APP_NAME -o yaml + ``` + +A successful response returns the Application custom resource with the specified name. This is an example response: -```yaml -apiVersion: applicationconnector.kyma-project.io/v1alpha1 -kind: Application -metadata: - clusterName: "" - creationTimestamp: 2018-11-22T13:53:20Z - generation: 1 - name: test1 - namespace: "" - resourceVersion: "30728" - selfLink: /apis/applicationconnector.kyma-project.io/v1alpha1/applications/test1 - uid: f8ca5595-ee5d-11e8-acb2-000d3a443243 -spec: - description: {APP_DESCRIPTION} - labels: - kind: "production" - region: "us" -``` + ```yaml + apiVersion: applicationconnector.kyma-project.io/v1alpha1 + kind: Application + metadata: + clusterName: "" + creationTimestamp: 2018-11-22T13:53:20Z + generation: 1 + name: test1 + namespace: "" + resourceVersion: "30728" + selfLink: /apis/applicationconnector.kyma-project.io/v1alpha1/applications/test1 + uid: f8ca5595-ee5d-11e8-acb2-000d3a443243 + spec: + description: {APP_DESCRIPTION} + labels: + kind: "production" + region: "us" + ``` -If there are registered services connected to your Application in Kyma, the response also shows them: +If there are registered services connected to your Application in Kyma, the response also shows them: ```yaml ... @@ -72,5 +73,6 @@ spec: region: "us" services: {LIST_OF_REGISTERED_SERVICES} ``` + > [!TIP] -> You can use Kyma dashboard to create and manage your Application. To do so, go to **Integration > Applications** from the **Cluster Details** view. \ No newline at end of file +> You can use Kyma dashboard to create and manage your Application. To do so, go to **Integration > Applications** from the **Cluster Details** view. diff --git a/docs/user/tutorials/01-100-reconnect-runtime-agent-with-compass.md b/docs/user/tutorials/01-100-reconnect-runtime-agent-with-compass.md index 54d42e1a..fdbd767a 100644 --- a/docs/user/tutorials/01-100-reconnect-runtime-agent-with-compass.md +++ b/docs/user/tutorials/01-100-reconnect-runtime-agent-with-compass.md @@ -18,4 +18,4 @@ To force Runtime Agent to reconnect using the parameters from the Secret, delete kubectl delete compassconnection compass-connection ``` -After the Connection CR is removed, Runtime Agent tries to connect to Compass using the token from the Secret. \ No newline at end of file +After the Connection CR is removed, Runtime Agent tries to connect to Compass using the token from the Secret. diff --git a/docs/user/tutorials/01-20-register-manage-services.md b/docs/user/tutorials/01-20-register-manage-services.md index 71e6aab0..d1c9e62b 100644 --- a/docs/user/tutorials/01-20-register-manage-services.md +++ b/docs/user/tutorials/01-20-register-manage-services.md @@ -1,8 +1,8 @@ # Register a Service -This guide shows you how to register a service of your external solution in Kyma. For this example, we use a Basic Authentication-secured API. +This guide shows you how to register a service of your external solution in Kyma. For this example, we use a Basic Authentication-secured API. -> [!NOTE] +> [!NOTE] > Learn how to [register APIs secured with different security schemes or protected against cross-site request forgery (CSRF) attacks](01-30-register-secured-api.md). ## Prerequisites @@ -28,11 +28,12 @@ This guide shows you how to register a service of your external solution in Kyma export TARGET_PATH=basic-auth/$USER_NAME/$PASSWORD export NAMESPACE=default ``` - - > [!NOTE] - > Replace the example values above with your actual values. + + > [!NOTE] + > Replace the example values above with your actual values. 2. Enable [Istio sidecar injection](https://kyma-project.io/#/istio/user/00-30-overview-istio-sidecars) in the namespace: + ```bash kubectl label namespace $NAMESPACE istio-injection=enabled ``` @@ -70,18 +71,18 @@ This guide shows you how to register a service of your external solution in Kyma EOF ``` -## Access the Registered Service +## Access the Registered Service -To check that the service was registered correctly, create a test Pod, and make a call to Application Gateway from within this Pod. +To check that the service was registered correctly, create a test Pod, and make a call to Application Gateway from within this Pod. 1. To build a path to access your registered service, run this command: ```bash export GATEWAY_URL=http://central-application-gateway.kyma-system:8080/$APP_NAME/$SERVICE_DISPLAY_NAME/$TARGET_PATH ``` - + > [!WARNING] - > `SERVICE_DISPLAY_NAME` in the **GATEWAY_URL** path must be in its [normalized form](01-30-register-secured-api.md#register-a-secured-api). This means that, for example, if you used `test-basic-auth` as the service **displayName**, you're good to go, but if you used `"Test Basic Auth"`, you must replace it with `test-basic-auth` in the path. + > `SERVICE_DISPLAY_NAME` in the **GATEWAY_URL** path must be in its [normalized form](01-30-register-secured-api.md#register-a-secured-api). This means that, for example, if you used `test-basic-auth` as the service **displayName**, you're good to go, but if you used `"Test Basic Auth"`, you must replace it with `test-basic-auth` in the path. 2. Export the name of the test Pod as an environment variable: @@ -119,10 +120,10 @@ To check that the service was registered correctly, create a test Pod, and make kubectl wait --for=condition=Ready pod $POD_NAME -n $NAMESPACE ``` -5. To make a call to Application Gateway from within the Pod, run: +5. To make a call to Application Gateway from within the Pod, run: ```bash kubectl exec $POD_NAME -c $POD_NAME -n $NAMESPACE -- sh -c "wget -O- '$GATEWAY_URL'" ``` - A successful response from the service means that it was registered correctly. \ No newline at end of file + A successful response from the service means that it was registered correctly. diff --git a/docs/user/tutorials/01-30-register-secured-api.md b/docs/user/tutorials/01-30-register-secured-api.md index bf551570..2771f7cc 100644 --- a/docs/user/tutorials/01-30-register-secured-api.md +++ b/docs/user/tutorials/01-30-register-secured-api.md @@ -2,11 +2,11 @@ Application Connectivity allows you to register a secured API exposed by your external solution. The supported authentication methods are [Basic Authentication](https://tools.ietf.org/html/rfc7617), [OAuth](https://tools.ietf.org/html/rfc6750), [OAuth 2.0 mTLS](https://datatracker.ietf.org/doc/html/rfc8705), and client certificates. -You can specify only one authentication method for every secured API you register. +You can specify only one authentication method for every secured API you register. Additionally, you can secure the API against cross-site request forgery (CSRF) attacks. CSRF tokens are an additional layer of protection and can accompany any authentication method. -> [!NOTE] +> [!NOTE] > Registering a secured API is a part of [registering services](01-20-register-manage-services.md) of an external solution connected to Kyma. ## Register a Secured API @@ -40,200 +40,201 @@ The **credentials** object must contain the following fields: | Field | Description | | --------------------- |-----------------------------------------------------------------------------| | **secretName** | Name of a Secret storing credentials. | -| **type** | Authentication method type. Supported values: `Basic`, `OAuth`, `OAuthWithCert `, `CertificateGen`. | +| **type** | Authentication method type. Supported values: `Basic`, `OAuth`, `OAuthWithCert`, `CertificateGen`. | | **authenticationUrl** | Optional OAuth token URL, valid only for the `OAuth` and `OAuthWithCert` types. | ## Register a Basic Authentication-secured API This is an example of the **service** object for an API secured with Basic Authentication: -```yaml - - id: {TARGET_UUID} - name: my-basic-auth-service - displayName: "My Basic Auth Service" - description: "My service" - providerDisplayName: "My organisation" - entries: - - credentials: - secretName: {SECRET_NAME} - type: Basic - targetUrl: {TARGET_API_URL} - type: API -``` - -This is an example Secret containing credentials: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: {SECRET_NAME} - namespace: kyma-system -data: - username: {BASE64_ENCODED_USER_NAME} - password: {BASE64_ENCODED_PASSWORD} -``` + ```yaml + - id: {TARGET_UUID} + name: my-basic-auth-service + displayName: "My Basic Auth Service" + description: "My service" + providerDisplayName: "My organisation" + entries: + - credentials: + secretName: {SECRET_NAME} + type: Basic + targetUrl: {TARGET_API_URL} + type: API + ``` + +This is an example Secret containing credentials: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: {SECRET_NAME} + namespace: kyma-system + data: + username: {BASE64_ENCODED_USER_NAME} + password: {BASE64_ENCODED_PASSWORD} + ``` To create such a Secret, run this command: -```bash -kubectl create secret generic {SECRET_NAME} --from-literal username={USER_NAME} --from-literal password={PASSWORD} -n kyma-system -``` + ```bash + kubectl create secret generic {SECRET_NAME} --from-literal username={USER_NAME} --from-literal password={PASSWORD} -n kyma-system + ``` ## Register an OAuth-secured API This is an example of the **service** object for an API secured with OAuth: -```yaml - - id: {TARGET_UUID} - name: my-oauth-service - displayName: "My OAuth Service" - description: "My service" - providerDisplayName: "My organisation" - entries: - - credentials: - secretName: {SECRET_NAME} - authenticationUrl: {OAUTH_TOKEN_URL} - type: OAuth - targetUrl: {TARGET_API_URL} - type: API -``` - -This is an example of the Secret containing credentials: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: {SECRET_NAME} - namespace: kyma-system -data: - clientId: {BASE64_ENCODED_CLIENT_ID} - clientSecret: {BASE64_ENCODED_CLIENT_SECRET} -``` + ```yaml + - id: {TARGET_UUID} + name: my-oauth-service + displayName: "My OAuth Service" + description: "My service" + providerDisplayName: "My organisation" + entries: + - credentials: + secretName: {SECRET_NAME} + authenticationUrl: {OAUTH_TOKEN_URL} + type: OAuth + targetUrl: {TARGET_API_URL} + type: API + ``` + +This is an example of the Secret containing credentials: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: {SECRET_NAME} + namespace: kyma-system + data: + clientId: {BASE64_ENCODED_CLIENT_ID} + clientSecret: {BASE64_ENCODED_CLIENT_SECRET} + ``` To create such a Secret, run this command: -```bash -kubectl create secret generic {SECRET_NAME} --from-literal clientId={CLIENT_ID} --from-literal clientSecret={CLIENT_SECRET} -n kyma-system -``` + ```bash + kubectl create secret generic {SECRET_NAME} --from-literal clientId={CLIENT_ID} --from-literal clientSecret={CLIENT_SECRET} -n kyma-system + ``` + ## Register an OAuth 2.0 mTLS-secured API This is an example of the **service** object for an API secured with OAuth where the token is fetched from an mTLS-secured endpoint: -```yaml - - id: {TARGET_UUID} - name: my-mTLS-oauth-service - displayName: "My mTLS OAuth Service" - description: "My service" - providerDisplayName: "My organisation" - entries: - - credentials: - secretName: {SECRET_NAME} - authenticationUrl: {OAUTH_TOKEN_URL} - type: OAuthWithCert - targetUrl: {TARGET_API_URL} - type: API -``` + ```yaml + - id: {TARGET_UUID} + name: my-mTLS-oauth-service + displayName: "My mTLS OAuth Service" + description: "My service" + providerDisplayName: "My organisation" + entries: + - credentials: + secretName: {SECRET_NAME} + authenticationUrl: {OAUTH_TOKEN_URL} + type: OAuthWithCert + targetUrl: {TARGET_API_URL} + type: API + ``` This is an example of the Secret containing credentials: -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: {SECRET_NAME} - namespace: kyma-system -data: - clientId: {BASE64_ENCODED_CLIENT_ID} - crt: {BASE64_ENCODED_CERTIFICATE} - key: {BASE64_ENCODED_PRIVATE_KEY} -``` + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: {SECRET_NAME} + namespace: kyma-system + data: + clientId: {BASE64_ENCODED_CLIENT_ID} + crt: {BASE64_ENCODED_CERTIFICATE} + key: {BASE64_ENCODED_PRIVATE_KEY} + ``` To create such a Secret, run this command: -```bash -kubectl create secret generic {SECRET_NAME} --from-literal clientId={CLIENT_ID} --from-literal crt={CERTIFICATE} --from-literal key={PRIVATE_KEY} -n kyma-system -``` + ```bash + kubectl create secret generic {SECRET_NAME} --from-literal clientId={CLIENT_ID} --from-literal crt={CERTIFICATE} --from-literal key={PRIVATE_KEY} -n kyma-system + ``` -## Register a client certificate-secured API +## Register a Client Certificate-Secured API This is an example of the **service** object for an API secured with a client certificate: -```yaml - - id: {TARGET_UUID} - name: my-client-cert-service - displayName: "My Client Cert Service" - description: "My service" - providerDisplayName: "My organisation" - entries: - - credentials: - secretName: {SECRET_NAME} - type: CertificateGen - targetUrl: {TARGET_API_URL} - type: API -``` - -This is an example of the Secret containing credentials: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: {SECRET_NAME} - namespace: kyma-system -data: - crt: {BASE64_ENCODED_CERTIFICATE} - key: {BASE64_ENCODED_PRIVATE_KEY} -``` + ```yaml + - id: {TARGET_UUID} + name: my-client-cert-service + displayName: "My Client Cert Service" + description: "My service" + providerDisplayName: "My organisation" + entries: + - credentials: + secretName: {SECRET_NAME} + type: CertificateGen + targetUrl: {TARGET_API_URL} + type: API + ``` + +This is an example of the Secret containing credentials: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: {SECRET_NAME} + namespace: kyma-system + data: + crt: {BASE64_ENCODED_CERTIFICATE} + key: {BASE64_ENCODED_PRIVATE_KEY} + ``` To create such a Secret, run this command: -```bash -kubectl create secret generic {SECRET_NAME} --from-literal crt={CERTIFICATE} --from-literal key={PRIVATE_KEY} -n kyma-system -``` + ```bash + kubectl create secret generic {SECRET_NAME} --from-literal crt={CERTIFICATE} --from-literal key={PRIVATE_KEY} -n kyma-system + ``` ## Register a CSRF-protected API This is an example of the **service** object for an API secured with both Basic Authentication and a CSRF token: -```yaml - - id: {TARGET_UUID} - name: my-csrf-service - displayName: "My CSRF Service" - description: "My service" - providerDisplayName: "My organisation" - entries: - - credentials: - secretName: {SECRET_NAME} - type: Basic - csrfInfo: - tokenEndpointURL: {CSRF_TOKEN_URL} - targetUrl: {TARGET_API_URL} - type: API -``` - -> [!NOTE] + ```yaml + - id: {TARGET_UUID} + name: my-csrf-service + displayName: "My CSRF Service" + description: "My service" + providerDisplayName: "My organisation" + entries: + - credentials: + secretName: {SECRET_NAME} + type: Basic + csrfInfo: + tokenEndpointURL: {CSRF_TOKEN_URL} + targetUrl: {TARGET_API_URL} + type: API + ``` + +> [!NOTE] > The example assumes that the CSRF token endpoint service uses the same credentials as the target API. -This is an example of the Secret containing credentials: +This is an example of the Secret containing credentials: -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: {SECRET_NAME} - namespace: kyma-system -data: - username: {BASE64_ENCODED_USER_NAME} - password: {BASE64_ENCODED_PASSWORD} -``` + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: {SECRET_NAME} + namespace: kyma-system + data: + username: {BASE64_ENCODED_USER_NAME} + password: {BASE64_ENCODED_PASSWORD} + ``` To create such a Secret, run this command: -```bash -kubectl create secret generic {SECRET_NAME} --from-literal username={USER_NAME} --from-literal password={PASSWORD} -n kyma-system -``` + ```bash + kubectl create secret generic {SECRET_NAME} --from-literal username={USER_NAME} --from-literal password={PASSWORD} -n kyma-system + ``` ## Use Headers and Query Parameters for Custom Authentication @@ -241,69 +242,67 @@ You can specify additional headers and query parameters to inject to requests ma This is an example of the **service** object for an API secured with Basic Authentication and including additional headers and query parameters. -```yaml - - id: {TARGET_UUID} - name: my-headers-params-service - displayName: "My Headers Params Service" - description: "My service" - providerDisplayName: "My organisation" - entries: - - credentials: - secretName: {SECRET_NAME} - type: Basic - targetUrl: {TARGET_API_URL} - requestParametersSecretName: {QUERY_PARAMS_SECRET_NAME} - type: API -``` - -This is an example of the Secret containing credentials: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: {SECRET_NAME} - namespace: kyma-system -data: - username: {BASE64_ENCODED_USER_NAME} - password: {BASE64_ENCODED_PASSWORD} -``` + ```yaml + - id: {TARGET_UUID} + name: my-headers-params-service + displayName: "My Headers Params Service" + description: "My service" + providerDisplayName: "My organisation" + entries: + - credentials: + secretName: {SECRET_NAME} + type: Basic + targetUrl: {TARGET_API_URL} + requestParametersSecretName: {QUERY_PARAMS_SECRET_NAME} + type: API + ``` + +This is an example of the Secret containing credentials: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: {SECRET_NAME} + namespace: kyma-system + data: + username: {BASE64_ENCODED_USER_NAME} + password: {BASE64_ENCODED_PASSWORD} + ``` To create such a Secret, run this command: -```bash -kubectl create secret generic {SECRET_NAME} --from-literal username={USER_NAME} --from-literal password={PASSWORD} -n kyma-system -``` + ```bash + kubectl create secret generic {SECRET_NAME} --from-literal username={USER_NAME} --from-literal password={PASSWORD} -n kyma-system + ``` -This is an example of the Secret containing headers and request parameters: +This is an example of the Secret containing headers and request parameters: -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: {SECRET_NAME} - namespace: kyma-system -data: - headers: {BASE64_ENCODED_HEADERS_JSON} - queryParameters: {BASE64_ENCODED_QUERY_PARAMS_JSON} -``` + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: {SECRET_NAME} + namespace: kyma-system + data: + headers: {BASE64_ENCODED_HEADERS_JSON} + queryParameters: {BASE64_ENCODED_QUERY_PARAMS_JSON} + ``` To create such a Secret, run this command: -```bash -kubectl create secret generic {SECRET_NAME} --from-literal headers={HEADERS_JSON} --from-literal queryParameters={QUERY_PARAMS_JSON} -n kyma-system -``` + ```bash + kubectl create secret generic {SECRET_NAME} --from-literal headers={HEADERS_JSON} --from-literal queryParameters={QUERY_PARAMS_JSON} -n kyma-system + ``` Additional headers stored in the Secret must be provided in the form of a valid JSON document. This is an example of a headers JSON containing one entry: -```json -{"{MY_HEADER}":["{MY_HEADER_VALUE}"]} -``` + ```json + {"{MY_HEADER}":["{MY_HEADER_VALUE}"]} + ``` Additional query parameters stored in the Secret must be provided in the form of a valid JSON document. This is an example of a headers JSON containing one entry: -```json -{"{MY_QUERY_PARAM}":["{MY_QUERY_PARAM_VALUE}"]} -``` - - \ No newline at end of file + ```json + {"{MY_QUERY_PARAM}":["{MY_QUERY_PARAM_VALUE}"]} + ``` diff --git a/docs/user/tutorials/01-40-call-registered-service-from-kyma.md b/docs/user/tutorials/01-40-call-registered-service-from-kyma.md index efc947c3..a28f65d9 100644 --- a/docs/user/tutorials/01-40-call-registered-service-from-kyma.md +++ b/docs/user/tutorials/01-40-call-registered-service-from-kyma.md @@ -8,18 +8,21 @@ This guide shows how to call a registered external service from Kyma using a sim - Your [service display name exported](01-20-register-manage-services.md#prerequisites) as an environment variable - Your [Application name exported](01-10-create-application.md#prerequisites) as an environment variable - Your desired namespace, cluster domain, and the names for your Function and APIRule exported as environment variables + ```bash export NAMESPACE=default export CLUSTER_DOMAIN=local.kyma.dev export FUNCTION_NAME=my-function export APIRULE_NAME=$FUNCTION_NAME-ar ``` + - [Istio sidecar injection](https://kyma-project.io/#/istio/user/00-30-overview-istio-sidecars) enabled in your namespace + ```bash kubectl label namespace $NAMESPACE istio-injection=enabled ``` -> [!WARNING] +> [!WARNING] > On a local Kyma deployment, skip SSL certificate verification when making a `curl` call, by adding the `-k` flag to it. Alternatively, add the Kyma certificates to your local certificate storage on your machine using the `kyma import certs` command. ## Steps @@ -126,4 +129,4 @@ This guide shows how to call a registered external service from Kyma using a sim { "uuid": "d44cc373-b26e-4a36-9890-6418d131a285" } - ``` \ No newline at end of file + ``` diff --git a/docs/user/tutorials/01-50-disable-tls-certificate-verification.md b/docs/user/tutorials/01-50-disable-tls-certificate-verification.md index 46444942..b1c8e16c 100644 --- a/docs/user/tutorials/01-50-disable-tls-certificate-verification.md +++ b/docs/user/tutorials/01-50-disable-tls-certificate-verification.md @@ -2,10 +2,10 @@ You can disable the [TLS certificate verification](../00-20-security.md#tls-certificate-verification-for-external-systems) for the connections between Kyma and an external solution represented by an Application. This allows Kyma to send requests and data to an unsecured Application without verifying its presented TLS certificate. Disabling the certificate verification can be useful in certain testing scenarios. -> [!NOTE] +> [!NOTE] > By default, the TLS certificate verification is enabled when sending data and requests to every Application. -To disable TLS certificate verification [export your Application name as an environment variable](01-10-create-application.md#prerequisites) and follow these steps: +To disable TLS certificate verification [export your Application name as an environment variable](01-10-create-application.md#prerequisites) and follow these steps: 1. Edit the Application custom resource (CR) for your Application. Run: @@ -14,4 +14,4 @@ To disable TLS certificate verification [export your Application name as an envi ``` 2. Edit the Application by setting the **skipVerify** parameter to `true`. -3. Save the changes and quit. \ No newline at end of file +3. Save the changes and quit. diff --git a/docs/user/tutorials/01-60-establish-secure-connection-with-compass.md b/docs/user/tutorials/01-60-establish-secure-connection-with-compass.md index de00ffef..a4b3162f 100644 --- a/docs/user/tutorials/01-60-establish-secure-connection-with-compass.md +++ b/docs/user/tutorials/01-60-establish-secure-connection-with-compass.md @@ -62,24 +62,27 @@ To establish a secure connection with Compass and generate the client certificat 3. Generate a key and a Certificate Signing Request (CSR). - Generate a CSR with the following command. `SUBJECT` is the certificate subject data returned with the CSR information as `subject`. + Generate a CSR with the following command. `SUBJECT` is the certificate subject data returned with the CSR information as `subject`. ```bash export KEY_LENGTH=4096 openssl genrsa -out compass-app.key $KEY_LENGTH openssl req -new -sha256 -out compass-app.csr -key compass-app.key -subj "{SUBJECT}" ``` + > [!NOTE] > The key length is configurable, however, 4096 is the recommended value. 4. Sign the CSR and get a client certificate. Encode the obtained CSR with base64: + ```bash openssl base64 -in compass-app.csr ``` To get the CSR signed, use the encoded CSR in this GraphQL mutation: + ```graphql mutation { result: signCertificateSigningRequest(csr: "{BASE64_ENCODED_CSR}") { @@ -97,9 +100,10 @@ To establish a secure connection with Compass and generate the client certificat 5. Decode the certificate chain. After you receive the certificates, decode the certificate chain with the base64 method and use it in your application: + ```bash base64 -d {CERTIFICATE_CHAIN} ``` -> [!NOTE] -> See how to [maintain a secure connection with Compass and renew a client certificate](01-70-maintain-secure-connection-with-compass.md). \ No newline at end of file +> [!NOTE] +> See how to [maintain a secure connection with Compass and renew a client certificate](01-70-maintain-secure-connection-with-compass.md). diff --git a/docs/user/tutorials/01-70-maintain-secure-connection-with-compass.md b/docs/user/tutorials/01-70-maintain-secure-connection-with-compass.md index 3406382b..c17d99df 100644 --- a/docs/user/tutorials/01-70-maintain-secure-connection-with-compass.md +++ b/docs/user/tutorials/01-70-maintain-secure-connection-with-compass.md @@ -40,22 +40,26 @@ After you have established a secure connection with Compass, you can fetch the c 2. Generate a key and a Certificate Signing Request (CSR). Generate a CSR with this command using the certificate subject data obtained with the CSR information: - ``` + + ```bash export KEY_LENGTH=4096 openssl genrsa -out compass-app.key $KEY_LENGTH openssl req -new -sha256 -out compass-app.csr -key compass-app.key -subj "{SUBJECT}" ``` + > [!NOTE] > The key length is configurable, however, 4096 is the recommended value. 3. Sign the CSR and renew the client certificate. Encode the obtained CSR with base64: + ```bash openssl base64 -in compass-app.csr ``` Send the following GraphQL mutation with the encoded CSR to the Certificate-Secured Connector URL: + ```graphql mutation { result: signCertificateSigningRequest(csr: "{BASE64_ENCODED_CSR}") { @@ -77,5 +81,5 @@ After you have established a secure connection with Compass, you can fetch the c base64 -d {CERTIFICATE_CHAIN} ``` -> [!NOTE] -> See how to [revoke a client certificate](01-80-revoke-client-certificate.md). \ No newline at end of file +> [!NOTE] +> See how to [revoke a client certificate](01-80-revoke-client-certificate.md). diff --git a/docs/user/tutorials/01-80-revoke-client-certificate.md b/docs/user/tutorials/01-80-revoke-client-certificate.md index e307d0c4..602c124c 100644 --- a/docs/user/tutorials/01-80-revoke-client-certificate.md +++ b/docs/user/tutorials/01-80-revoke-client-certificate.md @@ -5,7 +5,7 @@ After you have established a secure connection with Compass and generated a client certificate, you may want to revoke this certificate at some point. To revoke a client certificate, follow the steps in this tutorial. -> [!NOTE] +> [!NOTE] > A revoked client certificate remains valid until it expires, but it cannot be renewed. ## Prerequisites @@ -33,4 +33,4 @@ A successful call returns the following response: ```json {"data":{"result":true}} -``` \ No newline at end of file +``` diff --git a/docs/user/tutorials/01-90-configure-runtime-agent-with-compass.md b/docs/user/tutorials/01-90-configure-runtime-agent-with-compass.md index 92798a30..10dbc60b 100644 --- a/docs/user/tutorials/01-90-configure-runtime-agent-with-compass.md +++ b/docs/user/tutorials/01-90-configure-runtime-agent-with-compass.md @@ -13,7 +13,7 @@ This tutorial shows how to configure Runtime Agent with Compass. - One-time token from the Connector - Tenant ID -> [!NOTE] +> [!NOTE] > Learn also about the [parameters required](../technical-reference/05-20-connection-with-compass.md) to initialize the connection between Runtime Agent and Compass. ## Steps @@ -33,4 +33,4 @@ metadata: name: compass-agent-configuration namespace: kyma-system EOF -``` \ No newline at end of file +``` diff --git a/docs/user/tutorials/README.md b/docs/user/tutorials/README.md index 192cc914..b0e3ac93 100644 --- a/docs/user/tutorials/README.md +++ b/docs/user/tutorials/README.md @@ -1,3 +1,3 @@ # Application Connectivity - Tutorials -Browse the tutorials for Application Connectivity to learn how to use it step-by-step in different scenarios. \ No newline at end of file +Browse the tutorials for Application Connectivity to learn how to use it step-by-step in different scenarios. diff --git a/markdown_heading_capitalization.js b/markdown_heading_capitalization.js new file mode 100644 index 00000000..2fdede35 --- /dev/null +++ b/markdown_heading_capitalization.js @@ -0,0 +1,30 @@ +// This file is used to trigger the custom rule that checks if all markdown headings (words longer than 4 characters) are written in the title case. To run this check, you must include the check in the markdownlint command. +// For example, if you want to run the check on the `docs` folder, run the following command: `markdownlint -r ./markdown_heading_capitalization.js docs/`. +module.exports = [{ + "names": [ "custom/capitalize-headings" ], + "description": "Heading words longer than 4 characters should be capitalized", + "tags": [ "formatting" ], + "function": function rule(params, onError) { + params.tokens.filter(function filterToken(token) { + return token.type === "heading_open"; + }).forEach(function forToken(heading) { + var headingTokenContent = heading.line.trim(); + var wordsInHeading = headingTokenContent.split(' '); + + for (var i = 0; i < wordsInHeading.length; i++) { + if (wordsInHeading[i].length > 4 && wordsInHeading[i] && + wordsInHeading[i].charAt(0) !== wordsInHeading[i].charAt(0).toUpperCase()) { + var capitalizedWord = wordsInHeading[i].charAt(0).toUpperCase() + wordsInHeading[i].slice(1); + var detailMessage = "Change " + "'" + wordsInHeading[i] + "'" + " to " + "'" + capitalizedWord + "'"; + + onError({ + "lineNumber": heading.lineNumber, + "detail": detailMessage, + "context": headingTokenContent, // Show the whole heading as context + "range": [headingTokenContent.indexOf(wordsInHeading[i]), wordsInHeading[i].length] // Underline the word which needs a change + }); + } + } + }); + } + }]; \ No newline at end of file