From 9b87176a5e8a7476d79097621542806aaaeb2e22 Mon Sep 17 00:00:00 2001 From: sgayangi Date: Fri, 8 Nov 2024 16:16:42 +0530 Subject: [PATCH 1/2] Update links and files in QSG --- .../EmployeeServiceDefinition.json | 2 +- .../cors/enable-cors-via-rest-api.md | 2 +- .../get-started/quick-start-guide-with-cp.md | 4 +- en/docs/get-started/quick-start-guide.md | 79 +++++++++++++------ ...tomizing-Helm-Deployment-Configurations.md | 1 - en/docs/includes/create-apk-conf-api.md | 2 +- en/docs/includes/direct-deploy.md | 2 +- en/docs/includes/start-apk-cp.md | 2 +- en/docs/includes/start-apk.md | 3 +- 9 files changed, 62 insertions(+), 35 deletions(-) diff --git a/en/docs/assets/files/get-started/EmployeeServiceDefinition.json b/en/docs/assets/files/get-started/EmployeeServiceDefinition.json index a0eaa1261..e9551f726 100644 --- a/en/docs/assets/files/get-started/EmployeeServiceDefinition.json +++ b/en/docs/assets/files/get-started/EmployeeServiceDefinition.json @@ -6,7 +6,7 @@ }, "servers": [ { - "url": "http://employee-service:80", + "url": "http://employee-service:8080", "description": "Server URL", "variables": {} } diff --git a/en/docs/create-api/create-and-attach-api-policies/cors/enable-cors-via-rest-api.md b/en/docs/create-api/create-and-attach-api-policies/cors/enable-cors-via-rest-api.md index bd846823c..3d8685278 100644 --- a/en/docs/create-api/create-and-attach-api-policies/cors/enable-cors-via-rest-api.md +++ b/en/docs/create-api/create-and-attach-api-policies/cors/enable-cors-via-rest-api.md @@ -75,7 +75,7 @@ Sample content before the modification is shown below. defaultVersion: false endpointConfigurations: production: - endpoint: "http://employee-service:80" + endpoint: "http://employee-service:8080" operations: - target: "/employee" verb: "GET" diff --git a/en/docs/get-started/quick-start-guide-with-cp.md b/en/docs/get-started/quick-start-guide-with-cp.md index 91aefdec3..efa46637d 100644 --- a/en/docs/get-started/quick-start-guide-with-cp.md +++ b/en/docs/get-started/quick-start-guide-with-cp.md @@ -71,7 +71,7 @@ Apart from the above API definition file, we also need an `apk-conf` file that d defaultVersion: false endpointConfigurations: production: - endpoint: "http://employee-service:80" + endpoint: "http://employee-service:8080" operations: - target: "/employee" verb: "GET" @@ -149,7 +149,7 @@ You now have the API Definition (`EmployeeServiceDefinition.json`) and the apk-c ## Step 3 - Create the Backend -The endpoint "http://employee-service:80" provided in the above files points to a backend deployed on a kubernetes service. Prior to invoking the API, you will need to have this backend up. +The endpoint "http://employee-service:8080" provided in the above files points to a backend deployed on a kubernetes service. Prior to invoking the API, you will need to have this backend up. We have provided the file containing this sample backend [here](../assets/files/get-started/employee-service-backend.yaml). Download it and create the backend service using the following command. diff --git a/en/docs/get-started/quick-start-guide.md b/en/docs/get-started/quick-start-guide.md index 30d21772f..4076361eb 100644 --- a/en/docs/get-started/quick-start-guide.md +++ b/en/docs/get-started/quick-start-guide.md @@ -3,7 +3,7 @@ This section is a step-by-step guide to creating, deploying, and invoking an API using the WSO2 API Platform For Kubernetes. !!!NOTE - To set up the APK as an enterprise version, please follow the steps specified in the [Install APK Enterprise](../setup/enterprise-apk-install.md) section. + To set up the APK as an enterprise version, please follow the steps specified in the Install APK Enterprise section. ## Before you begin... @@ -36,7 +36,7 @@ kubectl get pods 1. Save and download the sample EmployeeServiceDefinition.json file. This is the OAS definition of the API that we are going to deploy in APK. + target="_blank" onclick="downloadFile(event)">EmployeeServiceDefinition.json file. This is the OAS definition of the API that we are going to deploy in APK. 2. Add a hostname mapping to the ```/etc/hosts``` file as follows. | IP | Domain name | @@ -84,24 +84,24 @@ Apart from the above API definition file, we also need an `apk-conf` file that d defaultVersion: false endpointConfigurations: production: - endpoint: "http://employee-service:80" + endpoint: "http://employee-service:8080" operations: + - target: "/employees + verb: "GET" + secured: true + scopes: [] - target: "/employee" - verb: "GET" - secured: true - scopes: [] - - target: "/employee" - verb: "POST" - secured: true - scopes: [] + verb: "POST" + secured: true + scopes: [] - target: "/employee/{employeeId}" - verb: "PUT" - secured: true - scopes: [] + verb: "PUT" + secured: true + scopes: [] - target: "/employee/{employeeId}" - verb: "DELETE" - secured: true - scopes: [] + verb: "DELETE" + secured: true + scopes: [] ``` === "Request Format" @@ -113,7 +113,36 @@ Apart from the above API definition file, we also need an `apk-conf` file that d ``` -2. You will get the apk-conf file content as the response. Save this content into a file named `EmployeeService.apk-conf`. +2. You will get the apk-conf file content as the response. Save this content into a file named `EmployeeService.apk-conf`. You can edit these values as necessary. Let's change the basepath from the autogenerated value to "/employees". Your apk-conf file should now appear as follows. + +``` +--- +name: "EmployeeServiceAPI" +basePath: "/employees" +version: "3.14" +type: "REST" +defaultVersion: false +endpointConfigurations: + production: + endpoint: "http://employee-service:8080" +operations: +- target: "/employees" + verb: "GET" + secured: true + scopes: [] +- target: "/employee" + verb: "POST" + secured: true + scopes: [] +- target: "/employee/{employeeId}" + verb: "PUT" + secured: true + scopes: [] +- target: "/employee/{employeeId}" + verb: "DELETE" + secured: true + scopes: [] +``` !!! Important We recommend installing the APK Config Language Support Visual Studio Code (VS Code) extension to edit the APK Configuration file. @@ -124,7 +153,7 @@ Apart from the above API definition file, we also need an `apk-conf` file that d To invoke the system APIs such as for deploying, we need a valid access token issued by an identity provider (IdP). While APK supports third-party IdPs such as Asgardeo and Auth0, it also supports an inbuilt non-production identity provider as well, which is only meant for testing purposes. We are going to use the non-production inbuilt IdP for this guide. !!!NOTE - If you are using a different organization to the one used in this guide, you will have to create a TokenIssuer with the relevant organization name in APK before proceeding to the next step. You can use the [Add Token Issuer](../develop-and-deploy-api/token-issuers/token-issuers.md) to create a new token issuer. + If you are using a different organization to the one used in this guide, you will have to create a TokenIssuer with the relevant organization name in APK before proceeding to the next step. You can use the Add Token Issuer to create a new token issuer. 1. We will be using the client credentials grant type to generate the token. @@ -186,15 +215,15 @@ You now have the API Definition (`EmployeeServiceDefinition.json`) and the apk-c --- id: "3940857a942e08686e58b511d43d046a7168281e" name: "EmployeeServiceAPI" - basePath: "/RW1wbG95ZWVTZXJ2aWNlQVBJMy4xNA" + basePath: "/employees" version: "3.14" type: "REST" defaultVersion: false endpointConfigurations: production: - endpoint: "http://employee-service:80" + endpoint: "http://employee-service:8080" operations: - - target: "/employee" + - target: "/employees" verb: "GET" secured: true scopes: [] @@ -231,14 +260,14 @@ You now have the API Definition (`EmployeeServiceDefinition.json`) and the apk-c ## Step 4 - Invoke the API -Now the API is ready to be invoked. Let’s get the list of Employees by invoking the `/employee` resource in the `EmployeeServiceAPI`. +Now the API is ready to be invoked. Let’s get the list of employees by invoking the `/employees` resource in the `EmployeeServiceAPI`. 1. Execute the following request to invoke the API. Make sure to provide the access token obtained in the previous step under ["Generate an access token to invoke APIs"](#generate-an-access-token-to-invoke-apis) section as the `Authorization` header in this request. === "Sample Request" ``` - curl -k --location 'https://default.gw.wso2.com:9095/RW1wbG95ZWVTZXJ2aWNlQVBJMy4xNA/3.14/employee' \ + curl -k --location 'https://default.gw.wso2.com:9095/employees/3.14/employees' \ --header 'Host: default.gw.wso2.com' \ --header 'Authorization: bearer eyJhbGciOiJSUzI1NiIsICJ0eXAiOiJKV1QiLCAia2lkIjoiZ2F0ZXdheV9jZXJ0aWZpY2F0ZV9hbGlhcyJ9.eyJpc3MiOiJodHRwczovL2lkcC5hbS53c28yLmNvbS90b2tlbiIsICJzdWIiOiI0NWYxYzVjOC1hOTJlLTExZWQtYWZhMS0wMjQyYWMxMjAwMDIiLCAiZXhwIjoxNjg4MTMxNDQ0LCAibmJmIjoxNjg4MTI3ODQ0LCAiaWF0IjoxNjg4MTI3ODQ0LCAianRpIjoiMDFlZTE3NDEtMDA0Ni0xOGE2LWFhMjEtYmQwYTk4ZjYzNzkwIiwgImNsaWVudElkIjoiNDVmMWM1YzgtYTkyZS0xMWVkLWFmYTEtMDI0MmFjMTIwMDAyIiwgInNjb3BlIjoiZGVmYXVsdCJ9.RfKQq2fUZKZFAyjimvsPD3cOzaVWazabmq7b1iKYacqIdNjkvO9CQmu7qdtrVNDmdZ_gHhWLXiGhN4UTSCXv_n1ArDnxTLFBroRS8dxuFBZoD9Mpj10vYFSDDhUfFqjgMqtpr30TpDMfee1wkqB6K757ZSjgCDa0hAbv555GkLdZtRsSgR3xWcxPBsIozqAMFDCWoUCbgTQuA5OiEhhpVco2zv4XLq2sz--VRoBieO12C69KnGRmoLuPtvOayInvrnV96Tbt9fR0fLS2l1nvAdFzVou0SIf9rMZLnURLVQQYE64GR14m-cFRYdUI9vTsFHZBl5w-uCLdzMMofzZaLQ' ``` @@ -270,12 +299,12 @@ Now the API is ready to be invoked. Let’s get the list of Employees by invokin ``` === "Request Format" ``` - curl --location 'https://:9095//3.14/employee' \ + curl --location 'https://:9095//3.14/employees' \ --header 'Host: ' \ --header 'Authorization: bearer ' ``` -You will now be able to see a successful response with the details of the Employees from the mock backend that we used for this guide. +You will now be able to see a successful response with the details of the employees from the mock backend that we used for this guide. !!!Note To invoke the APIs, we need a valid access token issued by an identity provider (IdP). APK supports third-party IdPs such as Asgardeo and Auth0. Refer Configure IDP. diff --git a/en/docs/includes/Customizing-Helm-Deployment-Configurations.md b/en/docs/includes/Customizing-Helm-Deployment-Configurations.md index fe379331f..f106d8f02 100644 --- a/en/docs/includes/Customizing-Helm-Deployment-Configurations.md +++ b/en/docs/includes/Customizing-Helm-Deployment-Configurations.md @@ -6,7 +6,6 @@ To customize configurations in the Helm deployment, you need to have the `values ``` git clone https://github.com/wso2/apk.git - ``` This will create a local copy of the entire repository on your machine. You can then navigate to the `helm-charts` directory and locate the `values.yaml` file. diff --git a/en/docs/includes/create-apk-conf-api.md b/en/docs/includes/create-apk-conf-api.md index cef79e94f..388bbcf7a 100644 --- a/en/docs/includes/create-apk-conf-api.md +++ b/en/docs/includes/create-apk-conf-api.md @@ -59,7 +59,7 @@ type: "REST" defaultVersion: false endpointConfigurations: production: - endpoint: "http://employee-service:80" + endpoint: "http://employee-service:8080" operations: - target: "/employee" verb: "GET" diff --git a/en/docs/includes/direct-deploy.md b/en/docs/includes/direct-deploy.md index 87a1d4aa3..1aa4137e9 100644 --- a/en/docs/includes/direct-deploy.md +++ b/en/docs/includes/direct-deploy.md @@ -21,7 +21,7 @@ organization: "default" defaultVersion: false endpointConfigurations: production: - endpoint: "http://employee-service:80" + endpoint: "http://employee-service:8080" operations: - target: "/employee" verb: "GET" diff --git a/en/docs/includes/start-apk-cp.md b/en/docs/includes/start-apk-cp.md index 008c97d35..db79879a6 100644 --- a/en/docs/includes/start-apk-cp.md +++ b/en/docs/includes/start-apk-cp.md @@ -35,7 +35,7 @@ Setup WSO2 API Manager 4.4.0 in K8s cluster using Helm Charts. helm install /wso2am-cp --version -f ``` -4. Install NGINX Ingress Controller using the following command. Please refer to the [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/deploy/#local-development-clusters) documentation for more information. +4. Install NGINX Ingress Controller using the following command. Please refer to the NGINX Ingress Controller documentation for more information. ### Setup WSO2 APK Dataplane 1.2.0 diff --git a/en/docs/includes/start-apk.md b/en/docs/includes/start-apk.md index 3dcb86a11..9932562e0 100644 --- a/en/docs/includes/start-apk.md +++ b/en/docs/includes/start-apk.md @@ -43,7 +43,6 @@ Now you can verify the deployment by executing the following command. You will s [![Pod Status](../assets/img/get-started/pod-status.png)](../assets/img/get-started/podstatus.png) !!! Important - Except for the `gateway-apim-admission` and `gateway-apim-admission-patch`, all other pods should transition to the running state. - If they have not, please refer the FAQs to troubleshoot the problem. + Except for the `gateway-apim-admission` and `gateway-apim-admission-patch` (which will run as soon as APK is installed and then complete), all other pods should transition to the running state. If they have not, please refer the FAQs to troubleshoot the problem. From 1e0325dcaee09805e79b7c9f59bf3603abf2dea4 Mon Sep 17 00:00:00 2001 From: sgayangi Date: Fri, 8 Nov 2024 16:50:55 +0530 Subject: [PATCH 2/2] Update documentation format --- en/docs/get-started/quick-start-guide.md | 10 ++++---- en/docs/includes/start-apk-cp.md | 2 +- en/docs/setup/prerequisites.md | 32 +++++++++++------------- 3 files changed, 21 insertions(+), 23 deletions(-) diff --git a/en/docs/get-started/quick-start-guide.md b/en/docs/get-started/quick-start-guide.md index 4076361eb..a29aedd46 100644 --- a/en/docs/get-started/quick-start-guide.md +++ b/en/docs/get-started/quick-start-guide.md @@ -36,8 +36,8 @@ kubectl get pods 1. Save and download the sample EmployeeServiceDefinition.json file. This is the OAS definition of the API that we are going to deploy in APK. -2. Add a hostname mapping to the ```/etc/hosts``` file as follows. + target="_blank" onclick="downloadFile(event)">EmployeeServiceDefinition.json file. This is the OAS definition of the API that we are going to deploy in APK. +1. Add a hostname mapping to the ```/etc/hosts``` file as follows. | IP | Domain name | | --------- | ------------------- | @@ -118,7 +118,7 @@ Apart from the above API definition file, we also need an `apk-conf` file that d ``` --- name: "EmployeeServiceAPI" -basePath: "/employees" +basePath: "/employees-info" version: "3.14" type: "REST" defaultVersion: false @@ -215,7 +215,7 @@ You now have the API Definition (`EmployeeServiceDefinition.json`) and the apk-c --- id: "3940857a942e08686e58b511d43d046a7168281e" name: "EmployeeServiceAPI" - basePath: "/employees" + basePath: "/employees-info" version: "3.14" type: "REST" defaultVersion: false @@ -267,7 +267,7 @@ Now the API is ready to be invoked. Let’s get the list of employees by invokin === "Sample Request" ``` - curl -k --location 'https://default.gw.wso2.com:9095/employees/3.14/employees' \ + curl -k --location 'https://default.gw.wso2.com:9095/employees-info/3.14/employees' \ --header 'Host: default.gw.wso2.com' \ --header 'Authorization: bearer eyJhbGciOiJSUzI1NiIsICJ0eXAiOiJKV1QiLCAia2lkIjoiZ2F0ZXdheV9jZXJ0aWZpY2F0ZV9hbGlhcyJ9.eyJpc3MiOiJodHRwczovL2lkcC5hbS53c28yLmNvbS90b2tlbiIsICJzdWIiOiI0NWYxYzVjOC1hOTJlLTExZWQtYWZhMS0wMjQyYWMxMjAwMDIiLCAiZXhwIjoxNjg4MTMxNDQ0LCAibmJmIjoxNjg4MTI3ODQ0LCAiaWF0IjoxNjg4MTI3ODQ0LCAianRpIjoiMDFlZTE3NDEtMDA0Ni0xOGE2LWFhMjEtYmQwYTk4ZjYzNzkwIiwgImNsaWVudElkIjoiNDVmMWM1YzgtYTkyZS0xMWVkLWFmYTEtMDI0MmFjMTIwMDAyIiwgInNjb3BlIjoiZGVmYXVsdCJ9.RfKQq2fUZKZFAyjimvsPD3cOzaVWazabmq7b1iKYacqIdNjkvO9CQmu7qdtrVNDmdZ_gHhWLXiGhN4UTSCXv_n1ArDnxTLFBroRS8dxuFBZoD9Mpj10vYFSDDhUfFqjgMqtpr30TpDMfee1wkqB6K757ZSjgCDa0hAbv555GkLdZtRsSgR3xWcxPBsIozqAMFDCWoUCbgTQuA5OiEhhpVco2zv4XLq2sz--VRoBieO12C69KnGRmoLuPtvOayInvrnV96Tbt9fR0fLS2l1nvAdFzVou0SIf9rMZLnURLVQQYE64GR14m-cFRYdUI9vTsFHZBl5w-uCLdzMMofzZaLQ' ``` diff --git a/en/docs/includes/start-apk-cp.md b/en/docs/includes/start-apk-cp.md index db79879a6..008c97d35 100644 --- a/en/docs/includes/start-apk-cp.md +++ b/en/docs/includes/start-apk-cp.md @@ -35,7 +35,7 @@ Setup WSO2 API Manager 4.4.0 in K8s cluster using Helm Charts. helm install /wso2am-cp --version -f ``` -4. Install NGINX Ingress Controller using the following command. Please refer to the NGINX Ingress Controller documentation for more information. +4. Install NGINX Ingress Controller using the following command. Please refer to the [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/deploy/#local-development-clusters) documentation for more information. ### Setup WSO2 APK Dataplane 1.2.0 diff --git a/en/docs/setup/prerequisites.md b/en/docs/setup/prerequisites.md index 0397914ce..3d5ad3506 100644 --- a/en/docs/setup/prerequisites.md +++ b/en/docs/setup/prerequisites.md @@ -1,11 +1,8 @@ # Prerequisites -To successfully deploy WSO2 APK in your environment, you’ll need a Kubernetes cluster, a Kubernetes client (`kubectl`), and Helm for package management. Below, we outline the supported versions of each tool to ensure compatibility with APK. If you have not setup any of these tools, refer to the [sections](#1-set-up-a-kubernetes-cluster) provided below to set them up. - -### Kubernetes - -To deploy WSO2 APK, your environment must meet specific requirements across managed Kubernetes services, resource allocations, and supported Kubernetes distributions. Each section below outlines these requirements for a successful deployment. +To successfully deploy WSO2 APK in your environment, you’ll need a Kubernetes cluster, a Kubernetes client (`kubectl`), and Helm for package management. Additionally, your environment must meet specific requirements across managed Kubernetes services, resource allocations, and supported Kubernetes distributions. Each section below outlines these requirements for a successful deployment. +### Supported Versions #### Managed Kubernetes Services WSO2 APK supports several managed Kubernetes services. To ensure compatibility, verify that your service’s Kubernetes version falls within the specified range. @@ -27,7 +24,15 @@ WSO2 APK is compatible with a variety of Kubernetes distributions. Check the com | Kind | 1.26.3 - 1.30.3 | 0.24.0 | | OpenShift | 1.28 | 4.15 | -#### Resource Requirements +#### Helm + +Below is the version requirement for Helm to be compatible with WSO2 APK. + +| Package Manager | Version | +| --------------- | --------------- | +| Helm | 3.10.0 - 3.16.1 | + +### Resource Requirements We recommend the following minimum resource requirements for running WSO2 APK on a Kubernetes cluster. These requirements are based on whether you are deploying the APK Data Plane only or with the APIM Control Plane as well. @@ -47,23 +52,16 @@ We recommend the following minimum resource requirements for running WSO2 APK on | Memory | 8 GB | | Storage | 15 GB | -#### Helm - -Below is the version requirement for Helm to be compatible with WSO2 APK. - -| Package Manager | Version | -| --------------- | --------------- | -| Helm | 3.10.0 - 3.16.1 | - -## 1. Set up a Kubernetes Cluster +### Steps to Follow +#### 1. Set up a Kubernetes Cluster Refer to the Kubernetes documentation to set up a Kubernetes cluster. -## 2. Install the Kubernetes Client (`kubectl`) +#### 2. Install the Kubernetes Client (`kubectl`) Refer to the Kubernetes documentation to install the `kubectl` client. -## 3. Install Helm +#### 3. Install Helm Refer to the Helm documentation to install Helm.