diff --git a/FEATURES.md b/FEATURES.md new file mode 100644 index 000000000..3a2ef93a1 --- /dev/null +++ b/FEATURES.md @@ -0,0 +1,113 @@ +# Features + +The Kong Gateway Operator (KGO) enables provisioning and lifecycle management +of [Kong Gateways][gw] on [Kubernetes][k8s] and also includes automation +for various related components (such as optional control-planes like the +[Kong Kubernetes Ingress Controller (KIC)][kic]) and configuration management +to deploy the Kong Gateway in various [deployment topologies][tops]. + +The subsections that follow are a list of the current [capabilities][caps] for +this operator which are actively developed & maintained. + +If you're interested in tracking or creating proposals for new features and +capabilities, please see our [KEPs][keps]. If you'd like to track the progress +of development for active features or get involved and contribute in them, check +our Github [milestones][mst] and [issues][iss]. + +## Kong Gateway Deployment & Configuration Management + +We support the ability to create (and destroy) `Gateways` using the Kubernetes +resource of the same name from [Kubernetes Gateway API][gwapi]. A `Gateway` is +comprised of multiple sub-components "under the hood" including the [Kong +Gateway][gw] (implemented via the [DataPlane API][dapi]) and the [Kong +Kubernetes Ingress Controller (KIC)][kic] (implemented via the [ControlPlane +API][capi]). + +Declarative configuration management for `Gateways` and the underlying +sub-components is provided by our [GatewayConfiguration API][gwcfg] which +includes (non-exhaustively) configuration options for the `ControlPlane` +and `DataPlane`. The `GatewayConfiguration` API can be attached to any +number of `Gateways`, enabling lifecycle management for a single `Gateway` +or for a group of `Gateways` from a single configuration. Multiple groups of +`Gateways` which need different and independent configuration can be managed +using multiple `GatewayConfigurations`. + +The `DataPlane` (e.g. the [Kong Gateway][gw]) can be configured and deployed +according to its available [deployment topologies][tops] using the +`GatewayConfiguration` API. The following topologies are currently supported: + +- [Kong Gateway][gw] in [dbless mode][dbl] + [Kong Ingress Controller (KIC)][kic] + +More configurations and topologies may become available in future releases. + +> **Note**: We currently don't support [traditional mode][trd] for the Kong +> Gateway as managing an independent database server in a Kubernetes cluster +> is non-trivial and out of scope for community support. + +> **Note**: While we don't currently support the Kong Gateway configured in +> [hybrid mode control-plane][hybrc] configuration, we do support +> [hybrid mode data-plane][hybrd] configuration using the `DataPlane` API. See +> below sections for details. + +## Gateway Upgrades & Downgrades + +We support user-triggered upgrades and downgrades of the [ControlPlane][capi] +and [DataPlane][dapi] sub-components of `Gateways` by configuring the +[corresponding versioning information][sp] in the [GatewayConfiguration][gwcfg]. + +Upgrades and downgrades of sub-components include transitions where existing +routes do not fail as automation is in place to "smoothly" wait for health +and `DataPlane` configuration before traffic is pivoted to the new version. + +## Gateway Horizontal Scaling + +We support user-triggered scaling of `DataPlanes` for `Gateway` deployments, +where the number of `Pods` can be adjusted up and down as needed according to +`DataPlane` resource utilization and traffic. + +> **Warning**: Currently this only affects the `DataPlane` `Pod` scaling. `ControlPlane` +> `Pod` scaling is a consideration for future releases. + +## Kong Hybrid Mode DataPlane + +The [Kong Gateway][gw] can be deployed in [hybrid mode][hybr] which allows +multiple gateways to be joined together for scaling and resiliency. This +operator supports attaching a [hybrid mode dataplane][hybrd] to an [existing +hybrid mode [control-plane][hybrc] using the `DataPlane` API. A quick start for +this feature can be in the [docs][quick-start-konnect]. + +## Kong AI Gateway + +We provide an `AIGateway` resource which can be used to deploy the [Kong +Gateway][gw] with our [AI Plugins][aiplugins] automatically configured and +enabled, to provide managed access to various AI models such as those provided +by OpenAI (e.g. ChatGPT). + +> **Note**: this feature is currently considered _experimental_ and is not +> enabled by default. The CRD must be deployed manually (it is not provided as +> part of our `kustomize` bundle): +> +> kubectl apply -f config/crd/bases/gateway-operator.konghq.com_aigateways.yaml +> +> Then see our `config/samples/aigateway.yaml` example to get started. + +[hybr]:https://docs.konghq.com/gateway/latest/production/deployment-topologies/hybrid-mode/ +[keps]:https://github.com/Kong/gateway-operator/tree/main/keps +[k8s]:https://kubernetes.io +[caps]:https://sdk.operatorframework.io/docs/overview/operator-capabilities/ +[mst]:https://github.com/kong/gateway-operator/milestone +[iss]:https://github.com/kong/gateway-operator/issues +[sp]:https://pkg.go.dev/github.com/kong/gateway-operator@main/apis/v1beta1#GatewayConfigurationSpec +[gwapi]:https://gateway-api.sigs.k8s.io +[gw]:https://github.com/kong/kong +[gwcfg]:https://pkg.go.dev/github.com/kong/gateway-operator@main/apis/v1beta1#GatewayConfiguration +[tops]:https://docs.konghq.com/gateway/latest/production/deployment-topologies/ +[dapi]:https://pkg.go.dev/github.com/kong/gateway-operator@main/apis/v1beta1#DataPlane +[kic]:https://github.com/kong/kubernetes-ingress-controller +[capi]:https://pkg.go.dev/github.com/kong/gateway-operator@main/apis/v1alpha1#ControlPlane +[dbl]:https://docs.konghq.com/gateway/latest/production/deployment-topologies/db-less-and-declarative-config/ +[trd]:https://docs.konghq.com/gateway/latest/production/deployment-topologies/traditional/ +[hybrd]:https://docs.konghq.com/gateway/latest/production/deployment-topologies/hybrid-mode/setup/#install-and-start-data-planes +[hybrc]:https://docs.konghq.com/gateway/latest/production/deployment-topologies/hybrid-mode/setup/#set-up-the-control-plane +[aiplugins]:https://konghq.com/products/kong-ai-gateway +[quick-start-konnect]:https://docs.konghq.com/gateway-operator/latest/get-started/konnect/install/ diff --git a/README.md b/README.md new file mode 100644 index 000000000..c8f86ac5c --- /dev/null +++ b/README.md @@ -0,0 +1,80 @@ +# [Kong Gateway Operator](https://docs.konghq.com/gateway-operator/latest/) + +KGO logo + +## Current Features + +The following features are considered supported: + +- Kong Gateway Deployment & Configuration Management using the [Gateway API][gwapi] +- Creation of [Kong Gateways][konggw] using the `DataPlane` API +- [Kong Gateways][konggw] upgrades, downgrades and autoscaling +- Creation of [Kong Ingress Controller][kic] instances using the `ControlPlane` API +- Hybrid Mode Attachment using the `DataPlane` API +- Configuration and management of `AIGateway`s (experimental feature) + +See our [Features Page](/FEATURES.md) for details on these capabilities. + +## Quick Start and documentation + +If you are eager to start with the operator, you can visit the quick start [section][docsqs] +of the documentation. Alternatively, the complete [docs][docs] provide a full and detailed +description of how to thoroughly use this project. + +## Development + +### Prerequisites + +In order to build the operator you'll have to have Go installed on your machine. +In order to do so, follow instructions on [its website][go-dev-site]. + +### Build process + +Building the operator should be as simple as running: + +```console +make build +``` + +This `Makefile` target will take care of everything from generating client side code, +generating Kubernetes manifests, downloading the dependencies and the tools used +in the build process and finally it will build the binary. + +After this step has finished successfully you should see the operator's binary `bin/manager`. + +You can also run it directly via `make run` which will run the operator on your +machine against the cluster that you have configured via your `KUBECONFIG`. + +## Seeking Help + +Please search through the posts on the [discussions page][disc] as it's likely +that another user has run into the same problem. If you don't find an answer, +please feel free to post a question. + +If you've found a bug, please [open an issue][issues]. + +For a feature request, please open an issue using the feature request template. + +You can also talk to the developers behind Kong in the [#kong][slack] channel on +the Kubernetes Slack server. + +## Community Meetings + +You can join bi-weekly meetups hosted by [Kong][kong] to ask questions, provide +feedback, or just to listen and hang out. + +See the [Online Meetups Page][kong-meet] to sign up and receive meeting invites +and [Zoom][zoom] links. + +[kong]:https://konghq.com +[konggw]:https://github.com/kong/kong +[kic]:https://github.com/kong/kubernetes-ingress-controller +[gwapi]:https://github.com/kubernetes-sigs/gateway-api +[go-dev-site]: https://go.dev/ +[disc]:https://github.com/kong/gateway-operator/discussions +[issues]:https://github.com/kong/kubernetes-ingress-controller/issues +[slack]:https://kubernetes.slack.com/messages/kong +[kong-meet]:https://konghq.com/online-meetups/ +[zoom]:https://zoom.us +[docs]:https://docs.konghq.com/gateway-operator/latest/ +[docsqs]:https://docs.konghq.com/gateway-operator/latest/get-started/kic/install/