Kong entities (#21)

* wip for a bunch of entities

* add a plugins landing page

* splitting out plugins page

app/_kong_entities/plugin.md

@@ -0,0 +1,31 @@
+---
+title: Plugins
+entities:
+  - plugin
+
+content_type: reference
+
+related_resources:
+  - text: Kong Plugin Hub
+    url: /hub/
+  - text: Supported scopes by plugin
+    url: /hub/plugins/compatibility/#scopes
+  - text: Supported topologies by plugin
+    url: /hub/plugins/compatibility/
+  - text: Supported protocols for each plugin
+    url: /hub/plugins/compatibility/#protocols
+  - text: Self-managed Kong Gateway license tiers
+    url: /hub/plugins/license-tiers/
+  - text: Konnect pricing tiers
+    url: konnect/compatibility/#plugin-compatibility
+
+---
+
+## What is a plugin?
+
+{{site.base_gateway}} is a Lua application designed to load and execute modules, which we commonly refer to as plugins. Plugins provide advanced functionality and extend the use of the Kong Gateway, allowing you to add more features to your implementation.
+
+Kong provides a set of standard Lua plugins that get bundled with {{site.base_gateway}} and {{site.konnect_short_name}}. 
+The set of plugins you have access to depends on your license tier.
+
+You can also develop custom plugins, adding your own custom functionality to {{site.base_gateway}}.

app/_kong_entities/route.md

@@ -0,0 +1,157 @@
+---
+title: Routes
+entities:
+  - route
+
+content_type: reference
+
+related_resources:
+  - text: Services
+    url: /kong-entity/service/
+---
+
+## What is a route?
+
+A route is a path to a resource within an upstream application. Routes are added to services to allow access to the underlying application. In Kong Gateway, routes typically map to endpoints that are exposed through the Kong Gateway application. Routes can also define rules that match requests to associated services. Because of this, one route can reference multiple endpoints. A basic route should have a name, path or paths, and reference an existing service.
+
+You can also configure routes with:
+
+* Protocols: The protocol used to communicate with the upstream application.
+* Hosts: Lists of domains that match a route
+* Methods: HTTP methods that match a route
+* Headers: Lists of values that are expected in the header of a request
+* Redirect status codes: HTTPS status codes
+* Tags: Optional set of strings to group routes with
+
+
+{% contentfor setup_entity %}
+{% entity_example %}
+type: route
+data:
+  name: example-route
+  paths:
+    - "/mock"
+formats:
+  - admin-api
+  - konnect
+  - kic
+  - deck
+  - ui
+{% endentity_example %}
+{% endcontentfor %}
+
+## Route and service interaction
+
+Routes, in conjunction with [services](/kong-entities/service/), let you expose your services to applications with Kong Gateway. Kong Gateway abstracts the service from the applications by using routes. Since the application always uses the route to make a request, changes to the services, like versioning, don’t impact how applications make the request. Routes also allow the same service to be used by multiple applications and apply different policies based on the route used.
+
+For example, if you have an external application and an internal application that need to access the example_service service, but the external application should be limited in how often it can query the service to assure no denial of service. If a rate limit policy is configured for the service when the internal application calls the service, the internal application is limited as well. Routes can solve this problem.
+
+In the example above, two routes can be created, say /external and /internal, and both routes can point to example_service. A policy can be configured to limit how often the /external route is used and the route can be communicated to the external client for use. When the external client tries to access the service via Kong Gateway using /external, they are rate limited. But when the internal client accesses the service using Kong Gateway using /internal, the internal client will not be limited.
+
+
+## How requests are routed
+<!-- Should there be a separate reference for the router vs the route entity? -->
+
+For each incoming request, {{site.base_gateway}} must determine which
+service gets to handle it based on the routes that are defined.  With
+release 3.0, {{site.base_gateway}} introduced a new router that can be
+running in two modes, the `traditional_compat` mode, which is
+configured like prior releases, and the `expressions` mode which uses
+a new configuration scheme. It is recommended that new deployments use
+the expressions router as it is more powerful and expressive.
+
+The default mode of the router is `traditional_compat` and the
+following sections describe how it operates. `traditional_compat`
+mode is designed to behave like the router in versions before
+{{site.base_gateway}} 3.x. For a description of the `expressions` mode, see
+[How to Configure Routes using Expressions](expressions).
+
+In general, the router orders all defined routes by their priority and
+uses the highest priority matching route to handle a request. If there
+are multiple matching routes with the same priority, it is not defined
+which of the matching routes will be used and {{site.base_gateway}}
+will use either of them according to how its internal data structures
+are organized.
+
+If a route contains prefix or regular expression paths, the priority
+of the route will be calculated separately for each of the paths and
+requests will be routed accordingly.
+
+In `traditional_compat` mode, the priority of a route is determined as
+follows, by the order of descending significance:
+
+1. Priority points
+2. Wildcard hosts
+3. Header count
+4. Regular expressions and prefix paths
+
+### Priority points
+
+For the presence of each of a route's `methods`, `host`, `headers`,
+and `snis`, a "priority point" will be added to the route. The number
+of "priority points" determines the overall order in which the routes
+will be considered. Routes with a higher "priority point" values will
+be considered before those with lower values. This means that if one
+route has `methods` defined, and second one has `methods` and
+`headers` defined, the second one will be considered before the first
+one.
+
+### Wildcard hosts
+
+Among the routes with the same "priority point" value, those that have
+any wildcard host specification will be considered after routes that
+don't have any wildcard host (or no host) specified.
+
+### Header count
+
+The resulting groups are sorted so the routes with a higher number of
+specified headers have higher priority than those with a lower number
+of headers.
+
+### Regular expressions and prefix paths
+
+Within the resulting groups of routes with equal priority, the router
+sorts the routes as follows:
+
+ - Routes that have a regular expression path are considered first and
+   are ordered by their `regex_priority` value. Routes with a higher
+   `regex_priority` are considered before routes with lower
+   `regex_priority` values.
+ - Routes that have no regular expression path are ordered by the
+   length of their paths. Routes with longer paths are considered
+   before routes with shorter paths.
+
+For a route with multiple paths, each path will be considered
+separately for priority determination. Effectively, this means that
+separate routes exists for each of the paths.
+
+## Regular expressions
+
+Regular expressions used in routes use more resources to evaluate than
+simple prefix routes. If many regular expressions must be evaluated
+to route a request, the latency introduced by {{site.base_gateway}}
+can suffer and its CPU usage can increase. In installations with
+thousands of routes, replacing regular expression routes by simple
+prefix routes can improve throughput and latency of
+{{site.base_gateway}}. If regex must be used because an exact
+path match must be performed, using the [expressions router](expressions)
+will significantly improve {{site.base_gateway}}'s performance in this case.
+
+Starting with version 3.0, {{site.base_gateway}} uses the regular
+expression engine shipped with the [Rust](https://docs.rs/regex/latest/regex/) programming language if the
+router is operating in `expressions` or `traditional_compatible` mode.
+Prior versions used the
+[PCRE library](https://www.pcre.org/original/doc/html/pcrepattern.html)
+to evaluate regular expression. While the two engines are largely
+compatible, subtle differences exist between the two. Refer to
+the documentation pertinent to the engine that you are using if you
+have problems getting regular expression routes to work.
+
+
+## Dynamically rewrite request URLs with routes
+
+Routes can be configured dynamically to rewrite the requested URL to a different URL for the upstream. For example, your legacy upstream endpoint may have a base URI like `/api/old/`. However, you want your publicly accessible API endpoint to now be named `/new/api`. To route the service's upstream endpoint to the new URL, you could set up a service with the path `/api/old/` and a route with the path `/new/api`. 
+
+{{site.base_gateway}} can also handle more complex URL rewriting cases by using regular expression capture groups in the route path and the [Request Transformer Advanced](/hub/kong-inc/request-transformer-advanced/) plugin. For example, this can be used when you must replace `/api/<function>/old` with `/new/api/<function>`.
+
+{{site.base_gateway}} 3.0.x or later ships with a new router. The new router can use regex expression capture groups to describe routes using a domain-specific language called Expressions. Expressions can describe routes or paths as patterns using regular expressions. For more information about how to configure the router using Expressions, see [How to configure routes using expressions](/gateway/{{page.release}}/key-concepts/routes/expressions/).

app/_kong_entities/service.md

@@ -0,0 +1,60 @@
+---
+title: Services
+entities:
+  - service
+
+content_type: reference
+
+related_resources:
+  - text: Routes entity
+    url: /kong-entities/route/
+---
+
+## What is a service?
+
+In {{site.base_gateway}}, a service is an abstraction of an existing upstream application. Services can store collections of objects like plugin configurations, and policies, and they can be associated with routes.
+
+When defining a service, the administrator provides a name and the upstream application connection information. The connection details can be provided in the url field as a single string, or by providing individual values for protocol, host, port, and path individually.
+
+Services have a one-to-many relationship with upstream applications, which allows administrators to create sophisticated traffic management behaviors.
+
+Services, in conjunction with [routes](/kong-entities/route/), let you expose your services to clients with {{site.base_gateway}}. {{site.base_gateway}} abstracts the service from the clients by using routes. Since the client always calls the route, changes to the services (like versioning) don’t impact how clients make the call. Routes also allow the same service to be used by multiple clients and apply different policies based on the route used.
+
+{% mermaid %}
+flowchart LR
+  A(API client)
+  B("`Route 
+  (/mock)`")
+  C("`Service
+  (example-service)`")
+  D(Upstream 
+  application)
+
+  A <--requests
+  responses--> B
+  subgraph id1 ["`
+  **KONG GATEWAY**`"]
+    B <--requests
+    responses--> C
+  end
+  C <--requests
+  responses--> D
+
+  style id1 rx:10,ry:10
+
+{% endmermaid %}
+
+{% contentfor setup_entity %}
+{% entity_example %}
+type: service
+data:
+  name: example-service
+  url: "http://httpbin.org"
+formats:
+  - admin-api
+  - konnect
+  - kic
+  - deck
+  - ui
+{% endentity_example %}
+{% endcontentfor %}

app/_kong_entities/target.md

@@ -0,0 +1,20 @@
+---
+title: Targets
+entities:
+  - target
+
+content_type: reference
+
+related_resources:
+  - text: 
+    url: 
+
+---
+
+## What is a target?
+
+
+## Use cases for targets
+
+The following are examples of common use cases for targets:
+

app/_kong_entities/upstream.md

@@ -0,0 +1,20 @@
+---
+title: Upstreams
+entities:
+  - upstream
+
+content_type: reference
+
+related_resources:
+  - text:
+    url: 
+---
+
+## What is an upstream?
+
+An upstream refers to the service applications sitting behind Kong Gateway, to which client requests are forwarded. In {{site.base_gateway}}, an upstream represents a virtual hostname and can be used to health check, circuit break, and load balance incoming requests over multiple [target](/kong-entity/target/) backend services.
+
+## Use cases for upstreams
+
+The following are examples of common use cases for upstreams:
+

app/_landing_pages/custom-plugins.yaml

@@ -0,0 +1,98 @@
+content:
+  - row:
+      - column:
+          - type: header
+            config:
+              type: h1
+              text: "Custom plugins"
+              align: center
+
+  - row:
+      - column:
+          - type: structured_text
+            config:
+              header:
+                text: "Developing custom plugins"
+              blocks:
+                - type: text
+                  text: | 
+                    Kong provides an entire development environment for developing plugins, 
+                    including Plugin Development Kits (or PDKs), database abstractions, migrations, and more.
+
+                    Plugins consist of modules interacting with the request/response objects or
+                    streams via a PDK to implement arbitrary logic. With custom plugins, you can configure these modules to provide custom functionality to Kong Gateway.
+
+                    To start creating your own plugins, review the [Getting Started documentation](/gateway/latest/plugin-development/get-started/),
+                    or see the following references:
+                    * [Plugin Development Kit reference](/gateway/latest/plugin-development/pdk/)
+                    * [Other Language Support](/gateway/latest/plugin-development/pluginserver/go/)
+
+
+  - row:
+      - column:
+          - type: structured_text
+            config:
+              header:
+                text: "Plugin Development Kits (PDKs)"
+              blocks:
+                - type: text
+                  text: "PDKs are sets of functions that a plugin can use to facilitate interactions between plugins
+                    and the core (or other components) of Kong. Kong provides PDKs in the following languages:"
+
+  - row:
+      - column:
+          - type: structured_text
+            config:
+              header:
+                text: "Lua"
+              blocks:
+                - type: text
+                  text: Something about the Lua PDK
+                - type: text
+                  text: <a href="/gateway/latest/plugin-development/">Lua PDK &rarr;</a>
+
+      - column:
+          - type: structured_text
+            config:
+              header:
+                text: "Go"
+              blocks:
+                - type: text
+                  text: Something about the Go PDK
+                - type: text
+                  text: <a href="/gateway/latest/plugin-development/pluginserver/go/">Go PDK &rarr;</a>
+      - column:
+          - type: structured_text
+            config:
+              header:
+                text: "Python"
+              blocks:
+                - type: text
+                  text: Something about the Python PDK
+                - type: text
+                  text: <a href="/gateway/latest/plugin-development/pluginserver/python/">Python PDK &rarr;</a>
+
+      - column:
+          - type: structured_text
+            config:
+              header:
+                text: "JavaScript"
+              blocks:
+                - type: text
+                  text: Something about the JavaScript PDK
+                - type: text
+                  text: <a href="/gateway/latest/plugin-development/pluginserver/javascript/">JavaScript PDK &rarr;</a>
+
+  - row:
+      - column:
+          - type: structured_text
+            config:
+              header:
+                text: "Third-party plugins"
+              blocks:
+                - type: text
+                  text: |
+                    Through partnerships with third parties, Kong lists some [third-party custom plugins](/hub/?support=third-party-partner%2Ccommunity) on the Kong Plugin Hub. 
+                    These plugins are maintained by Kong partners. 
+                    If you would like to have your plugin featured on the Kong Plugin Hub, we encourage you to become a [Kong Partner](https://konghq.com/partners/).
+