How-To Kong

app/_data/docs_nav_gateway_3.0.x.yml

@@ -1,12 +1,13 @@
 product: gateway
 release: 3.0.x
 generate: true
+assume_generated: true
 items:
   - title: Introduction
     icon: /assets/images/icons/documentation/icn-flag.svg
     items:
       - text: Overview of Kong Gateway
-        url: /gateway/
+        url: /gateway/3.0.x/
         absolute_url: true
       - text: Version Support Policy
         url: /konnect-platform/support-policy
@@ -16,6 +17,12 @@ items:
         absolute_url: true
       - text: Understanding Kong
         items:
+          - text: Guides
+            items:
+              - text: Run Kong Gateway in Minutes
+                url: /understanding-kong/how-to/kong-gateway
+              - text: Request Transformations
+                url: /understanding-kong/how-to/request-transformations
           - text: Key Concepts
             items: 
               - text: Services
@@ -38,11 +45,12 @@ items:
             url: /understanding-kong/kong-performance-testing
           - text: Glossary
             url: /understanding-kong/glossary
-
-
+
   - title: Get Started with Kong
     icon: /assets/images/icons/documentation/icn-deployment-color.svg
     items:
+      - text: Overview
+        url: /get-started/
       - text: Get Kong with Docker
         url: /get-started/get-kong-with-docker
       - text: Configure Services and Routes
@@ -57,7 +65,6 @@ items:
         url: /get-started/load-balancing
       - text: Workspaces and Teams
         url: /get-started/manage-teams
-
   - title: Kong in Production
     icon: /assets/images/icons/documentation/icn-quickstart-color.svg
     items:

src/gateway/understanding-kong/how-to/kong-gateway.md

