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..d034d1d7d --- /dev/null +++ b/en/docs/create-api/create-and-deploy-apis/grpc/create-grpc-api-using-rest-api.md @@ -0,0 +1,152 @@ +# 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 '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 c324eb744..322b78433 100644 --- a/en/mkdocs.yml +++ b/en/mkdocs.yml @@ -97,6 +97,9 @@ nav: - GraphQL APIs: - Via REST API: create-api/create-and-deploy-apis/graphql/create-graphql-api-using-rest-api.md - Via CRs: create-api/create-and-deploy-apis/graphql/create-graphql-api-using-crs.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 @@ -205,6 +208,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