From 1b6b7d3dcc704ab3e5b71906a17250b8f030cbdf Mon Sep 17 00:00:00 2001 From: nataliasitko Date: Tue, 9 Jul 2024 16:01:09 +0200 Subject: [PATCH 1/4] Update the APIRule tutorial --- docs/user/tutorials/01-20-expose-function.md | 117 +++++++++---------- 1 file changed, 57 insertions(+), 60 deletions(-) diff --git a/docs/user/tutorials/01-20-expose-function.md b/docs/user/tutorials/01-20-expose-function.md index 053fff64d..39a5fcbaa 100644 --- a/docs/user/tutorials/01-20-expose-function.md +++ b/docs/user/tutorials/01-20-expose-function.md @@ -1,11 +1,11 @@ -# Expose a Function with an API Rule +# Expose a Function Using the APIRule Custom Resource This tutorial shows how you can expose your Function to access it outside the cluster, through an HTTP proxy. To expose it, use an [APIRule custom resource (CR)](https://kyma-project.io/docs/kyma/latest/05-technical-reference/00-custom-resources/apix-01-apirule/). Function Controller reacts to an instance of the APIRule CR and, based on its details, it creates an Istio VirtualService and Oathkeeper Access Rules that specify your permissions for the exposed Function. When you complete this tutorial, you get a Function that: -- Is available on an unsecured endpoint (**handler** set to `noop` in the APIRule CR). -- Accepts the `GET`, `POST`, `PUT`, and `DELETE` methods. +- Is available on an unsecured endpoint using the `no_auth` handler. +- Allows access to the specified HTTP methods of the exposed function. To learn more about securing your Function, see the [Expose and secure a workload with OAuth2](https://kyma-project.io/docs/kyma/latest/03-tutorials/00-api-exposure/apix-05-expose-and-secure-a-workload/apix-05-01-expose-and-secure-workload-oauth2/) or [Expose and secure a workload with JWT](https://kyma-project.io/docs/kyma/latest/03-tutorials/00-api-exposure/apix-05-expose-and-secure-a-workload/apix-05-03-expose-and-secure-workload-jwt/) tutorials. @@ -14,20 +14,17 @@ Read also about [Function’s specification](../technical-reference/07-70-functi ## Prerequisites - [Existing Function](01-10-create-inline-function.md) -- [API Gateway component installed](https://kyma-project.io/docs/kyma/latest/04-operation-guides/operations/02-install-kyma/#install-specific-components) +- [API Gateway module added](https://kyma-project.io/docs/kyma/latest/04-operation-guides/operations/02-install-kyma/#install-specific-components) ## Steps -You can expose a Function with Kyma dashboard, Kyma CLI, or kubectl: +You can expose a Function using Kyma dashboard, Kyma CLI, or kubectl: #### **Kyma Dashboard** -> [!NOTE] -> Kyma dashboard uses Busola, which is not installed by default. Follow the [installation instructions](https://github.com/kyma-project/busola/blob/main/docs/install-kyma-dashboard-manually.md). - -1. Select a namespace from the drop-down list in the top navigation panel. Make sure the namespace includes the Function that you want to expose through an APIRule. +1. Select a namespace from the drop-down list in the top navigation panel. Make sure the namespace includes the Function that you want to expose using the APIRule CR. 2. Go to **Discovery and Network** > **API Rules**, and click on **Create API Rule**. @@ -40,72 +37,73 @@ You can expose a Function with Kyma dashboard, Kyma CLI, or kubectl: - **Service Name** matching the Function's name. - - **Host** to determine the host on which you want to expose your Function. You must change the `*` symbol at the beginning to the subdomain name you want. + - **Host** to determine the host on which you want to expose your Function. -4. In the **Rules > Access Strategies > Config** section, change the handler from `allow` to `noop` and select all the methods below. +4. Edit the access strategy in the **Rules** > **Access Strategies** section + - Select the methods `GET`, `POST`, `PUT`, and `DELETE`. + - Use the default `no_auth` handler. 5. Select **Create** to confirm your changes. -6. Check if you can access the Function by selecting the HTTPS link under the **Host** column for the newly created APIRule. +6. Check if you can access the Function by selecting the HTTPS link under the **Host** column for the newly created APIRule. If successful, the `Hello World!` massage appears. #### **Kyma CLI** 1. Export these variables: - ```bash - export DOMAIN={DOMAIN_NAME} - export NAME={FUNCTION_NAME} - export NAMESPACE={NAMESPACE_NAME} - ``` + ```bash + export DOMAIN={DOMAIN_NAME} + export NAME={FUNCTION_NAME} + export NAMESPACE={NAMESPACE_NAME} + ``` - > [!NOTE] - > The Function takes the name from the Function CR name. The APIRule CR can have a different name but for the purpose of this tutorial, all related resources share a common name defined under the **NAME** variable. 2. Download the latest configuration of the Function from the cluster. This way, you update the local `config.yaml` file with the Function's code. - ```bash - kyma sync function $NAME -n $NAMESPACE - ``` + ```bash + kyma sync function $NAME -n $NAMESPACE + ``` 3. Edit the local `config.yaml` file and add the **apiRules** schema for the Function at the end of the file: - ```yaml - apiRules: - - name: {FUNCTION_NAME} - service: - host: {FUNCTION_NAME}.{DOMAIN_NAME} - rules: - - methods: - - GET - - POST - - PUT - - DELETE - accessStrategies: - - handler: noop - ``` + ```yaml + apiRules: + - name: {FUNCTION_NAME} + service: + host: {FUNCTION_NAME}.{DOMAIN_NAME} + rules: + - methods: + - GET + - POST + - PUT + - DELETE + accessStrategies: + - handler: no_auth + ``` 4. Apply the new configuration to the cluster: - ```bash - kyma apply function - ``` + ```bash + kyma apply function + ``` 5. Check if the Function's code was pushed to the cluster and reflects the local configuration: - ```bash - kubectl get apirules $NAME -n $NAMESPACE - ``` + ```bash + kubectl get apirules $NAME -n $NAMESPACE + ``` 6. Check that the APIRule was created successfully and has the status `OK`: - ```bash - kubectl get apirules $NAME -n $NAMESPACE -o=jsonpath='{.status.APIRuleStatus.code}' - ``` + ```bash + kubectl get apirules $NAME -n $NAMESPACE -o=jsonpath='{.status.APIRuleStatus.code}' + ``` 7. Call the Function's external address: - ```bash - curl https://$NAME.$DOMAIN - ``` + ```bash + curl https://$NAME.$DOMAIN + ``` + If successful, the `Hello World!` message appears. #### **kubectl** @@ -118,9 +116,9 @@ You can expose a Function with Kyma dashboard, Kyma CLI, or kubectl: ``` > [!NOTE] - > The Function takes the name from the Function CR name. The APIRule CR can have a different name but for the purpose of this tutorial, all related resources share a common name defined under the **NAME** variable. + > The APIRule CR can have a name different from that of the Function, but it is recommended that all related resources share a common name. -2. Create an APIRule CR for your Function. It is exposed on port `80`, which is the default port of the [Service Placeholder](../technical-reference/04-10-architecture.md). +2. Create an APIRule CR, which exposes your Function on port `80`. ```bash cat < Date: Tue, 9 Jul 2024 16:04:33 +0200 Subject: [PATCH 2/4] add the if successful message --- docs/user/tutorials/01-20-expose-function.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/user/tutorials/01-20-expose-function.md b/docs/user/tutorials/01-20-expose-function.md index 39a5fcbaa..25bcc5048 100644 --- a/docs/user/tutorials/01-20-expose-function.md +++ b/docs/user/tutorials/01-20-expose-function.md @@ -103,7 +103,7 @@ You can expose a Function using Kyma dashboard, Kyma CLI, or kubectl: ```bash curl https://$NAME.$DOMAIN ``` - If successful, the `Hello World!` message appears. + If successful, the `Hello World!` message appears. #### **kubectl** @@ -156,5 +156,6 @@ You can expose a Function using Kyma dashboard, Kyma CLI, or kubectl: ```bash curl https://$NAME.$DOMAIN ``` + If successful, the `Hello World!` message appears. \ No newline at end of file From b29f27e080e2f073d0bb5e739b8de2647cb07b0b Mon Sep 17 00:00:00 2001 From: nataliasitko Date: Wed, 10 Jul 2024 10:06:51 +0200 Subject: [PATCH 3/4] update the objectives --- docs/user/tutorials/01-20-expose-function.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user/tutorials/01-20-expose-function.md b/docs/user/tutorials/01-20-expose-function.md index 25bcc5048..96c82cbf9 100644 --- a/docs/user/tutorials/01-20-expose-function.md +++ b/docs/user/tutorials/01-20-expose-function.md @@ -4,8 +4,8 @@ This tutorial shows how you can expose your Function to access it outside the cl When you complete this tutorial, you get a Function that: -- Is available on an unsecured endpoint using the `no_auth` handler. -- Allows access to the specified HTTP methods of the exposed function. +- Uses the `no_auth` handler, allowing access on an unsecured endpoint. +- Accepts the `GET`, `POST`, `PUT`, and `DELETE` methods. To learn more about securing your Function, see the [Expose and secure a workload with OAuth2](https://kyma-project.io/docs/kyma/latest/03-tutorials/00-api-exposure/apix-05-expose-and-secure-a-workload/apix-05-01-expose-and-secure-workload-oauth2/) or [Expose and secure a workload with JWT](https://kyma-project.io/docs/kyma/latest/03-tutorials/00-api-exposure/apix-05-expose-and-secure-a-workload/apix-05-03-expose-and-secure-workload-jwt/) tutorials. From 07464b807c548703b67e51024d7fbdb273600f61 Mon Sep 17 00:00:00 2001 From: Natalia Sitko <80401180+nataliasitko@users.noreply.github.com> Date: Wed, 10 Jul 2024 15:13:07 +0200 Subject: [PATCH 4/4] Update docs/user/tutorials/01-20-expose-function.md Co-authored-by: Tim Riffer --- docs/user/tutorials/01-20-expose-function.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/tutorials/01-20-expose-function.md b/docs/user/tutorials/01-20-expose-function.md index 96c82cbf9..d419fe794 100644 --- a/docs/user/tutorials/01-20-expose-function.md +++ b/docs/user/tutorials/01-20-expose-function.md @@ -45,7 +45,7 @@ You can expose a Function using Kyma dashboard, Kyma CLI, or kubectl: 5. Select **Create** to confirm your changes. -6. Check if you can access the Function by selecting the HTTPS link under the **Host** column for the newly created APIRule. If successful, the `Hello World!` massage appears. +6. Check if you can access the Function by selecting the HTTPS link under the **Host** column for the newly created APIRule. If successful, the `Hello World!` message appears. #### **Kyma CLI**