Adjust API Gateway to the new content guidelines (#776)

* adjust API Gateway to the new content guidelines * replace html tags with docsify solution * adjust HTTPBin capitalization * fix identation * fix indentation * fix heading * fix tabs * fix tabs * fix tabs * capitalize without * HTTPBin * remove nested ordered lists * fix tabs * move example * add code of conduct and contributing * Apply suggestions from code review Co-authored-by: Iwona Langer <[email protected]> * add notice and security files * add missing title case * note test * note test * test notes * test note * note test * test note styles * note and cr * fix note * note test * test notes * test notes * test notes * revert note changes * test notes * correct the word namespace * test notes rendering * fix broken link * Specify tag for busola --------- Co-authored-by: Iwona Langer <[email protected]> Co-authored-by: Marek Kolodziejczak <[email protected]>
kyma-project · Jan 2, 2024 · a1724d8 · a1724d8
1 parent 39f4700
commit a1724d8
Show file tree

Hide file tree

Showing 66 changed files with 855 additions and 953 deletions.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,3 @@
+# Code of Conduct
+
+Each contributor and maintainer of this project agrees to follow the [community Code of Conduct](https://github.com/kyma-project/community/blob/main/docs/contributing/01-code-of-conduct.md) that relies on the CNCF Code of Conduct. Read it to learn about the agreed standards of behavior, shared values that govern our community, and details on how to report any suspected Code of Conduct violations.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,3 @@
+# Contributing
+
+To contribute to this project, follow the general [contributing](https://github.com/kyma-project/community/blob/main/docs/contributing/02-contributing.md) guidelines.
diff --git a/NOTICE.md b/NOTICE.md
@@ -0,0 +1 @@
+Copyright (c) 2018 SAP SE or an SAP affiliate company. All rights reserved.
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 # API Gateway
 
-## What is API Gateway?
+## What Is API Gateway?
 
 API Gateway provides functionalities that allow you to expose and secure APIs by using [Ory Oathkeeper](https://www.ory.sh/docs/oathkeeper) and the [Istio service mesh](https://istio.io/) resources.
 
@@ -21,10 +21,10 @@ To use API Gateway, you must install Istio and Ory Oathkeeper in your cluster. L
 ### Procedure
 1. Create the `kyma-system` namespace and label it with `istio-injection=enabled`:
 
-    ```bash
-    kubectl create namespace kyma-system
-    kubectl label namespace kyma-system istio-injection=enabled --overwrite
-    ```
+   ```bash
+   kubectl create namespace kyma-system
+   kubectl label namespace kyma-system istio-injection=enabled --overwrite
+   ```
 
 2. To install API Gateway, you must install the latest version of Kyma API Gateway Operator and API Gateway CustomResourceDefinition first. Run:
 
@@ -59,12 +59,23 @@ To use API Gateway, you must install Istio and Ory Oathkeeper in your cluster. L
 
 For more installation options, visit the [installation guide](./docs/contributor/01-00-installation.md).
 
-## Useful links
+## Useful Links
 
 To learn how to use the API Gateway module, read the documentation in the [`user`](./docs/user/) directory.
 
 If you are interested in the detailed documentation of the Kyma API Gateway Operator's design and technical aspects, check the [`contributor`](./docs/contributor/) directory.
 
 ## Contributing
+<!--- mandatory section - do not change this! --->
+
+See the [Contributing](CONTRIBUTING.md) guidelines.
+
+## Code of Conduct
+<!--- mandatory section - do not change this! --->
+
+See the [Code of Conduct](CODE_OF_CONDUCT.md) document.
+
+## Licensing
+<!--- mandatory section - do not change this! --->
 
-To contribute to this project, follow the general [contributing](https://github.com/kyma-project/community/blob/main/docs/contributing/02-contributing.md) guidelines.
+See the [license](./LICENSE) file.
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,3 @@
+# Security Policy
+
+If you suspect you have found a security vulnerability in Kyma, please report it to us as described in the [SAP Open Source Security Policy](https://github.com/SAP/.github/blob/main/SECURITY.md).
diff --git a/docs/contributor/01-00-installation.md b/docs/contributor/01-00-installation.md
@@ -9,61 +9,61 @@
 - [Docker](https://www.docker.com)
 - [Kyma CLI](https://kyma-project.io/#/04-operation-guides/operations/01-install-kyma-CLI)
 
-## Install Kyma API Gateway Operator manually
+## Install Kyma API Gateway Operator Manually
 
 1. Clone the project.
 
-```bash
-git clone https://github.com/kyma-project/api-gateway.git && cd api-gateway
-```
+    ```bash
+    git clone https://github.com/kyma-project/api-gateway.git && cd api-gateway
+    ```
 
 2. Set the API Gateway Operator image name.
 
-```bash
-export IMG=api-gateway-operator:0.0.1
-export K3D_CLUSTER_NAME=kyma
-```
+    ```bash
+    export IMG=api-gateway-operator:0.0.1
+    export K3D_CLUSTER_NAME=kyma
+    ```
 
 3. Provision the k3d cluster.
 
-```bash
-kyma provision k3d
-```
->**TIP:** To verify the correctness of the project, build it using the `make build` command.
+    ```bash
+    kyma provision k3d
+    ```
+    >**TIP:** To verify the correctness of the project, build it using the `make build` command.
 
 4. Build the image.
 
-```bash
-make docker-build
-```
+    ```bash
+    make docker-build
+    ```
 
 5. Push the image to the registry.
 
-<div tabs name="Push image" group="api-gateway-operator-installation">
-  <details>
-  <summary label="k3d">
-  k3d
-  </summary>
+    <div tabs name="Push image" group="api-gateway-operator-installation">
+      <details>
+      <summary label="k3d">
+      k3d
+      </summary>
 
-   ```bash
-   k3d image import $IMG -c $K3D_CLUSTER_NAME
-   ```
+      ```bash
+      k3d image import $IMG -c $K3D_CLUSTER_NAME
+      ```
 
-  </details>
-  <details>
-  <summary label="Docker registry">
-  Globally available Docker registry
-  </summary>
+      </details>
+      <details>
+      <summary label="Docker registry">
+      Globally available Docker registry
+      </summary>
 
-   ```bash
-   make docker-push
-   ```
+      ```bash
+      make docker-push
+      ```
 
-  </details>
-</div>
+      </details>
+    </div>
 
-6. Create the `kyma-system` Namespace and deploy API Gateway Operator in it.
+6. Create the `kyma-system` namespace and deploy API Gateway Operator in it.
 
-```bash
-make deploy
-```
+    ```bash
+    make deploy
+    ```
diff --git a/docs/contributor/01-10-API-Gateway-CRD-proposal.md b/docs/contributor/01-10-API-Gateway-CRD-proposal.md
@@ -1,8 +1,8 @@
-# API Gateway CRD proposal
+# API Gateway CRD Proposal
 
 This document describes the proposed API for installing the APIGateway component.
 
-## Proposed CR structure
+## Proposed CR Structure
 
 ```yaml
 kind: APIGateway
@@ -40,9 +40,9 @@ status:
 
 ```
 
-## Example use cases
+## Example Use Cases
 
-### The user wants to use API Gateway with no additional configuration
+### The User Wants to Use API Gateway Without Additional Configuration
 
 The user creates an APIGateway CR with no additional configuration.
 
@@ -54,7 +54,7 @@ name: default
 
 By default, APIGateway generates a Certificate and DNSEntry for the default Kyma domain. With this configuration, the user can expose their workloads under the Kyma domain.
 
-### The managed Kyma user wants to expose their workloads under a custom domain
+### The SAP BTP, Kyma Runtime User Wants to Expose Their Workloads Under a Custom Domain
 
 Prerequisite:
 - The DNS secret `dns-secret` exists in the `my-namespace` namespace.
@@ -81,7 +81,7 @@ Because it is a managed Kyma cluster (SKR), a DNSProvider with the provided Secr
 
 The user can now expose their Services under the hosts `test.example.com` and `test2.example.com`.
 
-### The user wants to expose their Mongo instance
+### The User Wants To Expose Their Mongo Instance
 
 The user configures API Gateway as follows: 
 

diff --git a/docs/contributor/01-20-api-gateway-dependencies.md b/docs/contributor/01-20-api-gateway-dependencies.md
@@ -1,9 +1,9 @@
-# Dependencies of the API Gateway module
+# Dependencies of the API Gateway Module
 
-## Istio dependency
+## Istio Dependency
 
 To use API Gateway, you must install Istio on your cluster. This is required because API Gateway creates the custom resources `Gateway` and `VirtualService`, which are provided by Istio. The recommended method for installing Istio is by using [Kyma Istio Operator](https://github.com/kyma-project/istio#install-kyma-istio-operator-and-istio-from-the-latest-release).
 
-## Dependencies in SAP BTP, Kyma runtime
+## Dependencies in SAP BTP, Kyma Runtime
 
 In SAP BTP, Kyma runtime, API Gateway uses `DNSEntry` and `Certificate` custom resources provided by [Gardener](https://gardener.cloud). Because SAP BTP, Kyma runtime uses Gardener as the running environment, managed offering users are not required to install any dependencies manually.
diff --git a/docs/contributor/01-30-api-rule-dependencies.md b/docs/contributor/01-30-api-rule-dependencies.md
@@ -6,7 +6,7 @@ APIRules require Istio to be installed on the cluster because APIRule Controller
 
 ## Ory Oathkeeper
 
-> **CAUTION:** Ory Oathkeeper has been deprecated. This dependency will change in the future.
+>**CAUTION:** Ory Oathkeeper has been deprecated. This dependency will change in the future.
 
 To use APIRules, both Ory Oathkeeper and Ory Oathkeeper Maester must be installed on the cluster. This is required because APIRule Controller creates the Rule custom resource when an APIRule has defined an access strategy other than `allow`.
 

diff --git a/docs/contributor/04-10-technical-design.md b/docs/contributor/04-10-technical-design.md
@@ -4,6 +4,7 @@ API Gateway Operator consists of two controllers that reconcile different CRs. T
 API Gateway Operator has a dependency on [Istio](https://istio.io/) and [Ory Oathkeeper](https://www.ory.sh/docs/oathkeeper), and it installs Ory Oathkeeper itself.
 
 The following diagram illustrates the APIRule reconciliation process and the resources created in the process:
+
 ![Kyma API Gateway Overview](../assets/operator-contributor-skr-overview.svg)
 
 ## APIGateway Controller

diff --git a/docs/contributor/04-20-apirule-performance.md b/docs/contributor/04-20-apirule-performance.md
@@ -1,8 +1,8 @@
-# APIRule performance tests
+# APIRule Performance Tests
 
 Tests were performed on Gardener GCP cluster with the help of `k6s` on Kyma `production` profile. Requests were made from inside the cluster with HPA disabled for the sake of having identical environment on all runs. The tests were made using 500 Virtual Users making constant requests for 1 minute.
 
-## Performance on deployments without Istio sidecar
+## Performance of Deployments Without Istio Sidecar
 
 |Handler type|No. of successfull calls|No. of failed calls|Data recieved by server [MB]|Transfer speed (recieving) [kB/s]|Data sent by server [MB]|Transfer speed (sending) [kB/s]|Median request duration [ms]|
 |---|---|---|---|---|---|---|---|
@@ -11,7 +11,7 @@ Tests were performed on Gardener GCP cluster with the help of `k6s` on Kyma `pro
 |OAuth2|24198|4|5.5|89|6.3|104|861.75|
 |Ory JWT|66775|5|10|169|17|282|388.36|
 
-## Performance on deployments with Istio sidecar
+## Performance of Deployments with Istio Sidecar
 
 |Handler type|No. of successfull calls|No. of failed calls|Data recieved by server [MB]|Transfer speed (recieving) [kB/s]|Data sent by server [MB]|Transfer speed (sending) [kB/s]|Median request duration [ms]|
 |---|---|---|---|---|---|---|---|

diff --git a/docs/contributor/04-30-ci-cd.md b/docs/contributor/04-30-ci-cd.md
@@ -17,7 +17,7 @@ There are two environments configured:
 - 'restricted' - used when an outside collaborator runs a job in the repository. The run must be approved by
   @kyma-project/goat.
 
-## Pipelines running on pull requests to the `main` branch
+## Pipelines Running on Pull Requests to the Main Branch
 
 The following CI jobs are part of the development cycle.
 
@@ -34,7 +34,7 @@ The following CI jobs are part of the development cycle.
 | [`Pull Request / Run unit tests (pull_request)`](https://github.com/kyma-project/api-gateway/blob/main/.github/workflows/pull-request.yaml#L41)               | Runs unit tests with code coverage information.                                                                                                              |
 | [`pre-api-gateway-presubmit-scanner`](https://github.com/kyma-project/test-infra/blob/main/prow/jobs/test-infra/presubmit-scanner.yaml#L412)                  | Runs the Gitleaks presubmit scanner to detect any sensitive data that might have been committed.                                                             |
 
-## Pipelines running on pull requests to release branches
+## Pipelines Running on Pull Requests to Release Branches
 
 The following CI jobs are part of the release cycle.
 
@@ -52,7 +52,8 @@ The following CI jobs are part of the release cycle.
 | [`pull-api-gateway-manager-custom-domain-integration-gcp`](https://github.com/kyma-project/test-infra/blob/main/prow/jobs/api-gateway/api-gateway-manager-integration-tests.yaml#L6)  | Executes the integration test suite that verifies the functional correctness of Kyma API Gateway Operator. The test suite uses a custom domain and a Gardener GCP cluster. |
 | [`pull-api-gateway-manager-custom-domain-integration-aws`](https://github.com/kyma-project/test-infra/blob/main/prow/jobs/api-gateway/api-gateway-manager-integration-tests.yaml#L58) | Executes the integration test suite that verifies the functional correctness of the API Gateway Operator. The test suite uses a custom domain and a Gardener AWS cluster.  |
 
-## Pipelines running on the main branch
+
+## Pipelines Running on the Main Branch
 
 The following CI jobs run on the main branch.
 
@@ -67,15 +68,15 @@ The following CI jobs run on the main branch.
 | [`post-api-gateway-manager-custom-domain-integration-aws`](https://github.com/kyma-project/test-infra/blob/main/prow/jobs/api-gateway/api-gateway-manager-integration-tests.yaml#L58) | Executes the integration test suite that verifies the functional correctness of the API Gateway Operator. The test suite uses a custom domain and a Gardener AWS cluster.  |
 | [`Main Integration / Slack Notification`](https://github.com/kyma-project/api-gateway/blob/main/.github/workflows/main-integration.yaml#L83)                                          | Sends a Slack notification to the team's channel if any pipelines fail on the main branch.                                                                                 |
 
-## Pipelines running on the release branch
+## Pipelines Running on the Release Branch
 
 The following CI jobs generate release artifacts. They are triggered on Git tag creation.
 
 | Name                                                                                                                                              | Description                                                                                 |
 |---------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
 | [`rel-api-gateway-manager-build`](https://github.com/kyma-project/test-infra/blob/main/prow/jobs/api-gateway/api-gateway-manager-build.yaml#L247) | Builds Kyma API Gateway Operator image on the release and pushes it to the `prod` registry. |
 
-## Pipelines running on a schedule
+## Pipelines Running on a Schedule
 
 The following CI jobs are scheduled to run at specific times.
 

diff --git a/docs/contributor/04-40-cors-policy-design.md b/docs/contributor/04-40-cors-policy-design.md
@@ -1,4 +1,4 @@
-# Proposal for APIRule API CORS headers configuration in IstioVirtual Service
+# Proposal for APIRule API CORS Headers Configuration in IstioVirtual Service
 
 ## API Proposal
 
@@ -22,9 +22,9 @@ type CorsPolicy struct {
 }
 ```
 
-## Security considerations
+## Security Considerations
 
-### Default values
+### Default Values
 
 In the most secure scenario, CORS should be configured not to respond with any of the **Access-Control** headers. However, for backward compatibility with the current implementation, it is important to note that the current configuration for all APIRules is as follows:
 ```yaml
@@ -36,7 +36,7 @@ CorsAllowHeaders: "Authorization,Content-Type,*"
 **Decision**
 The default values should be empty to ensure the secure by default configuration. The transition to that default should be gradual, with the current CORS configuration staying in place for now.
 
-### CORS headers sanitization
+### CORS Headers Sanitization
 
 If a workload provides its own CORS headers, Istio Ingress Gateway does not sanitize or change the CORS headers unless the request origin matches one of the origins specified in the **AllowOrigins** configuration of the VirtualService. This can pose a security risk because it may be unexpected for the server response to contain different headers than those defined in the APIRule.
 

diff --git a/docs/release-notes/template.md b/docs/release-notes/template.md
@@ -1,7 +1,7 @@
-## New features
+## New Features
 
 - Some feature
 
-## Fixed bugs
+## Fixed Bugs
 
 - Some bug fix
diff --git a/docs/user/00-10-overview-api-gateway-controller.md b/docs/user/00-10-overview-api-gateway-controller.md
@@ -12,7 +12,7 @@ APIGateway Controller is part of Kyma API Gateway Operator. Its role is to manag
 
 The `apigateways.operator.kyma-project.io` CustomResourceDefinition (CRD) describes the APIGateway CR that is used to manage the API Gateway resources. To learn more, read the [APIGateway CR documentation](./custom-resources/apigateway/04-00-apigateway-custom-resource.md).
 
-## Status codes
+## Status Codes
 
 |     Code     | Description                              |
 |:------------:|:-----------------------------------------|

diff --git a/docs/user/00-20-overview-api-rule-controller.md b/docs/user/00-20-overview-api-rule-controller.md
@@ -4,15 +4,15 @@
 
 APIRule Controller is part of Kyma API Gateway Operator. It uses [Ory Oathkeeper](https://www.ory.sh/docs/oathkeeper) and [Istio Service Mesh](https://istio.io/) resources to expose and secure APIs.
 
-## APIRule CR
+## APIRule Custom Resource
 
-The `apirules.gateway.kyma-project.io` CustomResourceDefinition (CRD) describes the APIRule CR that is used to expose and secure APIs. To learn more, read the [APIRule CR documentation](./custom-resources/apirule/04-10-apirule-custom-resource.md).
+The `apirules.gateway.kyma-project.io` CustomResourceDefinition (CRD) describes the APIRule custom resource (CR) that is used to expose and secure APIs. To learn more, read the [APIRule CR documentation](./custom-resources/apirule/04-10-apirule-custom-resource.md).
 
 ## api-gateway-config ConfigMap
 
 The `api-gateway-config` ConfigMap contains the configuration of the JWT Handler. To learn more about how to [enable Istio the JWT handling](./custom-resources/apirule/04-20-apirule-istio-jwt-access-strategy.md).
 
-## Status codes
+## Status Codes
 
 The APIRule CR includes status information for all created sub-resources. However, the field **apiRuleStatus** specifically reflects the status of the controller's reconciliation.
 
@@ -23,7 +23,7 @@ The APIRule CR includes status information for all created sub-resources. Howeve
 | **ERROR**     | An error occurred during reconciliation.  |
 
 
-## Controller limitations
+## Controller Limitations
 
 APIRule Controller relies on Istio and Ory custom resources to provide routing capabilities. In terms of persistence, the controller depends only on APIRules stored in the Kubernetes cluster.
 In terms of the resource configuration, the following requirements are set on APIGateway Controller:

diff --git a/docs/user/README.md b/docs/user/README.md
@@ -1,6 +1,6 @@
-# API Gateway module
+# API Gateway Module
 
-## What is API Gateway?
+## What Is API Gateway?
 
 API Gateway provides functionalities that allow you to expose and secure APIs by using [Ory Oathkeeper](https://www.ory.sh/docs/oathkeeper) and the [Istio Service Mesh](https://istio.io/) resources.
 
@@ -15,7 +15,7 @@ Kyma API Gateway Operator is an extension to the Kyma runtime that manages the a
 
 You must enable the Istio module to be able to use the API Gateway module.
 
-## Useful links
+## Useful Links
 
 To learn how to use the API Gateway module, read the documentation in the [`user`](../user/) directory. It contains:
 - Overview documentation of [APIGateway Controller](./00-10-overview-api-gateway-controller.md) and [APIRule Controller](./00-20-overview-api-rule-controller.md)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Code of Conduct

		Each contributor and maintainer of this project agrees to follow the [community Code of Conduct](https://github.com/kyma-project/community/blob/main/docs/contributing/01-code-of-conduct.md) that relies on the CNCF Code of Conduct. Read it to learn about the agreed standards of behavior, shared values that govern our community, and details on how to report any suspected Code of Conduct violations.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Contributing

		To contribute to this project, follow the general [contributing](https://github.com/kyma-project/community/blob/main/docs/contributing/02-contributing.md) guidelines.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Copyright (c) 2018 SAP SE or an SAP affiliate company. All rights reserved.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Security Policy

		If you suspect you have found a security vulnerability in Kyma, please report it to us as described in the [SAP Open Source Security Policy](https://github.com/SAP/.github/blob/main/SECURITY.md).