From b9badb16871329912d231a5cb2404e968ac066f5 Mon Sep 17 00:00:00 2001 From: Yi Tao Date: Fri, 7 Jun 2024 12:09:31 +0800 Subject: [PATCH 1/4] add guide page for example in configuring custom entity --- app/_data/docs_nav_kic_3.2.x.yml | 2 + .../guides/services/custom-entity.md | 208 ++++++++++++++++++ 2 files changed, 210 insertions(+) create mode 100644 app/_src/kubernetes-ingress-controller/guides/services/custom-entity.md diff --git a/app/_data/docs_nav_kic_3.2.x.yml b/app/_data/docs_nav_kic_3.2.x.yml index 6bbc5169a121..a6f0832b9f65 100644 --- a/app/_data/docs_nav_kic_3.2.x.yml +++ b/app/_data/docs_nav_kic_3.2.x.yml @@ -113,6 +113,8 @@ items: url: /guides/services/multiple-backends - text: Configuring Gateway API resources across namespaces url: /guides/services/cross-namespace + - text: Configuring Custom Kong Entities + url: /guides/services/custom-entity - text: Request Manipulation items: - text: Rewriting Hosts and Paths diff --git a/app/_src/kubernetes-ingress-controller/guides/services/custom-entity.md b/app/_src/kubernetes-ingress-controller/guides/services/custom-entity.md new file mode 100644 index 000000000000..23f815d4d11b --- /dev/null +++ b/app/_src/kubernetes-ingress-controller/guides/services/custom-entity.md @@ -0,0 +1,208 @@ +--- +title: Using Custom Entities +type: how-to +purpose: | + How to create custom Kong entities +alpha: true +--- + +This document introduces how to configure a custom Kong entity by the example +of `degraphql_routes` entity and `degraphql` plugin. +Not all Kong entities are processed in dedicated procedure of KIC. You can +configure Kong entities whose types are not supported in KIC by `KongCustomEntity` +resource: [KongCustomEntity]. + +**Note** The KongCustomEntity controller is an opt-in feature. You must enable it by +setting feature gate `KongCustomEntity` to `true` to enable the controller. + +**Note** The following example uses `degraphql` plugin and `degraphql_routes` entity +which are only available in {{site.ee_product_name}}. So you need to try the example +with {{site.ee_product_name}} installed. + +## Create a GraphQL Service + +You can use [hasura] to create an example GraphQL service with the following steps: + +### Create the deployment,service and the ingress to configure the GraphQL service + +```bash + echo 'apiVersion: apps/v1 +kind: Deployment +metadata: + labels: + app: hasura + hasuraService: custom + name: hasura + namespace: default +spec: + replicas: 1 + selector: + matchLabels: + app: hasura + template: + metadata: + labels: + app: hasura + spec: + containers: + - image: hasura/graphql-engine:v2.38.0 + imagePullPolicy: IfNotPresent + name: hasura + env: + - name: HASURA_GRAPHQL_DATABASE_URL + value: postgres://user:password@localhost:5432/hasura_data + - name: HASURA_GRAPHQL_ENABLE_CONSOLE + value: "true" + - name: HASURA_GRAPHQL_DEV_MODE + value: "true" + ports: + - name: http + containerPort: 8080 + protocol: TCP + resources: {} + - image: postgres:15 + name: postgres + env: + - name: POSTGRES_USER + value: "user" + - name: POSTGRES_PASSWORD + value: "password" + - name: POSTGRES_DB + value: "hasura_data" +--- +apiVersion: v1 +kind: Service +metadata: + labels: + app: hasura + name: hasura + namespace: default +spec: + ports: + - protocol: TCP + port: 80 + targetPort: 8080 + selector: + app: hasura +--- +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: hasura-ingress-console + annotations: + konghq.com/strip-path: "true" +spec: + ingressClassName: kong + rules: + - http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: hasura + port: + number: 80' | kubectl apply -f - +``` + +### Configure data provided in GraqhQL service + +You can access http://${PROXY_IP}/console to access hasura's console to set up data +for serving GraphQL service following the [steps][hasura_console_steps]. + +In this step, you can create a `contacts` table under `public` schema including 3 columns: + +`id` Integer auto increment; `name` Text; `phone` Text. + +Then insert a row: (name = "Alice", phone = "0123456789"). + +Or you can insert data by directly calling the hasura's API: + +```bash + curl -XPOST -H"Content-Type:application/json" -H"X-Hasura-Role:admin" http://${PROXY_IP}/v2/query -d'{"type": "run_sql","args": {"sql": "CREATE TABLE contacts(id serial NOT NULL, name text NOT NULL, phone text NOT NULL, PRIMARY KEY(id));"}}' + curl -XPOST -H"Content-Type:application/json" -H"X-Hasura-Role:admin" http://${PROXY_IP}/v2/query -d'{"type": "run_sql","args": {"sql": "INSERT INTO contacts (name, phone) VALUES ('Alice','0123456789');"}}' + curl -XPOST -H"Content-Type:application/json" -H"X-Hasura-Role:admin" http://${PROXY_IP}/v1/metadata -d'{"type": "pg_track_table","args": {"schema": "public","name": "contacts"}}' +``` + +## Create degraphql Plugin and degraphql_routes Entity + +Then you can create an ingress and attach a `degraphql` plugin and +a `degrpahql_routes` entity to the ingress. + +```bash + echo '# This is the ingress to expose graqhql services. +# Because we attached the `degraphql` plugin to the ingress, regular route matching is not available. +# So we cannot access the console, then we used two ingresses for console and graphQL service. +# You could use `curl -H"Host:graphql.service.example" http://${PROXY_IP}/...` to test function of degraphql plugin. +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: hasura-ingress-graphql + annotations: + konghq.com/strip-path: "true" + konghq.com/plugins: "degraphql-example" +spec: + ingressClassName: kong + rules: + - host: "graphql.service.example" + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: hasura + port: + number: 80 +--- +apiVersion: configuration.konghq.com/v1 +kind: KongPlugin +metadata: + namespace: default + name: degraphql-example +plugin: degraphql +config: + graphql_server_path: /v1/graphql +--- +# This route serves endpoint `/contacts` which extracts column `name` of all rows in `contacts` table in your `hasura_data` DB. +# You can use other query in the `query` field for fetching other data. +apiVersion: configuration.konghq.com/v1alpha1 +kind: KongCustomEntity +metadata: + namespace: default + name: degraphql-route-example +spec: + controllerName: kong + type: degraphql_routes + parentRef: + group: "configuration.konghq.com" + kind: "KongPlugin" + name: "degraphql-example" + fields: + uri: "/contacts" + query: "query{ contacts { name } }" +' | kubectl apply -f - +``` + +## Test the Service with the degraphql Plugin + +You can try to access the `hasura-ingress-graphql` ingress with `degraphql` +plugin attached to verify the `degraphql` plugin and `degraphql_routes` entity works: + +```bash + curl -H"Host:graphql.service.example" http://${PROXY_IP}/contacts +``` + +The `curl` command should return +``` +{"data":{"contacts":[{"name":"Alice"}]}} +``` +which matches the data inserted in the previous steps. + +[hasura]: https://hasura.io/ +[hasura_console_steps]: https://hasura.io/docs/latest/getting-started/docker-simple/#step-2-connect-a-database + + From 0ad2dcc03f54257b0926312a090fa21ac55f41d3 Mon Sep 17 00:00:00 2001 From: Tao Yi Date: Fri, 7 Jun 2024 17:58:45 +0800 Subject: [PATCH 2/4] Update note tags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Patryk Małek --- .../guides/services/custom-entity.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/app/_src/kubernetes-ingress-controller/guides/services/custom-entity.md b/app/_src/kubernetes-ingress-controller/guides/services/custom-entity.md index 23f815d4d11b..61fc1dccd81e 100644 --- a/app/_src/kubernetes-ingress-controller/guides/services/custom-entity.md +++ b/app/_src/kubernetes-ingress-controller/guides/services/custom-entity.md @@ -12,12 +12,14 @@ Not all Kong entities are processed in dedicated procedure of KIC. You can configure Kong entities whose types are not supported in KIC by `KongCustomEntity` resource: [KongCustomEntity]. -**Note** The KongCustomEntity controller is an opt-in feature. You must enable it by -setting feature gate `KongCustomEntity` to `true` to enable the controller. - -**Note** The following example uses `degraphql` plugin and `degraphql_routes` entity -which are only available in {{site.ee_product_name}}. So you need to try the example -with {{site.ee_product_name}} installed. +{:.note} +> **Note:** The KongCustomEntity controller is an opt-in feature. You must enable it by +> setting feature gate `KongCustomEntity` to `true` to enable the controller. + +{:.note} +> **Note:** The following example uses `degraphql` plugin and `degraphql_routes` entity +> which are only available in {{site.ee_product_name}}. So you need to try the example +> with {{site.ee_product_name}} installed. ## Create a GraphQL Service From 9614871159e6a79f9aef7e565fe96dd04b71b84b Mon Sep 17 00:00:00 2001 From: Michael Heap Date: Fri, 7 Jun 2024 18:14:16 +0100 Subject: [PATCH 3/4] Fix image customization guide --- .../guides/customize/image.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/app/_src/kubernetes-ingress-controller/guides/customize/image.md b/app/_src/kubernetes-ingress-controller/guides/customize/image.md index 10608fc68c51..f1f72c0f0538 100644 --- a/app/_src/kubernetes-ingress-controller/guides/customize/image.md +++ b/app/_src/kubernetes-ingress-controller/guides/customize/image.md @@ -37,8 +37,9 @@ You can test the latest build of {{ site.kic_product_name }} using the `kong/nig ```yaml controller: - image: - repository: kong/nightly-ingress-controller - tag: nightly - effectiveSemver: v{{ site.data.kong_latest_KIC.version }} + ingressController: + image: + repository: kong/nightly-ingress-controller + tag: nightly + effectiveSemver: v{{ site.data.kong_latest_KIC.version }} ``` \ No newline at end of file From 6103527fa251e89d839e120679f8a58ea469639d Mon Sep 17 00:00:00 2001 From: Michael Heap Date: Fri, 7 Jun 2024 13:36:44 +0100 Subject: [PATCH 4/4] Refactor KongCustomEntity guide --- .github/styles/kong/auto-ignore.txt | 3 +- .../guides/services/custom-entity.md | 135 +++++++++--------- 2 files changed, 70 insertions(+), 68 deletions(-) diff --git a/.github/styles/kong/auto-ignore.txt b/.github/styles/kong/auto-ignore.txt index 133703699b73..5c5fc4d10c97 100644 --- a/.github/styles/kong/auto-ignore.txt +++ b/.github/styles/kong/auto-ignore.txt @@ -93,4 +93,5 @@ KongPlugin KongClusterPlugin KongConsumer Rekor -Sigstore \ No newline at end of file +Sigstore +Hasura \ No newline at end of file diff --git a/app/_src/kubernetes-ingress-controller/guides/services/custom-entity.md b/app/_src/kubernetes-ingress-controller/guides/services/custom-entity.md index 61fc1dccd81e..66752aefb492 100644 --- a/app/_src/kubernetes-ingress-controller/guides/services/custom-entity.md +++ b/app/_src/kubernetes-ingress-controller/guides/services/custom-entity.md @@ -6,29 +6,40 @@ purpose: | alpha: true --- -This document introduces how to configure a custom Kong entity by the example -of `degraphql_routes` entity and `degraphql` plugin. -Not all Kong entities are processed in dedicated procedure of KIC. You can -configure Kong entities whose types are not supported in KIC by `KongCustomEntity` -resource: [KongCustomEntity]. +{{ site.kic_product_name }} provides an interface to configure {{ site.base_gateway }} entities using CRDs. + +Some Kong plugins define custom entities that require configuration. These entities can be configured using the `KongCustomEntity` resource. {:.note} > **Note:** The KongCustomEntity controller is an opt-in feature. You must enable it by > setting feature gate `KongCustomEntity` to `true` to enable the controller. -{:.note} -> **Note:** The following example uses `degraphql` plugin and `degraphql_routes` entity -> which are only available in {{site.ee_product_name}}. So you need to try the example -> with {{site.ee_product_name}} installed. +The `KongCustomEntity` resource contains a `type` field which indicates the type of Kong entity to create, and a `fields` property which can contain any values that need to be set on an entity. + +In the following example, a `degraphql_routes` entity is created with two properties, `uri` and `query`. -## Create a GraphQL Service +```yaml +spec: + type: degraphql_routes + fields: + uri: "/contacts" + query: "query{ contacts { name } }" +``` -You can use [hasura] to create an example GraphQL service with the following steps: +This corresponds to the `uri` and `query` parameters documented in the [plugin documentation](/hub/kong-inc/degraphql/#available-endpoints) -### Create the deployment,service and the ingress to configure the GraphQL service +# Tutorial: DeGraphQL custom entities + +{% include /md/kic/prerequisites.md release=page.release disable_gateway_api=false enterprise=true %} + +This example configures custom entities for the `degraphql` plugin, which allows you to access a GraphQL endpoint as a REST API. + +### Create a GraphQL Service + +The `degraphql` plugin requires an upstream GraphQL API. For this tutorial, we'll use [Hasura] to create an example GraphQL service: ```bash - echo 'apiVersion: apps/v1 +echo 'apiVersion: apps/v1 kind: Deployment metadata: labels: @@ -98,7 +109,7 @@ spec: rules: - http: paths: - - path: / + - path: /hasura pathType: Prefix backend: service: @@ -107,56 +118,22 @@ spec: number: 80' | kubectl apply -f - ``` -### Configure data provided in GraqhQL service - -You can access http://${PROXY_IP}/console to access hasura's console to set up data -for serving GraphQL service following the [steps][hasura_console_steps]. - -In this step, you can create a `contacts` table under `public` schema including 3 columns: - -`id` Integer auto increment; `name` Text; `phone` Text. - -Then insert a row: (name = "Alice", phone = "0123456789"). - -Or you can insert data by directly calling the hasura's API: +Once the Hasura Pod is running, create an API to return contact details using the Hasura API: ```bash - curl -XPOST -H"Content-Type:application/json" -H"X-Hasura-Role:admin" http://${PROXY_IP}/v2/query -d'{"type": "run_sql","args": {"sql": "CREATE TABLE contacts(id serial NOT NULL, name text NOT NULL, phone text NOT NULL, PRIMARY KEY(id));"}}' - curl -XPOST -H"Content-Type:application/json" -H"X-Hasura-Role:admin" http://${PROXY_IP}/v2/query -d'{"type": "run_sql","args": {"sql": "INSERT INTO contacts (name, phone) VALUES ('Alice','0123456789');"}}' - curl -XPOST -H"Content-Type:application/json" -H"X-Hasura-Role:admin" http://${PROXY_IP}/v1/metadata -d'{"type": "pg_track_table","args": {"schema": "public","name": "contacts"}}' +curl -X POST -H "Content-Type:application/json" -H "X-Hasura-Role:admin" http://${PROXY_IP}/hasura/v2/query -d '{"type": "run_sql","args": {"sql": "CREATE TABLE contacts(id serial NOT NULL, name text NOT NULL, phone text NOT NULL, PRIMARY KEY(id));"}}' +curl -X POST -H "Content-Type:application/json" -H "X-Hasura-Role:admin" http://${PROXY_IP}/hasura/v2/query -d $'{"type": "run_sql","args": {"sql": "INSERT INTO contacts (name, phone) VALUES (\'Alice\',\'0123456789\');"}}' +curl -X POST -H "Content-Type:application/json" -H "X-Hasura-Role:admin" http://${PROXY_IP}/hasura/v1/metadata -d '{"type": "pg_track_table","args": {"schema": "public","name": "contacts"}}' ``` -## Create degraphql Plugin and degraphql_routes Entity +## Configure the degraphql plugin -Then you can create an ingress and attach a `degraphql` plugin and -a `degrpahql_routes` entity to the ingress. +The degraphql entity requires you to configure a mapping between paths and GraphQL queries. In this example, we'll map the `/contact` path to `query{ contacts { name } }`. -```bash - echo '# This is the ingress to expose graqhql services. -# Because we attached the `degraphql` plugin to the ingress, regular route matching is not available. -# So we cannot access the console, then we used two ingresses for console and graphQL service. -# You could use `curl -H"Host:graphql.service.example" http://${PROXY_IP}/...` to test function of degraphql plugin. -apiVersion: networking.k8s.io/v1 -kind: Ingress -metadata: - name: hasura-ingress-graphql - annotations: - konghq.com/strip-path: "true" - konghq.com/plugins: "degraphql-example" -spec: - ingressClassName: kong - rules: - - host: "graphql.service.example" - http: - paths: - - path: / - pathType: Prefix - backend: - service: - name: hasura - port: - number: 80 ---- +The `KongPlugin` CRD creates a new `degraphql` plugin, and the `KongCustomEntity` CRD attaches the `fields` to the `KongPlugin` in `parentRef`. + +```yaml +echo '--- apiVersion: configuration.konghq.com/v1 kind: KongPlugin metadata: @@ -166,43 +143,67 @@ plugin: degraphql config: graphql_server_path: /v1/graphql --- -# This route serves endpoint `/contacts` which extracts column `name` of all rows in `contacts` table in your `hasura_data` DB. -# You can use other query in the `query` field for fetching other data. apiVersion: configuration.konghq.com/v1alpha1 kind: KongCustomEntity metadata: namespace: default name: degraphql-route-example spec: - controllerName: kong type: degraphql_routes + fields: + uri: "/contacts" + query: "query{ contacts { name } }" + controllerName: kong parentRef: group: "configuration.konghq.com" kind: "KongPlugin" name: "degraphql-example" - fields: - uri: "/contacts" - query: "query{ contacts { name } }" ' | kubectl apply -f - ``` +Once the `KongPlugin` is configured, you can attach it to an `Ingress`: + + +```bash +echo ' +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: demo-graphql + annotations: + konghq.com/plugins: "degraphql-example" +spec: + ingressClassName: kong + rules: + - http: + paths: + - path: /contacts + pathType: Prefix + backend: + service: + name: hasura + port: + number: 80' | kubectl apply -f - +``` + ## Test the Service with the degraphql Plugin -You can try to access the `hasura-ingress-graphql` ingress with `degraphql` +You can access the `demo-graphql` ingress with the `degraphql` plugin attached to verify the `degraphql` plugin and `degraphql_routes` entity works: ```bash - curl -H"Host:graphql.service.example" http://${PROXY_IP}/contacts + curl http://${PROXY_IP}/contacts ``` The `curl` command should return + ``` {"data":{"contacts":[{"name":"Alice"}]}} ``` + which matches the data inserted in the previous steps. [hasura]: https://hasura.io/ -[hasura_console_steps]: https://hasura.io/docs/latest/getting-started/docker-simple/#step-2-connect-a-database