@@ -0,0 +1,100 @@
+---
+title: Run Kong Gateway in minutes
+description: A how-to guide for quickly starting a Kong Gateway
+---
+
+In order to explore the capabilities of [{{site.base_gateway}}](/gateway/latest/), 
+you'll need one to experiment with. This guide helps you quickly deploy Kong 
+using [Docker](https://docs.docker.com/get-started/overview/). This guide's purpose is not to provide a production-like deployment or an explanation of deployment steps but rather to quickly get you a running {{site.base_gateway}} instance and an example [service](/gateway/latest/admin-api/#service-object) as quickly as possible.
+
+### Prerequisites
+
+This guide assumes each of the following tools are installed locally. 
+* [Docker](https://docs.docker.com/get-docker/) is used to run Kong and the supporting database locally. 
+* [curl](https://curl.se/) is used to send requests to the gateway. Most systems come with `curl` pre-installed.
+
+### Steps 
+
+In order to get started, you'll download and execute a shell script that automatically installs Kong, its supporting database, and an example service.
+Then you'll interact with the gateway using `curl` to ensure it has been started properly.
+
+Run the following command to start {{site.base_gateway}} using Docker:
+
+```sh
+curl -Ls get.konghq.com/quickstart | sh -s
+```
+
+{:.note}
+> **Note:** The script creates a log file in the current directory named `kong-quickstart.log`
+
+Docker will download and run {{site.base_gateway}} and the supporting database. Additionally,
+the script bootstraps the database and installs a [mock service](https://mockbin.org/).
+
+Once Kong is available, you will see:
+
+```text
+✔ Kong is ready!
+```
+
+The script outputs connectivity details for your new gateway, which should look similar to the following:
+
+```text
+Kong Data Plane endpoint = localhost:55248
+Kong Admin API endpoint  = localhost:55247
+```
+
+Docker assigns available network ports on the host machine to {{site.base_gateway}} services and forwards 
+network traffic to {{site.base_gateway}}. You can see all the ports that {{site.base_gateway}} is listening on and the related host ports 
+using this Docker command:
+
+```sh
+docker port kong-quickstart-gateway
+```
+
+The script will create a file with connection values you can source into your environment
+that you can use throughout the rest of the guide. Load the values into your current environment: 
+
+```sh
+source kong.env
+```
+
+After you have sourced the `kong.env` environment variable file, 
+test the [Kong Admin API](/gateway/latest/admin-api/) with the following:
+
+```sh
+curl $KONG_ADMIN_API
+```
+
+You will see a large JSON response from the Admin API containing information about the running gateway, 
+including network, configuration, and plugins details.
+
+Test that {{site.base_gateway}} is proxying data by making a mock request to the gateway's data plane endpoint:
+
+```sh
+curl $KONG_PROXY/mock/requests
+```
+
+If everything is working correctly, you will see a JSON response from the mock service with various 
+information about the request made, including headers, timestamps, and IP addresses.
+
+### Cleanup
+
+Once you are done working with {{site.base_gateway}}, you can use the shell script to stop and 
+remove the gateway and database containers with the following command:
+
+```sh
+curl -Ls get.konghq.com/quickstart | sh -s -- -d
+```
+
+### What's next?
+
+You now have a {{site.base_gateway}} instance running locally. Kong offers a tremendous amount of capabilities
+to help you manage, configure and route requests to your APIs.
+
+* To follow a more detailed step-by-step guide to starting Kong, see the 
+[Kong Getting Started guide](/gateway/latest/get-started/).
+* The [Admin API documentation](/gateway/latest/admin-api/) 
+provides more details on managing a {{site.base_gateway}}.
+* Learn about modifying incoming JSON requests with no code by using the 
+[request-transformer plugin](/gateway/latest/understanding-kong/how-to/request-transformations).
+

src/gateway/understanding-kong/how-to/request-transformations.md

@@ -0,0 +1,111 @@
+---
+title: "Adding attributes to HTTP requests with Kong Gateway"
+description: "A no-code solution to modifying requests for your APIs"
+---
+
+It's very common to have an HTTP service which accepts requests expecting a JSON document in the body.
+Let's assume that the development team of your service plans to change the request API in the near future, 
+and will eventually begin to require a new field in the JSON body of the requests. 
+Eventually your client applications will need to upgrade their requests to support this new value, 
+but how could you provide a default value for your services in the meantime?
+
+[{{site.base_gateway}}](/gateway/{{page.kong_version}}/) supports a [Plugin](/hub/) 
+architecture including a [Request Transformer Plugin](/hub/kong-inc/request-transformer/) 
+that can modify incoming requests before proxying them to your upstream service. 
+This can all be accomplished using a no-code solution and managed with no downtime using 
+Kong's dynamic administrative capabilities.
+
+This guide will show you how to configure the Request Transformer plugin using 
+the [Kong Admin API](/gateway/{{page.kong_version}}/admin-api/) to modify incoming 
+requests with a static constant value. Then you will test the feature with a mock 
+request to verify the transformation process.
+
+### Prerequisites
+
+* This document is best used after following the companion 
+[{{site.base_gateway}} in minutes](/gateway/latest/understanding-kong/how-to/kong-gateway/) guide, which
+walks you through running a local {{site.base_gateway}} in Docker, setting up
+a mock [service](/gateway/latest/admin-api/#service-object), and the necessary connection details. 
+If you'd like to use an existing {{site.base_gateway}} or a different service, you will need to adjust the 
+commands in this guide as necessary.
+* You have [`curl`](https://curl.se/) installed on your system, which is used to send 
+requests to the gateway. Most systems come with `curl` pre-installed.
+* This guide uses the [`jq`](https://stedolan.github.io/jq/) command line JSON processing tool. While
+this tool is not necessary to complete the tasks, it's helpful for processing JSON responses from
+the gateway. If you do not have `jq` or do not wish to install it, you can modify the commands to remove
+`jq` processing.
+
+### Steps
+
+There are a large number of Kong plugins, many of which need to 
+be [custom installed](/gateway/{{page.kong_version}}/plugin-development/distribution/) 
+prior to utilization. Kong ships prepackaged with a number of useful plugins including
+the Request Transformer you will use in this guide.
+
+First verify the Request Transformer plugin is available on your gateway by querying the Admin API and using `jq` to filter the response looking at the plugins available on the server.
+
+```sh
+curl -s $KONG_ADMIN_API | \
+  jq -r '.plugins.available_on_server."request-transformer"'
+```
+
+The command output should be:
+```
+true
+```
+
+Now, assign a new instance of the Request Transformer plugin to
+the mock service by sending a `POST` request to the Admin API.
+In this command, the `config.add.body` value instructs the plugin to add a new
+field to the body of incoming requests before forwarding them to the `mock` service.
+In this example, we are instructing the plugin to add a field named `new-field` and 
+give it a static value of `defaultValue`. 
+
+```sh
+curl -i -X POST $KONG_ADMIN_API/services/mock/plugins \
+  --data "name=request-transformer" \
+  --data "config.add.body=new-field:defaultValue"
+```
+
+If successful the API will return a `201 Created` HTTP response code with a 
+JSON body including information about the new plugin instance.
+
+{:.note}
+> **Note:** The Request Transformer can perform more complex transformations than 
+shown here, see the [full documentation](/hub/kong-inc/request-transformer/) for the details.
+
+Next, use the `mock` service's `/requests` endpoint to test the behavior of the plugin.
+The `/requests` API will echo back helpful information from the request we send it, including
+headers and the request body.
+
+```sh
+curl -s -XPOST $KONG_PROXY/mock/requests \
+	-H 'Content-Type: application/json' \
+	-d '{"existing-field": "abc123"}'
+```
+
+The JSON response will contain the `postData` field which includes the 
+JSON body sent to the service. You can use `jq` to fully extract the request body 
+returned from the `mock` service, as follows:
+
+```sh
+curl -s -XPOST $KONG_PROXY/mock/requests \
+	-H 'Content-Type: application/json' \
+	-d '{"existing-field": "Kong FTW!"}' | \
+	jq -r '.postData.text'
+```
+
+This will output the following text indicating `new-field` has been added to the request body.
+
+```txt
+{"existing-field":"Kong FTW!","new-field":"defaultValue"}
+```
+
+### What's next?
+
+* More advanced transformations can be accomplished with the 
+[Request Transformer Advanced](/hub/kong-inc/request-transformer-advanced/) 
+plugin.
+* If no standard plugin is available to satisfy your use case, the 
+[Plugin Development Guide](/gateway/{{page.kong_version}}/plugin-development/) 
+can help you with developing your own plugin.