From a1724d8d36c4c58dc1d638d70bca2e5754d390c9 Mon Sep 17 00:00:00 2001 From: Natalia Sitko <80401180+nataliasitko@users.noreply.github.com> Date: Tue, 2 Jan 2024 11:29:19 +0100 Subject: [PATCH] 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 * 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 Co-authored-by: Marek Kolodziejczak --- CODE_OF_CONDUCT.md | 3 + CONTRIBUTING.md | 3 + NOTICE.md | 1 + README.md | 25 +- SECURITY.md | 3 + docs/contributor/01-00-installation.md | 74 +++--- .../01-10-API-Gateway-CRD-proposal.md | 12 +- .../01-20-api-gateway-dependencies.md | 6 +- .../01-30-api-rule-dependencies.md | 2 +- docs/contributor/04-10-technical-design.md | 1 + docs/contributor/04-20-apirule-performance.md | 6 +- docs/contributor/04-30-ci-cd.md | 11 +- docs/contributor/04-40-cors-policy-design.md | 8 +- docs/release-notes/template.md | 4 +- .../00-10-overview-api-gateway-controller.md | 2 +- .../00-20-overview-api-rule-controller.md | 8 +- docs/user/README.md | 6 +- docs/user/_sidebar.md | 10 +- docs/user/custom-resources/README.md | 22 +- .../04-00-apigateway-custom-resource.md | 4 +- .../apigateway/04-10-kyma-gateway.md | 10 +- .../apigateway/04-20-oathkeeper.md | 2 +- .../apirule/04-10-apirule-custom-resource.md | 11 +- ...04-20-apirule-istio-jwt-access-strategy.md | 30 +-- ...30-apirule-jwt-ory-and-istio-comparison.md | 40 ++-- .../apirule/04-40-apirule-mutators.md | 38 +-- .../apirule/04-50-apirule-authorizations.md | 26 +- .../05-00-api-gateway-operator-parameters.md | 6 +- .../05-50-ory-limitations.md | 6 +- docs/user/technical-reference/README.md | 6 +- .../03-00-basic-diagnostics.md | 2 +- .../03-01-401-unauthorized-403-forbidden.md | 2 +- .../03-02-404-not-found.md | 12 +- .../03-03-500-server-error.md | 70 +++--- .../03-10-dns-mgt-connection-refused.md | 2 +- .../03-11-dns-mgt-could-not-resolve-host.md | 8 +- .../03-12-dns-mgt-resource-ignored.md | 2 +- .../03-10-dns-mgt/README.md | 8 +- .../03-20-cert-mgt-issuer-not-created.md | 8 +- .../03-30-gateway-not-reachable.md | 2 +- .../03-40-api-rule-troubleshooting.md | 12 +- .../03-50-certificates-gardener.md | 25 +- docs/user/troubleshooting-guides/README.md | 2 +- docs/user/tutorials/01-00-create-workload.md | 12 +- .../01-10-setup-custom-domain-for-workload.md | 162 ++++++------- .../tutorials/01-20-set-up-tls-gateway.md | 15 +- .../01-40-expose-workload-apigateway.md | 114 ++++----- .../01-41-expose-multiple-workloads.md | 164 ++++++------- ...42-expose-workloads-multiple-namespaces.md | 150 ++++++------ .../tutorials/01-40-expose-workload/README.md | 8 +- ...01-50-expose-and-secure-workload-oauth2.md | 226 ++++++++---------- .../01-51-get-jwt.md | 2 +- .../01-52-expose-and-secure-workload-jwt.md | 100 ++++---- .../01-53-expose-and-secure-workload-istio.md | 168 ++++++------- ...se-and-secure-workload-with-certificate.md | 12 +- .../README.md | 10 +- .../01-61-mtls-selfsign-client-certicate.md | 16 +- .../01-60-security/01-62-set-up-idp.md | 10 +- docs/user/tutorials/01-60-security/README.md | 4 +- docs/user/tutorials/README.md | 28 +-- hack/managed-kyma-migration/README.md | 22 +- performance_tests/Readme.md | 2 +- tests/integration/README.md | 16 +- tests/integration/scripts/README.md | 4 +- tests/ui/tests/README.md | 20 +- .../k3d-ci-kyma-dashboard-integration.sh | 2 +- 66 files changed, 855 insertions(+), 953 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 NOTICE.md create mode 100644 SECURITY.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..610c91058 --- /dev/null +++ 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. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..1306593c7 --- /dev/null +++ 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. \ No newline at end of file diff --git a/NOTICE.md b/NOTICE.md new file mode 100644 index 000000000..850cc7d78 --- /dev/null +++ b/NOTICE.md @@ -0,0 +1 @@ +Copyright (c) 2018 SAP SE or an SAP affiliate company. All rights reserved. \ No newline at end of file diff --git a/README.md b/README.md index 2f9277bca..3bfdd3893 100644 --- 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 + + +See the [Contributing](CONTRIBUTING.md) guidelines. + +## Code of Conduct + + +See the [Code of Conduct](CODE_OF_CONDUCT.md) document. + +## Licensing + -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. \ No newline at end of file diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..75b291449 --- /dev/null +++ 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). \ No newline at end of file diff --git a/docs/contributor/01-00-installation.md b/docs/contributor/01-00-installation.md index 2ec04d315..1d6132bf1 100644 --- 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. -
-
- - k3d - +
+
+ + k3d + - ```bash - k3d image import $IMG -c $K3D_CLUSTER_NAME - ``` + ```bash + k3d image import $IMG -c $K3D_CLUSTER_NAME + ``` -
-
- - Globally available Docker registry - +
+
+ + Globally available Docker registry + - ```bash - make docker-push - ``` + ```bash + make docker-push + ``` -
-
+
+
-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 + ``` \ No newline at end of file diff --git a/docs/contributor/01-10-API-Gateway-CRD-proposal.md b/docs/contributor/01-10-API-Gateway-CRD-proposal.md index 68ed744e9..7671686f8 100644 --- 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 index ceb11448c..83a847284 100644 --- 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. \ No newline at end of file diff --git a/docs/contributor/01-30-api-rule-dependencies.md b/docs/contributor/01-30-api-rule-dependencies.md index a05ce6f27..0062a2f12 100644 --- 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 index 9b31c3771..653c016d7 100644 --- 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 index bddd8e433..90d9bf2f8 100644 --- 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 index fa7bd25d9..0b21d0d4a 100644 --- 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,7 +68,7 @@ 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. @@ -75,7 +76,7 @@ The following CI jobs generate release artifacts. They are triggered on Git tag |---------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------| | [`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 index bc1577573..04561419c 100644 --- 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 index 25632b298..270e51f6c 100644 --- 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 \ No newline at end of file diff --git a/docs/user/00-10-overview-api-gateway-controller.md b/docs/user/00-10-overview-api-gateway-controller.md index 2e58573ea..0768eef50 100644 --- 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 index 22f658477..f1e65d41f 100644 --- 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 index b7c3b3406..b6cc95f0f 100644 --- 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) diff --git a/docs/user/_sidebar.md b/docs/user/_sidebar.md index f0edeb8ed..e3df4da1e 100644 --- a/docs/user/_sidebar.md +++ b/docs/user/_sidebar.md @@ -11,11 +11,11 @@ * [Expose Multiple Workloads](/api-gateway/user/tutorials/01-40-expose-workload/01-41-expose-multiple-workloads.md) * [Expose Workloads in Multiple Namespaces](/api-gateway/user/tutorials/01-40-expose-workload/01-42-expose-workloads-multiple-namespaces.md) * [Expose and Secure a Workload](/api-gateway/user/tutorials/01-50-expose-and-secure-a-workload/README.md) - * [Secure a Workload With OAuth2](/api-gateway/user/tutorials/01-50-expose-and-secure-a-workload/01-50-expose-and-secure-workload-oauth2.md) + * [Secure a Workload with OAuth2](/api-gateway/user/tutorials/01-50-expose-and-secure-a-workload/01-50-expose-and-secure-workload-oauth2.md) * [Get JSON Web Tokens (JWT)](/api-gateway/user/tutorials/01-50-expose-and-secure-a-workload/01-51-get-jwt.md) - * [Secure a Workload With JWT](/api-gateway/user/tutorials/01-50-expose-and-secure-a-workload/01-52-expose-and-secure-workload-jwt.md) - * [Secure a Workload With Istio](/api-gateway/user/tutorials/01-50-expose-and-secure-a-workload/01-53-expose-and-secure-workload-istio.md) - * [Secure a Workload With a Certificate](/api-gateway/user/tutorials/01-50-expose-and-secure-a-workload/01-54-expose-and-secure-workload-with-certificate.md) + * [Secure a Workload with JWT](/api-gateway/user/tutorials/01-50-expose-and-secure-a-workload/01-52-expose-and-secure-workload-jwt.md) + * [Secure a Workload with Istio](/api-gateway/user/tutorials/01-50-expose-and-secure-a-workload/01-53-expose-and-secure-workload-istio.md) + * [Secure a Workload with a Certificate](/api-gateway/user/tutorials/01-50-expose-and-secure-a-workload/01-54-expose-and-secure-workload-with-certificate.md) * [Security](/api-gateway/user/tutorials/01-60-security/README.md) * [Prepare Self-Signed Root CA and Client Certificates](/api-gateway/user/tutorials/01-60-security/01-61-mtls-selfsign-client-certicate.md) * [Set Up a Custom Identity Provider](/api-gateway/user/tutorials/01-60-security/01-62-set-up-idp.md) @@ -35,7 +35,7 @@ * [Certificate Issuer Not Created](/api-gateway/user/troubleshooting-guides/03-20-cert-mgt-issuer-not-created.md) * [Kyma Gateway Not Reachable](/api-gateway/user/troubleshooting-guides/03-30-gateway-not-reachable.md) * [Issues When Creating APIRule](/api-gateway/user/troubleshooting-guides/03-40-api-rule-troubleshooting.md) - * [Issues With Gardener Certificates](/api-gateway/user/troubleshooting-guides/03-50-certificates-gardener.md) + * [Issues with Gardener Certificates](/api-gateway/user/troubleshooting-guides/03-50-certificates-gardener.md) * [Cannot Connect to a Service](/api-gateway/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-00-basic-diagnostics.md) * [401 Unauthorized or 403 Forbidden](/api-gateway/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-01-401-unauthorized-403-forbidden.md) * [404 Not Found](/api-gateway/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-02-404-not-found.md) diff --git a/docs/user/custom-resources/README.md b/docs/user/custom-resources/README.md index 7c10283c0..01f1916c5 100644 --- a/docs/user/custom-resources/README.md +++ b/docs/user/custom-resources/README.md @@ -1,21 +1,21 @@ -# Custom resources +# Custom Resources -## APIGateway custom resource +## APIGateway Custom Resource -The `apigateways.operator.kyma-project.io` CRD describes the kind and the format of data that APIGateway Controller uses to configure the resources. +The `apigateways.operator.kyma-project.io` CustomResourceDefinition (CRD) describes the kind and the format of data that APIGateway Controller uses to configure the resources. -Browse the documentation related to the APIGateway CR: +Browse the documentation related to the APIGateway custom resource (CR): - [Specification of APIGateway CR](./apigateway/04-00-apigateway-custom-resource.md) - [Kyma Gateway](./apigateway/04-10-kyma-gateway.md) -- [Oathkeeper dependency](./apigateway/04-20-oathkeeper.md) +- [Oathkeeper Dependency](./apigateway/04-20-oathkeeper.md) -## APIRule custom resource +## APIRule Custom Resource -The `apirules.gateway.kyma-project.io` CustomResourceDefinition (CRD) describes the kind and the format of data the APIRule Controller uses to configure the resources. +The `apirules.gateway.kyma-project.io` CRD describes the kind and the format of data the APIRule Controller uses to configure the resources. -Browse the documentation related to the APIRule custom resource (CR): +Browse the documentation related to the APIRule CR: - [Specification of APIRule CR](./apirule/04-10-apirule-custom-resource.md) describing all primary parameters of APIRule CR -- [Istio JWT access strategy](./apirule/04-20-apirule-istio-jwt-access-strategy.md) that explains how to configure **rules.accessStrategies** for Istio JWT -- [Comparison of Ory Oathkeeper and Istio JWT access strategies](./apirule/04-30-apirule-jwt-ory-and-istio-comparison.md) +- [Istio JWT Access Strategy](./apirule/04-20-apirule-istio-jwt-access-strategy.md) that explains how to configure **rules.accessStrategies** for Istio JWT +- [Comparison of Ory Oathkeeper and Istio JWT Access Strategies](./apirule/04-30-apirule-jwt-ory-and-istio-comparison.md) - [APIRule Mutators](./apirule/04-40-apirule-mutators.md) -- [OAuth2 and JWT authorization](./apirule/04-50-apirule-authorizations.md) \ No newline at end of file +- [OAuth2 and JWT Authorization](./apirule/04-50-apirule-authorizations.md) \ No newline at end of file diff --git a/docs/user/custom-resources/apigateway/04-00-apigateway-custom-resource.md b/docs/user/custom-resources/apigateway/04-00-apigateway-custom-resource.md index 4315a0984..1f5b82ee8 100644 --- a/docs/user/custom-resources/apigateway/04-00-apigateway-custom-resource.md +++ b/docs/user/custom-resources/apigateway/04-00-apigateway-custom-resource.md @@ -1,4 +1,4 @@ -# APIGateway custom resource +# APIGateway Custom Resource The `apigateways.operator.kyma-project.io` CustomResourceDefinition (CRD) describes the kind and the format of data that APIGateway Controller uses to configure the API Gateway resources. Applying the custom resource (CR) triggers the installation of API Gateway resources, and deleting it triggers the uninstallation of those resources. The default CR has the name `default`. @@ -18,7 +18,7 @@ This table lists the parameters of the given resource together with their descri | Parameter | Type | Description | |-----------------------|----------|-------------------------------------------------------------------------------------------------------------------------| -| **enableKymaGateway** | **NO** | Specifies whether the default [Kyma Gateway](./04-10-kyma-gateway.md), named `kyma-gateway`, should be created in the `kyma-system` Namespace. | +| **enableKymaGateway** | **NO** | Specifies whether the default [Kyma Gateway](./04-10-kyma-gateway.md), named `kyma-gateway`, should be created in the `kyma-system` namespace. | **Status:** diff --git a/docs/user/custom-resources/apigateway/04-10-kyma-gateway.md b/docs/user/custom-resources/apigateway/04-10-kyma-gateway.md index b7ce7462c..7744525ed 100644 --- a/docs/user/custom-resources/apigateway/04-10-kyma-gateway.md +++ b/docs/user/custom-resources/apigateway/04-10-kyma-gateway.md @@ -1,23 +1,23 @@ # APIGateway Kyma Gateway -Kyma Gateway is an [Istio Gateway CR](https://istio.io/latest/docs/reference/config/networking/gateway/) named `kyma-gateway` that is located in the `kyma-system` Namespace. Istio Gateway describes which ports and protocols should be exposed for a particular domain. +Kyma Gateway is an [Istio Gateway CR](https://istio.io/latest/docs/reference/config/networking/gateway/) named `kyma-gateway` that is located in the `kyma-system` namespace. Istio Gateway describes which ports and protocols should be exposed for a particular domain. The configuration of Kyma Gateway varies depending on whether you use a managed SAP BTP, Kyma runtime cluster, or an open-source Kyma cluster. -## SAP BTP, Kyma runtime +## SAP BTP, Kyma Runtime In a managed SAP BTP, Kyma runtime cluster, Kyma Gateway uses the Gardener Shoot domain. For this domain, an Istio Gateway CR exposes the HTTPS port (`443`) and the HTTP port (`80`) with a redirect to port `443`. -Additionally, Istio Gateway uses a certificate managed by a [Gardener Certificate CR](https://gardener.cloud/docs/guides/networking/certificate-extension/#using-the-custom-certificate-resource). +Istio Gateway uses a certificate managed by a [Gardener Certificate CR](https://gardener.cloud/docs/guides/networking/certificate-extension/#using-the-custom-certificate-resource). The Gardener [DNSEntry CR](https://gardener.cloud/docs/guides/networking/dns-extension/#creating-a-dnsentry-resource-explicitly) creates a DNS record for the specified domain with the Istio Ingress Gateway Load Balancer Service as the target. Furthermore, an Istio Virtual Service is created, which exposes the Istio readiness endpoint at `healthz.{GARDENER_SHOOT_DOMAIN}/healthz/ready`. ![Kyma Gateway Resources Gardener](../../../assets/kyma-gateway-resources-gardener.svg) -## Open-source Kyma +## Open-Source Kyma In an open-source Kyma cluster, Kyma Gateway uses the domain `local.kyma.dev`. For this domain, an Istio Gateway CR exposes the HTTPS port (`443`) and the HTTP port (`80`) with a redirect to port `443`. Istio Gateway uses a default certificate for the domain `local.kyma.dev` that is valid until July 2030. Furthermore, an Istio Virtual Service is created, which exposes the Istio readiness endpoint at `healthz.local.kyma.dev/healthz/ready`. ![Kyma Gateway Resources Open Source](../../../assets/kyma-gateway-resources-os.svg) -## Disable or enable Kyma Gateway +## Disable or Enable Kyma Gateway By default, Kyma Gateway is enabled. You can disable it by removing the `enableKymaGateway` field in the [APIGateway CR](./04-00-apigateway-custom-resource.md) or setting it to `false`. Kyma Gateway can be disabled only if no APIRules are configured on the cluster. diff --git a/docs/user/custom-resources/apigateway/04-20-oathkeeper.md b/docs/user/custom-resources/apigateway/04-20-oathkeeper.md index 5582cfb32..dc1ac5feb 100644 --- a/docs/user/custom-resources/apigateway/04-20-oathkeeper.md +++ b/docs/user/custom-resources/apigateway/04-20-oathkeeper.md @@ -2,6 +2,6 @@ When you create the API Gateway custom resource, Ory Oathkeeper is automatically installed as a dependency. It is necessary to provide support for API Rules that use `accessStrategies` of types other than `allow`. -## Ory Oathkeeper configuration +## Ory Oathkeeper Configuration See the [resource configuration of Ory Oathkeeper](../../technical-reference/05-50-ory-limitations.md). diff --git a/docs/user/custom-resources/apirule/04-10-apirule-custom-resource.md b/docs/user/custom-resources/apirule/04-10-apirule-custom-resource.md index 2055b8c02..6ed6c9cb9 100644 --- a/docs/user/custom-resources/apirule/04-10-apirule-custom-resource.md +++ b/docs/user/custom-resources/apirule/04-10-apirule-custom-resource.md @@ -1,4 +1,4 @@ -# APIRule custom resource +# APIRule Custom Resource The `apirules.gateway.kyma-project.io` CustomResourceDefinition (CRD) describes the kind and the format of data the APIGateway Controller listens for. To get the up-to-date CRD in the `yaml` format, run the following command: @@ -7,7 +7,7 @@ APIGateway Controller listens for. To get the up-to-date CRD in the `yaml` forma kubectl get crd apirules.gateway.kyma-project.io -o yaml ``` -## Specification of APIRule custom resource +## Specification of APIRule Custom Resource This table lists all parameters of APIRule CRD together with their descriptions: @@ -25,7 +25,7 @@ This table lists all parameters of APIRule CRD together with their descriptions: | **corsPolicy.maxAge** | **NO** | Specifies the maximum age of CORS policy cache. The value is provided in the **Access-Control-Max-Age** CORS header. | | **host** | **YES** | Specifies the Service's communication address for inbound external traffic. If only the leftmost label is provided, the default domain name will be used. | | **service.name** | **NO** | Specifies the name of the exposed Service. | -| **service.namespace** | **NO** | Specifies the Namespace of the exposed Service. | +| **service.namespace** | **NO** | Specifies the namespace of the exposed Service. | | **service.port** | **NO** | Specifies the communication port of the exposed Service. | | **timeout** | **NO** | Specifies the timeout for HTTP requests in seconds for all Oathkeeper Access Rules. The value can be overridden for each Access Rule. The maximum timeout is limited to 3900 seconds (65 minutes).
If no timeout is specified, the default timeout of 180 seconds applies. | | **rules** | **YES** | Specifies the list of Oathkeeper Access Rules. | @@ -36,8 +36,7 @@ This table lists all parameters of APIRule CRD together with their descriptions: | **rules.accessStrategies** | **YES** | Specifies the list of access strategies. Supported are the [Oathkeeper's](https://www.ory.sh/docs/next/oathkeeper/pipeline/authn) `oauth2_introspection`, `jwt`, `noop` and `allow`. We also support `jwt` as [Istio](https://istio.io/latest/docs/tasks/security/authorization/authz-jwt/) access strategy. | | **rules.timeout** | **NO** | Specifies the timeout, in seconds, for HTTP requests made to **spec.rules.path**. The maximum timeout is limited to 3900 seconds (65 minutes). Timeout definitions set at this level take precedence over any timeout defined at the **spec.timeout** level. | -> **CAUTION:** If `service` is not defined at the **spec.service** level, all defined Access Rules must have `service` -> defined at **spec.rules.service** level. Otherwise, the validation fails. +> **CAUTION:** If `service` is not defined at the **spec.service** level, all defined Access Rules must have `service` defined at the **spec.rules.service** level. Otherwise, the validation fails. > **CAUTION:** Having both the Oathkeeper and Istio `jwt` access strategies defined is not supported. Access > strategies `noop` or `allow` cannot be used with any other access strategy on the same **spec.rules.path**. @@ -66,7 +65,7 @@ The following status codes describe VirtualServices and Oathkeeper Access Rules: | **SKIPPED** | Skipped creating a resource. | | **ERROR** | Resource not created. | -## Sample custom resource +## Sample Custom Resource This is a sample custom resource (CR) that the APIGateway Controller listens for to expose a Service. The following example has the **rules** section specified, which makes APIGateway Controller create an Oathkeeper Access Rule for the diff --git a/docs/user/custom-resources/apirule/04-20-apirule-istio-jwt-access-strategy.md b/docs/user/custom-resources/apirule/04-20-apirule-istio-jwt-access-strategy.md index 85aeef9d7..a79f7bb5b 100644 --- a/docs/user/custom-resources/apirule/04-20-apirule-istio-jwt-access-strategy.md +++ b/docs/user/custom-resources/apirule/04-20-apirule-istio-jwt-access-strategy.md @@ -1,4 +1,4 @@ -# JWT access strategy +# JWT Access Strategy To enable Istio JWT, run the following command: @@ -12,7 +12,7 @@ To enable Oathkeeper JWT, run the following command: kubectl patch configmap/api-gateway-config -n kyma-system --type merge -p '{"data":{"api-gateway-config":"jwtHandler: ory"}}' ``` -## Istio JWT configuration +## Istio JWT Configuration >**CAUTION:** Istio JWT is not a production-ready feature, and API might change. @@ -38,12 +38,15 @@ This table lists all the possible parameters of the Istio JWT access strategy to >**CAUTION:** Currently, we support only a single `fromHeader` or a single `fromParameter`. Specifying both of these fields for a JWT issuer is not supported. +### Authentications +Under the hood, an authentications array creates a corresponding [requestPrincipals](https://istio.io/latest/docs/reference/config/security/authorization-policy/#Source) array in the Istio's [Authorization Policy](https://istio.io/latest/docs/reference/config/security/authorization-policy/) resource. Every `requestPrincipals` string is formatted as `/*`. + +### Authorizations +The authorizations field is optional. When not defined, the authorization is satisfied if the JWT is valid. You can define multiple authorizations for an access strategy. The request is allowed if at least one of them is satisfied. + +The **requiredScopes** and **audiences** fields are optional. If **requiredScopes** is defined, the JWT must contain all the scopes in the `scp`, `scope`, or `scopes` claims to be authorized. If **audiences** is defined, the JWT has to contain all the audiences in the `aud` claim to be authorized. -
-
- - Example - +### Example In the following example, the APIRule has two defined Issuers. The first Issuer, called `ISSUER`, uses a JWT token extracted from the HTTP header. The header is named `X-JWT-Assertion` and has a prefix of `Kyma`. The second Issuer, called `ISSUER2`, uses a JWT token extracted from a URL parameter named `jwt-token`. **requiredScopes** defined in the **authorizations** field allow only for JWTs that have the claims `scp`, `scope`, or `scopes` with a value of `test`. Additionally, the JWTs must have an audience of either `example.com` or `example.org`. Alternatively, the JWTs can have the same claims with the `read` and `write` values. @@ -81,15 +84,4 @@ spec: - requiredScopes: ["test"] audiences: ["example.com", "example.org"] - requiredScopes: ["read", "write"] -``` - -
-
- -### Authentications -Under the hood, an authentications array creates a corresponding [requestPrincipals](https://istio.io/latest/docs/reference/config/security/authorization-policy/#Source) array in the Istio's [Authorization Policy](https://istio.io/latest/docs/reference/config/security/authorization-policy/) resource. Every `requestPrincipals` string is formatted as `/*`. - -### Authorizations -The authorizations field is optional. When not defined, the authorization is satisfied if the JWT is valid. You can define multiple authorizations for an access strategy. The request is allowed if at least one of them is satisfied. - -The **requiredScopes** and **audiences** fields are optional. If **requiredScopes** is defined, the JWT must contain all the scopes in the `scp`, `scope`, or `scopes` claims to be authorized. If **audiences** is defined, the JWT has to contain all the audiences in the `aud` claim to be authorized. \ No newline at end of file +``` \ No newline at end of file diff --git a/docs/user/custom-resources/apirule/04-30-apirule-jwt-ory-and-istio-comparison.md b/docs/user/custom-resources/apirule/04-30-apirule-jwt-ory-and-istio-comparison.md index bdb57e235..df2a16567 100644 --- a/docs/user/custom-resources/apirule/04-30-apirule-jwt-ory-and-istio-comparison.md +++ b/docs/user/custom-resources/apirule/04-30-apirule-jwt-ory-and-istio-comparison.md @@ -1,8 +1,8 @@ -# Differences between Ory Oathkeeper and Istio JWT access strategies +# Differences Between Ory Oathkeeper and Istio JWT Access Strategies We are in the process of transitioning from Ory Oathkeeper to Istio JWT access strategy. This document explains the differences between those two strategies and compares their configuration. -## Corresponding JWT configuration properties in Ory Oathkeeper and Istio +## Corresponding JWT Configuration Properties in Ory Oathkeeper and Istio This table lists all possible configuration properties of the Ory Oathkeeper JWT access strategy and their corresponding properties in Istio: @@ -20,17 +20,14 @@ This table lists all possible configuration properties of the Ory Oathkeeper JWT | **jwks_ttl** | **NO** | → | *Not Supported* | **-** | | **allowed_algorithms** | **NO** | → | *Not Supported* | **-** | -## Examplary APIRule custom resources +## Examplary APIRule Custom Resources >**CAUTION:** Istio JWT is **not** a production-ready feature, and API might change. These are sample APIRule custom resources (CRs) of both Ory Oathkeeper and Istio JWT access strategy configuration for a Service. -
-
- - Ory Oathkeeper - + +#### Ory Oathkeeper ```yaml apiVersion: gateway.kyma-project.io/v1beta1 @@ -65,12 +62,7 @@ spec: token_from: header: X-JWT-Assertion ``` - -
-
- - Istio - +#### Istio ```yaml apiVersion: gateway.kyma-project.io/v1beta1 @@ -107,9 +99,7 @@ spec: audiences: ["example.com", "example.org"] - requiredScopes: ["read", "write"] ``` - -
-
+ >**CAUTION:** Both `jwks_urls` and `trusted_issuers` must be valid URLs. Although HTTP is allowed, it is recommended that you use only HTTPS endpoints. @@ -117,30 +107,30 @@ spec: >**CAUTION:** We support only a single `fromHeader` or a single `fromParameter` for a JWT issuer. -## How Istio JWT access strategy differs from Ory Oathkeeper JWT access strategy +## How Istio JWT Access Strategy Differs from Ory Oathkeeper JWT Access Strategy -### Configuration of properties handling in Ory Oathkeeper and Istio resources +### Configuration of Properties Handling in Ory Oathkeeper and Istio Resources When you use Ory Oathkeeper, the APIRule JWT access strategy configuration is translated directly as [authenticator configuration](https://www.ory.sh/docs/oathkeeper/api-access-rules#handler-configuration) in the [Ory Oathkeeper Access Rule CR](https://www.ory.sh/docs/oathkeeper/api-access-rules). See the official Ory Oathkeeper [JWT authenticator documentation](https://www.ory.sh/docs/oathkeeper/pipeline/authn#jwt) to learn more. With Istio JWT access strategy, for each `authentications` entry, an Istio's [Request Authentication](https://istio.io/latest/docs/reference/config/security/request_authentication/) resource is created, and for each `authorizations` entry, an [Authorization Policy](https://istio.io/latest/docs/reference/config/security/authorization-policy/) resource is created. -### Header support +### Header Support Istio JWT access strategy only supports `header` and `cookie` mutators. Learn more about [supported mutators](./04-40-apirule-mutators.md). -### Regex type of path matching +### Regex Type of Path Matching Istio doesn't support regex type of path matching in Authorization Policies. Ory Oathkeeper Access Rules and Virtual Service do support this feature. -### Configuring a JWT token from `cookie` +### Configuring a JWT Token from `cookie` Istio doesn't support configuring a JWT token from `cookie`, and Ory Oathkeeper does. Istio supports only `fromHeaders` and `fromParams` configurations. -### Workload in the service mesh +### Workload in the Service Mesh Using Istio as JWT access strategy requires the workload behind the Service to be in the service mesh, for example, to have the Istio proxy injected. Learn how to [add workloads to the Istio service mesh](https://istio.io/latest/docs/ops/common-problems/injection/). -### Change of status `401` to `403` when calling an endpoint without the `Authorization` header +### Change of Status `401` to `403` When Calling an Endpoint Without the `Authorization` Header Previously, when using ORY Oathkeeper, if you called a secured workload without a JWT token, it resulted in the `401` error. This behavior has changed with the implementation of Istio-based JWT. Now, calls made without a token result in the `403` error. To learn more, read the Istio documentation on [RequestAuthentication](https://istio.io/latest/docs/concepts/security/#request-authentication) and [AuthorizationPolicy](https://istio.io/latest/docs/reference/config/security/authorization-policy). -### Blocking of in-cluster connectivity to an endpoint +### Blocking of In-Cluster Connectivity to an Endpoint Istio JWT uses the `istio-sidecar` container to validate requests in the context of the target Pod. Previously, in-cluster requests were allowed in the `ory-oathkeeper` context because request validation happened within the `ory-oathkeeper` Pod. Now, these requests fail unless they are explicitly permitted. diff --git a/docs/user/custom-resources/apirule/04-40-apirule-mutators.md b/docs/user/custom-resources/apirule/04-40-apirule-mutators.md index 1bda6c7c8..13559353e 100644 --- a/docs/user/custom-resources/apirule/04-40-apirule-mutators.md +++ b/docs/user/custom-resources/apirule/04-40-apirule-mutators.md @@ -1,4 +1,4 @@ -# APIRule mutators +# APIRule Mutators You can use mutators to enrich an incoming request with information. Different types of mutators are supported depending on the access strategy you use: @@ -11,17 +11,13 @@ You can use mutators to enrich an incoming request with information. Different t This document explains and provides examples of Istio mutators compatible with the JWT access strategy. Additionally, it explores the possibility of using Oathkeeper mutators with Istio and provides guidance on configuring them. -## Istio mutators +## Istio Mutators The `cookie` and `header` mutators are supported in combination with the JWT access strategy. You are allowed to configure multiple mutators for one APIRule, but only one mutator of each type is allowed. -### Header mutator +### Header Mutator The headers are defined in the **headers** field of the header mutator configuration. The keys represent the names of the headers, and each value is a string. You can use [Envoy command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) in the header value to perform operations such as copying an incoming header to a new one. The configured headers are applied to the request. They overwrite any existing headers with the same name. -
-
- - Example - +#### Example In the following example, two different headers are configured: **X-Custom-Auth**, which uses the incoming Authorization header as a value, and **X-Some-Data** with the value `some-data`. @@ -54,17 +50,10 @@ spec: jwksUri: $JWKS_URI ``` -
-
- -### Cookie mutator +### Cookie Mutator To configure cookies, use the **cookies** mutator configuration field. The keys represent the names of the cookies, and each value is a string. As the cookie value, you can use [Envoy command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators). The configured cookies are set as the `cookie` header in the request and overwrite any existing cookies. -
-
- - Example - +#### Example The following APIRule example has a new cookie added with the name `some-data` and the value `data`. @@ -96,16 +85,13 @@ spec: jwksUri: $JWKS_URI ``` -
-
- -## Support for Ory Oathkeeper mutators with Istio +## Support for Ory Oathkeeper Mutators with Istio -### Templating support +### Templating Support The Ory Access Rules have support for templating in mutators. Simple cases can be implemented with the help of EnvoyFilter, such as the one presented in [id-token-envoyfilter](id-token-envoyfilter) directory. -### Header mutator +### Header Mutator To handle the `header` type mutator in Istio, you can use the VirtualService [HeaderOperations](https://istio.io/latest/docs/reference/config/networking/virtual-service/#Headers-HeaderOperations). HeaderOperations only allow you to add static data. However, [Ory Headers Mutator](https://www.ory.sh/docs/oathkeeper/pipeline/mutator#headers) supports templating, which receives the current AuthenticationSession. To support similar capabilities in Istio, you must use [EnvoyFilter](https://istio.io/latest/docs/reference/config/networking/envoy-filter/). @@ -132,7 +118,7 @@ spec: X-Some-Arbitrary-Data: "test" ``` -### Cookie mutator +### Cookie Mutator The mutator of type `cookie` can be handled the same as the `header` mutator with Istio using Virtual Service HeaderOperations. Like with the `header` mutator, Istio has the limitation of only allowing static data. However, the [Ory cookie mutator](https://www.ory.sh/docs/oathkeeper/pipeline/mutator#cookie) supports templating. @@ -159,11 +145,11 @@ spec: Cookie: "user=test" ``` -### Id_token mutator +### Id_token Mutator The functionality of the `id_token` mutator cannot be supported because it would require a mechanism for encoding and signing the response from the OAuth2 server, such as Ory Hydra, into a JWT. Additionally, the JWKS used for signing this JWT is deployed as the `ory-oathkeeper-jwks-secret` Secret, which would have to be fetched in the implementation context or mounted into the component responsible for the encoding. -### Hydrator mutator +### Hydrator Mutator Support for the Hydrator token would require to call external APIs in the context of the Istio proxy. This mutator also influences other mutators as it runs before them and supplies them with the outcome of its execution. diff --git a/docs/user/custom-resources/apirule/04-50-apirule-authorizations.md b/docs/user/custom-resources/apirule/04-50-apirule-authorizations.md index a758c4e28..49cff118f 100644 --- a/docs/user/custom-resources/apirule/04-50-apirule-authorizations.md +++ b/docs/user/custom-resources/apirule/04-50-apirule-authorizations.md @@ -18,12 +18,8 @@ Alternatively, you can set the **token_from.location** parameter to `query_param See these sample excerpts from APIRule custom resources that show the **rules** attribute for Services secured with OAuth2, JWT, and an OAuth2 and JWT combination. - -
-
- - OAuth2 - + +#### OAuth2 ```yaml rules: @@ -36,12 +32,7 @@ See these sample excerpts from APIRule custom resources that show the **rules** required_scope: ["read"] ``` - -
-
- - JWT - +#### JWT ```yaml rules: @@ -55,11 +46,7 @@ See these sample excerpts from APIRule custom resources that show the **rules** - {issuer URL of your custom OpenID Connect-compliant identity provider} ``` -
-
- - OAuth2 and JWT - +#### OAuth2 and JWT ```yaml rules: @@ -77,7 +64,4 @@ See these sample excerpts from APIRule custom resources that show the **rules** token_from: header: ID-Token ``` - -
- -
\ No newline at end of file + \ No newline at end of file diff --git a/docs/user/technical-reference/05-00-api-gateway-operator-parameters.md b/docs/user/technical-reference/05-00-api-gateway-operator-parameters.md index c30c0e430..0443f490e 100644 --- a/docs/user/technical-reference/05-00-api-gateway-operator-parameters.md +++ b/docs/user/technical-reference/05-00-api-gateway-operator-parameters.md @@ -1,8 +1,8 @@ -# Kyma API Gateway Operator parameters +# Kyma API Gateway Operator Parameters You can configure [APIGateway Controller](../00-10-overview-api-gateway-controller.md) and [APIRule Controller](../00-20-overview-api-rule-controller.md) using various parameters. This document contains all the options. -## Reconciliation interval +## Reconciliation Interval ### APIGateway Kyma API Gateway Operator reconciles the APIGateway custom resource every 10 hours or whenever it is changed. @@ -10,7 +10,7 @@ Kyma API Gateway Operator reconciles the APIGateway custom resource every 10 hou ### APIRule By default, Kyma API Gateway Operator reconciles APIRules every 60 minutes or whenever the APIRule is changed. You can adjust this interval by modifying the operator's parameters. For example, you can set the **-reconciliation-interval** parameter to `120s`. -## All configuration parameters +## All Configuration Parameters | Name | Required | Description | Example values | |-------------------------------|:--------:|-----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------| diff --git a/docs/user/technical-reference/05-50-ory-limitations.md b/docs/user/technical-reference/05-50-ory-limitations.md index f3f56037a..1d8ebab6f 100644 --- a/docs/user/technical-reference/05-50-ory-limitations.md +++ b/docs/user/technical-reference/05-50-ory-limitations.md @@ -1,6 +1,6 @@ -# Ory limitations +# Ory Limitations -## Resource configuration +## Resource Configuration The resources of the Ory components are configured differently based on the size of the cluster. Smaller clusters are defined as having less than 5 CPU capability or less than 10 Gi of memory capability, while larger clusters exceed these values. The default configuration for larger clusters includes the following settings for the Ory components' resources: @@ -22,7 +22,7 @@ The default configuration for smaller clusters includes the following settings f | Oathkeeper Maester | Requests | 10m | 20Mi | -## Autoscaling configuration +## Autoscaling Configuration The default configuration in terms of autoscaling of Ory components is as follows: diff --git a/docs/user/technical-reference/README.md b/docs/user/technical-reference/README.md index e4f59e43f..2f6e93388 100644 --- a/docs/user/technical-reference/README.md +++ b/docs/user/technical-reference/README.md @@ -1,7 +1,7 @@ -# Technical reference +# Technical Reference In this section, you can find the technical reference documents that might come in handy when using the API Gateway module: -- [Kyma API Gateway Operator parameters](./05-00-api-gateway-operator-parameters.md) -- [Ory limitations](./05-50-ory-limitations.md) +- [Kyma API Gateway Operator Parameters](./05-00-api-gateway-operator-parameters.md) +- [Ory Limitations](./05-50-ory-limitations.md) Learn more about [APIGateway and APIRule custom resources](../custom-resources/README.md). \ No newline at end of file diff --git a/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-00-basic-diagnostics.md b/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-00-basic-diagnostics.md index 731f3be99..f50ae93ac 100644 --- a/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-00-basic-diagnostics.md +++ b/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-00-basic-diagnostics.md @@ -1,4 +1,4 @@ -# Cannot connect to a Service exposed by an APIRule - basic diagnostics +# Cannot Connect to a Service Exposed by an APIRule - Basic Diagnostics API Gateway is a Kubernetes controller, which operates on APIRule custom resources (CRs). To diagnose problems, inspect the [`status` code](../../custom-resources/apirule/04-10-apirule-custom-resource.md) of the APIRule CR: diff --git a/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-01-401-unauthorized-403-forbidden.md b/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-01-401-unauthorized-403-forbidden.md index db0572611..6c16e144a 100644 --- a/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-01-401-unauthorized-403-forbidden.md +++ b/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-01-401-unauthorized-403-forbidden.md @@ -32,7 +32,7 @@ Make sure that you are using an access token with proper scopes, and it is activ 3. Generate a [new JWT](../../tutorials/01-50-expose-and-secure-a-workload/01-51-get-jwt.md) if needed. -### Opaque access token +### Opaque Access Token 1. Export the credentials of your Oauth2 client as environment variables: diff --git a/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-02-404-not-found.md b/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-02-404-not-found.md index b060bde3a..e3cc65b8d 100644 --- a/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-02-404-not-found.md +++ b/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-02-404-not-found.md @@ -40,15 +40,15 @@ If you suspect you are experiencing an issue caused by the Oathkeeper Maester co 2. Fetch the Access Rules from every Oathkeeper Pod and save them to a file: ```bash - kubectl cp -n kyma-system -c oathkeeper "{POD_NAME}":etc/rules/access-rules.json "access-rules.{POD_NAME}.json" - ``` + kubectl cp -n kyma-system -c oathkeeper "{POD_NAME}":etc/rules/access-rules.json "access-rules.{POD_NAME}.json" + ``` 3. If you have more than one instance of Oathkeeper, compare whether the files contain the same Access Rules. Because Oathkeeper stores Access Rules as JSON files, you can use [jd](https://github.com/josephburnett/jd) to automate the comparison: - ```bash - jd -set {FIRST_FILE} {SECOND_FILE} - ``` + ```bash + jd -set {FIRST_FILE} {SECOND_FILE} + ``` - The files are considered different by jd if there are any differences between the files other than the order of Access Rules. + The files are considered different by jd if there are any differences between the files other than the order of Access Rules. 4. Compare Access Rules in the files with those present in the cluster. If the files are different, Oathkeeper Pods are out of sync. diff --git a/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-03-500-server-error.md b/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-03-500-server-error.md index 847264139..93a71129d 100644 --- a/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-03-500-server-error.md +++ b/docs/user/troubleshooting-guides/03-00-cannot-connect-to-service/03-03-500-server-error.md @@ -4,36 +4,36 @@ You have a deployed APIRule that looks similar to the following one: - ```bash - apiVersion: gateway.kyma-project.io/v1beta1 - kind: APIRule - metadata: - name: sample-apirule - namespace: $NAMESPACE - spec: - gateway: kyma-system/kyma-gateway - host: httpbin.$DOMAIN - service: - name: httpbin - port: 8000 - rules: - - path: /.* - methods: ["GET"] - accessStrategies: - - handler: noop - - path: /headers - methods: ["GET"] - accessStrategies: - - handler: oauth2_introspection - config: - required_scope: ["read"] - ``` +```bash +apiVersion: gateway.kyma-project.io/v1beta1 +kind: APIRule +metadata: + name: sample-apirule + namespace: $NAMESPACE +spec: + gateway: kyma-system/kyma-gateway + host: httpbin.$DOMAIN + service: + name: httpbin + port: 8000 + rules: + - path: /.* + methods: ["GET"] + accessStrategies: + - handler: noop + - path: /headers + methods: ["GET"] + accessStrategies: + - handler: oauth2_introspection + config: + required_scope: ["read"] +``` The APIRule is configured under one host URL with the `/*` wildcard, the specific `/headers` path, and the same `GET` methods, which use different handlers. When you try to reach your Service, you get the `500 Internal Server Error` response: - ```bash - {"error":{"code":500,"status":"Internal Server Error","request":"e84400db-16b3-4818-9370-f10a6b4f3876","message":"An internal server error occurred, please contact the system administrator"}} - ``` +```bash +{"error":{"code":500,"status":"Internal Server Error","request":"e84400db-16b3-4818-9370-f10a6b4f3876","message":"An internal server error occurred, please contact the system administrator"}} +``` ## Cause @@ -46,7 +46,7 @@ To resolve the issue, follow these guidelines: - Set different hosts for different access strategies: - ```bash + ```bash apiVersion: gateway.kyma-project.io/v1beta1 kind: APIRule metadata: @@ -63,9 +63,9 @@ To resolve the issue, follow these guidelines: methods: ["GET"] accessStrategies: - handler: noop - ``` + ``` - ```bash + ```bash apiVersion: gateway.kyma-project.io/v1beta1 kind: APIRule metadata: @@ -84,11 +84,11 @@ To resolve the issue, follow these guidelines: - handler: oauth2_introspection config: required_scope: ["read"] - ``` + ``` - Set different methods for the specified paths: - ```bash + ```bash apiVersion: gateway.kyma-project.io/v1beta1 kind: APIRule metadata: @@ -111,7 +111,7 @@ To resolve the issue, follow these guidelines: - handler: oauth2_introspection config: required_scope: ["read"] - ``` + ``` When Oathkeeper throws the `503 Service Unavailable` or `502 Bad Gateway` responses, try to restart the Pod in order to resolve the issue. If you want to investigate what caused the error, follow these steps: @@ -126,10 +126,10 @@ When Oathkeeper throws the `503 Service Unavailable` or `502 Bad Gateway` respon ```bash kubectl top pods -n kyma-system -l app.kubernetes.io/name=oathkeeper - ``` + ``` 3. Access the logs to check for other Oathkeeper errors: ```bash kubectl logs -n kyma-system -l app.kubernetes.io/name=oathkeeper -c oathkeeper - ``` + ``` diff --git a/docs/user/troubleshooting-guides/03-10-dns-mgt/03-10-dns-mgt-connection-refused.md b/docs/user/troubleshooting-guides/03-10-dns-mgt/03-10-dns-mgt-connection-refused.md index 3a2bed7a2..0dec86a02 100644 --- a/docs/user/troubleshooting-guides/03-10-dns-mgt/03-10-dns-mgt-connection-refused.md +++ b/docs/user/troubleshooting-guides/03-10-dns-mgt/03-10-dns-mgt-connection-refused.md @@ -1,4 +1,4 @@ -# Connection refused or timeout +# Connection Refused or Timeout ## Symptom diff --git a/docs/user/troubleshooting-guides/03-10-dns-mgt/03-11-dns-mgt-could-not-resolve-host.md b/docs/user/troubleshooting-guides/03-10-dns-mgt/03-11-dns-mgt-could-not-resolve-host.md index a2ae9ee48..186fb14a2 100644 --- a/docs/user/troubleshooting-guides/03-10-dns-mgt/03-11-dns-mgt-could-not-resolve-host.md +++ b/docs/user/troubleshooting-guides/03-10-dns-mgt/03-11-dns-mgt-could-not-resolve-host.md @@ -1,4 +1,4 @@ -# Could not resolve host +# Could Not Resolve Host ## Symptom @@ -20,9 +20,9 @@ The error could result from: - Wait for the DNSEntry custom resource to be created. Check if it has the `Ready` status using the following command: -```bash -kubectl get dnsentry.dns.gardener.cloud dns-entry -``` + ```bash + kubectl get dnsentry.dns.gardener.cloud dns-entry + ``` - Turn the VPN off. diff --git a/docs/user/troubleshooting-guides/03-10-dns-mgt/03-12-dns-mgt-resource-ignored.md b/docs/user/troubleshooting-guides/03-10-dns-mgt/03-12-dns-mgt-resource-ignored.md index 5624a8ead..1236776ca 100644 --- a/docs/user/troubleshooting-guides/03-10-dns-mgt/03-12-dns-mgt-resource-ignored.md +++ b/docs/user/troubleshooting-guides/03-10-dns-mgt/03-12-dns-mgt-resource-ignored.md @@ -1,4 +1,4 @@ -# Resource ignored by the controller +# Resource Ignored by the Controller ## Symptom diff --git a/docs/user/troubleshooting-guides/03-10-dns-mgt/README.md b/docs/user/troubleshooting-guides/03-10-dns-mgt/README.md index ca1fef738..24d1bfb6b 100644 --- a/docs/user/troubleshooting-guides/03-10-dns-mgt/README.md +++ b/docs/user/troubleshooting-guides/03-10-dns-mgt/README.md @@ -1,7 +1,7 @@ -# Troubleshooting guides - DNS management +# Troubleshooting Guides - DNS Management Browse the API Gateway troubleshooting guides related to DNS management: -- [Connection refused or timeout](./03-10-dns-mgt-connection-refused.md) -- [Could not resolve host](./03-11-dns-mgt-could-not-resolve-host.md) -- [Resource ignored by the controller](./03-12-dns-mgt-resource-ignored.md) \ No newline at end of file +- [Connection Refused or Timeout](./03-10-dns-mgt-connection-refused.md) +- [Could Not Resolve Host](./03-11-dns-mgt-could-not-resolve-host.md) +- [Resource Ignored by the Controller](./03-12-dns-mgt-resource-ignored.md) \ No newline at end of file diff --git a/docs/user/troubleshooting-guides/03-20-cert-mgt-issuer-not-created.md b/docs/user/troubleshooting-guides/03-20-cert-mgt-issuer-not-created.md index 6b4a255ab..03fe6d534 100644 --- a/docs/user/troubleshooting-guides/03-20-cert-mgt-issuer-not-created.md +++ b/docs/user/troubleshooting-guides/03-20-cert-mgt-issuer-not-created.md @@ -1,4 +1,4 @@ -# Certificate management - Issuer not created +# Certificate Management - Issuer Not Created ## Symptom @@ -6,14 +6,14 @@ When you try to create an Issuer custom resource (CR) using `cert.gardener.cloud ## Cause -The Namespace in which the Issuer CR was created is incorrect. By default, `cert-management` watches the `default` Namespace for all Issuer CRs. +The namespace in which the Issuer CR was created is incorrect. By default, `cert-management` watches the `default` namespace for all Issuer CRs. ## Remedy -Make sure that you created the Issuer CR in the `default` Namespace. Run: +Make sure that you created the Issuer CR in the `default` namespace. Run: ```bash kubectl get issuers -A ``` -If you want to create the Issuer CR in a different Namespace, adjust the `cert-management` settings during the installation. +If you want to create the Issuer CR in a different namespace, adjust the `cert-management` settings during the installation. diff --git a/docs/user/troubleshooting-guides/03-30-gateway-not-reachable.md b/docs/user/troubleshooting-guides/03-30-gateway-not-reachable.md index f07d13836..4dbac9bdf 100644 --- a/docs/user/troubleshooting-guides/03-30-gateway-not-reachable.md +++ b/docs/user/troubleshooting-guides/03-30-gateway-not-reachable.md @@ -1,4 +1,4 @@ -# Kyma Gateway - not reachable +# Kyma Gateway - Not Reachable ## Symptom diff --git a/docs/user/troubleshooting-guides/03-40-api-rule-troubleshooting.md b/docs/user/troubleshooting-guides/03-40-api-rule-troubleshooting.md index 536ee6906..38c405a8d 100644 --- a/docs/user/troubleshooting-guides/03-40-api-rule-troubleshooting.md +++ b/docs/user/troubleshooting-guides/03-40-api-rule-troubleshooting.md @@ -1,4 +1,4 @@ -# Issues when creating an APIRule - various reasons +# Issues When Creating an APIRule - Various Reasons ## Symptom @@ -18,7 +18,7 @@ To check the error message of the APIRule resource, run: kubectl get apirule -n -o=jsonpath='{.status.APIRuleStatus}' ``` --- -## JWT handler's **trusted_issuers** configuration is missing +## JWT Handler's **trusted_issuers** Configuration Is Missing ### Cause The following APIRule is missing the **trusted_issuers** configuration for the JWT handler: @@ -55,7 +55,7 @@ spec: trusted_issuers: ["https://dev.kyma.local"] ``` --- -## Invalid **trusted_issuers** for the JWT handler +## Invalid **trusted_issuers** for the JWT Handler ### Cause Here's an example of an APIRule with the **trusted_issuers** URL configured: @@ -100,7 +100,7 @@ spec: trusted_issuers: ["https://dev.kyma.local"] ``` --- -## Unsupported handlers' combination +## Unsupported Handlers' Combination ### Cause The following APIRule has both `allow` and `jwt` handlers defined on the same path: @@ -129,7 +129,7 @@ The handlers' combination in the above example is not supported. If an APIRule h Decide on one configuration you want to use. You can either `allow` access to the specific path or restrict it using the JWT security token. Defining both configuration methods on the same path is not allowed. --- -## Occupied host +## Occupied Host ### Cause The following APIRules use the same host: @@ -158,7 +158,7 @@ spec: ``` --- -## Configuration of `noop` and `allow` handlers +## Configuration of `noop` and `allow` Handlers ### Cause In the following APIRule, the `noop` handler has the **trusted-issuers** field configured: diff --git a/docs/user/troubleshooting-guides/03-50-certificates-gardener.md b/docs/user/troubleshooting-guides/03-50-certificates-gardener.md index 82311ec41..ca2bb3672 100644 --- a/docs/user/troubleshooting-guides/03-50-certificates-gardener.md +++ b/docs/user/troubleshooting-guides/03-50-certificates-gardener.md @@ -1,4 +1,4 @@ -# Issues with certificates on Gardener +# Issues with Certificates on Gardener ## Symptom & Cause @@ -28,30 +28,23 @@ If any of these issues appears, follow these steps: The result describes the reason for the failure of issuing a domain SSL certificate. Depending on the moment when the error occurred, you can perform different actions. -
-
- - Error during the installation - + +#### Error During the Installation 1. Make sure the provided domain name is proper and meets the Gardener requirements. -2. Check if the `istio-ingressgateway` Service in the `istio-system` Namespace contains proper annotations: +2. Check if the `istio-ingressgateway` Service in the `istio-system` namespace contains proper annotations: ```yaml dns.gardener.cloud/class=garden dns.gardener.cloud/dnsnames=*.{DOMAIN} ``` -
-
- - Error after the installation - +#### Error After the Installation You can create a new Certificate resource applying suggestions from the error message to request a new domain SSL certificate. Follow these steps: -1. Make sure the Secret connected to the Certificate resource is not present on the cluster. To find its name and Namespace, run: +1. Make sure the Secret connected to the Certificate resource is not present on the cluster. To find its name and namespace, run: ```bash kubectl get certificates -n {CERTIFICATE_NAMESPACE} {CERTIFICATE_NAME} -o jsonpath='{ .spec.secretRef }' @@ -59,7 +52,5 @@ You can create a new Certificate resource applying suggestions from the error me 2. Delete the incorrect Certificate from the cluster. -3. Apply the fixed Certificate. - -
-
+3. Apply the fixed Certificate. + \ No newline at end of file diff --git a/docs/user/troubleshooting-guides/README.md b/docs/user/troubleshooting-guides/README.md index f43803b12..8444d0481 100644 --- a/docs/user/troubleshooting-guides/README.md +++ b/docs/user/troubleshooting-guides/README.md @@ -1,4 +1,4 @@ -# Troubleshooting guides +# Troubleshooting Guides The troubleshooting section aims to identify the most common recurring problems the users face when they expose APIs, as well as the most suitable solutions to these problems. diff --git a/docs/user/tutorials/01-00-create-workload.md b/docs/user/tutorials/01-00-create-workload.md index d83731ac5..e72d6f2c3 100644 --- a/docs/user/tutorials/01-00-create-workload.md +++ b/docs/user/tutorials/01-00-create-workload.md @@ -1,10 +1,10 @@ -# Create a workload +# Create a Workload -This tutorial explains how to create a sample HttpBin Service deployment. +This tutorial explains how to create a sample HTTPBin Service deployment. ## Steps -1. Create a Namespace and export its value as an environment variable. Run: +1. Create a namespace and export its value as an environment variable. Run: ```bash export NAMESPACE={NAMESPACE_NAME} @@ -12,13 +12,13 @@ This tutorial explains how to create a sample HttpBin Service deployment. kubectl label namespace $NAMESPACE istio-injection=enabled --overwrite ``` -2. Choose a name for your HttpBin Service instance and export it as an environment variable. +2. Choose a name for your HTTPBin Service instance and export it as an environment variable. ```bash export SERVICE_NAME={SERVICE_NAME} ``` -3. Deploy a sample instance of the HttpBin Service. +3. Deploy a sample instance of the HTTPBin Service. ```shell cat <**NOTE:** As `SPEC_TYPE`, use the relevant provider type. The `DOMAIN_NAME` value specifies the name of a domain that you own, for example, `mydomain.com`. + * Export the following values as environment variables. + >**NOTE:** As `SPEC_TYPE`, use the relevant provider type. The `DOMAIN_NAME` value specifies the name of a domain that you own, for example, `mydomain.com`. - ```bash - export SPEC_TYPE={PROVIDER_TYPE} - export DOMAIN_TO_EXPOSE_WORKLOADS={DOMAIN_NAME} - ```` + ```bash + export SPEC_TYPE={PROVIDER_TYPE} + export DOMAIN_TO_EXPOSE_WORKLOADS={DOMAIN_NAME} + ```` - * To create a DNSProvider CR, run: - - ```bash - cat <**NOTE:** For some cluster providers you need to replace the `ip` with the `hostname`, for example, in AWS, set `jsonpath='{.status.loadBalancer.ingress[0].hostname}'`. - - * To create a DNSEntry CR, run: - - ```bash - cat <**NOTE:** For some cluster providers you need to replace the `ip` with the `hostname`, for example, in AWS, set `jsonpath='{.status.loadBalancer.ingress[0].hostname}'`. + + * To create a DNSEntry CR, run: + + ```bash + cat <**NOTE:** `TLS_SECRET` is the name of the TLS Secret, for example, `httpbin-tls-credentials`. + >**NOTE:** `TLS_SECRET` is the name of the TLS Secret, for example, `httpbin-tls-credentials`. - ```bash - export TLS_SECRET={TLS_SECRET_NAME} - ``` + ```bash + export TLS_SECRET={TLS_SECRET_NAME} + ``` - * To create a Certificate CR, run: + * To create a Certificate CR, run: - ```bash - cat <**NOTE:** While using the default configuration, certificates with the Let's Encrypt Issuer are valid for 90 days and automatically renewed 30 days before their validity expires. For more information, read the documentation on [Gardener Certificate Management](https://github.com/gardener/cert-management#requesting-a-certificate) and [Gardener extensions for certificate Services](https://gardener.cloud/docs/extensions/others/gardener-extension-shoot-cert-service/). + ```bash + cat <**NOTE:** While using the default configuration, certificates with the Let's Encrypt Issuer are valid for 90 days and automatically renewed 30 days before their validity expires. For more information, read the documentation on [Gardener Certificate Management](https://github.com/gardener/cert-management#requesting-a-certificate) and [Gardener extensions for certificate Services](https://gardener.cloud/docs/extensions/others/gardener-extension-shoot-cert-service/). - * To check the certificate status, run: + * To check the certificate status, run: ```bash kubectl get certificate httpbin-cert -n istio-system ``` -5. [Set up a TLS Gateway](./01-20-set-up-tls-gateway.md). +5. [Set Up a TLS Gateway](./01-20-set-up-tls-gateway.md). Visit the [Gardener external DNS management documentation](https://github.com/gardener/external-dns-management/tree/master/examples) to see more examples of CRs for Services and ingresses. \ No newline at end of file diff --git a/docs/user/tutorials/01-20-set-up-tls-gateway.md b/docs/user/tutorials/01-20-set-up-tls-gateway.md index 11a99166d..4060036f5 100644 --- a/docs/user/tutorials/01-20-set-up-tls-gateway.md +++ b/docs/user/tutorials/01-20-set-up-tls-gateway.md @@ -1,10 +1,10 @@ -# Set up a TLS Gateway +# Set Up a TLS Gateway This tutorial shows how to set up a TLS Gateway in both manual and simple modes. It also explains how to configure authentication for an mTLS Gateway based on certificate details. ## Prerequisites -* Deploy [a sample HttpBin Service](./01-00-create-workload.md). +* Deploy [a sample HTTPBin Service](./01-00-create-workload.md). * Set up [your custom domain](./01-10-setup-custom-domain-for-workload.md) and export the following values as environment variables: ```bash @@ -12,7 +12,8 @@ This tutorial shows how to set up a TLS Gateway in both manual and simple modes. export GATEWAY=$NAMESPACE/httpbin-gateway ``` -## Set up a TLS Gateway in simple mode + +## Set Up a TLS Gateway in Simple Mode To create a TLS Gateway in simple mode, run: @@ -40,9 +41,9 @@ To create a TLS Gateway in simple mode, run: EOF ``` -## Set up a TLS Gateway in mutual mode +## Set Up a TLS Gateway in Mutual Mode - 1. Create a mutual TLS Gateway. Run: +1. Create a mutual TLS Gateway. Run: ```bash cat < **CAUTION:** Exposing a workload to the outside world is a potential security vulnerability, so tread carefully. In a production environment, always secure the workload you expose with [OAuth2](../01-50-expose-and-secure-a-workload/01-50-expose-and-secure-workload-oauth2.md) or [JWT](../01-50-expose-and-secure-a-workload/01-52-expose-and-secure-workload-jwt.md). +> **CAUTION:** Exposing a workload to the outside world is a potential security vulnerability, so tread carefully. In a production environment, always secure the workload you expose with [OAuth2](../01-50-expose-and-secure-a-workload/01-50-expose-and-secure-workload-oauth2.md) or [JWT](../01-50-expose-and-secure-a-workload/01-52-expose-and-secure-workload-jwt.md). ## Prerequisites -* Deploy [a sample HttpBin Service](../01-00-create-workload.md). +* Deploy [a sample HTTPBin Service](../01-00-create-workload.md). * Set up [your custom domain](../01-10-setup-custom-domain-for-workload.md) or use a Kyma domain instead. * Depending on whether you use your custom domain or a Kyma domain, export the necessary values as environment variables: -
- -
- - Custom domain - + + #### **Custom Domain** - ```bash - export DOMAIN_TO_EXPOSE_WORKLOADS={DOMAIN_NAME} - export GATEWAY=$NAMESPACE/httpbin-gateway - ``` -
- -
- - Kyma domain - + ```bash + export DOMAIN_TO_EXPOSE_WORKLOADS={DOMAIN_NAME} + export GATEWAY=$NAMESPACE/httpbin-gateway + ``` + #### **Kyma Domain** - ```bash - export DOMAIN_TO_EXPOSE_WORKLOADS={KYMA_DOMAIN_NAME} - export GATEWAY=kyma-system/kyma-gateway - ``` -
-
+ ```bash + export DOMAIN_TO_EXPOSE_WORKLOADS={KYMA_DOMAIN_NAME} + export GATEWAY=kyma-system/kyma-gateway + ``` + -## Expose and access your workload +## Expose and Access Your Workload Follow these steps: -1. Expose an instance of the HttpBin Service by creating APIRule CR in your Namespace. +1. Expose an instance of the HTTPBin Service by creating APIRule CR in your namespace. - ```bash - cat <**NOTE:** If you are using k3d, add `httpbin.kyma.local` to the entry with k3d IP in your system's `/etc/hosts` file. + > **NOTE:** If you are using k3d, add `httpbin.kyma.local` to the entry with k3d IP in your system's `/etc/hosts` file. - >**NOTE:** If you don't specify a Namespace for your Service, the default APIRule Namespace is used. + > **NOTE:** If you don't specify a namespace for your Service, the default APIRule namespace is used. -2. Call the endpoint by sending a `GET` request to the HttpBin Service. +2. Call the endpoint by sending a `GET` request to the HTTPBin Service. ```bash curl -ik -X GET https://httpbin.$DOMAIN_TO_EXPOSE_WORKLOADS/ip ``` - If successful, the call returns the code `200 OK` response. + If successful, the call returns the code `200 OK` response. -3. Call the endpoint by sending a `POST` request to the HttpBin Service. +3. Call the endpoint by sending a `POST` request to the HTTPBin Service. ```bash curl -ik -X POST https://httpbin.$DOMAIN_TO_EXPOSE_WORKLOADS/post -d "test data" ``` - If successful, the call returns the code `200 OK` response. \ No newline at end of file + If successful, the call returns the code `200 OK` response. \ No newline at end of file diff --git a/docs/user/tutorials/01-40-expose-workload/01-41-expose-multiple-workloads.md b/docs/user/tutorials/01-40-expose-workload/01-41-expose-multiple-workloads.md index e37dc94e5..10e51ad94 100644 --- a/docs/user/tutorials/01-40-expose-workload/01-41-expose-multiple-workloads.md +++ b/docs/user/tutorials/01-40-expose-workload/01-41-expose-multiple-workloads.md @@ -1,67 +1,57 @@ -# Expose multiple workloads on the same host +# Expose Multiple Workloads on the Same Host This tutorial shows how to expose multiple workloads on different paths by defining a Service at the root level and by defining Services on each path separately. - > **CAUTION:** Exposing a workload to the outside world is always a potential security vulnerability, so tread carefully. In a production environment, remember to secure the workload you expose with [OAuth2](../01-50-expose-and-secure-a-workload/01-50-expose-and-secure-workload-oauth2.md) or [JWT](../01-50-expose-and-secure-a-workload/01-52-expose-and-secure-workload-jwt.md). +> **CAUTION:** Exposing a workload to the outside world is always a potential security vulnerability, so tread carefully. In a production environment, remember to secure the workload you expose with [OAuth2](../01-50-expose-and-secure-a-workload/01-50-expose-and-secure-workload-oauth2.md) or [JWT](../01-50-expose-and-secure-a-workload/01-52-expose-and-secure-workload-jwt.md). ## Prerequisites -* Deploy two instances of a sample [HttpBin Service](../01-00-create-workload.md). Export their names as environment variables: +* Deploy two instances of a sample [HTTPBin Service](../01-00-create-workload.md). Export their names as environment variables: ```bash - export FIRST_SERVICE={SERVICE_NAME} - export SECOND_SERVICE={SERVICE_NAME} + export FIRST_SERVICE={SERVICE_NAME} + export SECOND_SERVICE={SERVICE_NAME} ``` * Set up [your custom domain](../01-10-setup-custom-domain-for-workload.md) or use a Kyma domain instead. * Depending on whether you use your custom domain or a Kyma domain, export the necessary values as environment variables: -
+ + #### **Custom Domain** + + ```bash + export DOMAIN_TO_EXPOSE_WORKLOADS={DOMAIN_NAME} + export GATEWAY=$NAMESPACE/httpbin-gateway + ``` + #### **Kyma Domain** -
- - Custom domain - - - ```bash - export DOMAIN_TO_EXPOSE_WORKLOADS={DOMAIN_NAME} - export GATEWAY=$NAMESPACE/httpbin-gateway - ``` -
+ ```bash + export DOMAIN_TO_EXPOSE_WORKLOADS={KYMA_DOMAIN_NAME} + export GATEWAY=kyma-system/kyma-gateway + ``` + -
- - Kyma domain - +## Define Multiple Services on Different Paths + +Follow the instructions to expose the instances of the HTTPBin Service on different paths at the `spec.rules` level without a root Service defined. + +1. To expose the instances of the HTTPBin Service, create an APIRule custom resource (CR) in your namespace. Run: ```bash - export DOMAIN_TO_EXPOSE_WORKLOADS={KYMA_DOMAIN_NAME} - export GATEWAY=kyma-system/kyma-gateway - ``` -
-
- -## Define multiple Services on different paths - -Follow the instructions to expose the instances of the HttpBin Service on different paths at the `spec.rules` level without a root Service defined. - -1. To expose the instances of the HttpBin Service, create an APIRule custom resource (CR) in your Namespace. Run: - - ```bash - cat < **NOTE:** Services definitions at the `spec.rules` level have precedence over Service definition at the `spec.service` level. -1. To expose the instances of the HttpBin Service, create an APIRule CR in your Namespace. Run: - - ```shell - cat < **CAUTION:** Exposing a workload to the outside world causes a potential security vulnerability, so tread carefully. In a production environment, secure the workload you expose with [OAuth2](../01-50-expose-and-secure-a-workload/01-50-expose-and-secure-workload-oauth2.md) or [JWT](../01-50-expose-and-secure-a-workload/01-52-expose-and-secure-workload-jwt.md). +>**CAUTION:** Exposing a workload to the outside world causes a potential security vulnerability, so tread carefully. In a production environment, secure the workload you expose with [OAuth2](../01-50-expose-and-secure-a-workload/01-50-expose-and-secure-workload-oauth2.md) or [JWT](../01-50-expose-and-secure-a-workload/01-52-expose-and-secure-workload-jwt.md). ## Prerequisites -1. Create three Namespaces. Deploy two instances of the HttpBin Service, each in a separate Namespace. To learn how to do it, follow the [Create a workload](../01-00-create-workload.md) tutorial. Reserve the third Namespace for creating an APIRule. +1. Create three namespaces. Deploy two instances of the HTTPBin Service, each in a separate namespace. To learn how to do it, follow the [Create a workload](../01-00-create-workload.md) tutorial. Reserve the third namespace for creating an APIRule. - >**NOTE:** Remember to [enable the Istio sidecar proxy injection](https://kyma-project.io/#/istio/user/02-operation-guides/operations/02-20-enable-sidecar-injection) in each Namespace. + >**NOTE:** Remember to [enable the Istio sidecar proxy injection](https://kyma-project.io/#/istio/user/02-operation-guides/operations/02-20-enable-sidecar-injection) in each namespace. -1. Export the Namespaces' and Services' names as environment variables: +1. Export the namespaces' and Services' names as environment variables: - ```bash - export FIRST_SERVICE={SERVICE_NAME} - export SECOND_SERVICE={SERVICE_NAME} - export NAMESPACE_FIRST_SERVICE={NAMESPACE_NAME} - export NAMESPACE_SECOND_SERVICE={NAMESPACE_NAME} - export NAMESPACE_APIRULE={NAMESPACE_NAME} - ``` + ```bash + export FIRST_SERVICE={SERVICE_NAME} + export SECOND_SERVICE={SERVICE_NAME} + export NAMESPACE_FIRST_SERVICE={NAMESPACE_NAME} + export NAMESPACE_SECOND_SERVICE={NAMESPACE_NAME} + export NAMESPACE_APIRULE={NAMESPACE_NAME} + ``` 3. Depending on whether you use your custom domain or a Kyma domain, export the necessary values as environment variables: -
- -
- - Custom domain - - + + #### **Custom Domain** + ```bash export DOMAIN_TO_EXPOSE_WORKLOADS={DOMAIN_NAME} - export GATEWAY=$NAMESPACE_APIRULE/httpbin-gateway + export GATEWAY=$NAMESPACE/httpbin-gateway ``` -
- -
- - Kyma domain - + #### **Kyma Domain** ```bash export DOMAIN_TO_EXPOSE_WORKLOADS={KYMA_DOMAIN_NAME} export GATEWAY=kyma-system/kyma-gateway ``` -
-
- -## Expose and access your workloads in multiple Namespaces - -1. Expose the HttpBin Services in their respective Namespaces by creating an APIRule custom resource (CR) in its own Namespace. Run: - - ```bash - cat <**NOTE:** If you are using k3d, add `httpbin.kyma.local` to the entry with k3d IP in your system's `/etc/hosts` file. - -2. Call the HttpBin endpoints by sending a `GET` request to the HttpBin Services: - - ```bash - curl -ik -X GET https://httpbin-services.$DOMAIN_TO_EXPOSE_WORKLOADS/headers - ``` - ```bash - curl -ik -X GET https://httpbin-services.$DOMAIN_TO_EXPOSE_WORKLOADS/get - ``` - - If successful, the calls return the code `200 OK` response. \ No newline at end of file + + +## Expose and Access Your Workloads in Multiple Namespaces + +1. Expose the HTTPBin Services in their respective namespaces by creating an APIRule custom resource (CR) in its own namespace. Run: + + ```bash + cat <**NOTE:** If you are using k3d, add `httpbin.kyma.local` to the entry with k3d IP in your system's `/etc/hosts` file. + +2. Call the HTTPBin endpoints by sending a `GET` request to the HTTPBin Services: + + ```bash + curl -ik -X GET https://httpbin-services.$DOMAIN_TO_EXPOSE_WORKLOADS/headers + ``` + ```bash + curl -ik -X GET https://httpbin-services. $DOMAIN_TO_EXPOSE_WORKLOADS/get + ``` + + If successful, the calls return the code `200 OK` response. \ No newline at end of file diff --git a/docs/user/tutorials/01-40-expose-workload/README.md b/docs/user/tutorials/01-40-expose-workload/README.md index 379938951..7df296097 100644 --- a/docs/user/tutorials/01-40-expose-workload/README.md +++ b/docs/user/tutorials/01-40-expose-workload/README.md @@ -1,6 +1,6 @@ -# Tutorials - Expose a workload +# Tutorials - Expose a Workload Browse the API Gateway tutorials to learn how to expose workloads: -- [Expose a workload](./01-40-expose-workload-apigateway.md) -- [Expose multiple workloads on the same host](./01-41-expose-multiple-workloads.md) -- [Expose workloads in multiple Namespaces with a single APIRule definition](./01-42-expose-workloads-multiple-namespaces.md) \ No newline at end of file +- [Expose a Workload](./01-40-expose-workload-apigateway.md) +- [Expose Multiple Workloads on the Same Host](./01-41-expose-multiple-workloads.md) +- [Expose Workloads in Multiple Namespaces with a Single APIRule Definition](./01-42-expose-workloads-multiple-namespaces.md) \ No newline at end of file diff --git a/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-50-expose-and-secure-workload-oauth2.md b/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-50-expose-and-secure-workload-oauth2.md index e8a1f7347..526514c47 100644 --- a/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-50-expose-and-secure-workload-oauth2.md +++ b/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-50-expose-and-secure-workload-oauth2.md @@ -1,39 +1,30 @@ -# Expose and secure a workload with OAuth2 +# Expose and Secure a Workload with OAuth2 This tutorial shows how to expose and secure Services using APIGateway Controller. The controller reacts to an instance of the APIRule custom resource (CR) and creates an Istio VirtualService and [Oathkeeper Access Rules](https://www.ory.sh/docs/oathkeeper/api-access-rules) according to the details specified in the CR. ## Prerequisites -* Deploy [a sample HttpBin Service](../01-00-create-workload.md). +* Deploy [a sample HTTPBin Service](../01-00-create-workload.md). * Set up [your custom domain](../01-10-setup-custom-domain-for-workload.md) or use a Kyma domain instead. * Depending on whether you use your custom domain or a Kyma domain, export the necessary values as environment variables: -
- -
- - Custom domain - - - ```bash - export DOMAIN_TO_EXPOSE_WORKLOADS={DOMAIN_NAME} - export GATEWAY=$NAMESPACE/httpbin-gateway - ``` -
- -
- - Kyma domain - - - ```bash - export DOMAIN_TO_EXPOSE_WORKLOADS={KYMA_DOMAIN_NAME} - export GATEWAY=kyma-system/kyma-gateway - ``` -
-
+ + #### **Custom Domain** + + ```bash + export DOMAIN_TO_EXPOSE_WORKLOADS={DOMAIN_NAME} + export GATEWAY=$NAMESPACE/httpbin-gateway + ``` + #### **Kyma Domain** + + ```bash + export DOMAIN_TO_EXPOSE_WORKLOADS={KYMA_DOMAIN_NAME} + export GATEWAY=kyma-system/kyma-gateway + ``` + * Configure your client ID and client Secret using an OAuth2-compliant provider. Then, export the following values as environment variables: + ```shell export CLIENT_ID={CLIENT_ID} export CLIENT_SECRET={CLIENT_SECRET} @@ -41,116 +32,109 @@ This tutorial shows how to expose and secure Services using APIGateway Controlle export INTROSPECTION_URL={INTROSPECTION_URL} ``` -## Get the tokens +## Get the Tokens 1. Encode the client's credentials and export them as environment variables: - ```shell - export ENCODED_CREDENTIALS=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64) - ``` - -2. Get tokens to interact with secured resources using the client credentials flow: -
-
- - Token with `read` scope - - * Export the following value as an environment variable: - ```shell - export KYMA_DOMAIN={KYMA_DOMAIN_NAME} - ``` - * Get the opaque token: - ```shell - curl --location --request POST "$TOKEN_URL?grant_type=client_credentials" --header "Content-Type: application/x-www-form-urlencoded" --header "Authorization: Basic $ENCODED_CREDENTIALS" - ``` - * Export the issued token as an environment variable: - ```shell - export ACCESS_TOKEN_READ={ISSUED_READ_TOKEN} - ``` -
-
- - Token with `write` scope - - * Export the following value as an environment variable: - ```shell - export KYMA_DOMAIN={KYMA_DOMAIN_NAME} - ``` - * Get the opaque token: - ```shell - curl --location --request POST "$TOKEN_URL?grant_type=client_credentials" --header "Content-Type: application/x-www-form-urlencoded" --header "Authorization: Basic $ENCODED_CREDENTIALS" - ``` - * Export the issued token as an environment variable: - ```shell - export ACCESS_TOKEN_WRITE={ISSUED_WRITE_TOKEN} - ``` -
-
- - -## Expose and secure your workload - -Follow the instructions to expose an instance of the HttpBin Service, and secure it with OAuth2 scopes. - -1. Expose the Service and secure it by creating an APIRule CR in your Namespace. Run: - - ```shell - cat <**NOTE:** If you are using k3d, add `httpbin.kyma.local` to the entry with k3d IP in your system's `/etc/hosts` file. +2. Get tokens to interact with secured resources using the client credentials flow: - The exposed Service requires tokens with `read` scope for `GET` requests in the entire Service, and tokens with `write` scope for `POST` requests to the `/post` endpoint of the Service. + + #### **Token with `read` scope** + + * Export the following value as an environment variable: + ```shell + export KYMA_DOMAIN={KYMA_DOMAIN_NAME} + ``` + * Get the opaque token: + ```shell + curl --location --request POST "$TOKEN_URL?grant_type=client_credentials" --header "Content-Type: application/x-www-form-urlencoded" --header "Authorization: Basic $ENCODED_CREDENTIALS" + ``` + * Export the issued token as an environment variable: + ```shell + export ACCESS_TOKEN_READ={ISSUED_READ_TOKEN} + ``` + #### **Token with `write` scope** + + * Export the following value as an environment variable: + ```shell + export KYMA_DOMAIN={KYMA_DOMAIN_NAME} + ``` + * Get the opaque token: + ```shell + curl --location --request POST "$TOKEN_URL?grant_type=client_credentials" --header "Content-Type: application/x-www-form-urlencoded" --header "Authorization: Basic $ENCODED_CREDENTIALS" + ``` + * Export the issued token as an environment variable: + ```shell + export ACCESS_TOKEN_WRITE={ISSUED_WRITE_TOKEN} + ``` + + + +## Expose and Secure Your Workload + +Expose an instance of the HTTPBin Service, and secure it with OAuth2 scopes by creating an APIRule CR in your namespace. Run: + +```shell +cat <**NOTE:** If you are using k3d, add `httpbin.kyma.local` to the entry with k3d IP in your system's `/etc/hosts` file. + +The exposed Service requires tokens with `read` scope for `GET` requests in the entire Service, and tokens with `write` scope for `POST` requests to the `/post` endpoint of the Service. >**CAUTION:** When you secure a workload, don't create overlapping Access Rules for paths. Doing so can cause unexpected behavior and reduce the security of your implementation. -## Access the secured resources +## Access the Secured Resources Follow the instructions to call the secured Service using the tokens issued for the client you registered. -1. Send a `GET` request with a token that has the `read` scope to the HttpBin service: +1. Send a `GET` request with a token that has the `read` scope to the HTTPBin service: - ```shell - curl -ik -X GET https://httpbin.$DOMAIN_TO_EXPOSE_WORKLOADS/headers -H "Authorization: Bearer $ACCESS_TOKEN_READ" - ``` + ```shell + curl -ik -X GET https://httpbin.$DOMAIN_TO_EXPOSE_WORKLOADS/headers -H "Authorization: Bearer $ACCESS_TOKEN_READ" + ``` -2. Send a `POST` request with a token that has the `write` scope to the HttpBin's `/post` endpoint: +2. Send a `POST` request with a token that has the `write` scope to the HTTPBin's `/post` endpoint: - ```shell - curl -ik -X POST https://httpbin.$DOMAIN_TO_EXPOSE_WORKLOADS/post -d "test data" -H "Authorization: bearer $ACCESS_TOKEN_WRITE" - ``` + ```shell + curl -ik -X POST https://httpbin.$DOMAIN_TO_EXPOSE_WORKLOADS/post -d "test data" -H "Authorization: bearer $ACCESS_TOKEN_WRITE" + ``` If successful, the call returns the code `200 OK` response. If you call the Service without a token, you get the code `401` response. If you call the Service or its secured endpoint with a token with the wrong scope, you get the code `403` response. diff --git a/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-51-get-jwt.md b/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-51-get-jwt.md index f3799c812..4f9b382c9 100644 --- a/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-51-get-jwt.md +++ b/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-51-get-jwt.md @@ -4,7 +4,7 @@ This tutorial shows how to get a JSON Web Token (JWT), which can be used to acce ## Prerequisites -* Use an OpenID Connect-compliant (OIDC-compliant) identity provider. +Use an OpenID Connect-compliant (OIDC-compliant) identity provider. ## Get a JWT diff --git a/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-52-expose-and-secure-workload-jwt.md b/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-52-expose-and-secure-workload-jwt.md index df305f053..002b5cec5 100644 --- a/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-52-expose-and-secure-workload-jwt.md +++ b/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-52-expose-and-secure-workload-jwt.md @@ -1,74 +1,64 @@ -# Expose and secure a workload with JWT +# Expose and Secure a Workload with JWT This tutorial shows how to expose and secure Services using APIGateway Controller. The Controller reacts to an instance of the APIRule custom resource (CR) and creates an Istio VirtualService and [Oathkeeper Access Rules](https://www.ory.sh/docs/oathkeeper/api-access-rules) according to the details specified in the CR. To interact with the secured workloads, the tutorial uses a JWT token. ## Prerequisites -* Deploy a [sample HttpBin Service](../01-00-create-workload.md). +* Deploy a [sample HTTPBin Service](../01-00-create-workload.md). * [JSON Web Token (JWT)](./01-51-get-jwt.md) * Set up [your custom domain](../01-10-setup-custom-domain-for-workload.md) or use a Kyma domain instead. * Depending on whether you use your custom domain or a Kyma domain, export the necessary values as environment variables: -
+ + #### **Custom Domain** + + ```bash + export DOMAIN_TO_EXPOSE_WORKLOADS={DOMAIN_NAME} + export GATEWAY=$NAMESPACE/httpbin-gateway + ``` + #### **Kyma Domain** -
- - Custom domain - - - ```bash - export DOMAIN_TO_EXPOSE_WORKLOADS={DOMAIN_NAME} - export GATEWAY=$NAMESPACE/httpbin-gateway - ``` -
+ ```bash + export DOMAIN_TO_EXPOSE_WORKLOADS={KYMA_DOMAIN_NAME} + export GATEWAY=kyma-system/kyma-gateway + ``` + -
- - Kyma domain - +## Expose, Secure, and Access Your Workload + +1. Expose the Service and secure it by creating an APIRule CR in your namespace. Run: ```bash - export DOMAIN_TO_EXPOSE_WORKLOADS={KYMA_DOMAIN_NAME} - export GATEWAY=kyma-system/kyma-gateway + cat < -
- -## Expose, secure, and access your workload -1. Expose the Service and secure it by creating an APIRule CR in your Namespace. Run: - - ```bash - cat <**NOTE:** If you are using k3d, add `httpbin.kyma.local` to the entry with k3d IP in your system's `/etc/hosts` file. + >**NOTE:** If you are using k3d, add `httpbin.kyma.local` to the entry with k3d IP in your system's `/etc/hosts` file. 2. To access the secured Service, call it using the JWT access token: - ```bash - curl -ik https://httpbin.$DOMAIN_TO_EXPOSE_WORKLOADS/headers -H "Authorization: Bearer $ACCESS_TOKEN" - ``` + ```bash + curl -ik https://httpbin.$DOMAIN_TO_EXPOSE_WORKLOADS/headers -H "Authorization: Bearer $ACCESS_TOKEN" + ``` - If successful, the call returns the code `200 OK` response. + If successful, the call returns the code `200 OK` response. diff --git a/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-53-expose-and-secure-workload-istio.md b/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-53-expose-and-secure-workload-istio.md index ab280aa55..a2af8c515 100644 --- a/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-53-expose-and-secure-workload-istio.md +++ b/docs/user/tutorials/01-50-expose-and-secure-a-workload/01-53-expose-and-secure-workload-istio.md @@ -1,114 +1,104 @@ -# Expose and secure a workload with Istio +# Expose and Secure a Workload with Istio This tutorial shows how to expose and secure a workload using Istio's built-in security features. You will expose the workload by creating a [VirtualService](https://istio.io/latest/docs/reference/config/networking/virtual-service/). Then, you will secure access to your workload by adding the JWT validation verified by the Istio security configuration with [Authorization Policy](https://istio.io/latest/docs/reference/config/security/authorization-policy/) and [Request Authentication](https://istio.io/latest/docs/reference/config/security/request_authentication/). ## Prerequisites -* Deploy a [sample HttpBin Service](../01-00-create-workload.md). +* Deploy a [sample HTTPBin Service](../01-00-create-workload.md). * [JSON Web Token (JWT)](./01-51-get-jwt.md). * Set up [your custom domain](../01-10-setup-custom-domain-for-workload.md) or use a Kyma domain instead. * Depending on whether you use your custom domain or a Kyma domain, export the necessary values as environment variables: -
- -
- - Custom domain - + + #### **Custom Domain** - ```bash - export DOMAIN_TO_EXPOSE_WORKLOADS={DOMAIN_NAME} - export GATEWAY=$NAMESPACE/httpbin-gateway - ``` -
+ ```bash + export DOMAIN_TO_EXPOSE_WORKLOADS={DOMAIN_NAME} + export GATEWAY=$NAMESPACE/httpbin-gateway + ``` + #### **Kyma Domain** -
- - Kyma domain - + ```bash + export DOMAIN_TO_EXPOSE_WORKLOADS={KYMA_DOMAIN_NAME} + export GATEWAY=kyma-system/kyma-gateway + ``` + - ```bash - export DOMAIN_TO_EXPOSE_WORKLOADS={KYMA_DOMAIN_NAME} - export GATEWAY=kyma-system/kyma-gateway - ``` -
-
+## Expose Your Workload Using a VirtualService -## Expose your workload using a Virtual Service - -Follow the instructions in the tabs to expose the HttpBin workload using a VirtualService. +Follow the instructions in the tabs to expose the HTTPBin workload using a VirtualService. 1. Create a VirtualService: - ```shell - cat <**NOTE:** Create AuthorizationPolicy to check if the client's common name in the certificate matches. @@ -73,9 +73,9 @@ The following instructions describe how to secure an mTLS Service. EOF ``` -3. Call the secured endpoints of the HttpBin Service. +3. Call the secured endpoints of the HTTPBin Service. - Send a `GET` request to the HttpBin Service with the client certificates that you used to create mTLS Gateway: + Send a `GET` request to the HTTPBin Service with the client certificates that you used to create mTLS Gateway: ```shell curl --key ${CLIENT_CERT_KEY_FILE} \ @@ -84,4 +84,4 @@ The following instructions describe how to secure an mTLS Service. -ik -X GET https://httpbin-vs.$DOMAIN_TO_EXPOSE_WORKLOADS/headers ``` - If successful, the call returns the code `200 OK` response. If you call the Service without the proper certificates or with invalid ones, you get the code `403` response. \ No newline at end of file + If successful, the call returns the code `200 OK` response. If you call the Service without the proper certificates or with invalid ones, you get the code `403` response. \ No newline at end of file diff --git a/docs/user/tutorials/01-50-expose-and-secure-a-workload/README.md b/docs/user/tutorials/01-50-expose-and-secure-a-workload/README.md index c1006806a..e8cd473ac 100644 --- a/docs/user/tutorials/01-50-expose-and-secure-a-workload/README.md +++ b/docs/user/tutorials/01-50-expose-and-secure-a-workload/README.md @@ -1,8 +1,8 @@ -# Tutorials - Expose and secure a workload +# Tutorials - Expose and Secure a Workload Browse the API Gateway tutorials to learn how to expose and secure workloads: -- [Expose and secure a workload with OAuth2](./01-50-expose-and-secure-workload-oauth2.md) +- [Expose and Secure a Workload with OAuth2](./01-50-expose-and-secure-workload-oauth2.md) - [Get a JSON Web Token (JWT)](./01-51-get-jwt.md) -- [Expose and secure a workload with JWT](./01-52-expose-and-secure-workload-jwt.md) -- [Expose and secure a workload with Istio](./01-53-expose-and-secure-workload-istio.md) -- [Expose and secure a workload with a certificate](./01-54-expose-and-secure-workload-with-certificate.md) \ No newline at end of file +- [Expose and Secure a Workload with JWT](./01-52-expose-and-secure-workload-jwt.md) +- [Expose and Secure a Workload with Istio](./01-53-expose-and-secure-workload-istio.md) +- [Expose and Secure a Workload with a Certificate](./01-54-expose-and-secure-workload-with-certificate.md) \ No newline at end of file diff --git a/docs/user/tutorials/01-60-security/01-61-mtls-selfsign-client-certicate.md b/docs/user/tutorials/01-60-security/01-61-mtls-selfsign-client-certicate.md index cecab657c..225e34725 100644 --- a/docs/user/tutorials/01-60-security/01-61-mtls-selfsign-client-certicate.md +++ b/docs/user/tutorials/01-60-security/01-61-mtls-selfsign-client-certicate.md @@ -1,11 +1,11 @@ -# Prepare self-signed root certificate authority and client certificates +# Prepare Self-Signed Root Certificate Authority and Client Certificates This tutorial shows how to create a self-signed root certificate authority (CA) and how to use it to sign a client certificate. >**NOTE:** This solution is not recommended for production purposes. -## Prepare a client root CA +## Prepare a Client Root CA 1. Export the following values as environment variables: @@ -23,7 +23,7 @@ This tutorial shows how to create a self-signed root certificate authority (CA) openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=${CLIENT_ROOT_CA_ORG}/CN=${CLIENT_ROOT_CA_CN}' -keyout ${CLIENT_ROOT_CA_KEY_FILE} -out ${CLIENT_ROOT_CA_CRT_FILE} ``` -## Prepare client certificate +## Prepare a Client Certificate 1. Export the following values as environment variables: @@ -35,11 +35,13 @@ This tutorial shows how to create a self-signed root certificate authority (CA) export CLIENT_CERT_KEY_FILE=${CLIENT_CERT_CN}.key ``` -2. Generate a client certificate and sign it with the root CA: - +2. Create a new key and CSR for the client certificate. + ```bash - # Create a new key and CSR for the client certificate openssl req -out ${CLIENT_CERT_CSR_FILE} -newkey rsa:2048 -nodes -keyout ${CLIENT_CERT_KEY_FILE} -subj "/CN=${CLIENT_CERT_CN}/O=${CLIENT_CERT_ORG}" - # Sign the client certificate with the Client Root CA certificate + ``` + +3. Sign the client certificate with the Client Root CA certificate. + ```bash openssl x509 -req -days 365 -CA ${CLIENT_ROOT_CA_CRT_FILE} -CAkey ${CLIENT_ROOT_CA_KEY_FILE} -set_serial 0 -in ${CLIENT_CERT_CSR_FILE} -out ${CLIENT_CERT_CRT_FILE} ``` diff --git a/docs/user/tutorials/01-60-security/01-62-set-up-idp.md b/docs/user/tutorials/01-60-security/01-62-set-up-idp.md index 57390fd90..5b8063860 100644 --- a/docs/user/tutorials/01-60-security/01-62-set-up-idp.md +++ b/docs/user/tutorials/01-60-security/01-62-set-up-idp.md @@ -1,4 +1,4 @@ -# Set up a custom identity provider +# Set Up a Custom Identity Provider Kyma sits on top of Kubernetes and leverages [authentication strategies](https://kubernetes.io/docs/reference/access-authn-authz/authentication/) from it. The purpose of all of those authentication strategies is to associate the identity of the caller with the request to the API server and evaluate access based on roles (RBAC). @@ -13,7 +13,7 @@ One of the strategies enables you to use your own identity provider. This is ver ## Steps -### Configure your identity provider +### Configure Your Identity Provider > **NOTE:** If you don't have access to the identity provider, you can sign up for a free tier plan at [Auth0](https://auth0.com/). @@ -29,7 +29,7 @@ Configure a dedicated client (often referred to as an application) at your ident 3. Configure the name of the **username** and **group** claims. 4. Enable the Proof Key for Code Exchange (PKCE) authentication flow. -### Configure your identity provider as the OIDC server +### Configure Your Identity Provider as the OIDC Server Add flags to the API server as described in the [Kubernetes documentation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#configuring-the-api-server). The ways of adding the flags to the API server differ depending on the Kubernetes distribution you use. For example, if you want to use k3d, you need to pass the additional `--k3s-server-arg` flags containing the OIDC server configuration when creating the cluster. See the [specification](https://k3d.io/v5.1.0/usage/commands/k3d_cluster_create/) of the `k3d cluster create` command: @@ -45,7 +45,7 @@ k3d cluster create kyma \ For managed Kubernetes, see the documentation related to your provider. For example, if you use Gardener as a managed Kubernetes offering, see the [OIDC Preset](https://github.com/gardener/gardener/blob/master/docs/usage/openidconnect-presets.md) documentation. -### Configure role-based access to identities provided by your OIDC server +### Configure Role-Based Access to Identities Provided by Your OIDC Server Including the JWT token in the call to the API server enables the API server to validate and extract the associated identity from the **username** and **group** claims of the JWT token. @@ -53,7 +53,7 @@ Now, define which individuals or groups should have access to which Kyma resourc You can combine user-level and group-level permissions in one binding. Run `kubectl create clusterrolebinding --help` in your terminal to see more options. -### Configure kubectl access +### Configure kubectl Access With this step, you will set up the OIDC provider in the `kubeconfig` file to enforce authentication flow when accessing Kyma using `kubectl`. diff --git a/docs/user/tutorials/01-60-security/README.md b/docs/user/tutorials/01-60-security/README.md index f988ba38d..50cc4e551 100644 --- a/docs/user/tutorials/01-60-security/README.md +++ b/docs/user/tutorials/01-60-security/README.md @@ -2,5 +2,5 @@ Browse the API Gateway Security tutorials to learn how to prepare certificates and set up a custom identity provider: -- [Prepare self-signed root CA and client certificates](./01-61-mtls-selfsign-client-certicate.md) -- [Set up a custom identity provider](./01-62-set-up-idp.md) \ No newline at end of file +- [Prepare Self-Signed Root CA and Client Certificates](./01-61-mtls-selfsign-client-certicate.md) +- [Set Up a Custom Identity Provider](./01-62-set-up-idp.md) \ No newline at end of file diff --git a/docs/user/tutorials/README.md b/docs/user/tutorials/README.md index ddadb0d07..424f2004a 100644 --- a/docs/user/tutorials/README.md +++ b/docs/user/tutorials/README.md @@ -2,21 +2,21 @@ Browse the API Gateway tutorials to learn how to set up your custom domain, create, expose and secure workloads: -- [Create a workload](./01-00-create-workload.md) -- [Set up a custom domain for a workload](./01-10-setup-custom-domain-for-workload.md) -- [Set up a TLS Gateway](./01-20-set-up-tls-gateway.md) -- Expose a workload - - [Expose a workload](./01-40-expose-workload/01-40-expose-workload-apigateway.md) - - [Expose multiple workloads on the same host](./01-40-expose-workload/01-41-expose-multiple-workloads.md) - - [Expose workloads in multiple Namespaces with a single APIRule](./01-40-expose-workload/01-42-expose-workloads-multiple-namespaces.md) -- Expose and secure a workload - - [Expose and secure a workload with OAuth2](./01-50-expose-and-secure-a-workload/01-50-expose-and-secure-workload-oauth2.md) +- [Create a Workload](./01-00-create-workload.md) +- [Set Up a Custom Domain for a Workload](./01-10-setup-custom-domain-for-workload.md) +- [Set Up a TLS Gateway](./01-20-set-up-tls-gateway.md) +- Expose a Workload + - [Expose a Workload](./01-40-expose-workload/01-40-expose-workload-apigateway.md) + - [Expose Multiple Workloads on the Same Host](./01-40-expose-workload/01-41-expose-multiple-workloads.md) + - [Expose Workloads in Multiple Namespaces With a Single APIRule](./01-40-expose-workload/01-42-expose-workloads-multiple-namespaces.md) +- Expose and Secure a Workload + - [Expose and Secure a Workload with OAuth2](./01-50-expose-and-secure-a-workload/01-50-expose-and-secure-workload-oauth2.md) - [Get a JSON Web Token (JWT)](./01-50-expose-and-secure-a-workload/01-51-get-jwt.md) - - [Expose and secure a workload with JWT](./01-50-expose-and-secure-a-workload/01-52-expose-and-secure-workload-jwt.md) - - [Expose and secure a workload with Istio](./01-50-expose-and-secure-a-workload/01-53-expose-and-secure-workload-istio.md) - - [Expose and secure a workload with a certificate](./01-50-expose-and-secure-a-workload/01-54-expose-and-secure-workload-with-certificate.md) + - [Expose and Secure a Workload with JWT](./01-50-expose-and-secure-a-workload/01-52-expose-and-secure-workload-jwt.md) + - [Expose and Secure a workload with Istio](./01-50-expose-and-secure-a-workload/01-53-expose-and-secure-workload-istio.md) + - [Expose and Secure a Workload with a Certificate](./01-50-expose-and-secure-a-workload/01-54-expose-and-secure-workload-with-certificate.md) Browse the API Gateway Security tutorials to learn how to prepare certificates and set up a custom identity provider: -- [Prepare self-signed root CA and client certificates](./01-60-security/01-61-mtls-selfsign-client-certicate.md) -- [Set up a custom identity provider](./01-60-security/01-62-set-up-idp.md) \ No newline at end of file +- [Prepare Self-Signed Root CA and Client Certificates](./01-60-security/01-61-mtls-selfsign-client-certicate.md) +- [Set Up a Custom Identity Provider](./01-60-security/01-62-set-up-idp.md) \ No newline at end of file diff --git a/hack/managed-kyma-migration/README.md b/hack/managed-kyma-migration/README.md index 42423e0d0..9aa7aec4a 100644 --- a/hack/managed-kyma-migration/README.md +++ b/hack/managed-kyma-migration/README.md @@ -1,33 +1,33 @@ -# SAP BTP, Kyma runtime migration +# SAP BTP, Kyma Runtime Migration > **NOTE**: This documentation is relevant for SAP BTP, Kyma runtime only and does not apply to open-source Kyma. ## Scenarios -### Provisioning of API Gateway CR using Lifecycle Manager in a new cluster +### Provisioning of API Gateway CR Using Lifecycle Manager in a New Cluster If there is no APIGateway custom resource (CR), then Lifecycle Manager provisions the default API Gateway CR defined in the API Gateway ModuleTemplate. The migration adds the API Gateway module to the Kyma CR. -### Provisioning of Istio CR using Lifecycle Manager in a cluster with existing modules +### Provisioning of Istio CR Using Lifecycle Manager in a Cluster with Existing Modules If there is no APIGateway CR, then Lifecycle Manager provisions the default APIGateway CR defined in the APIGateway ModuleTemplate. The migration adds the API Gateway module to the Kyma CR without overwriting existing module configuration. -## Migration test process +## Migration Test Process -### Test scenarios +### Test Scenarios Apply the ModuleTemplate for both `fast` and `regular` channels to Dev Control Plane. -#### SAP BTP, Kyma runtime clusters without existing modules +#### SAP BTP, Kyma Runtime Clusters Without Existing Modules 1. Create a Dev SAP BTP, Kyma runtime cluster. 2. Execute the migration. 3. Verify that `api-gateway-manager` is installed and the APIGateway CR's status is `Ready`. 4. Verify that the `api-gateway` deployment is not present. -#### SAP BTP, Kyma runtime cluster with an existing module +#### SAP BTP, Kyma Runtime Cluster with an Existing Module 1. Create a Dev SAP BTP, Kyma runtime cluster. 2. Add the Keda module to the Kyma CR. @@ -40,7 +40,7 @@ Apply the ModuleTemplate for both `fast` and `regular` channels to Dev Control P 4. Verify that `api-gateway-manager` is installed and the APIGateway CR's status is `Ready`. 5. Verify that the `api-gateway` deployment is not present. -## Module's rollout and migration +## Module's Rollout and Migration ### Preparations @@ -52,7 +52,7 @@ Executing `kcp taskrun` requires the path to the kubeconfig file of the correspo - Reconciliation is disabled for the Dev environment. See PR #4485 in the `kyma/management-plane-config` repository. -#### Migration procedure +#### Migration Procedure 1. Apply the ModuleTemplate for both `fast` and `regular` channels to Dev Control Plane. 2. Verify that the ModuleTemplate in the `fast` and `regular` channels is available on SAP BTP, Kyma runtime clusters of the Dev environment. @@ -77,7 +77,7 @@ Perform the rollout to Stage together with the SRE team. Since they have already - Reconciliation is disabled for the Stage environment. See PR #4486 to the `kyma/management-plane-config` repository. -#### Migration procedure +#### Migration Procedure 1. Apply the ModuleTemplate for both `fast` and `regular` channels to Stage Control Plane. 2. Verify that the ModuleTemplate in the `fast` and `regular` channels is available in SAP BTP, Kyma runtime clusters of the Stage environment. @@ -96,7 +96,7 @@ Perform the rollout to Prod together with the SRE team. Since they have already - Reconciliation is disabled for the Prod environment. See PR #4487 to the `kyma/management-plane-config` repository. -#### Migration procedure +#### Migration Procedure 1. Commit the module manifest to the `regular` and `fast` channels in the `kyma/module-manifests` internal repository. 2. Verify that the ModuleTemplates are present in the `kyma/kyma-modules` internal repository. diff --git a/performance_tests/Readme.md b/performance_tests/Readme.md index 3a1eb9783..547bb3dec 100644 --- a/performance_tests/Readme.md +++ b/performance_tests/Readme.md @@ -1,4 +1,4 @@ -# Istio performance tests +# Istio Performance Tests This directory contains the scripts for running kyma performance tests. diff --git a/tests/integration/README.md b/tests/integration/README.md index 239d49a72..1a8f64350 100644 --- a/tests/integration/README.md +++ b/tests/integration/README.md @@ -1,4 +1,4 @@ -# Api-gateway component tests +# API Gateway Component Tests Api-gateway component tests use the [cucumber/godog](https://github.com/cucumber/godog) library. @@ -10,7 +10,7 @@ Api-gateway component tests use the [cucumber/godog](https://github.com/cucumber - `scope` with values `read` and `write` - `aud` with values `https://example.com` and `https://example.com/user` -### Environment variables +### Environment Variables These environment variables determine how the tests are run on both Prow and your local machine: @@ -26,7 +26,7 @@ export CLIENT_SECRET="" export OIDC_ISSUER_URL="" ``` -## Usage for standard API Gateway test suite +## Usage for Standard API Gateway Test Suite To start the test suite, run: @@ -34,13 +34,13 @@ To start the test suite, run: make test-integration ``` -## Integration tests run on `presubmit` and `postsubmit` in Prow +## CI/CD Integration Tests -Job definitions are specified [in test-infra repository](https://github.com/kyma-project/test-infra/blob/main/templates/data/api-gateway-validation.yaml). +For more information, see [CI/CD documentation](../../docs/contributor/04-30-ci-cd.md). -## Usage for custom-domain test suite +## Usage for Custom Domain Test Suite -### Set the custom domain environment variables +### Set the Custom Domain Environment Variables If you are using Gardener, make sure that your Kubernetes cluster has the `shoot-cert-service` and `shoot-dns-service` extensions enabled. The desired shoot specification is mentioned in the description of this [issue](https://github.com/kyma-project/control-plane/issues/875). Obtain a service account access key with permissions to maintain custom domain DNS entries and export it as a JSON file. To learn how to do it, follow this [guide](https://cloud.google.com/iam/docs/keys-create-delete). @@ -50,7 +50,7 @@ Set the following environment variables: - `TEST_CUSTOM_DOMAIN` - your custom domain, for example, `custom.domain.build.kyma-project.io` - `TEST_SA_ACCESS_KEY_PATH` - the path to the service account access key exported as a JSON file, for example, `/Users/user/gcp/service-account.json` -### Run the tests +### Run the Tests To start the test suite, run: diff --git a/tests/integration/scripts/README.md b/tests/integration/scripts/README.md index 68f9e73bd..c7a9ff206 100644 --- a/tests/integration/scripts/README.md +++ b/tests/integration/scripts/README.md @@ -1,4 +1,4 @@ -# Scripts for API Gateway integration tests +# Scripts for API Gateway Integration Tests Scripts are based on the gardener provision scripts and utilities from `test-infra`: https://github.com/kyma-project/test-infra/tree/main/prow/scripts @@ -9,7 +9,7 @@ https://github.com/kyma-project/test-infra/tree/main/prow/scripts - `jobguard`: job guard script that executes `/prowutils/jobguard` utility from `test-infra/kyma-integration` image, waiting for image build job to complete - `lib`: general utility functions for logging, kyma cli install, etc. -## Entrypoint for integration tests on Gardener +## Entrypoint for Integration Tests on Gardener API Gateway integration tests are triggered on `presubmit` (PR) and `postsubmit` (main branch) by executing `integration-gardener.sh` script, which provisions a Gardener cluster and starts the tests in `integration-tests.sh`. diff --git a/tests/ui/tests/README.md b/tests/ui/tests/README.md index ac5b2b3e6..3bfb0f6a2 100644 --- a/tests/ui/tests/README.md +++ b/tests/ui/tests/README.md @@ -12,9 +12,9 @@ If you want to use an existing cluster, you must copy your cluster's kubeconfig To install the dependencies, run the `npm clean install` command. -## Test development using Headless mode with Chrome browser +## Test Development Using Headless Mode with Chrome Browser -### Using a local Kyma Dashboard instance +### Using a Local Kyma Dashboard Instance Start a k3d cluster: @@ -22,42 +22,42 @@ Start a k3d cluster: npm run start-k3d ``` -Start the local Kyma Dashboard instance: +Start the local Kyma dashboard instance: ```bash npm run start-dashboard ``` -#### Run tests +#### Run the Tests ```bash npm run test ``` -#### Run Cypress UI tests in the test runner mode +#### Run Cypress UI Tests in the Test Runner Mode ```bash npm run start ``` -### Using a remote Kyma Dashboard instance +### Using a Remote Kyma Dashboard Instance -#### Optional: Log in to a cluster using OIDC +#### Optional: Log In to a Cluster Using OIDC If a cluster requires OIDC authentication, include the additional arguments **CYPRESS_OIDC_PASS** and **CYPRESS_OIDC_USER** while running the npm scripts. -#### Run tests +#### Run Tests ```bash CYPRESS_OIDC_PASS={YOUR_PASSWORD} CYPRESS_OIDC_USER={YOUR_USERNAME} CYPRESS_DOMAIN={REMOTE_CLUSTER_DASHBOARD_DOMAIN} npm run test ``` -#### Run Cypress UI tests in the test runner mode +#### Run Cypress UI Tests in the Test Runner Mode ```bash CYPRESS_OIDC_PASS={YOUR_PASSWORD} CYPRESS_OIDC_USER={YOUR_USERNAME} CYPRESS_DOMAIN={REMOTE_CLUSTER_DASHBOARD_DOMAIN} npm run start ``` -## Run tests in Continuous Integration System +## Run Tests in Continuous Integration System Start a k3d cluster and run the tests: diff --git a/tests/ui/tests/scripts/k3d-ci-kyma-dashboard-integration.sh b/tests/ui/tests/scripts/k3d-ci-kyma-dashboard-integration.sh index a4a743cab..1d9a96061 100755 --- a/tests/ui/tests/scripts/k3d-ci-kyma-dashboard-integration.sh +++ b/tests/ui/tests/scripts/k3d-ci-kyma-dashboard-integration.sh @@ -2,7 +2,7 @@ set -ex export CYPRESS_DOMAIN=http://localhost:3001 -export DASHBOARD_IMAGE="europe-docker.pkg.dev/kyma-project/prod/kyma-dashboard-local-prod:latest" +export DASHBOARD_IMAGE="europe-docker.pkg.dev/kyma-project/prod/kyma-dashboard-local-prod:aa0e80d8" sudo apt-get update -y sudo apt-get install -y gettext-base