From f1e9f9f65ade9617cd5a9dcc028b22a2a5ede262 Mon Sep 17 00:00:00 2001 From: DinethH Date: Sat, 27 Apr 2024 01:51:59 +0530 Subject: [PATCH 1/3] add docs for grpc support on the data plane --- .../assets/files/get-started/Student.proto | 19 +++ en/docs/catalogs/kubernetes-crds.md | 1 + en/docs/catalogs/samples/grpc-route.md | 36 +++++ .../grpc/create-grpc-api-using-crs.md | 110 +++++++++++++ .../grpc/create-grpc-api-using-rest-api.md | 153 ++++++++++++++++++ en/mkdocs.yml | 4 + 6 files changed, 323 insertions(+) create mode 100644 en/docs/assets/files/get-started/Student.proto create mode 100644 en/docs/catalogs/samples/grpc-route.md create mode 100644 en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-crs.md create mode 100644 en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-rest-api.md diff --git a/en/docs/assets/files/get-started/Student.proto b/en/docs/assets/files/get-started/Student.proto new file mode 100644 index 000000000..86f699fa3 --- /dev/null +++ b/en/docs/assets/files/get-started/Student.proto @@ -0,0 +1,19 @@ +syntax = "proto3"; + +package grpc.base.path.v1.student; + +service StudentService { + rpc GetStudent(StudentRequest) returns (StudentResponse) {}; + rpc GetStudentStream(StudentRequest) returns (stream StudentResponse) {}; + rpc SendStudentStream(stream StudentRequest) returns (StudentResponse) {}; + rpc SendAndGetStudentStream(stream StudentRequest) returns (stream StudentResponse) {} +} + +message StudentRequest { + int32 id = 3; +} + +message StudentResponse { + string name = 1; + int32 age = 2; +} diff --git a/en/docs/catalogs/kubernetes-crds.md b/en/docs/catalogs/kubernetes-crds.md index bfff93667..363787a95 100644 --- a/en/docs/catalogs/kubernetes-crds.md +++ b/en/docs/catalogs/kubernetes-crds.md @@ -12,6 +12,7 @@ The catalogs of the CRDs, including examples and the configuration definitions, - [API](../../catalogs/crds/api_types) - [HTTPRoute](../../catalogs/samples/http-route) +- [GRPCRoute](../../catalogs/samples/grpc-route) - [Authentication](../../catalogs/crds/authentication_types) - [Backend](../../catalogs/crds/backend_types) - [BackendJWT](../../catalogs/crds/backendjwt_types) diff --git a/en/docs/catalogs/samples/grpc-route.md b/en/docs/catalogs/samples/grpc-route.md new file mode 100644 index 000000000..2ca34351e --- /dev/null +++ b/en/docs/catalogs/samples/grpc-route.md @@ -0,0 +1,36 @@ +# GRPCRoute Custom Resource + +This is the resource where you define resources of your API. This GRPCRoute is linked to the API by referring to this resource name from the API resource. + +Refer the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.GRPCRoute) for more information on how to configure GRPCRoute. +``` +apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: GRPCRoute +metadata: + name: grpc-app-1 +spec: + parentRefs: + - group: gateway.networking.k8s.io + kind: Gateway + name: default + sectionName: httpslistener + hostnames: + - "grpc.gw.wso2.com" + rules: + - matches: + - method: + service: student.StudentService + method: GetStudent + backendRefs: + - kind: Backend + name: grpc-service1 + port: 50051 + - matches: + method: + service: student.StudentService + method: GetStudentStream + backendRefs: + - kind: Backend + name: grpc-service2 + port: 50051 +``` \ No newline at end of file diff --git a/en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-crs.md b/en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-crs.md new file mode 100644 index 000000000..634f82ff8 --- /dev/null +++ b/en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-crs.md @@ -0,0 +1,110 @@ +Similar to the approach for [REST APIs](../rest/create-rest-api-using-crs.md), this approach requires three CRs. + +- API CR +- GRPCRoute CR +- Backend CR + +For this guide, you can create a sample backend for the gRPC API using the following command. +``` +kubectl apply -f https://raw.githubusercontent.com/wso2/apk/main/developer/tryout/samples/grpc-sample-backend.yaml -n +``` + +The proto file used for this guide is available at https://raw.githubusercontent.com/wso2/apk/main/developer/tryout/samples/definitions/Student.proto. + +#### API CR + +In the following CR, we have defined the gRPC API giving the name, context, and version information for the API. We have also referred to `GRPCRoute` resource in `spec.production.routeRefs[0]` path which we create in the next step. + +```yaml +apiVersion: dp.wso2.com/v1alpha2 +kind: API +metadata: + name: demo-grpc-api +spec: + apiName: "Demo gRPC API" + apiType: GRPC + apiVersion: v1 + basePath: /grpc.base.path.v1 + isDefaultVersion: false + organization: default + production: + - routeRefs: + - demo-grpc-route +``` + +#### GRPCRoute CR + +This is the resource where you define resources of your API. This `GRPCRoute` is linked to the API by referring to this resource name from the `API` resource. + +```yaml +apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: GRPCRoute +metadata: + name: demo-grpc-route + namespace: default +spec: + hostnames: + - default.gw.wso2.com + parentRefs: + - group: gateway.networking.k8s.io + kind: Gateway + name: wso2-apk-default + sectionName: httpslistener + rules: + - matches: + - method: + service: student.StudentService + method: GetStudent + - method: + service: student.StudentService + method: SendStudentStream + - method: + service: student.StudentService + method: GetStudentStream + - method: + service: student.StudentService + method: SendAndGetStudentStream + backendRefs: + - name: demo-grpc-backend + kind: Backend + port: 6565 + +``` + +#### Backend CR + +In the above created GQLRoute resource we have referred to a `Backend` resource in `spec.rules[0].backendRefs[0]` path. That `Backend` should be created as below: + +```yaml +apiVersion: dp.wso2.com/v1alpha1 +kind: Backend +metadata: + name: demo-grpc-backend + namespace: default +spec: + services: + - host: grpc-backend + port: 6565 + basePath: "" + protocol: http + +``` + +This Backend CR points to the backend that can be created using the following command. Replace with the relevant name of the namespace. + +``` +kubectl apply -f https://raw.githubusercontent.com/wso2/apk/main/developer/tryout/samples/grpc-sample-backend.yaml -n +``` + +The `host`, `port`, `basepath` fields should point to your gRPC backend. +If your backend is a Kubernetes-native `Service`, then derive the following value according to your `Service` and use it as the `host`. + +``` +. +``` + +Once you have designed your APIs using these essential CRs, the next step is to apply them to the Kubernetes API server. APK will process and deploy your APIs seamlessly, taking full advantage of the Kubernetes infrastructure. + +``` +kubectl apply -f -n +``` \ No newline at end of file diff --git a/en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-rest-api.md b/en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-rest-api.md new file mode 100644 index 000000000..5f895eec1 --- /dev/null +++ b/en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-rest-api.md @@ -0,0 +1,153 @@ +# gRPC + +gRPC is a modern open source high performance Remote Procedure Call (RPC) framework that can run in any environment. It can efficiently connect services in and across data centers with pluggable support for load balancing, tracing, health checking and authentication. It was initially developed by Google and is now a part of the Cloud Native Computing Foundation (CNCF) as an incubating project. + +You can use a proto file to design a gRPC API in WSO2 APK, similar to developing REST APIs using OpenAPI Specifications (a.k.a. Swagger Definitions). + +This guide will walk you through the process of creating and deploying a gRPC API using the WSO2 APK REST API. We will use the Student service API as an example in this guide. + +## Sample Backend for gRPC + +A sample gRPC backend for the Student service gRPC API can be created using the following command. You may have to replace the namespace value in the above CRs to match your namespace. + +``` +kubectl apply -f https://raw.githubusercontent.com/wso2/apk/main/developer/tryout/samples/grpc-sample-backend.yaml -n +``` + +You can check the status of the pods by using +``` +kubectl get pods -n +``` + +## Creating and deploying a gRPC API + +Follow the instructions below to design a gRPC API. + +1. Save and download the sample [Student.proto](../../../assets/files/get-started/Student.proto) file. This is the proto file of the API that we are going to deploy in APK. + +2. Execute the following request to generate the APK configuration. Use the values provided in the table below in the body of your request. + + | Field | Value | + | ---------- | -------------------------------------------------------------------------- | + | definition | `Student.proto` file that was downloaded at the beginning of Step 1. | + + === "Request Format" + ``` + curl --location 'https://:9095/api/configurator/1.1.0/apis/generate-configuration' \ + --header 'Host: ' \ + --form 'apiType="GRPC"' \ + --form 'definition=@""' + ``` + === "Sample Request" + ``` + curl -k --location 'https://api.am.wso2.com:9095/api/configurator/1.1.0/apis/generate-configuration' \ + --header 'Host: api.am.wso2.com' \ + --form 'apiType="GRPC"' \ + --form 'definition=@"/Users/user/Student.proto"' + ``` + === "Sample Response" + ```yaml + name: "" + basePath: "/grpc.base.path" + version: "v1" + type: "GRPC" + defaultVersion: false + subscriptionValidation: false + operations: + - target: "student.StudentService" + verb: "GetStudent" + secured: true + scopes: [] + - target: "student.StudentService" + verb: "GetStudentStream" + secured: true + scopes: [] + - target: "student.StudentService" + verb: "SendStudentStream" + secured: true + scopes: [] + - target: "student.StudentService" + verb: "SendAndGetStudentStream" + secured: true + scopes: [] + ``` + +3. You will get the apk-conf file content as the response, as seen in the above sample response. Save this content into a file named `StudentService.apk-conf`. You will need to fill in the name and endpoint configuration fields before deploying the API. + + Please note that the preferred basepath and version must be appended to the package name in the proto file. For example, the initial package name in the proto file is `student`, and the basepath is `/grpc.base.path` and the version is `v1`. Therefore, the package name in the proto file should be changed to `grpc.base.path.v1.student`. This will enable easy generation of code that can be used to invoke the grpc service via the apk gateway + +4. To invoke the system APIs such as for deploying, we need a valid access token issued by an identity provider (IdP). Follow the ["Generate Access Token"](../../../develop-and-deploy-api/security/generate-access-token.md) documentation to generate an access token. + +5. After generating the token, you can deploy the gRPC API with the command + + === "Request Format" + ``` + curl --location 'https://:9095/api/deployer/1.1.0/apis/deploy' \ + --header 'Host: ' \ + --header 'Authorization: bearer ' \ + --form 'apkConfiguration=@"path/to/StudentService.apk-conf"' \ + --form 'definitionFile=@"path/to/Student.proto"' + ``` + === "Sample Request" + ``` + curl -k --location 'https://api.am.wso2.com:9095/api/deployer/1.1.0/apis/deploy' \ + --header 'Host: api.am.wso2.com' \ + --header 'Authorization: bearer eyJhbGciOiJSUzI1NiIsICJ0eXAiOiJKV1QiLCAia2lkIjoiZ2F0ZXdheV9jZXJ0aWZpY2F0ZV9hbGlhcyJ9.eyJpc3MiOiJodHRwczovL2lkcC5hbS53c28yLmNvbS90b2tlbiIsICJzdWIiOiI0NWYxYzVjOC1hOTJlLTExZWQtYWZhMS0wMjQyYWMxMjAwMDIiLCAiZXhwIjoxNjg4MTMxNDQ0LCAibmJmIjoxNjg4MTI3ODQ0LCAiaWF0IjoxNjg4MTI3ODQ0LCAianRpIjoiMDFlZTE3NDEtMDA0Ni0xOGE2LWFhMjEtYmQwYTk4ZjYzNzkwIiwgImNsaWVudElkIjoiNDVmMWM1YzgtYTkyZS0xMWVkLWFmYTEtMDI0MmFjMTIwMDAyIiwgInNjb3BlIjoiZGVmYXVsdCJ9.RfKQq2fUZKZFAyjimvsPD3cOzaVWazabmq7b1iKYacqIdNjkvO9CQmu7qdtrVNDmdZ_gHhWLXiGhN4UTSCXv_n1ArDnxTLFBroRS8dxuFBZoD9Mpj10vYFSDDhUfFqjgMqtpr30TpDMfee1wkqB6K757ZSjgCDa0hAbv555GkLdZtRsSgR3xWcxPBsIozqAMFDCWoUCbgTQuA5OiEhhpVco2zv4XLq2sz--VRoBieO12C69KnGRmoLuPtvOayInvrnV96Tbt9fR0fLS2l1nvAdFzVou0SIf9rMZLnURLVQQYE64GR14m-cFRYdUI9vTsFHZBl5w-uCLdzMMofzZaLQ' \ + --form 'apkConfiguration=@"path/to/StudentService.apk-conf"' \ + --form 'definitionFile=@"path/to/Student.proto"' + ``` + === "Sample Response" + ``` + --- + id: "1516b9a7b06640877bdf9b8c7bde3f4c4d33d5d3" + name: "demo-grpc-api" + basePath: "/grpc.base.path" + version: "v1" + type: "GRPC" + defaultVersion: false + subscriptionValidation: false + endpointConfigurations: + production: + endpoint: "http://grpc-backend:6565" + operations: + - target: "student.StudentService" + verb: "GetStudent" + secured: true + scopes: [] + - target: "student.StudentService" + verb: "GetStudentStream" + secured: true + scopes: [] + - target: "student.StudentService" + verb: "SendStudentStream" + secured: true + scopes: [] + - target: "student.StudentService" + verb: "SendAndGetStudentStream" + secured: true + scopes: [] + + ``` + +7. Execute the command below. You will be able to see that the `StudentService` API is successfully deployed. + + === "Command" + ``` + kubectl get apis + ``` + + +## Invoking a gRPC API + +You will need a gRPC backend in order to invoke the API and get a correct response. A sample backend for the gRPC StudentService API has been provided under [this section.](#sample-backend-for-grpc) + +Once your gRPC API has been deployed, you can invoke it either via Postman, a custom client, or the `grpcurl` command-line tool. You can download the grpcurl tool from [here](https://github.com/fullstorydev/grpcurl). Code for custom clients can be [generated](https://grpc.io/docs/) by providing the modified proto file to the Protocol buffer Compiler. + +A sample gRPC call is provided below. + +=== "Sample Request" +``` +grpcurl -insecure -proto /Users/user/Student.proto -d '{"id": 1}' default.gw.wso2.com:9095 grpc.base.path.v1.student.StudentService/GetStudent + +``` + diff --git a/en/mkdocs.yml b/en/mkdocs.yml index c091b1c96..5351dfb92 100644 --- a/en/mkdocs.yml +++ b/en/mkdocs.yml @@ -97,6 +97,9 @@ nav: - GraphQL APIs: - Via CRs: create-api/create-and-deploy-apis/graphql/create-graphql-api-using-crs.md - Via REST API: create-api/create-and-deploy-apis/graphql/create-graphql-api-using-rest-api.md + - gRPC APIs: + - Via CRs: create-api/create-and-deploy-apis/grpc/create-grpc-api-using-crs.md + - Via REST API: create-api/create-and-deploy-apis/grpc/create-grpc-api-using-rest-api.md - Undeploy API: - Via REST API: undeploy/undeploy-rest-api.md - Via CRs: undeploy/undeploy-crs.md @@ -204,6 +207,7 @@ nav: - APIPolicy: catalogs/crds/apipolicy_types.md - HTTPRoute: catalogs/samples/http-route.md - GraphQL Route: catalogs/crds/gql_routes_types.md + - gRPC Route: catalogs/samples/grpc-route.md - Authentication: catalogs/crds/authentication_types.md - Backend: catalogs/crds/backend_types.md - BackendJWT: catalogs/crds/backendjwt_types.md From 663d634b7ae47a46ddf9506ae6a553092c2d999a Mon Sep 17 00:00:00 2001 From: DinethH Date: Tue, 14 May 2024 09:47:15 +0530 Subject: [PATCH 2/3] remove api type from deploying command --- .../grpc/create-grpc-api-using-rest-api.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-rest-api.md b/en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-rest-api.md index 5f895eec1..c48311127 100644 --- a/en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-rest-api.md +++ b/en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-rest-api.md @@ -35,14 +35,12 @@ Follow the instructions below to design a gRPC API. ``` curl --location 'https://:9095/api/configurator/1.1.0/apis/generate-configuration' \ --header 'Host: ' \ - --form 'apiType="GRPC"' \ --form 'definition=@""' ``` === "Sample Request" ``` curl -k --location 'https://api.am.wso2.com:9095/api/configurator/1.1.0/apis/generate-configuration' \ --header 'Host: api.am.wso2.com' \ - --form 'apiType="GRPC"' \ --form 'definition=@"/Users/user/Student.proto"' ``` === "Sample Response" From aa3180f8699365e1be00fc832a25a75e2d43ebd8 Mon Sep 17 00:00:00 2001 From: DinethH Date: Tue, 14 May 2024 10:21:57 +0530 Subject: [PATCH 3/3] add api type for conf generation --- .../grpc/create-grpc-api-using-rest-api.md | 1 + 1 file changed, 1 insertion(+) diff --git a/en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-rest-api.md b/en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-rest-api.md index c48311127..d034d1d7d 100644 --- a/en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-rest-api.md +++ b/en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-rest-api.md @@ -35,6 +35,7 @@ Follow the instructions below to design a gRPC API. ``` curl --location 'https://:9095/api/configurator/1.1.0/apis/generate-configuration' \ --header 'Host: ' \ + --form 'apiType="GRPC"' \ --form 'definition=@""' ``` === "Sample Request"