diff --git a/site/README.md b/site/README.md deleted file mode 100644 index fac9f706d618..000000000000 --- a/site/README.md +++ /dev/null @@ -1,154 +0,0 @@ -# Docsy Example - -[Docsy][] is a [Hugo theme module][] for technical documentation sites, providing easy -site navigation, structure, and more. This **Docsy Example Project** uses the Docsy -theme component as a hugo module and provides a skeleton documentation structure for you to use. -You can clone/copy this project and edit it with your own content, or use it as an example. - -In this project, the Docsy theme component is pulled in as a Hugo module, together with other module dependencies: - -```console -$ hugo mod graph -hugo: collected modules in 566 ms -hugo: collected modules in 578 ms -github.com/google/docsy-example github.com/google/docsy@v0.7.1 -github.com/google/docsy-example github.com/google/docsy/dependencies@v0.7.1 -github.com/google/docsy/dependencies@v0.7.1 github.com/twbs/bootstrap@v5.2.3+incompatible -github.com/google/docsy/dependencies@v0.7.1 github.com/FortAwesome/Font-Awesome@v0.0.0-20230327165841-0698449d50f2 -``` - -You can find detailed theme instructions in the [Docsy user guide][]. - -This Docsy Example Project is hosted on [Netlify][] at [example.docsy.dev][]. -You can view deploy logs from the [deploy section of the project's Netlify -dashboard][deploys], or this [alternate dashboard][]. - -This is not an officially supported Google product. This project is currently maintained. - -## Using the Docsy Example Project as a template - -A simple way to get started is to use this project as a template, which gives you a site project that is set up and ready to use. To do this: - -1. Use the dropdown for switching branches/tags to change to the latest released tag `v0.7.1` - -2. Click **Use this template**. - -3. Select a name for your new project and click **Create repository from template**. - -4. Make your own local working copy of your new repo using git clone, replacing https://github.com/me/example.git with your repo’s web URL: - -```bash -git clone --depth 1 https://github.com/me/example.git -``` - -You can now edit your own versions of the site’s source files. - -If you want to do SCSS edits and want to publish these, you need to install `PostCSS` - -```bash -npm install -``` - -## Running the website locally - -Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io). -You can find out more about how to install Hugo for your environment in our -[Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation) guide. - -Once you've made your working copy of the site repo, from the repo root folder, run: - -```bash -hugo server -``` - -## Running a container locally - -You can run docsy-example inside a [Docker](https://docs.docker.com/) -container, the container runs with a volume bound to the `docsy-example` -folder. This approach doesn't require you to install any dependencies other -than [Docker Desktop](https://www.docker.com/products/docker-desktop) on -Windows and Mac, and [Docker Compose](https://docs.docker.com/compose/install/) -on Linux. - -1. Build the docker image - - ```bash - docker-compose build - ``` - -1. Run the built image - - ```bash - docker-compose up - ``` - - > NOTE: You can run both commands at once with `docker-compose up --build`. - -1. Verify that the service is working. - - Open your web browser and type `http://localhost:1313` in your navigation bar, - This opens a local instance of the docsy-example homepage. You can now make - changes to the docsy example and those changes will immediately show up in your - browser after you save. - -### Cleanup - -To stop Docker Compose, on your terminal window, press **Ctrl + C**. - -To remove the produced images run: - -```bash -docker-compose rm -``` -For more information see the [Docker Compose documentation][]. - -## Troubleshooting - -As you run the website locally, you may run into the following error: - -```console -$ hugo server -WARN 2023/06/27 16:59:06 Module "project" is not compatible with this Hugo version; run "hugo mod graph" for more information. -Start building sites … -hugo v0.101.0-466fa43c16709b4483689930a4f9ac8add5c9f66+extended windows/amd64 BuildDate=2022-06-16T07:09:16Z VendorInfo=gohugoio -Error: Error building site: "C:\Users\foo\path\to\docsy-example\content\en\_index.md:5:1": failed to extract shortcode: template for shortcode "blocks/cover" not found -Built in 27 ms -``` - -This error occurs if you are running an outdated version of Hugo. As of docsy theme version `v0.7.0`, hugo version `0.110.0` or higher is required. -See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo. - -Or you may be confronted with the following error: - -```console -$ hugo server - -INFO 2021/01/21 21:07:55 Using config file: -Building sites … INFO 2021/01/21 21:07:55 syncing static files to / -Built in 288 ms -Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache -``` - -This error occurs if you have not installed the extended version of Hugo. -See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo. - -Or you may encounter the following error: - -```console -$ hugo server - -Error: failed to download modules: binary with name "go" not found -``` - -This error occurs if you have not installed the `go` programming language on your system. -See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-go-language) of the user guide for instructions on how to install `go`. - - -[alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys -[deploys]: https://app.netlify.com/sites/docsy-example/deploys -[Docsy user guide]: https://docsy.dev/docs -[Docsy]: https://github.com/google/docsy -[example.docsy.dev]: https://example.docsy.dev -[Hugo theme module]: https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme -[Netlify]: https://netlify.com -[Docker Compose documentation]: https://docs.docker.com/compose/gettingstarted/ diff --git a/site/content/en/_index.md b/site/content/en/_index.md index 5921d1d97ff4..f4718c71a5b1 100644 --- a/site/content/en/_index.md +++ b/site/content/en/_index.md @@ -3,28 +3,30 @@ title: Envoy Gateway --- {{< blocks/cover title="Welcome to Envoy Gateway!" image_anchor="top" height="full" >}} - - Learn More + + Get Started - Download + Contributing

Manages Envoy Proxy as a Standalone or Kubernetes-based Application Gateway

{{< blocks/link-down color="info" >}} {{< /blocks/cover >}} {{% blocks/lead color="black" %}} -Envoy Gateway is an open source project for managing Envoy Proxy as a Standalone or Kubernetes-based Application Gateway. +Manage **Envoy Proxy** as a **Standalone** or **Kubernetes-based** Application Gateway. -Gateway API resources are used to dynamically provision and configure the managed Envoy Proxies. +**Gateway API** are used to **dynamically** provision and configure the managed Envoy Proxies. {{% /blocks/lead %}} -{{% blocks/lead %}} +{{% blocks/lead color="pink" %}} Lower barriers to adoption through **Expressive, Extensible, Role-oriented APIs** Support a multitude of **ingress** and **L7/L4** traffic routing -Common foundation for vendors to build **value-added** products without having to **re-engineer** +Common foundation for vendors to build **value-added** products + +Without having to **re-engineer** fundamental interactions. {{% /blocks/lead %}} diff --git a/site/content/en/about/featured-background.jpg b/site/content/en/about/featured-background.jpg deleted file mode 100644 index b1f8c56bc299..000000000000 Binary files a/site/content/en/about/featured-background.jpg and /dev/null differ diff --git a/site/content/en/about/index.md b/site/content/en/about/index.md deleted file mode 100644 index b363cdfd0256..000000000000 --- a/site/content/en/about/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: About Envoy Gateway -linkTitle: About -menu: {main: {weight: 10}} ---- - -{{% blocks/cover title="About Envoy Gateway" image_anchor="bottom" height="auto" %}} - -{{% /blocks/cover %}} - -{{% blocks/lead %}} - -Envoy Gateway is an open source project for managing **Envoy Proxy** as a standalone or Kubernetes-based application -gateway. **Gateway API** resources are used to dynamically provision and configure the managed Envoy Proxies. - -{{% /blocks/lead %}} - -{{% blocks/lead %}} - -The high-level goal of the Envoy Gateway project is to attract more users to Envoy by lowering barriers to adoption -through expressive, extensible, role-oriented APIs that support a multitude of ingress and L7/L4 traffic routing -use cases; and provide a common foundation for vendors to build value-added products without having to re-engineer -fundamental interactions. - -{{% /blocks/lead %}} diff --git a/site/content/en/blog/_index.md b/site/content/en/blog/_index.md index 95ccb91d5d9e..45f940a58238 100644 --- a/site/content/en/blog/_index.md +++ b/site/content/en/blog/_index.md @@ -1,6 +1,5 @@ --- title: Blog -menu: {main: {weight: 30}} --- This is the **blog** section. It has two categories: News and Releases. diff --git a/site/content/en/blog/compatibility/matrix/matrix.md b/site/content/en/blog/compatibility/matrix/matrix.md index 87a9be7a2fc7..4f7377b80af3 100644 --- a/site/content/en/blog/compatibility/matrix/matrix.md +++ b/site/content/en/blog/compatibility/matrix/matrix.md @@ -1,6 +1,6 @@ --- title: Versions -date: 2022-10-25 +date: 2022-10-01 description: This section includes Compatibility Matrix of Envoy Gateway. --- diff --git a/site/content/en/community/_index.md b/site/content/en/community/_index.md deleted file mode 100644 index 637654126083..000000000000 --- a/site/content/en/community/_index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Community -menu: {main: {weight: 60}} ---- - - - -{{% blocks/lead color="yellow" %}} - -## Getting Involved! - -We welcome contributions from the community. - -Please carefully review the -project [Goals](https://github.com/envoyproxy/gateway/blob/main/GOALS.md) and the -[Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md) before diving in. - -{{% /blocks/lead %}} diff --git a/site/content/en/docs/_index.md b/site/content/en/docs/_index.md deleted file mode 100644 index 1c01c7e5e4ee..000000000000 --- a/site/content/en/docs/_index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: "Documents" ---- diff --git a/site/content/en/docs/latest/helm/_index.md b/site/content/en/docs/latest/helm/_index.md deleted file mode 100644 index 8606fd7759c1..000000000000 --- a/site/content/en/docs/latest/helm/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: "Helm" -description: This section includes Helm related contents of Envoy Gateway. ---- diff --git a/site/content/en/docs/v0.5.0/_index.md b/site/content/en/docs/v0.5.0/_index.md deleted file mode 100644 index de8038ac4481..000000000000 --- a/site/content/en/docs/v0.5.0/_index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "Welcome to Envoy Gateway" -description: v0.5.0 version of Envoy Gateway -linktitle: v0.5.0 -weight: 2 ---- - -Envoy Gateway is an open source project for managing **Envoy Proxy** as a standalone or Kubernetes-based application -gateway. **Gateway API** resources are used to dynamically provision and configure the managed Envoy Proxies. diff --git a/site/content/en/docs/v0.5.0/helm/_index.md b/site/content/en/docs/v0.5.0/helm/_index.md deleted file mode 100644 index 8606fd7759c1..000000000000 --- a/site/content/en/docs/v0.5.0/helm/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: "Helm" -description: This section includes Helm related contents of Envoy Gateway. ---- diff --git a/site/content/en/docs/v0.4.0/_index.md b/site/content/en/latest/_index.md similarity index 67% rename from site/content/en/docs/v0.4.0/_index.md rename to site/content/en/latest/_index.md index 1f5904f3f6ad..3772c64b1ccc 100644 --- a/site/content/en/docs/v0.4.0/_index.md +++ b/site/content/en/latest/_index.md @@ -1,8 +1,10 @@ ---- -title: "Welcome to Envoy Gateway" -description: v0.4.0 version of Envoy Gateway -linktitle: v0.4.0 ---- ++++ +title = "Welcome to Envoy Gateway" +description = "Envoy Gateway Documents" + +[[cascade]] +type = "docs" ++++ Envoy Gateway is an open source project for managing **Envoy Proxy** as a standalone or Kubernetes-based application gateway. **Gateway API** resources are used to dynamically provision and configure the managed Envoy Proxies. diff --git a/site/content/en/docs/latest/api/_index.md b/site/content/en/latest/api/_index.md similarity index 87% rename from site/content/en/docs/latest/api/_index.md rename to site/content/en/latest/api/_index.md index 1d7c67c8c151..396d9ffcefcf 100644 --- a/site/content/en/docs/latest/api/_index.md +++ b/site/content/en/latest/api/_index.md @@ -1,4 +1,5 @@ --- title: "API" description: This section includes APIs of Envoy Gateway. +weight: 80 --- diff --git a/site/content/en/docs/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md similarity index 100% rename from site/content/en/docs/latest/api/extension_types.md rename to site/content/en/latest/api/extension_types.md diff --git a/site/content/en/docs/contribution-guidelines/CODEOWNERS.md b/site/content/en/latest/contributions/CODEOWNERS.md similarity index 100% rename from site/content/en/docs/contribution-guidelines/CODEOWNERS.md rename to site/content/en/latest/contributions/CODEOWNERS.md diff --git a/site/content/en/docs/contribution-guidelines/CODE_OF_CONDUCT.md b/site/content/en/latest/contributions/CODE_OF_CONDUCT.md similarity index 100% rename from site/content/en/docs/contribution-guidelines/CODE_OF_CONDUCT.md rename to site/content/en/latest/contributions/CODE_OF_CONDUCT.md diff --git a/site/content/en/docs/contribution-guidelines/CONTRIBUTING.md b/site/content/en/latest/contributions/CONTRIBUTING.md similarity index 100% rename from site/content/en/docs/contribution-guidelines/CONTRIBUTING.md rename to site/content/en/latest/contributions/CONTRIBUTING.md diff --git a/site/content/en/docs/contribution-guidelines/DEVELOP.md b/site/content/en/latest/contributions/DEVELOP.md similarity index 100% rename from site/content/en/docs/contribution-guidelines/DEVELOP.md rename to site/content/en/latest/contributions/DEVELOP.md diff --git a/site/content/en/docs/contribution-guidelines/DOCS.md b/site/content/en/latest/contributions/DOCS.md similarity index 100% rename from site/content/en/docs/contribution-guidelines/DOCS.md rename to site/content/en/latest/contributions/DOCS.md diff --git a/site/content/en/docs/contribution-guidelines/RELEASING.md b/site/content/en/latest/contributions/RELEASING.md similarity index 100% rename from site/content/en/docs/contribution-guidelines/RELEASING.md rename to site/content/en/latest/contributions/RELEASING.md diff --git a/site/content/en/docs/contribution-guidelines/_index.md b/site/content/en/latest/contributions/_index.md similarity index 79% rename from site/content/en/docs/contribution-guidelines/_index.md rename to site/content/en/latest/contributions/_index.md index 23a001304712..3255d996472a 100644 --- a/site/content/en/docs/contribution-guidelines/_index.md +++ b/site/content/en/latest/contributions/_index.md @@ -1,5 +1,5 @@ --- title: Get Involved -menu: {main: {weight: 40}} description: "This section includes contents related to **Contributions**" +weight: 100 --- diff --git a/site/content/en/docs/latest/design/_index.md b/site/content/en/latest/design/_index.md similarity index 100% rename from site/content/en/docs/latest/design/_index.md rename to site/content/en/latest/design/_index.md diff --git a/site/content/en/docs/latest/design/accesslog.md b/site/content/en/latest/design/accesslog.md similarity index 100% rename from site/content/en/docs/latest/design/accesslog.md rename to site/content/en/latest/design/accesslog.md diff --git a/site/content/en/docs/latest/design/bootstrap.md b/site/content/en/latest/design/bootstrap.md similarity index 100% rename from site/content/en/docs/latest/design/bootstrap.md rename to site/content/en/latest/design/bootstrap.md diff --git a/site/content/en/docs/latest/design/client-traffic-policy.md b/site/content/en/latest/design/client-traffic-policy.md similarity index 100% rename from site/content/en/docs/latest/design/client-traffic-policy.md rename to site/content/en/latest/design/client-traffic-policy.md diff --git a/site/content/en/docs/latest/design/config-api.md b/site/content/en/latest/design/config-api.md similarity index 100% rename from site/content/en/docs/latest/design/config-api.md rename to site/content/en/latest/design/config-api.md diff --git a/site/content/en/docs/latest/design/egctl.md b/site/content/en/latest/design/egctl.md similarity index 100% rename from site/content/en/docs/latest/design/egctl.md rename to site/content/en/latest/design/egctl.md diff --git a/site/content/en/docs/latest/design/envoy-patch-policy.md b/site/content/en/latest/design/envoy-patch-policy.md similarity index 100% rename from site/content/en/docs/latest/design/envoy-patch-policy.md rename to site/content/en/latest/design/envoy-patch-policy.md diff --git a/site/content/en/docs/latest/design/extending-envoy-gateway.md b/site/content/en/latest/design/extending-envoy-gateway.md similarity index 100% rename from site/content/en/docs/latest/design/extending-envoy-gateway.md rename to site/content/en/latest/design/extending-envoy-gateway.md diff --git a/site/content/en/docs/latest/design/gatewayapi-translator.md b/site/content/en/latest/design/gatewayapi-translator.md similarity index 100% rename from site/content/en/docs/latest/design/gatewayapi-translator.md rename to site/content/en/latest/design/gatewayapi-translator.md diff --git a/site/content/en/docs/contribution-guidelines/INITIAL_GOALS.md b/site/content/en/latest/design/goals.md similarity index 100% rename from site/content/en/docs/contribution-guidelines/INITIAL_GOALS.md rename to site/content/en/latest/design/goals.md diff --git a/site/content/en/docs/latest/design/local-envoy-gateway.md b/site/content/en/latest/design/local-envoy-gateway.md similarity index 100% rename from site/content/en/docs/latest/design/local-envoy-gateway.md rename to site/content/en/latest/design/local-envoy-gateway.md diff --git a/site/content/en/docs/latest/design/metrics.md b/site/content/en/latest/design/metrics.md similarity index 100% rename from site/content/en/docs/latest/design/metrics.md rename to site/content/en/latest/design/metrics.md diff --git a/site/content/en/docs/latest/design/pprof.md b/site/content/en/latest/design/pprof.md similarity index 100% rename from site/content/en/docs/latest/design/pprof.md rename to site/content/en/latest/design/pprof.md diff --git a/site/content/en/docs/latest/design/rate-limit.md b/site/content/en/latest/design/rate-limit.md similarity index 100% rename from site/content/en/docs/latest/design/rate-limit.md rename to site/content/en/latest/design/rate-limit.md diff --git a/site/content/en/docs/latest/design/request-authentication.md b/site/content/en/latest/design/request-authentication.md similarity index 100% rename from site/content/en/docs/latest/design/request-authentication.md rename to site/content/en/latest/design/request-authentication.md diff --git a/site/content/en/docs/latest/design/roadmap.md b/site/content/en/latest/design/roadmap.md similarity index 100% rename from site/content/en/docs/latest/design/roadmap.md rename to site/content/en/latest/design/roadmap.md diff --git a/site/content/en/docs/latest/design/system-design.md b/site/content/en/latest/design/system-design.md similarity index 100% rename from site/content/en/docs/latest/design/system-design.md rename to site/content/en/latest/design/system-design.md diff --git a/site/content/en/docs/latest/design/tcp-udp-design.md b/site/content/en/latest/design/tcp-udp-design.md similarity index 100% rename from site/content/en/docs/latest/design/tcp-udp-design.md rename to site/content/en/latest/design/tcp-udp-design.md diff --git a/site/content/en/docs/latest/design/tracing.md b/site/content/en/latest/design/tracing.md similarity index 100% rename from site/content/en/docs/latest/design/tracing.md rename to site/content/en/latest/design/tracing.md diff --git a/site/content/en/docs/latest/design/watching.md b/site/content/en/latest/design/watching.md similarity index 100% rename from site/content/en/docs/latest/design/watching.md rename to site/content/en/latest/design/watching.md diff --git a/site/content/en/latest/helm/_index.md b/site/content/en/latest/helm/_index.md new file mode 100644 index 000000000000..b4c6f79c6fda --- /dev/null +++ b/site/content/en/latest/helm/_index.md @@ -0,0 +1,5 @@ +--- +title: "Installation" +description: This section includes installation related contents of Envoy Gateway. +weight: 70 +--- diff --git a/site/content/en/docs/latest/helm/api.md b/site/content/en/latest/helm/api.md similarity index 99% rename from site/content/en/docs/latest/helm/api.md rename to site/content/en/latest/helm/api.md index ca33e2c5e1fe..130c82250ced 100644 --- a/site/content/en/docs/latest/helm/api.md +++ b/site/content/en/latest/helm/api.md @@ -1,5 +1,5 @@ --- -title: "Helm Chart Details" +title: "Helm Chart Values" --- ![Version: v0.0.0-latest](https://img.shields.io/badge/Version-v0.0.0--latest-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: latest](https://img.shields.io/badge/AppVersion-latest-informational?style=flat-square) diff --git a/site/content/en/docs/latest/images/architecture.png b/site/content/en/latest/images/architecture.png similarity index 100% rename from site/content/en/docs/latest/images/architecture.png rename to site/content/en/latest/images/architecture.png diff --git a/site/content/en/docs/latest/images/extension-example.png b/site/content/en/latest/images/extension-example.png similarity index 100% rename from site/content/en/docs/latest/images/extension-example.png rename to site/content/en/latest/images/extension-example.png diff --git a/site/content/en/docs/latest/user/_index.md b/site/content/en/latest/user/_index.md similarity index 100% rename from site/content/en/docs/latest/user/_index.md rename to site/content/en/latest/user/_index.md diff --git a/site/content/en/docs/latest/user/authn.md b/site/content/en/latest/user/authn.md similarity index 100% rename from site/content/en/docs/latest/user/authn.md rename to site/content/en/latest/user/authn.md diff --git a/site/content/en/docs/latest/user/customize-envoyproxy.md b/site/content/en/latest/user/customize-envoyproxy.md similarity index 100% rename from site/content/en/docs/latest/user/customize-envoyproxy.md rename to site/content/en/latest/user/customize-envoyproxy.md diff --git a/site/content/en/docs/latest/user/deployment-mode.md b/site/content/en/latest/user/deployment-mode.md similarity index 100% rename from site/content/en/docs/latest/user/deployment-mode.md rename to site/content/en/latest/user/deployment-mode.md diff --git a/site/content/en/docs/latest/user/egctl.md b/site/content/en/latest/user/egctl.md similarity index 100% rename from site/content/en/docs/latest/user/egctl.md rename to site/content/en/latest/user/egctl.md diff --git a/site/content/en/docs/latest/user/envoy-patch-policy.md b/site/content/en/latest/user/envoy-patch-policy.md similarity index 100% rename from site/content/en/docs/latest/user/envoy-patch-policy.md rename to site/content/en/latest/user/envoy-patch-policy.md diff --git a/site/content/en/docs/latest/user/gateway-address.md b/site/content/en/latest/user/gateway-address.md similarity index 100% rename from site/content/en/docs/latest/user/gateway-address.md rename to site/content/en/latest/user/gateway-address.md diff --git a/site/content/en/docs/latest/user/gateway-api-metrics.md b/site/content/en/latest/user/gateway-api-metrics.md similarity index 100% rename from site/content/en/docs/latest/user/gateway-api-metrics.md rename to site/content/en/latest/user/gateway-api-metrics.md diff --git a/site/content/en/docs/latest/user/gatewayapi-support.md b/site/content/en/latest/user/gatewayapi-support.md similarity index 100% rename from site/content/en/docs/latest/user/gatewayapi-support.md rename to site/content/en/latest/user/gatewayapi-support.md diff --git a/site/content/en/docs/latest/user/grpc-routing.md b/site/content/en/latest/user/grpc-routing.md similarity index 100% rename from site/content/en/docs/latest/user/grpc-routing.md rename to site/content/en/latest/user/grpc-routing.md diff --git a/site/content/en/docs/latest/user/http-redirect.md b/site/content/en/latest/user/http-redirect.md similarity index 100% rename from site/content/en/docs/latest/user/http-redirect.md rename to site/content/en/latest/user/http-redirect.md diff --git a/site/content/en/docs/latest/user/http-request-headers.md b/site/content/en/latest/user/http-request-headers.md similarity index 100% rename from site/content/en/docs/latest/user/http-request-headers.md rename to site/content/en/latest/user/http-request-headers.md diff --git a/site/content/en/docs/latest/user/http-request-mirroring.md b/site/content/en/latest/user/http-request-mirroring.md similarity index 100% rename from site/content/en/docs/latest/user/http-request-mirroring.md rename to site/content/en/latest/user/http-request-mirroring.md diff --git a/site/content/en/docs/latest/user/http-response-headers.md b/site/content/en/latest/user/http-response-headers.md similarity index 100% rename from site/content/en/docs/latest/user/http-response-headers.md rename to site/content/en/latest/user/http-response-headers.md diff --git a/site/content/en/docs/latest/user/http-routing.md b/site/content/en/latest/user/http-routing.md similarity index 100% rename from site/content/en/docs/latest/user/http-routing.md rename to site/content/en/latest/user/http-routing.md diff --git a/site/content/en/docs/latest/user/http-traffic-splitting.md b/site/content/en/latest/user/http-traffic-splitting.md similarity index 100% rename from site/content/en/docs/latest/user/http-traffic-splitting.md rename to site/content/en/latest/user/http-traffic-splitting.md diff --git a/site/content/en/docs/latest/user/http-urlrewrite.md b/site/content/en/latest/user/http-urlrewrite.md similarity index 100% rename from site/content/en/docs/latest/user/http-urlrewrite.md rename to site/content/en/latest/user/http-urlrewrite.md diff --git a/site/content/en/docs/latest/user/installation.md b/site/content/en/latest/user/installation.md similarity index 100% rename from site/content/en/docs/latest/user/installation.md rename to site/content/en/latest/user/installation.md diff --git a/site/content/en/docs/latest/user/multicluster-service.md b/site/content/en/latest/user/multicluster-service.md similarity index 100% rename from site/content/en/docs/latest/user/multicluster-service.md rename to site/content/en/latest/user/multicluster-service.md diff --git a/site/content/en/docs/latest/user/proxy-observability.md b/site/content/en/latest/user/proxy-observability.md similarity index 100% rename from site/content/en/docs/latest/user/proxy-observability.md rename to site/content/en/latest/user/proxy-observability.md diff --git a/site/content/en/docs/latest/user/quickstart.md b/site/content/en/latest/user/quickstart.md similarity index 100% rename from site/content/en/docs/latest/user/quickstart.md rename to site/content/en/latest/user/quickstart.md diff --git a/site/content/en/docs/latest/user/rate-limit.md b/site/content/en/latest/user/rate-limit.md similarity index 100% rename from site/content/en/docs/latest/user/rate-limit.md rename to site/content/en/latest/user/rate-limit.md diff --git a/site/content/en/docs/latest/user/secure-gateways.md b/site/content/en/latest/user/secure-gateways.md similarity index 100% rename from site/content/en/docs/latest/user/secure-gateways.md rename to site/content/en/latest/user/secure-gateways.md diff --git a/site/content/en/docs/latest/user/tcp-routing.md b/site/content/en/latest/user/tcp-routing.md similarity index 100% rename from site/content/en/docs/latest/user/tcp-routing.md rename to site/content/en/latest/user/tcp-routing.md diff --git a/site/content/en/docs/latest/user/tls-cert-manager.md b/site/content/en/latest/user/tls-cert-manager.md similarity index 100% rename from site/content/en/docs/latest/user/tls-cert-manager.md rename to site/content/en/latest/user/tls-cert-manager.md diff --git a/site/content/en/docs/latest/user/tls-passthrough.md b/site/content/en/latest/user/tls-passthrough.md similarity index 100% rename from site/content/en/docs/latest/user/tls-passthrough.md rename to site/content/en/latest/user/tls-passthrough.md diff --git a/site/content/en/docs/latest/user/tls-termination.md b/site/content/en/latest/user/tls-termination.md similarity index 100% rename from site/content/en/docs/latest/user/tls-termination.md rename to site/content/en/latest/user/tls-termination.md diff --git a/site/content/en/docs/latest/user/udp-routing.md b/site/content/en/latest/user/udp-routing.md similarity index 100% rename from site/content/en/docs/latest/user/udp-routing.md rename to site/content/en/latest/user/udp-routing.md diff --git a/site/content/en/docs/v0.2.0/_index.md b/site/content/en/v0.2.0/_index.md similarity index 67% rename from site/content/en/docs/v0.2.0/_index.md rename to site/content/en/v0.2.0/_index.md index 045c5cfab1c5..3772c64b1ccc 100644 --- a/site/content/en/docs/v0.2.0/_index.md +++ b/site/content/en/v0.2.0/_index.md @@ -1,8 +1,10 @@ ---- -title: "Welcome to Envoy Gateway" -description: v0.2.0 version of Envoy Gateway -linktitle: v0.2.0 ---- ++++ +title = "Welcome to Envoy Gateway" +description = "Envoy Gateway Documents" + +[[cascade]] +type = "docs" ++++ Envoy Gateway is an open source project for managing **Envoy Proxy** as a standalone or Kubernetes-based application gateway. **Gateway API** resources are used to dynamically provision and configure the managed Envoy Proxies. diff --git a/site/content/en/v0.2.0/contributions/CODEOWNERS.md b/site/content/en/v0.2.0/contributions/CODEOWNERS.md new file mode 100644 index 000000000000..9e596002bb33 --- /dev/null +++ b/site/content/en/v0.2.0/contributions/CODEOWNERS.md @@ -0,0 +1,18 @@ +--- +title: "Maintainers" +--- + +## The following maintainers, listed in alphabetical order, own everything + +- @AliceProxy +- @arkodg +- @Xunzhuo +- @zirain +- @qicz + +## Emeritus Maintainers + +- @danehans +- @alexgervais +- @skriss +- @youngnick diff --git a/site/content/en/v0.2.0/contributions/CODE_OF_CONDUCT.md b/site/content/en/v0.2.0/contributions/CODE_OF_CONDUCT.md new file mode 100644 index 000000000000..1f17c0889458 --- /dev/null +++ b/site/content/en/v0.2.0/contributions/CODE_OF_CONDUCT.md @@ -0,0 +1,5 @@ +--- +title: "Code of Conduct" +--- + +Gateway follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). diff --git a/site/content/en/v0.2.0/contributions/CONTRIBUTING.md b/site/content/en/v0.2.0/contributions/CONTRIBUTING.md new file mode 100644 index 000000000000..21dcd9a1941a --- /dev/null +++ b/site/content/en/v0.2.0/contributions/CONTRIBUTING.md @@ -0,0 +1,189 @@ +--- +title: "Contributing" +weight: 3 +--- + +We welcome contributions from the community. Please carefully review the [project goals](GOALS.md) +and following guidelines to streamline your contributions. + +## Communication + +* Before starting work on a major feature, please contact us via GitHub or Slack. We will ensure no + one else is working on it and ask you to open a GitHub issue. +* A "major feature" is defined as any change that is > 100 LOC altered (not including tests), or + changes any user-facing behavior. We will use the GitHub issue to discuss the feature and come to + agreement. This is to prevent your time being wasted, as well as ours. The GitHub review process + for major features is also important so that [affiliations with commit access](CODEOWNERS.md) can + come to agreement on the design. If it's appropriate to write a design document, the document must + be hosted either in the GitHub issue, or linked to from the issue and hosted in a world-readable + location. +* Small patches and bug fixes don't need prior communication. + +## Inclusivity + +The Envoy Gateway community has an explicit goal to be inclusive to all. As such, all PRs must adhere +to the following guidelines for all code, APIs, and documentation: + +* The following words and phrases are not allowed: + * *Whitelist*: use allowlist instead. + * *Blacklist*: use denylist or blocklist instead. + * *Master*: use primary instead. + * *Slave*: use secondary or replica instead. +* Documentation should be written in an inclusive style. The [Google developer + documentation](https://developers.google.com/style/inclusive-documentation) contains an excellent + reference on this topic. +* The above policy is not considered definitive and may be amended in the future as industry best + practices evolve. Additional comments on this topic may be provided by maintainers during code + review. + +## Submitting a PR + +* Fork the repo. +* Hack +* DCO sign-off each commit. This can be done with `git commit -s`. +* Submit your PR. +* Tests will automatically run for you. +* We will **not** merge any PR that is not passing tests. +* PRs are expected to have 100% test coverage for added code. This can be verified with a coverage + build. If your PR cannot have 100% coverage for some reason please clearly explain why when you + open it. +* Any PR that changes user-facing behavior **must** have associated documentation in the [docs](https://github.com/envoyproxy/gateway/tree/main/docs) folder of the repo as + well as the [changelog](../releases). +* All code comments and documentation are expected to have proper English grammar and punctuation. + If you are not a fluent English speaker (or a bad writer ;-)) please let us know and we will try + to find some help but there are no guarantees. +* Your PR title should be descriptive, and generally start with type that contains a subsystem name with `()` if necessary + and summary followed by a colon. format `chore/docs/feat/fix/refactor/style/test: summary`. + Examples: + * "docs: fix grammar error" + * "feat(translator): add new feature" + * "fix: fix xx bug" + * "chore: change ci & build tools etc" +* Your PR commit message will be used as the commit message when your PR is merged. You should + update this field if your PR diverges during review. +* Your PR description should have details on what the PR does. If it fixes an existing issue it + should end with "Fixes #XXX". +* If your PR is co-authored or based on an earlier PR from another contributor, + please attribute them with `Co-authored-by: name `. See + GitHub's [multiple author + guidance](https://help.github.com/en/github/committing-changes-to-your-project/creating-a-commit-with-multiple-authors) + for further details. +* When all tests are passing and all other conditions described herein are satisfied, a maintainer + will be assigned to review and merge the PR. +* Once you submit a PR, *please do not rebase it*. It's much easier to review if subsequent commits + are new commits and/or merges. We squash and merge so the number of commits you have in the PR + doesn't matter. +* We expect that once a PR is opened, it will be actively worked on until it is merged or closed. + We reserve the right to close PRs that are not making progress. This is generally defined as no + changes for 7 days. Obviously PRs that are closed due to lack of activity can be reopened later. + Closing stale PRs helps us to keep on top of all the work currently in flight. + +## Maintainer PR Review Policy + +* See [CODEOWNERS.md](CODEOWNERS.md) for the current list of maintainers. +* A maintainer representing a different affiliation from the PR owner is required to review and + approve the PR. +* When the project matures, it is expected that a "domain expert" for the code the PR touches should + review the PR. This person does not require commit access, just domain knowledge. +* The above rules may be waived for PRs which only update docs or comments, or trivial changes to + tests and tools (where trivial is decided by the maintainer in question). +* If there is a question on who should review a PR please discuss in Slack. +* Anyone is welcome to review any PR that they want, whether they are a maintainer or not. +* Please make sure that the PR title, commit message, and description are updated if the PR changes + significantly during review. +* Please **clean up the title and body** before merging. By default, GitHub fills the squash merge + title with the original title, and the commit body with every individual commit from the PR. + The maintainer doing the merge should make sure the title follows the guidelines above and should + overwrite the body with the original commit message from the PR (cleaning it up if necessary) + while preserving the PR author's final DCO sign-off. + +## Decision making + +This is a new and complex project, and we need to make a lot of decisions very quickly. +To this end, we've settled on this process for making (possibly contentious) decisions: + +* For decisions that need a record, we create an issue. +* In that issue, we discuss opinions, then a maintainer can call for a vote in a comment. +* Maintainers can cast binding votes on that comment by reacting or replying in another comment. +* Non-maintainer community members are welcome to cast non-binding votes by either of these methods. +* Voting will be resolved by simple majority. +* In the event of deadlocks, the question will be put to steering instead. + +## DCO: Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](https://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign-off when creating the git commit via `git commit -s`. + +If you want this to be automatic you can set up some aliases: + +```bash +git config --add alias.amend "commit -s --amend" +git config --add alias.c "commit -s" +``` + +## Fixing DCO + +If your PR fails the DCO check, it's necessary to fix the entire commit history in the PR. Best +practice is to [squash](https://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html) +the commit history to a single commit, append the DCO sign-off as described above, and [force +push](https://git-scm.com/docs/git-push#git-push---force). For example, if you have 2 commits in +your history: + +```bash +git rebase -i HEAD^^ +(interactive squash + DCO append) +git push origin -f +``` + +Note, that in general rewriting history in this way is a hindrance to the review process and this +should only be done to correct a DCO mistake. diff --git a/site/content/en/v0.2.0/contributions/DEVELOP.md b/site/content/en/v0.2.0/contributions/DEVELOP.md new file mode 100644 index 000000000000..a6fd3846f565 --- /dev/null +++ b/site/content/en/v0.2.0/contributions/DEVELOP.md @@ -0,0 +1,162 @@ +--- +title: "Developer Guide" +weight: 2 +--- + +Envoy Gateway is built using a [make][]-based build system. Our CI is based on [Github Actions][] using [workflows][]. + +## Prerequisites + +### go + +* Version: 1.20 +* Installation Guide: https://go.dev/doc/install + +### make + +* Recommended Version: 4.0 or later +* Installation Guide: https://www.gnu.org/software/make + +### docker + +* Optional when you want to build a Docker image or run `make` inside Docker. +* Recommended Version: 20.10.16 +* Installation Guide: https://docs.docker.com/engine/install + +### python3 + +* Need a `python3` program +* Must have a functioning `venv` module; this is part of the standard + library, but some distributions (such as Debian and Ubuntu) replace + it with a stub and require you to install a `python3-venv` package + separately. + +## Quickstart + +* Run `make help` to see all the available targets to build, test and run Envoy Gateway. + +### Building + +* Run `make build` to build all the binaries. +* Run `make build BINS="envoy-gateway"` to build the Envoy Gateway binary. +* Run `make build BINS="egctl"` to build the egctl binary. + +__Note:__ The binaries get generated in the `bin/$OS/$ARCH` directory, for example, `bin/linux/amd64/`. + +### Testing + +* Run `make test` to run the golang tests. + +* Run `make testdata` to generate the golden YAML testdata files. + +### Running Linters + +* Run `make lint` to make sure your code passes all the linter checks. +__Note:__ The `golangci-lint` configuration resides [here](https://github.com/envoyproxy/gateway/blob/main/tools/linter/golangci-lint/.golangci.yml). + +### Building and Pushing the Image + +* Run `IMAGE=docker.io/you/gateway-dev make image` to build the docker image. +* Run `IMAGE=docker.io/you/gateway-dev make push-multiarch` to build and push the multi-arch docker image. + +__Note:__ Replace `IMAGE` with your registry's image name. + +### Deploying Envoy Gateway for Test/Dev + +* Run `make create-cluster` to create a [Kind][] cluster. + +#### Option 1: Use the Latest [gateway-dev][] Image + +* Run `TAG=latest make kube-deploy` to deploy Envoy Gateway in the Kind cluster using the latest image. Replace `latest` + to use a different image tag. + +#### Option 2: Use a Custom Image + +* Run `make kube-install-image` to build an image from the tip of your current branch and load it in the Kind cluster. +* Run `IMAGE_PULL_POLICY=IfNotPresent make kube-deploy` to install Envoy Gateway into the Kind cluster using your custom image. + +### Deploying Envoy Gateway in Kubernetes + +* Run `TAG=latest make kube-deploy` to deploy Envoy Gateway using the latest image into a Kubernetes cluster (linked to + the current kube context). Preface the command with `IMAGE` or replace `TAG` to use a different Envoy Gateway image or + tag. +* Run `make kube-undeploy` to uninstall Envoy Gateway from the cluster. + +__Note:__ Envoy Gateway is tested against Kubernetes v1.24.0. + +### Demo Setup + +* Run `make kube-demo` to deploy a demo backend service, gatewayclass, gateway and httproute resource +(similar to steps outlined in the [Quickstart][] docs) and test the configuration. +* Run `make kube-demo-undeploy` to delete the resources created by the `make kube-demo` command. + +### Run Gateway API Conformance Tests + +The commands below deploy Envoy Gateway to a Kubernetes cluster and run the Gateway API conformance tests. Refer to the +Gateway API [conformance homepage][] to learn more about the tests. If Envoy Gateway is already installed, run +`TAG=latest make run-conformance` to run the conformance tests. + +#### On a Linux Host + +* Run `TAG=latest make conformance` to create a Kind cluster, install Envoy Gateway using the latest [gateway-dev][] + image, and run Gateway API conformance tests. + +#### On a Mac Host + +Since Mac doesn't support [directly exposing][] the Docker network to the Mac host, use one of the following +workarounds to run conformance tests: + +* Deploy your own Kubernetes cluster or use Docker Desktop with [Kubernetes support][] and then run + `TAG=latest make kube-deploy run-conformance`. This will install Envoy Gateway using the latest [gateway-dev][] image + to the Kubernetes cluster using the current kubectl context and run the conformance tests. Use `make kube-undeploy` to + uninstall Envoy Gateway. +* Install and run [Docker Mac Net Connect][mac_connect] and then run `TAG=latest make conformance`. + +__Note:__ Preface commands with `IMAGE` or replace `TAG` to use a different Envoy Gateway image or tag. If `TAG` +is unspecified, the short SHA of your current branch is used. + +### Debugging the Envoy Config + +An easy way to view the envoy config that Envoy Gateway is using is to port-forward to the admin interface port +(currently `19000`) on the Envoy deployment that corresponds to a Gateway so that it can be accessed locally. + +Get the name of the Envoy deployment. The following example is for Gateway `eg` in the `default` namespace: + +```shell +export ENVOY_DEPLOYMENT=$(kubectl get deploy -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Port forward the admin interface port: + +```shell +kubectl port-forward deploy/${ENVOY_DEPLOYMENT} -n envoy-gateway-system 19000:19000 +``` + +Now you are able to view the running Envoy configuration by navigating to `127.0.0.1:19000/config_dump`. + +There are many other endpoints on the [Envoy admin interface][] that may be helpful when debugging. + +### JWT Testing + +An example [JSON Web Token (JWT)][jwt] and [JSON Web Key Set (JWKS)][jwks] are used for the [request authentication][] +user guide. The JWT was created by the [JWT Debugger][], using the `RS256` algorithm. The public key from the JWTs +verify signature was copied to [JWK Creator][] for generating the JWK. The JWK Creator was configured with matching +settings, i.e. `Signing` public key use and the `RS256` algorithm. The generated JWK was wrapped in a JWKS structure +and is hosted in the repo. + +[Quickstart]: https://github.com/envoyproxy/gateway/blob/main/docs/latest/user/quickstart.md +[make]: https://www.gnu.org/software/make/ +[Github Actions]: https://docs.github.com/en/actions +[workflows]: https://github.com/envoyproxy/gateway/tree/main/.github/workflows +[Kind]: https://kind.sigs.k8s.io/ +[conformance homepage]: https://gateway-api.sigs.k8s.io/concepts/conformance/ +[directly exposing]: https://kind.sigs.k8s.io/docs/user/loadbalancer/ +[Kubernetes support]: https://docs.docker.com/desktop/kubernetes/ +[gateway-dev]: https://hub.docker.com/r/envoyproxy/gateway-dev/tags +[mac_connect]: https://github.com/chipmk/docker-mac-net-connect +[Envoy admin interface]: https://www.envoyproxy.io/docs/envoy/latest/operations/admin#operations-admin-interface +[jwt]: https://tools.ietf.org/html/rfc7519 +[jwks]: https://tools.ietf.org/html/rfc7517 +[request authentication]: https://gateway.envoyproxy.io/latest/user/authn.html +[JWT Debugger]: https://jwt.io/ +[JWK Creator]: https://russelldavies.github.io/jwk-creator/ diff --git a/site/content/en/v0.2.0/contributions/DOCS.md b/site/content/en/v0.2.0/contributions/DOCS.md new file mode 100644 index 000000000000..1abae95763c5 --- /dev/null +++ b/site/content/en/v0.2.0/contributions/DOCS.md @@ -0,0 +1,65 @@ +--- +title: "Working on the Envoy Gateway Docs" +--- + +The documentation for the Envoy Gateway lives in the `docs/` directory. Any +individual document can be written using either [reStructuredText] or [Markdown], +you can choose the format that you're most comfortable with when working on the +documentation. + +## Documentation Structure + +We supported the versioned Docs now, the directory name under docs represents +the version of docs. The root of the latest site is in `docs/latest/index.rst`. +This is probably where to start if you're trying to understand how things fit together. + +Note that the new contents should be added to `docs/latest` and will be cut off at +the next release. The contents under `docs/v0.2.0` are auto-generated, +and usually do not need to make changes to them, unless if you find the current release pages have +some incorrect contents. If so, you should send a PR to update contents both of `docs/latest` +and `docs/v0.2.0`. + +It's important to note that a given document _must_ have a reference in some +`.. toctree::` section for the document to be reachable. Not everything needs +to be in `docs/index.rst`'s `toctree` though. + +You can access the website which represents the current release in default, +and you can access the website which contains the latest version changes in +[Here][latest-website] or at the footer of the pages. + +## Documentation Workflow + +To work with the docs, just edit reStructuredText or Markdown files in `docs`, +then run + +```bash +make docs +``` + +This will create `docs/html` with the built HTML pages. You can view the docs +either simply by pointing a web browser at the `file://` path to your +`docs/html`, or by firing up a static webserver from that directory, e.g. + +``` shell +make docs-serve +``` + +If you want to generate a new release version of the docs, like `v0.3.0`, then run + +```bash +make docs-release TAG=v0.3.0 +``` + +This will update the VERSION file at the project root, which records current release version, +and it will be used in the pages version context and binary version output. Also, this will generate +new dir `docs/v0.3.0`, which contains docs at v0.3.0 and updates artifact links to `v0.3.0` +in all files under `docs/v0.3.0/user`, like `quickstart.md`, `http-routing.md` and etc. + +## Publishing Docs + +Whenever docs are pushed to `main`, CI will publish the built docs to GitHub +Pages. For more details, see `.github/workflows/docs.yaml`. + +[reStructuredText]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html +[Markdown]: https://daringfireball.net/projects/markdown/syntax +[latest-website]: https://gateway.envoyproxy.io/latest diff --git a/site/content/en/v0.2.0/contributions/RELEASING.md b/site/content/en/v0.2.0/contributions/RELEASING.md new file mode 100644 index 000000000000..617baf1933e0 --- /dev/null +++ b/site/content/en/v0.2.0/contributions/RELEASING.md @@ -0,0 +1,230 @@ +--- +title: "Release Process" +--- + +This document guides maintainers through the process of creating an Envoy Gateway release. + +- [Release Candidate](#release-candidate) +- [Minor Release](#minor-release) +- [Announce the Release](#announce-the-release) + +## Release Candidate + +The following steps should be used for creating a release candidate. + +### Prerequisites + +- Permissions to push to the Envoy Gateway repository. + +Set environment variables for use in subsequent steps: + +```shell +export MAJOR_VERSION=0 +export MINOR_VERSION=3 +export RELEASE_CANDIDATE_NUMBER=1 +export GITHUB_REMOTE=origin +``` + +1. Clone the repo, checkout the `main` branch, ensure it’s up-to-date, and your local branch is clean. +2. Create a topic branch for adding the release notes and updating the [VERSION][] file with the release version. Refer to previous [release notes][] and [VERSION][] for additional details. +3. Sign, commit, and push your changes to your fork. +4. Submit a [Pull Request][] to merge the changes into the `main` branch. Do not proceed until your PR has merged and + the [Build and Test][] has successfully completed. +5. Create a new release branch from `main`. The release branch should be named + `release/v${MAJOR_VERSION}.${MINOR_VERSION}`, e.g. `release/v0.3`. + + ```shell + git checkout -b release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +6. Push the branch to the Envoy Gateway repo. + + ```shell + git push ${GITHUB_REMOTE} release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +7. Create a topic branch for updating the Envoy proxy image to the tag supported by the release. Reference [PR #958][] + for additional details on updating the image tag. +8. Sign, commit, and push your changes to your fork. +9. Submit a [Pull Request][] to merge the changes into the `release/v${MAJOR_VERSION}.${MINOR_VERSION}` branch. Do not + proceed until your PR has merged into the release branch and the [Build and Test][] has completed for your PR. +10. Ensure your release branch is up-to-date and tag the head of your release branch with the release candidate number. + + ```shell + git tag -a v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} -m 'Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} Release Candidate' + ``` + +11. Push the tag to the Envoy Gateway repository. + + ```shell + git push ${GITHUB_REMOTE} v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} + ``` + +12. This will trigger the [release GitHub action][] that generates the release, release artifacts, etc. +13. Confirm that the [release workflow][] completed successfully. +14. Confirm that the Envoy Gateway [image][] with the correct release tag was published to Docker Hub. +15. Confirm that the [release][] was created. +16. Note that the [Quickstart Guide][] references are __not__ updated for release candidates. However, test + the quickstart steps using the release candidate by manually updating the links. +17. [Generate][] the GitHub changelog. +18. Ensure you check the "This is a pre-release" checkbox when editing the GitHub release. +19. If you find any bugs in this process, please create an issue. + +### Setup cherry picker action + +After release branch cut, RM (Release Manager) should add job [cherrypick action](../../../.github/workflows/cherrypick.yaml) for target release. + +Configuration looks like following: + +```yaml + cherry_pick_release_v0_4: + runs-on: ubuntu-latest + name: Cherry pick into release-v0.4 + if: ${{ contains(github.event.pull_request.labels.*.name, 'cherrypick/release-v0.4') && github.event.pull_request.merged == true }} + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + fetch-depth: 0 + - name: Cherry pick into release/v0.4 + uses: carloscastrojumo/github-cherry-pick-action@v1.0.9 + with: + branch: release/v0.4 + title: "[release/v0.4] {old_title}" + body: "Cherry picking #{old_pull_request_id} onto release/v0.4" + labels: | + cherrypick/release-v0.4 + # put release manager here + reviewers: | + AliceProxy +``` + +Replace `v0.4` with real branch name, and `AliceProxy` with the real name of RM. + +## Minor Release + +The following steps should be used for creating a minor release. + +### Prerequisites + +- Permissions to push to the Envoy Gateway repository. +- A release branch that has been cut from the corresponding release candidate. Refer to the + [Release Candidate](#release-candidate) section for additional details on cutting a release candidate. + +Set environment variables for use in subsequent steps: + +```shell +export MAJOR_VERSION=0 +export MINOR_VERSION=3 +export GITHUB_REMOTE=origin +``` + +1. Clone the repo, checkout the `main` branch, ensure it’s up-to-date, and your local branch is clean. +2. Create a topic branch for adding the release notes, release announcement, and versioned release docs. + + 1. Create the release notes. Reference previous [release notes][] for additional details. __Note:__ The release + notes should be an accumulation of the release candidate release notes and any changes since the release + candidate. + 2. Create a release announcement. Refer to [PR #635] as an example release announcement. + 3. Include the release in the compatibility matrix. Refer to [PR #1002] as an example. + 4. Generate the versioned release docs: + + ``` shell + make docs-release TAG=v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +3. Sign, commit, and push your changes to your fork. +4. Submit a [Pull Request][] to merge the changes into the `main` branch. Do not proceed until all your PRs have merged + and the [Build and Test][] has completed for your final PR. + +5. Checkout the release branch. + + ```shell + git checkout -b release/v${MAJOR_VERSION}.${MINOR_VERSION} $GITHUB_REMOTE/release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +6. If the tip of the release branch does not match the tip of `main`, perform the following: + + 1. Create a topic branch from the release branch. + 2. Cherry-pick the commits from `main` that differ from the release branch. + 3. Run tests locally, e.g. `make lint`. + 4. Sign, commit, and push your topic branch to your Envoy Gateway fork. + 5. Submit a PR to merge the topic from of your fork into the Envoy Gateway release branch. + 6. Do not proceed until the PR has merged and CI passes for the merged PR. + 7. If you are still on your topic branch, change to the release branch: + + ```shell + git checkout release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + + 8. Ensure your local release branch is up-to-date: + + ```shell + git pull $GITHUB_REMOTE release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +7. Tag the head of your release branch with the release tag. For example: + + ```shell + git tag -a v${MAJOR_VERSION}.${MINOR_VERSION}.0 -m 'Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION}.0 Release' + ``` + + __Note:__ The tag version differs from the release branch by including the `.0` patch version. + +8. Push the tag to the Envoy Gateway repository. + + ```shell + git push origin v${MAJOR_VERSION}.${MINOR_VERSION}.0 + ``` + +9. This will trigger the [release GitHub action][] that generates the release, release artifacts, etc. +10. Confirm that the [release workflow][] completed successfully. +11. Confirm that the Envoy Gateway [image][] with the correct release tag was published to Docker Hub. +12. Confirm that the [release][] was created. +13. Confirm that the steps in the [Quickstart Guide][] work as expected. +14. [Generate][] the GitHub changelog and include the following text at the beginning of the release page: + + ```console + # Release Announcement + + Check out the [v${MAJOR_VERSION}.${MINOR_VERSION} release announcement] + (https://gateway.envoyproxy.io/releases/v${MAJOR_VERSION}.${MINOR_VERSION}.html) to learn more about the release. + ``` + +If you find any bugs in this process, please create an issue. + +## Announce the Release + +It's important that the world knows about the release. Use the following steps to announce the release. + +1. Set the release information in the Envoy Gateway Slack channel. For example: + + ```shell + Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION} has been released: https://github.com/envoyproxy/gateway/releases/tag/v${MAJOR_VERSION}.${MINOR_VERSION}.0 + ``` + +2. Send a message to the Envoy Gateway Slack channel. For example: + + ```shell + On behalf of the entire Envoy Gateway community, I am pleased to announce the release of Envoy Gateway + v${MAJOR_VERSION}.${MINOR_VERSION}. A big thank you to all the contributors that made this release possible. + Refer to the official v${MAJOR_VERSION}.${MINOR_VERSION} announcement for release details and the project docs + to start using Envoy Gateway. + ... + ``` + + Link to the GitHub release and release announcement page that highlights the release. + +[release notes]: https://github.com/envoyproxy/gateway/tree/main/release-notes +[Pull Request]: https://github.com/envoyproxy/gateway/pulls +[Quickstart Guide]: https://github.com/envoyproxy/gateway/blob/main/docs/user/quickstart.md +[Build and Test]: https://github.com/envoyproxy/gateway/blob/main/.github/workflows/build_and_test.yaml +[release GitHub action]: https://github.com/envoyproxy/gateway/blob/main/.github/workflows/release.yaml +[release workflow]: https://github.com/envoyproxy/gateway/actions/workflows/release.yaml +[image]: https://hub.docker.com/r/envoyproxy/gateway/tags +[release]: https://github.com/envoyproxy/gateway/releases +[Generate]: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes +[PR #635]: https://github.com/envoyproxy/gateway/pull/635 +[PR #958]: https://github.com/envoyproxy/gateway/pull/958 +[PR #1002]: https://github.com/envoyproxy/gateway/pull/1002 +[VERSION]: https://github.com/envoyproxy/gateway/blob/main/VERSION diff --git a/site/content/en/v0.2.0/contributions/_index.md b/site/content/en/v0.2.0/contributions/_index.md new file mode 100644 index 000000000000..3255d996472a --- /dev/null +++ b/site/content/en/v0.2.0/contributions/_index.md @@ -0,0 +1,5 @@ +--- +title: Get Involved +description: "This section includes contents related to **Contributions**" +weight: 100 +--- diff --git a/site/content/en/docs/v0.2.0/design/_index.md b/site/content/en/v0.2.0/design/_index.md similarity index 100% rename from site/content/en/docs/v0.2.0/design/_index.md rename to site/content/en/v0.2.0/design/_index.md diff --git a/site/content/en/docs/v0.2.0/design/config-api.md b/site/content/en/v0.2.0/design/config-api.md similarity index 100% rename from site/content/en/docs/v0.2.0/design/config-api.md rename to site/content/en/v0.2.0/design/config-api.md diff --git a/site/content/en/docs/v0.2.0/design/gatewayapi-translator.md b/site/content/en/v0.2.0/design/gatewayapi-translator.md similarity index 100% rename from site/content/en/docs/v0.2.0/design/gatewayapi-translator.md rename to site/content/en/v0.2.0/design/gatewayapi-translator.md diff --git a/site/content/en/GOALS.md b/site/content/en/v0.2.0/design/goals.md similarity index 99% rename from site/content/en/GOALS.md rename to site/content/en/v0.2.0/design/goals.md index be4bdb76f6bc..fd38b2004c61 100644 --- a/site/content/en/GOALS.md +++ b/site/content/en/v0.2.0/design/goals.md @@ -1,8 +1,8 @@ --- title: "Goals" +weight: 1 --- - The high-level goal of the Envoy Gateway project is to attract more users to Envoy by lowering barriers to adoption through expressive, extensible, role-oriented APIs that support a multitude of ingress and L7/L4 traffic routing use cases; and provide a common foundation for vendors to build value-added products without having to re-engineer @@ -11,6 +11,7 @@ fundamental interactions. ## Objectives ### Expressive API + The Envoy Gateway project will expose a simple and expressive API, with defaults set for many capabilities. The API will be the Kubernetes-native [Gateway API][], plus Envoy-specific extensions and extension points. This @@ -26,6 +27,7 @@ This expressive API will not be implemented by Envoy Proxy, but rather an offici on top. ### Batteries included + Envoy Gateway will simplify how Envoy is deployed and managed, allowing application developers to focus on delivering core business value. @@ -40,6 +42,7 @@ will enjoy a simplified management model that doesn't require extensive knowledg operate. ### All environments + Envoy Gateway will support running natively in Kubernetes environments as well as non-Kubernetes deployments. Initially, Kubernetes will receive the most focus, with the aim of having Envoy Gateway become the de facto @@ -47,6 +50,7 @@ standard for Kubernetes ingress supporting the [Gateway API][]. Additional goals include multi-cluster support and various runtime environments. ### Extensibility + Vendors will have the ability to provide value-added products built on the Envoy Gateway foundation. It will remain easy for end-users to leverage common Envoy Proxy extension points such as providing an implementation @@ -60,21 +64,26 @@ allowing vendors to shift to a higher management plane layer. ## Non-objectives ### Cannibalize vendor models + Vendors need to have the ability to drive commercial value, so the goal is not to cannibalize any existing vendor monetization model, though some vendors may be affected by it. ### Disrupt current Envoy usage patterns + Envoy Gateway is purely an additive convenience layer and is not meant to disrupt any usage pattern of any user with Envoy Proxy, xDS, or go-control-plane. ## Personas + _In order of priority_ ### 1. Application developer + The application developer spends the majority of their time developing business logic code. They require the ability to manage access to their application. ### 2. Infrastructure administrators + The infrastructure administrators are responsible for the installation, maintenance, and operation of API gateways appliances in infrastructure, such as CRDs, roles, service accounts, certificates, etc. Infrastructure administrators support the needs of application developers by managing instances of Envoy Gateway. diff --git a/site/content/en/docs/v0.2.0/design/roadmap.md b/site/content/en/v0.2.0/design/roadmap.md similarity index 100% rename from site/content/en/docs/v0.2.0/design/roadmap.md rename to site/content/en/v0.2.0/design/roadmap.md diff --git a/site/content/en/docs/v0.2.0/design/system-design.md b/site/content/en/v0.2.0/design/system-design.md similarity index 100% rename from site/content/en/docs/v0.2.0/design/system-design.md rename to site/content/en/v0.2.0/design/system-design.md diff --git a/site/content/en/docs/v0.2.0/design/watching.md b/site/content/en/v0.2.0/design/watching.md similarity index 100% rename from site/content/en/docs/v0.2.0/design/watching.md rename to site/content/en/v0.2.0/design/watching.md diff --git a/site/content/en/docs/v0.2.0/images/architecture.png b/site/content/en/v0.2.0/images/architecture.png similarity index 100% rename from site/content/en/docs/v0.2.0/images/architecture.png rename to site/content/en/v0.2.0/images/architecture.png diff --git a/site/content/en/docs/v0.2.0/user/_index.md b/site/content/en/v0.2.0/user/_index.md similarity index 100% rename from site/content/en/docs/v0.2.0/user/_index.md rename to site/content/en/v0.2.0/user/_index.md diff --git a/site/content/en/docs/v0.2.0/user/http-redirect.md b/site/content/en/v0.2.0/user/http-redirect.md similarity index 100% rename from site/content/en/docs/v0.2.0/user/http-redirect.md rename to site/content/en/v0.2.0/user/http-redirect.md diff --git a/site/content/en/docs/v0.2.0/user/http-request-headers.md b/site/content/en/v0.2.0/user/http-request-headers.md similarity index 100% rename from site/content/en/docs/v0.2.0/user/http-request-headers.md rename to site/content/en/v0.2.0/user/http-request-headers.md diff --git a/site/content/en/docs/v0.2.0/user/http-routing.md b/site/content/en/v0.2.0/user/http-routing.md similarity index 100% rename from site/content/en/docs/v0.2.0/user/http-routing.md rename to site/content/en/v0.2.0/user/http-routing.md diff --git a/site/content/en/docs/v0.2.0/user/http-traffic-splitting.md b/site/content/en/v0.2.0/user/http-traffic-splitting.md similarity index 100% rename from site/content/en/docs/v0.2.0/user/http-traffic-splitting.md rename to site/content/en/v0.2.0/user/http-traffic-splitting.md diff --git a/site/content/en/docs/v0.2.0/user/quickstart.md b/site/content/en/v0.2.0/user/quickstart.md similarity index 100% rename from site/content/en/docs/v0.2.0/user/quickstart.md rename to site/content/en/v0.2.0/user/quickstart.md diff --git a/site/content/en/docs/v0.2.0/user/secure-gateways.md b/site/content/en/v0.2.0/user/secure-gateways.md similarity index 100% rename from site/content/en/docs/v0.2.0/user/secure-gateways.md rename to site/content/en/v0.2.0/user/secure-gateways.md diff --git a/site/content/en/docs/v0.2.0/user/tls-passthrough.md b/site/content/en/v0.2.0/user/tls-passthrough.md similarity index 100% rename from site/content/en/docs/v0.2.0/user/tls-passthrough.md rename to site/content/en/v0.2.0/user/tls-passthrough.md diff --git a/site/content/en/docs/v0.3.0/_index.md b/site/content/en/v0.3.0/_index.md similarity index 67% rename from site/content/en/docs/v0.3.0/_index.md rename to site/content/en/v0.3.0/_index.md index 35bb3ad518fb..3772c64b1ccc 100644 --- a/site/content/en/docs/v0.3.0/_index.md +++ b/site/content/en/v0.3.0/_index.md @@ -1,8 +1,10 @@ ---- -title: "Welcome to Envoy Gateway" -description: v0.3.0 version of Envoy Gateway -linktitle: v0.3.0 ---- ++++ +title = "Welcome to Envoy Gateway" +description = "Envoy Gateway Documents" + +[[cascade]] +type = "docs" ++++ Envoy Gateway is an open source project for managing **Envoy Proxy** as a standalone or Kubernetes-based application gateway. **Gateway API** resources are used to dynamically provision and configure the managed Envoy Proxies. diff --git a/site/content/en/docs/v0.5.0/api/_index.md b/site/content/en/v0.3.0/api/_index.md similarity index 87% rename from site/content/en/docs/v0.5.0/api/_index.md rename to site/content/en/v0.3.0/api/_index.md index 1d7c67c8c151..396d9ffcefcf 100644 --- a/site/content/en/docs/v0.5.0/api/_index.md +++ b/site/content/en/v0.3.0/api/_index.md @@ -1,4 +1,5 @@ --- title: "API" description: This section includes APIs of Envoy Gateway. +weight: 80 --- diff --git a/site/content/en/docs/v0.3.0/api/config_types.md b/site/content/en/v0.3.0/api/config_types.md similarity index 100% rename from site/content/en/docs/v0.3.0/api/config_types.md rename to site/content/en/v0.3.0/api/config_types.md diff --git a/site/content/en/docs/v0.3.0/api/extension_types.md b/site/content/en/v0.3.0/api/extension_types.md similarity index 100% rename from site/content/en/docs/v0.3.0/api/extension_types.md rename to site/content/en/v0.3.0/api/extension_types.md diff --git a/site/content/en/v0.3.0/contributions/CODEOWNERS.md b/site/content/en/v0.3.0/contributions/CODEOWNERS.md new file mode 100644 index 000000000000..9e596002bb33 --- /dev/null +++ b/site/content/en/v0.3.0/contributions/CODEOWNERS.md @@ -0,0 +1,18 @@ +--- +title: "Maintainers" +--- + +## The following maintainers, listed in alphabetical order, own everything + +- @AliceProxy +- @arkodg +- @Xunzhuo +- @zirain +- @qicz + +## Emeritus Maintainers + +- @danehans +- @alexgervais +- @skriss +- @youngnick diff --git a/site/content/en/v0.3.0/contributions/CODE_OF_CONDUCT.md b/site/content/en/v0.3.0/contributions/CODE_OF_CONDUCT.md new file mode 100644 index 000000000000..1f17c0889458 --- /dev/null +++ b/site/content/en/v0.3.0/contributions/CODE_OF_CONDUCT.md @@ -0,0 +1,5 @@ +--- +title: "Code of Conduct" +--- + +Gateway follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). diff --git a/site/content/en/v0.3.0/contributions/CONTRIBUTING.md b/site/content/en/v0.3.0/contributions/CONTRIBUTING.md new file mode 100644 index 000000000000..21dcd9a1941a --- /dev/null +++ b/site/content/en/v0.3.0/contributions/CONTRIBUTING.md @@ -0,0 +1,189 @@ +--- +title: "Contributing" +weight: 3 +--- + +We welcome contributions from the community. Please carefully review the [project goals](GOALS.md) +and following guidelines to streamline your contributions. + +## Communication + +* Before starting work on a major feature, please contact us via GitHub or Slack. We will ensure no + one else is working on it and ask you to open a GitHub issue. +* A "major feature" is defined as any change that is > 100 LOC altered (not including tests), or + changes any user-facing behavior. We will use the GitHub issue to discuss the feature and come to + agreement. This is to prevent your time being wasted, as well as ours. The GitHub review process + for major features is also important so that [affiliations with commit access](CODEOWNERS.md) can + come to agreement on the design. If it's appropriate to write a design document, the document must + be hosted either in the GitHub issue, or linked to from the issue and hosted in a world-readable + location. +* Small patches and bug fixes don't need prior communication. + +## Inclusivity + +The Envoy Gateway community has an explicit goal to be inclusive to all. As such, all PRs must adhere +to the following guidelines for all code, APIs, and documentation: + +* The following words and phrases are not allowed: + * *Whitelist*: use allowlist instead. + * *Blacklist*: use denylist or blocklist instead. + * *Master*: use primary instead. + * *Slave*: use secondary or replica instead. +* Documentation should be written in an inclusive style. The [Google developer + documentation](https://developers.google.com/style/inclusive-documentation) contains an excellent + reference on this topic. +* The above policy is not considered definitive and may be amended in the future as industry best + practices evolve. Additional comments on this topic may be provided by maintainers during code + review. + +## Submitting a PR + +* Fork the repo. +* Hack +* DCO sign-off each commit. This can be done with `git commit -s`. +* Submit your PR. +* Tests will automatically run for you. +* We will **not** merge any PR that is not passing tests. +* PRs are expected to have 100% test coverage for added code. This can be verified with a coverage + build. If your PR cannot have 100% coverage for some reason please clearly explain why when you + open it. +* Any PR that changes user-facing behavior **must** have associated documentation in the [docs](https://github.com/envoyproxy/gateway/tree/main/docs) folder of the repo as + well as the [changelog](../releases). +* All code comments and documentation are expected to have proper English grammar and punctuation. + If you are not a fluent English speaker (or a bad writer ;-)) please let us know and we will try + to find some help but there are no guarantees. +* Your PR title should be descriptive, and generally start with type that contains a subsystem name with `()` if necessary + and summary followed by a colon. format `chore/docs/feat/fix/refactor/style/test: summary`. + Examples: + * "docs: fix grammar error" + * "feat(translator): add new feature" + * "fix: fix xx bug" + * "chore: change ci & build tools etc" +* Your PR commit message will be used as the commit message when your PR is merged. You should + update this field if your PR diverges during review. +* Your PR description should have details on what the PR does. If it fixes an existing issue it + should end with "Fixes #XXX". +* If your PR is co-authored or based on an earlier PR from another contributor, + please attribute them with `Co-authored-by: name `. See + GitHub's [multiple author + guidance](https://help.github.com/en/github/committing-changes-to-your-project/creating-a-commit-with-multiple-authors) + for further details. +* When all tests are passing and all other conditions described herein are satisfied, a maintainer + will be assigned to review and merge the PR. +* Once you submit a PR, *please do not rebase it*. It's much easier to review if subsequent commits + are new commits and/or merges. We squash and merge so the number of commits you have in the PR + doesn't matter. +* We expect that once a PR is opened, it will be actively worked on until it is merged or closed. + We reserve the right to close PRs that are not making progress. This is generally defined as no + changes for 7 days. Obviously PRs that are closed due to lack of activity can be reopened later. + Closing stale PRs helps us to keep on top of all the work currently in flight. + +## Maintainer PR Review Policy + +* See [CODEOWNERS.md](CODEOWNERS.md) for the current list of maintainers. +* A maintainer representing a different affiliation from the PR owner is required to review and + approve the PR. +* When the project matures, it is expected that a "domain expert" for the code the PR touches should + review the PR. This person does not require commit access, just domain knowledge. +* The above rules may be waived for PRs which only update docs or comments, or trivial changes to + tests and tools (where trivial is decided by the maintainer in question). +* If there is a question on who should review a PR please discuss in Slack. +* Anyone is welcome to review any PR that they want, whether they are a maintainer or not. +* Please make sure that the PR title, commit message, and description are updated if the PR changes + significantly during review. +* Please **clean up the title and body** before merging. By default, GitHub fills the squash merge + title with the original title, and the commit body with every individual commit from the PR. + The maintainer doing the merge should make sure the title follows the guidelines above and should + overwrite the body with the original commit message from the PR (cleaning it up if necessary) + while preserving the PR author's final DCO sign-off. + +## Decision making + +This is a new and complex project, and we need to make a lot of decisions very quickly. +To this end, we've settled on this process for making (possibly contentious) decisions: + +* For decisions that need a record, we create an issue. +* In that issue, we discuss opinions, then a maintainer can call for a vote in a comment. +* Maintainers can cast binding votes on that comment by reacting or replying in another comment. +* Non-maintainer community members are welcome to cast non-binding votes by either of these methods. +* Voting will be resolved by simple majority. +* In the event of deadlocks, the question will be put to steering instead. + +## DCO: Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](https://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign-off when creating the git commit via `git commit -s`. + +If you want this to be automatic you can set up some aliases: + +```bash +git config --add alias.amend "commit -s --amend" +git config --add alias.c "commit -s" +``` + +## Fixing DCO + +If your PR fails the DCO check, it's necessary to fix the entire commit history in the PR. Best +practice is to [squash](https://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html) +the commit history to a single commit, append the DCO sign-off as described above, and [force +push](https://git-scm.com/docs/git-push#git-push---force). For example, if you have 2 commits in +your history: + +```bash +git rebase -i HEAD^^ +(interactive squash + DCO append) +git push origin -f +``` + +Note, that in general rewriting history in this way is a hindrance to the review process and this +should only be done to correct a DCO mistake. diff --git a/site/content/en/v0.3.0/contributions/DEVELOP.md b/site/content/en/v0.3.0/contributions/DEVELOP.md new file mode 100644 index 000000000000..a6fd3846f565 --- /dev/null +++ b/site/content/en/v0.3.0/contributions/DEVELOP.md @@ -0,0 +1,162 @@ +--- +title: "Developer Guide" +weight: 2 +--- + +Envoy Gateway is built using a [make][]-based build system. Our CI is based on [Github Actions][] using [workflows][]. + +## Prerequisites + +### go + +* Version: 1.20 +* Installation Guide: https://go.dev/doc/install + +### make + +* Recommended Version: 4.0 or later +* Installation Guide: https://www.gnu.org/software/make + +### docker + +* Optional when you want to build a Docker image or run `make` inside Docker. +* Recommended Version: 20.10.16 +* Installation Guide: https://docs.docker.com/engine/install + +### python3 + +* Need a `python3` program +* Must have a functioning `venv` module; this is part of the standard + library, but some distributions (such as Debian and Ubuntu) replace + it with a stub and require you to install a `python3-venv` package + separately. + +## Quickstart + +* Run `make help` to see all the available targets to build, test and run Envoy Gateway. + +### Building + +* Run `make build` to build all the binaries. +* Run `make build BINS="envoy-gateway"` to build the Envoy Gateway binary. +* Run `make build BINS="egctl"` to build the egctl binary. + +__Note:__ The binaries get generated in the `bin/$OS/$ARCH` directory, for example, `bin/linux/amd64/`. + +### Testing + +* Run `make test` to run the golang tests. + +* Run `make testdata` to generate the golden YAML testdata files. + +### Running Linters + +* Run `make lint` to make sure your code passes all the linter checks. +__Note:__ The `golangci-lint` configuration resides [here](https://github.com/envoyproxy/gateway/blob/main/tools/linter/golangci-lint/.golangci.yml). + +### Building and Pushing the Image + +* Run `IMAGE=docker.io/you/gateway-dev make image` to build the docker image. +* Run `IMAGE=docker.io/you/gateway-dev make push-multiarch` to build and push the multi-arch docker image. + +__Note:__ Replace `IMAGE` with your registry's image name. + +### Deploying Envoy Gateway for Test/Dev + +* Run `make create-cluster` to create a [Kind][] cluster. + +#### Option 1: Use the Latest [gateway-dev][] Image + +* Run `TAG=latest make kube-deploy` to deploy Envoy Gateway in the Kind cluster using the latest image. Replace `latest` + to use a different image tag. + +#### Option 2: Use a Custom Image + +* Run `make kube-install-image` to build an image from the tip of your current branch and load it in the Kind cluster. +* Run `IMAGE_PULL_POLICY=IfNotPresent make kube-deploy` to install Envoy Gateway into the Kind cluster using your custom image. + +### Deploying Envoy Gateway in Kubernetes + +* Run `TAG=latest make kube-deploy` to deploy Envoy Gateway using the latest image into a Kubernetes cluster (linked to + the current kube context). Preface the command with `IMAGE` or replace `TAG` to use a different Envoy Gateway image or + tag. +* Run `make kube-undeploy` to uninstall Envoy Gateway from the cluster. + +__Note:__ Envoy Gateway is tested against Kubernetes v1.24.0. + +### Demo Setup + +* Run `make kube-demo` to deploy a demo backend service, gatewayclass, gateway and httproute resource +(similar to steps outlined in the [Quickstart][] docs) and test the configuration. +* Run `make kube-demo-undeploy` to delete the resources created by the `make kube-demo` command. + +### Run Gateway API Conformance Tests + +The commands below deploy Envoy Gateway to a Kubernetes cluster and run the Gateway API conformance tests. Refer to the +Gateway API [conformance homepage][] to learn more about the tests. If Envoy Gateway is already installed, run +`TAG=latest make run-conformance` to run the conformance tests. + +#### On a Linux Host + +* Run `TAG=latest make conformance` to create a Kind cluster, install Envoy Gateway using the latest [gateway-dev][] + image, and run Gateway API conformance tests. + +#### On a Mac Host + +Since Mac doesn't support [directly exposing][] the Docker network to the Mac host, use one of the following +workarounds to run conformance tests: + +* Deploy your own Kubernetes cluster or use Docker Desktop with [Kubernetes support][] and then run + `TAG=latest make kube-deploy run-conformance`. This will install Envoy Gateway using the latest [gateway-dev][] image + to the Kubernetes cluster using the current kubectl context and run the conformance tests. Use `make kube-undeploy` to + uninstall Envoy Gateway. +* Install and run [Docker Mac Net Connect][mac_connect] and then run `TAG=latest make conformance`. + +__Note:__ Preface commands with `IMAGE` or replace `TAG` to use a different Envoy Gateway image or tag. If `TAG` +is unspecified, the short SHA of your current branch is used. + +### Debugging the Envoy Config + +An easy way to view the envoy config that Envoy Gateway is using is to port-forward to the admin interface port +(currently `19000`) on the Envoy deployment that corresponds to a Gateway so that it can be accessed locally. + +Get the name of the Envoy deployment. The following example is for Gateway `eg` in the `default` namespace: + +```shell +export ENVOY_DEPLOYMENT=$(kubectl get deploy -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Port forward the admin interface port: + +```shell +kubectl port-forward deploy/${ENVOY_DEPLOYMENT} -n envoy-gateway-system 19000:19000 +``` + +Now you are able to view the running Envoy configuration by navigating to `127.0.0.1:19000/config_dump`. + +There are many other endpoints on the [Envoy admin interface][] that may be helpful when debugging. + +### JWT Testing + +An example [JSON Web Token (JWT)][jwt] and [JSON Web Key Set (JWKS)][jwks] are used for the [request authentication][] +user guide. The JWT was created by the [JWT Debugger][], using the `RS256` algorithm. The public key from the JWTs +verify signature was copied to [JWK Creator][] for generating the JWK. The JWK Creator was configured with matching +settings, i.e. `Signing` public key use and the `RS256` algorithm. The generated JWK was wrapped in a JWKS structure +and is hosted in the repo. + +[Quickstart]: https://github.com/envoyproxy/gateway/blob/main/docs/latest/user/quickstart.md +[make]: https://www.gnu.org/software/make/ +[Github Actions]: https://docs.github.com/en/actions +[workflows]: https://github.com/envoyproxy/gateway/tree/main/.github/workflows +[Kind]: https://kind.sigs.k8s.io/ +[conformance homepage]: https://gateway-api.sigs.k8s.io/concepts/conformance/ +[directly exposing]: https://kind.sigs.k8s.io/docs/user/loadbalancer/ +[Kubernetes support]: https://docs.docker.com/desktop/kubernetes/ +[gateway-dev]: https://hub.docker.com/r/envoyproxy/gateway-dev/tags +[mac_connect]: https://github.com/chipmk/docker-mac-net-connect +[Envoy admin interface]: https://www.envoyproxy.io/docs/envoy/latest/operations/admin#operations-admin-interface +[jwt]: https://tools.ietf.org/html/rfc7519 +[jwks]: https://tools.ietf.org/html/rfc7517 +[request authentication]: https://gateway.envoyproxy.io/latest/user/authn.html +[JWT Debugger]: https://jwt.io/ +[JWK Creator]: https://russelldavies.github.io/jwk-creator/ diff --git a/site/content/en/v0.3.0/contributions/DOCS.md b/site/content/en/v0.3.0/contributions/DOCS.md new file mode 100644 index 000000000000..1abae95763c5 --- /dev/null +++ b/site/content/en/v0.3.0/contributions/DOCS.md @@ -0,0 +1,65 @@ +--- +title: "Working on the Envoy Gateway Docs" +--- + +The documentation for the Envoy Gateway lives in the `docs/` directory. Any +individual document can be written using either [reStructuredText] or [Markdown], +you can choose the format that you're most comfortable with when working on the +documentation. + +## Documentation Structure + +We supported the versioned Docs now, the directory name under docs represents +the version of docs. The root of the latest site is in `docs/latest/index.rst`. +This is probably where to start if you're trying to understand how things fit together. + +Note that the new contents should be added to `docs/latest` and will be cut off at +the next release. The contents under `docs/v0.2.0` are auto-generated, +and usually do not need to make changes to them, unless if you find the current release pages have +some incorrect contents. If so, you should send a PR to update contents both of `docs/latest` +and `docs/v0.2.0`. + +It's important to note that a given document _must_ have a reference in some +`.. toctree::` section for the document to be reachable. Not everything needs +to be in `docs/index.rst`'s `toctree` though. + +You can access the website which represents the current release in default, +and you can access the website which contains the latest version changes in +[Here][latest-website] or at the footer of the pages. + +## Documentation Workflow + +To work with the docs, just edit reStructuredText or Markdown files in `docs`, +then run + +```bash +make docs +``` + +This will create `docs/html` with the built HTML pages. You can view the docs +either simply by pointing a web browser at the `file://` path to your +`docs/html`, or by firing up a static webserver from that directory, e.g. + +``` shell +make docs-serve +``` + +If you want to generate a new release version of the docs, like `v0.3.0`, then run + +```bash +make docs-release TAG=v0.3.0 +``` + +This will update the VERSION file at the project root, which records current release version, +and it will be used in the pages version context and binary version output. Also, this will generate +new dir `docs/v0.3.0`, which contains docs at v0.3.0 and updates artifact links to `v0.3.0` +in all files under `docs/v0.3.0/user`, like `quickstart.md`, `http-routing.md` and etc. + +## Publishing Docs + +Whenever docs are pushed to `main`, CI will publish the built docs to GitHub +Pages. For more details, see `.github/workflows/docs.yaml`. + +[reStructuredText]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html +[Markdown]: https://daringfireball.net/projects/markdown/syntax +[latest-website]: https://gateway.envoyproxy.io/latest diff --git a/site/content/en/v0.3.0/contributions/RELEASING.md b/site/content/en/v0.3.0/contributions/RELEASING.md new file mode 100644 index 000000000000..617baf1933e0 --- /dev/null +++ b/site/content/en/v0.3.0/contributions/RELEASING.md @@ -0,0 +1,230 @@ +--- +title: "Release Process" +--- + +This document guides maintainers through the process of creating an Envoy Gateway release. + +- [Release Candidate](#release-candidate) +- [Minor Release](#minor-release) +- [Announce the Release](#announce-the-release) + +## Release Candidate + +The following steps should be used for creating a release candidate. + +### Prerequisites + +- Permissions to push to the Envoy Gateway repository. + +Set environment variables for use in subsequent steps: + +```shell +export MAJOR_VERSION=0 +export MINOR_VERSION=3 +export RELEASE_CANDIDATE_NUMBER=1 +export GITHUB_REMOTE=origin +``` + +1. Clone the repo, checkout the `main` branch, ensure it’s up-to-date, and your local branch is clean. +2. Create a topic branch for adding the release notes and updating the [VERSION][] file with the release version. Refer to previous [release notes][] and [VERSION][] for additional details. +3. Sign, commit, and push your changes to your fork. +4. Submit a [Pull Request][] to merge the changes into the `main` branch. Do not proceed until your PR has merged and + the [Build and Test][] has successfully completed. +5. Create a new release branch from `main`. The release branch should be named + `release/v${MAJOR_VERSION}.${MINOR_VERSION}`, e.g. `release/v0.3`. + + ```shell + git checkout -b release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +6. Push the branch to the Envoy Gateway repo. + + ```shell + git push ${GITHUB_REMOTE} release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +7. Create a topic branch for updating the Envoy proxy image to the tag supported by the release. Reference [PR #958][] + for additional details on updating the image tag. +8. Sign, commit, and push your changes to your fork. +9. Submit a [Pull Request][] to merge the changes into the `release/v${MAJOR_VERSION}.${MINOR_VERSION}` branch. Do not + proceed until your PR has merged into the release branch and the [Build and Test][] has completed for your PR. +10. Ensure your release branch is up-to-date and tag the head of your release branch with the release candidate number. + + ```shell + git tag -a v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} -m 'Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} Release Candidate' + ``` + +11. Push the tag to the Envoy Gateway repository. + + ```shell + git push ${GITHUB_REMOTE} v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} + ``` + +12. This will trigger the [release GitHub action][] that generates the release, release artifacts, etc. +13. Confirm that the [release workflow][] completed successfully. +14. Confirm that the Envoy Gateway [image][] with the correct release tag was published to Docker Hub. +15. Confirm that the [release][] was created. +16. Note that the [Quickstart Guide][] references are __not__ updated for release candidates. However, test + the quickstart steps using the release candidate by manually updating the links. +17. [Generate][] the GitHub changelog. +18. Ensure you check the "This is a pre-release" checkbox when editing the GitHub release. +19. If you find any bugs in this process, please create an issue. + +### Setup cherry picker action + +After release branch cut, RM (Release Manager) should add job [cherrypick action](../../../.github/workflows/cherrypick.yaml) for target release. + +Configuration looks like following: + +```yaml + cherry_pick_release_v0_4: + runs-on: ubuntu-latest + name: Cherry pick into release-v0.4 + if: ${{ contains(github.event.pull_request.labels.*.name, 'cherrypick/release-v0.4') && github.event.pull_request.merged == true }} + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + fetch-depth: 0 + - name: Cherry pick into release/v0.4 + uses: carloscastrojumo/github-cherry-pick-action@v1.0.9 + with: + branch: release/v0.4 + title: "[release/v0.4] {old_title}" + body: "Cherry picking #{old_pull_request_id} onto release/v0.4" + labels: | + cherrypick/release-v0.4 + # put release manager here + reviewers: | + AliceProxy +``` + +Replace `v0.4` with real branch name, and `AliceProxy` with the real name of RM. + +## Minor Release + +The following steps should be used for creating a minor release. + +### Prerequisites + +- Permissions to push to the Envoy Gateway repository. +- A release branch that has been cut from the corresponding release candidate. Refer to the + [Release Candidate](#release-candidate) section for additional details on cutting a release candidate. + +Set environment variables for use in subsequent steps: + +```shell +export MAJOR_VERSION=0 +export MINOR_VERSION=3 +export GITHUB_REMOTE=origin +``` + +1. Clone the repo, checkout the `main` branch, ensure it’s up-to-date, and your local branch is clean. +2. Create a topic branch for adding the release notes, release announcement, and versioned release docs. + + 1. Create the release notes. Reference previous [release notes][] for additional details. __Note:__ The release + notes should be an accumulation of the release candidate release notes and any changes since the release + candidate. + 2. Create a release announcement. Refer to [PR #635] as an example release announcement. + 3. Include the release in the compatibility matrix. Refer to [PR #1002] as an example. + 4. Generate the versioned release docs: + + ``` shell + make docs-release TAG=v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +3. Sign, commit, and push your changes to your fork. +4. Submit a [Pull Request][] to merge the changes into the `main` branch. Do not proceed until all your PRs have merged + and the [Build and Test][] has completed for your final PR. + +5. Checkout the release branch. + + ```shell + git checkout -b release/v${MAJOR_VERSION}.${MINOR_VERSION} $GITHUB_REMOTE/release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +6. If the tip of the release branch does not match the tip of `main`, perform the following: + + 1. Create a topic branch from the release branch. + 2. Cherry-pick the commits from `main` that differ from the release branch. + 3. Run tests locally, e.g. `make lint`. + 4. Sign, commit, and push your topic branch to your Envoy Gateway fork. + 5. Submit a PR to merge the topic from of your fork into the Envoy Gateway release branch. + 6. Do not proceed until the PR has merged and CI passes for the merged PR. + 7. If you are still on your topic branch, change to the release branch: + + ```shell + git checkout release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + + 8. Ensure your local release branch is up-to-date: + + ```shell + git pull $GITHUB_REMOTE release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +7. Tag the head of your release branch with the release tag. For example: + + ```shell + git tag -a v${MAJOR_VERSION}.${MINOR_VERSION}.0 -m 'Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION}.0 Release' + ``` + + __Note:__ The tag version differs from the release branch by including the `.0` patch version. + +8. Push the tag to the Envoy Gateway repository. + + ```shell + git push origin v${MAJOR_VERSION}.${MINOR_VERSION}.0 + ``` + +9. This will trigger the [release GitHub action][] that generates the release, release artifacts, etc. +10. Confirm that the [release workflow][] completed successfully. +11. Confirm that the Envoy Gateway [image][] with the correct release tag was published to Docker Hub. +12. Confirm that the [release][] was created. +13. Confirm that the steps in the [Quickstart Guide][] work as expected. +14. [Generate][] the GitHub changelog and include the following text at the beginning of the release page: + + ```console + # Release Announcement + + Check out the [v${MAJOR_VERSION}.${MINOR_VERSION} release announcement] + (https://gateway.envoyproxy.io/releases/v${MAJOR_VERSION}.${MINOR_VERSION}.html) to learn more about the release. + ``` + +If you find any bugs in this process, please create an issue. + +## Announce the Release + +It's important that the world knows about the release. Use the following steps to announce the release. + +1. Set the release information in the Envoy Gateway Slack channel. For example: + + ```shell + Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION} has been released: https://github.com/envoyproxy/gateway/releases/tag/v${MAJOR_VERSION}.${MINOR_VERSION}.0 + ``` + +2. Send a message to the Envoy Gateway Slack channel. For example: + + ```shell + On behalf of the entire Envoy Gateway community, I am pleased to announce the release of Envoy Gateway + v${MAJOR_VERSION}.${MINOR_VERSION}. A big thank you to all the contributors that made this release possible. + Refer to the official v${MAJOR_VERSION}.${MINOR_VERSION} announcement for release details and the project docs + to start using Envoy Gateway. + ... + ``` + + Link to the GitHub release and release announcement page that highlights the release. + +[release notes]: https://github.com/envoyproxy/gateway/tree/main/release-notes +[Pull Request]: https://github.com/envoyproxy/gateway/pulls +[Quickstart Guide]: https://github.com/envoyproxy/gateway/blob/main/docs/user/quickstart.md +[Build and Test]: https://github.com/envoyproxy/gateway/blob/main/.github/workflows/build_and_test.yaml +[release GitHub action]: https://github.com/envoyproxy/gateway/blob/main/.github/workflows/release.yaml +[release workflow]: https://github.com/envoyproxy/gateway/actions/workflows/release.yaml +[image]: https://hub.docker.com/r/envoyproxy/gateway/tags +[release]: https://github.com/envoyproxy/gateway/releases +[Generate]: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes +[PR #635]: https://github.com/envoyproxy/gateway/pull/635 +[PR #958]: https://github.com/envoyproxy/gateway/pull/958 +[PR #1002]: https://github.com/envoyproxy/gateway/pull/1002 +[VERSION]: https://github.com/envoyproxy/gateway/blob/main/VERSION diff --git a/site/content/en/v0.3.0/contributions/_index.md b/site/content/en/v0.3.0/contributions/_index.md new file mode 100644 index 000000000000..3255d996472a --- /dev/null +++ b/site/content/en/v0.3.0/contributions/_index.md @@ -0,0 +1,5 @@ +--- +title: Get Involved +description: "This section includes contents related to **Contributions**" +weight: 100 +--- diff --git a/site/content/en/docs/v0.3.0/design/_index.md b/site/content/en/v0.3.0/design/_index.md similarity index 100% rename from site/content/en/docs/v0.3.0/design/_index.md rename to site/content/en/v0.3.0/design/_index.md diff --git a/site/content/en/docs/v0.3.0/design/config-api.md b/site/content/en/v0.3.0/design/config-api.md similarity index 100% rename from site/content/en/docs/v0.3.0/design/config-api.md rename to site/content/en/v0.3.0/design/config-api.md diff --git a/site/content/en/docs/v0.3.0/design/egctl.md b/site/content/en/v0.3.0/design/egctl.md similarity index 100% rename from site/content/en/docs/v0.3.0/design/egctl.md rename to site/content/en/v0.3.0/design/egctl.md diff --git a/site/content/en/docs/v0.3.0/design/gatewayapi-support.md b/site/content/en/v0.3.0/design/gatewayapi-support.md similarity index 100% rename from site/content/en/docs/v0.3.0/design/gatewayapi-support.md rename to site/content/en/v0.3.0/design/gatewayapi-support.md diff --git a/site/content/en/docs/v0.3.0/design/gatewayapi-translator.md b/site/content/en/v0.3.0/design/gatewayapi-translator.md similarity index 100% rename from site/content/en/docs/v0.3.0/design/gatewayapi-translator.md rename to site/content/en/v0.3.0/design/gatewayapi-translator.md diff --git a/site/content/en/v0.3.0/design/goals.md b/site/content/en/v0.3.0/design/goals.md new file mode 100644 index 000000000000..fd38b2004c61 --- /dev/null +++ b/site/content/en/v0.3.0/design/goals.md @@ -0,0 +1,91 @@ +--- +title: "Goals" +weight: 1 +--- + +The high-level goal of the Envoy Gateway project is to attract more users to Envoy by lowering barriers to adoption +through expressive, extensible, role-oriented APIs that support a multitude of ingress and L7/L4 traffic routing +use cases; and provide a common foundation for vendors to build value-added products without having to re-engineer +fundamental interactions. + +## Objectives + +### Expressive API + +The Envoy Gateway project will expose a simple and expressive API, with defaults set for many capabilities. + +The API will be the Kubernetes-native [Gateway API][], plus Envoy-specific extensions and extension points. This +expressive and familiar API will make Envoy accessible to more users, especially application developers, and make Envoy +a stronger option for "getting started" as compared to other proxies. Application developers will use the API out of +the box without needing to understand in-depth concepts of Envoy Proxy or use OSS wrappers. The API will use familiar +nouns that [users](#personas) understand. + +The core full-featured Envoy xDS APIs will remain available for those who need more capability and for those who +add functionality on top of Envoy Gateway, such as commercial API gateway products. + +This expressive API will not be implemented by Envoy Proxy, but rather an officially supported translation layer +on top. + +### Batteries included + +Envoy Gateway will simplify how Envoy is deployed and managed, allowing application developers to focus on +delivering core business value. + +The project plans to include additional infrastructure components required by users to fulfill their Ingress and API +gateway needs: It will handle Envoy infrastructure provisioning (e.g. Kubernetes Service, Deployment, et cetera), and +possibly infrastructure provisioning of related sidecar services. It will include sensible defaults with the ability to +override. It will include channels for improving ops by exposing status through API conditions and Kubernetes status +sub-resources. + +Making an application accessible needs to be a trivial task for any developer. Similarly, infrastructure administrators +will enjoy a simplified management model that doesn't require extensive knowledge of the solution's architecture to +operate. + +### All environments + +Envoy Gateway will support running natively in Kubernetes environments as well as non-Kubernetes deployments. + +Initially, Kubernetes will receive the most focus, with the aim of having Envoy Gateway become the de facto +standard for Kubernetes ingress supporting the [Gateway API][]. +Additional goals include multi-cluster support and various runtime environments. + +### Extensibility + +Vendors will have the ability to provide value-added products built on the Envoy Gateway foundation. + +It will remain easy for end-users to leverage common Envoy Proxy extension points such as providing an implementation +for authentication methods and rate-limiting. For advanced use cases, users will have the ability to use the full power +of xDS. + +Since a general-purpose API cannot address all use cases, Envoy Gateway will provide additional extension points +for flexibility. As such, Envoy Gateway will form the base of vendor-provided managed control plane solutions, +allowing vendors to shift to a higher management plane layer. + +## Non-objectives + +### Cannibalize vendor models + +Vendors need to have the ability to drive commercial value, so the goal is not to cannibalize any existing vendor +monetization model, though some vendors may be affected by it. + +### Disrupt current Envoy usage patterns + +Envoy Gateway is purely an additive convenience layer and is not meant to disrupt any usage pattern of any user +with Envoy Proxy, xDS, or go-control-plane. + +## Personas + +_In order of priority_ + +### 1. Application developer + +The application developer spends the majority of their time developing business logic code. They require the ability to +manage access to their application. + +### 2. Infrastructure administrators + +The infrastructure administrators are responsible for the installation, maintenance, and operation of +API gateways appliances in infrastructure, such as CRDs, roles, service accounts, certificates, etc. +Infrastructure administrators support the needs of application developers by managing instances of Envoy Gateway. + +[Gateway API]: https://gateway-api.sigs.k8s.io/ diff --git a/site/content/en/docs/v0.3.0/design/ratelimit.md b/site/content/en/v0.3.0/design/ratelimit.md similarity index 100% rename from site/content/en/docs/v0.3.0/design/ratelimit.md rename to site/content/en/v0.3.0/design/ratelimit.md diff --git a/site/content/en/docs/v0.3.0/design/request-authentication.md b/site/content/en/v0.3.0/design/request-authentication.md similarity index 100% rename from site/content/en/docs/v0.3.0/design/request-authentication.md rename to site/content/en/v0.3.0/design/request-authentication.md diff --git a/site/content/en/docs/v0.3.0/design/roadmap.md b/site/content/en/v0.3.0/design/roadmap.md similarity index 100% rename from site/content/en/docs/v0.3.0/design/roadmap.md rename to site/content/en/v0.3.0/design/roadmap.md diff --git a/site/content/en/docs/v0.3.0/design/system-design.md b/site/content/en/v0.3.0/design/system-design.md similarity index 100% rename from site/content/en/docs/v0.3.0/design/system-design.md rename to site/content/en/v0.3.0/design/system-design.md diff --git a/site/content/en/docs/v0.3.0/design/tcp-udp-design.md b/site/content/en/v0.3.0/design/tcp-udp-design.md similarity index 100% rename from site/content/en/docs/v0.3.0/design/tcp-udp-design.md rename to site/content/en/v0.3.0/design/tcp-udp-design.md diff --git a/site/content/en/docs/v0.3.0/design/watching.md b/site/content/en/v0.3.0/design/watching.md similarity index 100% rename from site/content/en/docs/v0.3.0/design/watching.md rename to site/content/en/v0.3.0/design/watching.md diff --git a/site/content/en/docs/v0.3.0/images/architecture.png b/site/content/en/v0.3.0/images/architecture.png similarity index 100% rename from site/content/en/docs/v0.3.0/images/architecture.png rename to site/content/en/v0.3.0/images/architecture.png diff --git a/site/content/en/docs/v0.3.0/user/_index.md b/site/content/en/v0.3.0/user/_index.md similarity index 100% rename from site/content/en/docs/v0.3.0/user/_index.md rename to site/content/en/v0.3.0/user/_index.md diff --git a/site/content/en/docs/v0.3.0/user/authn.md b/site/content/en/v0.3.0/user/authn.md similarity index 100% rename from site/content/en/docs/v0.3.0/user/authn.md rename to site/content/en/v0.3.0/user/authn.md diff --git a/site/content/en/docs/v0.3.0/user/grpc-routing.md b/site/content/en/v0.3.0/user/grpc-routing.md similarity index 100% rename from site/content/en/docs/v0.3.0/user/grpc-routing.md rename to site/content/en/v0.3.0/user/grpc-routing.md diff --git a/site/content/en/docs/v0.3.0/user/http-redirect.md b/site/content/en/v0.3.0/user/http-redirect.md similarity index 100% rename from site/content/en/docs/v0.3.0/user/http-redirect.md rename to site/content/en/v0.3.0/user/http-redirect.md diff --git a/site/content/en/docs/v0.3.0/user/http-request-headers.md b/site/content/en/v0.3.0/user/http-request-headers.md similarity index 100% rename from site/content/en/docs/v0.3.0/user/http-request-headers.md rename to site/content/en/v0.3.0/user/http-request-headers.md diff --git a/site/content/en/docs/v0.3.0/user/http-response-headers.md b/site/content/en/v0.3.0/user/http-response-headers.md similarity index 100% rename from site/content/en/docs/v0.3.0/user/http-response-headers.md rename to site/content/en/v0.3.0/user/http-response-headers.md diff --git a/site/content/en/docs/v0.3.0/user/http-routing.md b/site/content/en/v0.3.0/user/http-routing.md similarity index 100% rename from site/content/en/docs/v0.3.0/user/http-routing.md rename to site/content/en/v0.3.0/user/http-routing.md diff --git a/site/content/en/docs/v0.3.0/user/http-traffic-splitting.md b/site/content/en/v0.3.0/user/http-traffic-splitting.md similarity index 100% rename from site/content/en/docs/v0.3.0/user/http-traffic-splitting.md rename to site/content/en/v0.3.0/user/http-traffic-splitting.md diff --git a/site/content/en/docs/v0.3.0/user/http-urlrewrite.md b/site/content/en/v0.3.0/user/http-urlrewrite.md similarity index 100% rename from site/content/en/docs/v0.3.0/user/http-urlrewrite.md rename to site/content/en/v0.3.0/user/http-urlrewrite.md diff --git a/site/content/en/docs/v0.3.0/user/quickstart.md b/site/content/en/v0.3.0/user/quickstart.md similarity index 100% rename from site/content/en/docs/v0.3.0/user/quickstart.md rename to site/content/en/v0.3.0/user/quickstart.md diff --git a/site/content/en/docs/v0.3.0/user/rate-limit.md b/site/content/en/v0.3.0/user/rate-limit.md similarity index 100% rename from site/content/en/docs/v0.3.0/user/rate-limit.md rename to site/content/en/v0.3.0/user/rate-limit.md diff --git a/site/content/en/docs/v0.3.0/user/secure-gateways.md b/site/content/en/v0.3.0/user/secure-gateways.md similarity index 100% rename from site/content/en/docs/v0.3.0/user/secure-gateways.md rename to site/content/en/v0.3.0/user/secure-gateways.md diff --git a/site/content/en/docs/v0.3.0/user/tcp-routing.md b/site/content/en/v0.3.0/user/tcp-routing.md similarity index 100% rename from site/content/en/docs/v0.3.0/user/tcp-routing.md rename to site/content/en/v0.3.0/user/tcp-routing.md diff --git a/site/content/en/docs/v0.3.0/user/tls-passthrough.md b/site/content/en/v0.3.0/user/tls-passthrough.md similarity index 100% rename from site/content/en/docs/v0.3.0/user/tls-passthrough.md rename to site/content/en/v0.3.0/user/tls-passthrough.md diff --git a/site/content/en/docs/v0.3.0/user/udp-routing.md b/site/content/en/v0.3.0/user/udp-routing.md similarity index 100% rename from site/content/en/docs/v0.3.0/user/udp-routing.md rename to site/content/en/v0.3.0/user/udp-routing.md diff --git a/site/content/en/docs/latest/_index.md b/site/content/en/v0.4.0/_index.md similarity index 66% rename from site/content/en/docs/latest/_index.md rename to site/content/en/v0.4.0/_index.md index bb29abe2d512..3772c64b1ccc 100644 --- a/site/content/en/docs/latest/_index.md +++ b/site/content/en/v0.4.0/_index.md @@ -1,9 +1,10 @@ ---- -title: "Welcome to Envoy Gateway" -description: latest version of Envoy Gateway -linktitle: latest -weight: 1 ---- ++++ +title = "Welcome to Envoy Gateway" +description = "Envoy Gateway Documents" + +[[cascade]] +type = "docs" ++++ Envoy Gateway is an open source project for managing **Envoy Proxy** as a standalone or Kubernetes-based application gateway. **Gateway API** resources are used to dynamically provision and configure the managed Envoy Proxies. diff --git a/site/content/en/docs/v0.4.0/api/_index.md b/site/content/en/v0.4.0/api/_index.md similarity index 87% rename from site/content/en/docs/v0.4.0/api/_index.md rename to site/content/en/v0.4.0/api/_index.md index 1d7c67c8c151..396d9ffcefcf 100644 --- a/site/content/en/docs/v0.4.0/api/_index.md +++ b/site/content/en/v0.4.0/api/_index.md @@ -1,4 +1,5 @@ --- title: "API" description: This section includes APIs of Envoy Gateway. +weight: 80 --- diff --git a/site/content/en/docs/v0.4.0/api/config_types.md b/site/content/en/v0.4.0/api/config_types.md similarity index 100% rename from site/content/en/docs/v0.4.0/api/config_types.md rename to site/content/en/v0.4.0/api/config_types.md diff --git a/site/content/en/docs/v0.4.0/api/extension_types.md b/site/content/en/v0.4.0/api/extension_types.md similarity index 100% rename from site/content/en/docs/v0.4.0/api/extension_types.md rename to site/content/en/v0.4.0/api/extension_types.md diff --git a/site/content/en/v0.4.0/contributions/CODEOWNERS.md b/site/content/en/v0.4.0/contributions/CODEOWNERS.md new file mode 100644 index 000000000000..9e596002bb33 --- /dev/null +++ b/site/content/en/v0.4.0/contributions/CODEOWNERS.md @@ -0,0 +1,18 @@ +--- +title: "Maintainers" +--- + +## The following maintainers, listed in alphabetical order, own everything + +- @AliceProxy +- @arkodg +- @Xunzhuo +- @zirain +- @qicz + +## Emeritus Maintainers + +- @danehans +- @alexgervais +- @skriss +- @youngnick diff --git a/site/content/en/v0.4.0/contributions/CODE_OF_CONDUCT.md b/site/content/en/v0.4.0/contributions/CODE_OF_CONDUCT.md new file mode 100644 index 000000000000..1f17c0889458 --- /dev/null +++ b/site/content/en/v0.4.0/contributions/CODE_OF_CONDUCT.md @@ -0,0 +1,5 @@ +--- +title: "Code of Conduct" +--- + +Gateway follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). diff --git a/site/content/en/v0.4.0/contributions/CONTRIBUTING.md b/site/content/en/v0.4.0/contributions/CONTRIBUTING.md new file mode 100644 index 000000000000..21dcd9a1941a --- /dev/null +++ b/site/content/en/v0.4.0/contributions/CONTRIBUTING.md @@ -0,0 +1,189 @@ +--- +title: "Contributing" +weight: 3 +--- + +We welcome contributions from the community. Please carefully review the [project goals](GOALS.md) +and following guidelines to streamline your contributions. + +## Communication + +* Before starting work on a major feature, please contact us via GitHub or Slack. We will ensure no + one else is working on it and ask you to open a GitHub issue. +* A "major feature" is defined as any change that is > 100 LOC altered (not including tests), or + changes any user-facing behavior. We will use the GitHub issue to discuss the feature and come to + agreement. This is to prevent your time being wasted, as well as ours. The GitHub review process + for major features is also important so that [affiliations with commit access](CODEOWNERS.md) can + come to agreement on the design. If it's appropriate to write a design document, the document must + be hosted either in the GitHub issue, or linked to from the issue and hosted in a world-readable + location. +* Small patches and bug fixes don't need prior communication. + +## Inclusivity + +The Envoy Gateway community has an explicit goal to be inclusive to all. As such, all PRs must adhere +to the following guidelines for all code, APIs, and documentation: + +* The following words and phrases are not allowed: + * *Whitelist*: use allowlist instead. + * *Blacklist*: use denylist or blocklist instead. + * *Master*: use primary instead. + * *Slave*: use secondary or replica instead. +* Documentation should be written in an inclusive style. The [Google developer + documentation](https://developers.google.com/style/inclusive-documentation) contains an excellent + reference on this topic. +* The above policy is not considered definitive and may be amended in the future as industry best + practices evolve. Additional comments on this topic may be provided by maintainers during code + review. + +## Submitting a PR + +* Fork the repo. +* Hack +* DCO sign-off each commit. This can be done with `git commit -s`. +* Submit your PR. +* Tests will automatically run for you. +* We will **not** merge any PR that is not passing tests. +* PRs are expected to have 100% test coverage for added code. This can be verified with a coverage + build. If your PR cannot have 100% coverage for some reason please clearly explain why when you + open it. +* Any PR that changes user-facing behavior **must** have associated documentation in the [docs](https://github.com/envoyproxy/gateway/tree/main/docs) folder of the repo as + well as the [changelog](../releases). +* All code comments and documentation are expected to have proper English grammar and punctuation. + If you are not a fluent English speaker (or a bad writer ;-)) please let us know and we will try + to find some help but there are no guarantees. +* Your PR title should be descriptive, and generally start with type that contains a subsystem name with `()` if necessary + and summary followed by a colon. format `chore/docs/feat/fix/refactor/style/test: summary`. + Examples: + * "docs: fix grammar error" + * "feat(translator): add new feature" + * "fix: fix xx bug" + * "chore: change ci & build tools etc" +* Your PR commit message will be used as the commit message when your PR is merged. You should + update this field if your PR diverges during review. +* Your PR description should have details on what the PR does. If it fixes an existing issue it + should end with "Fixes #XXX". +* If your PR is co-authored or based on an earlier PR from another contributor, + please attribute them with `Co-authored-by: name `. See + GitHub's [multiple author + guidance](https://help.github.com/en/github/committing-changes-to-your-project/creating-a-commit-with-multiple-authors) + for further details. +* When all tests are passing and all other conditions described herein are satisfied, a maintainer + will be assigned to review and merge the PR. +* Once you submit a PR, *please do not rebase it*. It's much easier to review if subsequent commits + are new commits and/or merges. We squash and merge so the number of commits you have in the PR + doesn't matter. +* We expect that once a PR is opened, it will be actively worked on until it is merged or closed. + We reserve the right to close PRs that are not making progress. This is generally defined as no + changes for 7 days. Obviously PRs that are closed due to lack of activity can be reopened later. + Closing stale PRs helps us to keep on top of all the work currently in flight. + +## Maintainer PR Review Policy + +* See [CODEOWNERS.md](CODEOWNERS.md) for the current list of maintainers. +* A maintainer representing a different affiliation from the PR owner is required to review and + approve the PR. +* When the project matures, it is expected that a "domain expert" for the code the PR touches should + review the PR. This person does not require commit access, just domain knowledge. +* The above rules may be waived for PRs which only update docs or comments, or trivial changes to + tests and tools (where trivial is decided by the maintainer in question). +* If there is a question on who should review a PR please discuss in Slack. +* Anyone is welcome to review any PR that they want, whether they are a maintainer or not. +* Please make sure that the PR title, commit message, and description are updated if the PR changes + significantly during review. +* Please **clean up the title and body** before merging. By default, GitHub fills the squash merge + title with the original title, and the commit body with every individual commit from the PR. + The maintainer doing the merge should make sure the title follows the guidelines above and should + overwrite the body with the original commit message from the PR (cleaning it up if necessary) + while preserving the PR author's final DCO sign-off. + +## Decision making + +This is a new and complex project, and we need to make a lot of decisions very quickly. +To this end, we've settled on this process for making (possibly contentious) decisions: + +* For decisions that need a record, we create an issue. +* In that issue, we discuss opinions, then a maintainer can call for a vote in a comment. +* Maintainers can cast binding votes on that comment by reacting or replying in another comment. +* Non-maintainer community members are welcome to cast non-binding votes by either of these methods. +* Voting will be resolved by simple majority. +* In the event of deadlocks, the question will be put to steering instead. + +## DCO: Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](https://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign-off when creating the git commit via `git commit -s`. + +If you want this to be automatic you can set up some aliases: + +```bash +git config --add alias.amend "commit -s --amend" +git config --add alias.c "commit -s" +``` + +## Fixing DCO + +If your PR fails the DCO check, it's necessary to fix the entire commit history in the PR. Best +practice is to [squash](https://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html) +the commit history to a single commit, append the DCO sign-off as described above, and [force +push](https://git-scm.com/docs/git-push#git-push---force). For example, if you have 2 commits in +your history: + +```bash +git rebase -i HEAD^^ +(interactive squash + DCO append) +git push origin -f +``` + +Note, that in general rewriting history in this way is a hindrance to the review process and this +should only be done to correct a DCO mistake. diff --git a/site/content/en/v0.4.0/contributions/DEVELOP.md b/site/content/en/v0.4.0/contributions/DEVELOP.md new file mode 100644 index 000000000000..a6fd3846f565 --- /dev/null +++ b/site/content/en/v0.4.0/contributions/DEVELOP.md @@ -0,0 +1,162 @@ +--- +title: "Developer Guide" +weight: 2 +--- + +Envoy Gateway is built using a [make][]-based build system. Our CI is based on [Github Actions][] using [workflows][]. + +## Prerequisites + +### go + +* Version: 1.20 +* Installation Guide: https://go.dev/doc/install + +### make + +* Recommended Version: 4.0 or later +* Installation Guide: https://www.gnu.org/software/make + +### docker + +* Optional when you want to build a Docker image or run `make` inside Docker. +* Recommended Version: 20.10.16 +* Installation Guide: https://docs.docker.com/engine/install + +### python3 + +* Need a `python3` program +* Must have a functioning `venv` module; this is part of the standard + library, but some distributions (such as Debian and Ubuntu) replace + it with a stub and require you to install a `python3-venv` package + separately. + +## Quickstart + +* Run `make help` to see all the available targets to build, test and run Envoy Gateway. + +### Building + +* Run `make build` to build all the binaries. +* Run `make build BINS="envoy-gateway"` to build the Envoy Gateway binary. +* Run `make build BINS="egctl"` to build the egctl binary. + +__Note:__ The binaries get generated in the `bin/$OS/$ARCH` directory, for example, `bin/linux/amd64/`. + +### Testing + +* Run `make test` to run the golang tests. + +* Run `make testdata` to generate the golden YAML testdata files. + +### Running Linters + +* Run `make lint` to make sure your code passes all the linter checks. +__Note:__ The `golangci-lint` configuration resides [here](https://github.com/envoyproxy/gateway/blob/main/tools/linter/golangci-lint/.golangci.yml). + +### Building and Pushing the Image + +* Run `IMAGE=docker.io/you/gateway-dev make image` to build the docker image. +* Run `IMAGE=docker.io/you/gateway-dev make push-multiarch` to build and push the multi-arch docker image. + +__Note:__ Replace `IMAGE` with your registry's image name. + +### Deploying Envoy Gateway for Test/Dev + +* Run `make create-cluster` to create a [Kind][] cluster. + +#### Option 1: Use the Latest [gateway-dev][] Image + +* Run `TAG=latest make kube-deploy` to deploy Envoy Gateway in the Kind cluster using the latest image. Replace `latest` + to use a different image tag. + +#### Option 2: Use a Custom Image + +* Run `make kube-install-image` to build an image from the tip of your current branch and load it in the Kind cluster. +* Run `IMAGE_PULL_POLICY=IfNotPresent make kube-deploy` to install Envoy Gateway into the Kind cluster using your custom image. + +### Deploying Envoy Gateway in Kubernetes + +* Run `TAG=latest make kube-deploy` to deploy Envoy Gateway using the latest image into a Kubernetes cluster (linked to + the current kube context). Preface the command with `IMAGE` or replace `TAG` to use a different Envoy Gateway image or + tag. +* Run `make kube-undeploy` to uninstall Envoy Gateway from the cluster. + +__Note:__ Envoy Gateway is tested against Kubernetes v1.24.0. + +### Demo Setup + +* Run `make kube-demo` to deploy a demo backend service, gatewayclass, gateway and httproute resource +(similar to steps outlined in the [Quickstart][] docs) and test the configuration. +* Run `make kube-demo-undeploy` to delete the resources created by the `make kube-demo` command. + +### Run Gateway API Conformance Tests + +The commands below deploy Envoy Gateway to a Kubernetes cluster and run the Gateway API conformance tests. Refer to the +Gateway API [conformance homepage][] to learn more about the tests. If Envoy Gateway is already installed, run +`TAG=latest make run-conformance` to run the conformance tests. + +#### On a Linux Host + +* Run `TAG=latest make conformance` to create a Kind cluster, install Envoy Gateway using the latest [gateway-dev][] + image, and run Gateway API conformance tests. + +#### On a Mac Host + +Since Mac doesn't support [directly exposing][] the Docker network to the Mac host, use one of the following +workarounds to run conformance tests: + +* Deploy your own Kubernetes cluster or use Docker Desktop with [Kubernetes support][] and then run + `TAG=latest make kube-deploy run-conformance`. This will install Envoy Gateway using the latest [gateway-dev][] image + to the Kubernetes cluster using the current kubectl context and run the conformance tests. Use `make kube-undeploy` to + uninstall Envoy Gateway. +* Install and run [Docker Mac Net Connect][mac_connect] and then run `TAG=latest make conformance`. + +__Note:__ Preface commands with `IMAGE` or replace `TAG` to use a different Envoy Gateway image or tag. If `TAG` +is unspecified, the short SHA of your current branch is used. + +### Debugging the Envoy Config + +An easy way to view the envoy config that Envoy Gateway is using is to port-forward to the admin interface port +(currently `19000`) on the Envoy deployment that corresponds to a Gateway so that it can be accessed locally. + +Get the name of the Envoy deployment. The following example is for Gateway `eg` in the `default` namespace: + +```shell +export ENVOY_DEPLOYMENT=$(kubectl get deploy -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Port forward the admin interface port: + +```shell +kubectl port-forward deploy/${ENVOY_DEPLOYMENT} -n envoy-gateway-system 19000:19000 +``` + +Now you are able to view the running Envoy configuration by navigating to `127.0.0.1:19000/config_dump`. + +There are many other endpoints on the [Envoy admin interface][] that may be helpful when debugging. + +### JWT Testing + +An example [JSON Web Token (JWT)][jwt] and [JSON Web Key Set (JWKS)][jwks] are used for the [request authentication][] +user guide. The JWT was created by the [JWT Debugger][], using the `RS256` algorithm. The public key from the JWTs +verify signature was copied to [JWK Creator][] for generating the JWK. The JWK Creator was configured with matching +settings, i.e. `Signing` public key use and the `RS256` algorithm. The generated JWK was wrapped in a JWKS structure +and is hosted in the repo. + +[Quickstart]: https://github.com/envoyproxy/gateway/blob/main/docs/latest/user/quickstart.md +[make]: https://www.gnu.org/software/make/ +[Github Actions]: https://docs.github.com/en/actions +[workflows]: https://github.com/envoyproxy/gateway/tree/main/.github/workflows +[Kind]: https://kind.sigs.k8s.io/ +[conformance homepage]: https://gateway-api.sigs.k8s.io/concepts/conformance/ +[directly exposing]: https://kind.sigs.k8s.io/docs/user/loadbalancer/ +[Kubernetes support]: https://docs.docker.com/desktop/kubernetes/ +[gateway-dev]: https://hub.docker.com/r/envoyproxy/gateway-dev/tags +[mac_connect]: https://github.com/chipmk/docker-mac-net-connect +[Envoy admin interface]: https://www.envoyproxy.io/docs/envoy/latest/operations/admin#operations-admin-interface +[jwt]: https://tools.ietf.org/html/rfc7519 +[jwks]: https://tools.ietf.org/html/rfc7517 +[request authentication]: https://gateway.envoyproxy.io/latest/user/authn.html +[JWT Debugger]: https://jwt.io/ +[JWK Creator]: https://russelldavies.github.io/jwk-creator/ diff --git a/site/content/en/v0.4.0/contributions/DOCS.md b/site/content/en/v0.4.0/contributions/DOCS.md new file mode 100644 index 000000000000..1abae95763c5 --- /dev/null +++ b/site/content/en/v0.4.0/contributions/DOCS.md @@ -0,0 +1,65 @@ +--- +title: "Working on the Envoy Gateway Docs" +--- + +The documentation for the Envoy Gateway lives in the `docs/` directory. Any +individual document can be written using either [reStructuredText] or [Markdown], +you can choose the format that you're most comfortable with when working on the +documentation. + +## Documentation Structure + +We supported the versioned Docs now, the directory name under docs represents +the version of docs. The root of the latest site is in `docs/latest/index.rst`. +This is probably where to start if you're trying to understand how things fit together. + +Note that the new contents should be added to `docs/latest` and will be cut off at +the next release. The contents under `docs/v0.2.0` are auto-generated, +and usually do not need to make changes to them, unless if you find the current release pages have +some incorrect contents. If so, you should send a PR to update contents both of `docs/latest` +and `docs/v0.2.0`. + +It's important to note that a given document _must_ have a reference in some +`.. toctree::` section for the document to be reachable. Not everything needs +to be in `docs/index.rst`'s `toctree` though. + +You can access the website which represents the current release in default, +and you can access the website which contains the latest version changes in +[Here][latest-website] or at the footer of the pages. + +## Documentation Workflow + +To work with the docs, just edit reStructuredText or Markdown files in `docs`, +then run + +```bash +make docs +``` + +This will create `docs/html` with the built HTML pages. You can view the docs +either simply by pointing a web browser at the `file://` path to your +`docs/html`, or by firing up a static webserver from that directory, e.g. + +``` shell +make docs-serve +``` + +If you want to generate a new release version of the docs, like `v0.3.0`, then run + +```bash +make docs-release TAG=v0.3.0 +``` + +This will update the VERSION file at the project root, which records current release version, +and it will be used in the pages version context and binary version output. Also, this will generate +new dir `docs/v0.3.0`, which contains docs at v0.3.0 and updates artifact links to `v0.3.0` +in all files under `docs/v0.3.0/user`, like `quickstart.md`, `http-routing.md` and etc. + +## Publishing Docs + +Whenever docs are pushed to `main`, CI will publish the built docs to GitHub +Pages. For more details, see `.github/workflows/docs.yaml`. + +[reStructuredText]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html +[Markdown]: https://daringfireball.net/projects/markdown/syntax +[latest-website]: https://gateway.envoyproxy.io/latest diff --git a/site/content/en/v0.4.0/contributions/RELEASING.md b/site/content/en/v0.4.0/contributions/RELEASING.md new file mode 100644 index 000000000000..617baf1933e0 --- /dev/null +++ b/site/content/en/v0.4.0/contributions/RELEASING.md @@ -0,0 +1,230 @@ +--- +title: "Release Process" +--- + +This document guides maintainers through the process of creating an Envoy Gateway release. + +- [Release Candidate](#release-candidate) +- [Minor Release](#minor-release) +- [Announce the Release](#announce-the-release) + +## Release Candidate + +The following steps should be used for creating a release candidate. + +### Prerequisites + +- Permissions to push to the Envoy Gateway repository. + +Set environment variables for use in subsequent steps: + +```shell +export MAJOR_VERSION=0 +export MINOR_VERSION=3 +export RELEASE_CANDIDATE_NUMBER=1 +export GITHUB_REMOTE=origin +``` + +1. Clone the repo, checkout the `main` branch, ensure it’s up-to-date, and your local branch is clean. +2. Create a topic branch for adding the release notes and updating the [VERSION][] file with the release version. Refer to previous [release notes][] and [VERSION][] for additional details. +3. Sign, commit, and push your changes to your fork. +4. Submit a [Pull Request][] to merge the changes into the `main` branch. Do not proceed until your PR has merged and + the [Build and Test][] has successfully completed. +5. Create a new release branch from `main`. The release branch should be named + `release/v${MAJOR_VERSION}.${MINOR_VERSION}`, e.g. `release/v0.3`. + + ```shell + git checkout -b release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +6. Push the branch to the Envoy Gateway repo. + + ```shell + git push ${GITHUB_REMOTE} release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +7. Create a topic branch for updating the Envoy proxy image to the tag supported by the release. Reference [PR #958][] + for additional details on updating the image tag. +8. Sign, commit, and push your changes to your fork. +9. Submit a [Pull Request][] to merge the changes into the `release/v${MAJOR_VERSION}.${MINOR_VERSION}` branch. Do not + proceed until your PR has merged into the release branch and the [Build and Test][] has completed for your PR. +10. Ensure your release branch is up-to-date and tag the head of your release branch with the release candidate number. + + ```shell + git tag -a v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} -m 'Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} Release Candidate' + ``` + +11. Push the tag to the Envoy Gateway repository. + + ```shell + git push ${GITHUB_REMOTE} v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} + ``` + +12. This will trigger the [release GitHub action][] that generates the release, release artifacts, etc. +13. Confirm that the [release workflow][] completed successfully. +14. Confirm that the Envoy Gateway [image][] with the correct release tag was published to Docker Hub. +15. Confirm that the [release][] was created. +16. Note that the [Quickstart Guide][] references are __not__ updated for release candidates. However, test + the quickstart steps using the release candidate by manually updating the links. +17. [Generate][] the GitHub changelog. +18. Ensure you check the "This is a pre-release" checkbox when editing the GitHub release. +19. If you find any bugs in this process, please create an issue. + +### Setup cherry picker action + +After release branch cut, RM (Release Manager) should add job [cherrypick action](../../../.github/workflows/cherrypick.yaml) for target release. + +Configuration looks like following: + +```yaml + cherry_pick_release_v0_4: + runs-on: ubuntu-latest + name: Cherry pick into release-v0.4 + if: ${{ contains(github.event.pull_request.labels.*.name, 'cherrypick/release-v0.4') && github.event.pull_request.merged == true }} + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + fetch-depth: 0 + - name: Cherry pick into release/v0.4 + uses: carloscastrojumo/github-cherry-pick-action@v1.0.9 + with: + branch: release/v0.4 + title: "[release/v0.4] {old_title}" + body: "Cherry picking #{old_pull_request_id} onto release/v0.4" + labels: | + cherrypick/release-v0.4 + # put release manager here + reviewers: | + AliceProxy +``` + +Replace `v0.4` with real branch name, and `AliceProxy` with the real name of RM. + +## Minor Release + +The following steps should be used for creating a minor release. + +### Prerequisites + +- Permissions to push to the Envoy Gateway repository. +- A release branch that has been cut from the corresponding release candidate. Refer to the + [Release Candidate](#release-candidate) section for additional details on cutting a release candidate. + +Set environment variables for use in subsequent steps: + +```shell +export MAJOR_VERSION=0 +export MINOR_VERSION=3 +export GITHUB_REMOTE=origin +``` + +1. Clone the repo, checkout the `main` branch, ensure it’s up-to-date, and your local branch is clean. +2. Create a topic branch for adding the release notes, release announcement, and versioned release docs. + + 1. Create the release notes. Reference previous [release notes][] for additional details. __Note:__ The release + notes should be an accumulation of the release candidate release notes and any changes since the release + candidate. + 2. Create a release announcement. Refer to [PR #635] as an example release announcement. + 3. Include the release in the compatibility matrix. Refer to [PR #1002] as an example. + 4. Generate the versioned release docs: + + ``` shell + make docs-release TAG=v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +3. Sign, commit, and push your changes to your fork. +4. Submit a [Pull Request][] to merge the changes into the `main` branch. Do not proceed until all your PRs have merged + and the [Build and Test][] has completed for your final PR. + +5. Checkout the release branch. + + ```shell + git checkout -b release/v${MAJOR_VERSION}.${MINOR_VERSION} $GITHUB_REMOTE/release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +6. If the tip of the release branch does not match the tip of `main`, perform the following: + + 1. Create a topic branch from the release branch. + 2. Cherry-pick the commits from `main` that differ from the release branch. + 3. Run tests locally, e.g. `make lint`. + 4. Sign, commit, and push your topic branch to your Envoy Gateway fork. + 5. Submit a PR to merge the topic from of your fork into the Envoy Gateway release branch. + 6. Do not proceed until the PR has merged and CI passes for the merged PR. + 7. If you are still on your topic branch, change to the release branch: + + ```shell + git checkout release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + + 8. Ensure your local release branch is up-to-date: + + ```shell + git pull $GITHUB_REMOTE release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +7. Tag the head of your release branch with the release tag. For example: + + ```shell + git tag -a v${MAJOR_VERSION}.${MINOR_VERSION}.0 -m 'Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION}.0 Release' + ``` + + __Note:__ The tag version differs from the release branch by including the `.0` patch version. + +8. Push the tag to the Envoy Gateway repository. + + ```shell + git push origin v${MAJOR_VERSION}.${MINOR_VERSION}.0 + ``` + +9. This will trigger the [release GitHub action][] that generates the release, release artifacts, etc. +10. Confirm that the [release workflow][] completed successfully. +11. Confirm that the Envoy Gateway [image][] with the correct release tag was published to Docker Hub. +12. Confirm that the [release][] was created. +13. Confirm that the steps in the [Quickstart Guide][] work as expected. +14. [Generate][] the GitHub changelog and include the following text at the beginning of the release page: + + ```console + # Release Announcement + + Check out the [v${MAJOR_VERSION}.${MINOR_VERSION} release announcement] + (https://gateway.envoyproxy.io/releases/v${MAJOR_VERSION}.${MINOR_VERSION}.html) to learn more about the release. + ``` + +If you find any bugs in this process, please create an issue. + +## Announce the Release + +It's important that the world knows about the release. Use the following steps to announce the release. + +1. Set the release information in the Envoy Gateway Slack channel. For example: + + ```shell + Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION} has been released: https://github.com/envoyproxy/gateway/releases/tag/v${MAJOR_VERSION}.${MINOR_VERSION}.0 + ``` + +2. Send a message to the Envoy Gateway Slack channel. For example: + + ```shell + On behalf of the entire Envoy Gateway community, I am pleased to announce the release of Envoy Gateway + v${MAJOR_VERSION}.${MINOR_VERSION}. A big thank you to all the contributors that made this release possible. + Refer to the official v${MAJOR_VERSION}.${MINOR_VERSION} announcement for release details and the project docs + to start using Envoy Gateway. + ... + ``` + + Link to the GitHub release and release announcement page that highlights the release. + +[release notes]: https://github.com/envoyproxy/gateway/tree/main/release-notes +[Pull Request]: https://github.com/envoyproxy/gateway/pulls +[Quickstart Guide]: https://github.com/envoyproxy/gateway/blob/main/docs/user/quickstart.md +[Build and Test]: https://github.com/envoyproxy/gateway/blob/main/.github/workflows/build_and_test.yaml +[release GitHub action]: https://github.com/envoyproxy/gateway/blob/main/.github/workflows/release.yaml +[release workflow]: https://github.com/envoyproxy/gateway/actions/workflows/release.yaml +[image]: https://hub.docker.com/r/envoyproxy/gateway/tags +[release]: https://github.com/envoyproxy/gateway/releases +[Generate]: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes +[PR #635]: https://github.com/envoyproxy/gateway/pull/635 +[PR #958]: https://github.com/envoyproxy/gateway/pull/958 +[PR #1002]: https://github.com/envoyproxy/gateway/pull/1002 +[VERSION]: https://github.com/envoyproxy/gateway/blob/main/VERSION diff --git a/site/content/en/v0.4.0/contributions/_index.md b/site/content/en/v0.4.0/contributions/_index.md new file mode 100644 index 000000000000..3255d996472a --- /dev/null +++ b/site/content/en/v0.4.0/contributions/_index.md @@ -0,0 +1,5 @@ +--- +title: Get Involved +description: "This section includes contents related to **Contributions**" +weight: 100 +--- diff --git a/site/content/en/docs/v0.4.0/design/_index.md b/site/content/en/v0.4.0/design/_index.md similarity index 100% rename from site/content/en/docs/v0.4.0/design/_index.md rename to site/content/en/v0.4.0/design/_index.md diff --git a/site/content/en/docs/v0.4.0/design/bootstrap.md b/site/content/en/v0.4.0/design/bootstrap.md similarity index 100% rename from site/content/en/docs/v0.4.0/design/bootstrap.md rename to site/content/en/v0.4.0/design/bootstrap.md diff --git a/site/content/en/docs/v0.4.0/design/config-api.md b/site/content/en/v0.4.0/design/config-api.md similarity index 100% rename from site/content/en/docs/v0.4.0/design/config-api.md rename to site/content/en/v0.4.0/design/config-api.md diff --git a/site/content/en/docs/v0.4.0/design/egctl.md b/site/content/en/v0.4.0/design/egctl.md similarity index 100% rename from site/content/en/docs/v0.4.0/design/egctl.md rename to site/content/en/v0.4.0/design/egctl.md diff --git a/site/content/en/docs/v0.4.0/design/extending-envoy-gateway.md b/site/content/en/v0.4.0/design/extending-envoy-gateway.md similarity index 100% rename from site/content/en/docs/v0.4.0/design/extending-envoy-gateway.md rename to site/content/en/v0.4.0/design/extending-envoy-gateway.md diff --git a/site/content/en/docs/v0.4.0/design/gatewayapi-translator.md b/site/content/en/v0.4.0/design/gatewayapi-translator.md similarity index 100% rename from site/content/en/docs/v0.4.0/design/gatewayapi-translator.md rename to site/content/en/v0.4.0/design/gatewayapi-translator.md diff --git a/site/content/en/v0.4.0/design/goals.md b/site/content/en/v0.4.0/design/goals.md new file mode 100644 index 000000000000..fd38b2004c61 --- /dev/null +++ b/site/content/en/v0.4.0/design/goals.md @@ -0,0 +1,91 @@ +--- +title: "Goals" +weight: 1 +--- + +The high-level goal of the Envoy Gateway project is to attract more users to Envoy by lowering barriers to adoption +through expressive, extensible, role-oriented APIs that support a multitude of ingress and L7/L4 traffic routing +use cases; and provide a common foundation for vendors to build value-added products without having to re-engineer +fundamental interactions. + +## Objectives + +### Expressive API + +The Envoy Gateway project will expose a simple and expressive API, with defaults set for many capabilities. + +The API will be the Kubernetes-native [Gateway API][], plus Envoy-specific extensions and extension points. This +expressive and familiar API will make Envoy accessible to more users, especially application developers, and make Envoy +a stronger option for "getting started" as compared to other proxies. Application developers will use the API out of +the box without needing to understand in-depth concepts of Envoy Proxy or use OSS wrappers. The API will use familiar +nouns that [users](#personas) understand. + +The core full-featured Envoy xDS APIs will remain available for those who need more capability and for those who +add functionality on top of Envoy Gateway, such as commercial API gateway products. + +This expressive API will not be implemented by Envoy Proxy, but rather an officially supported translation layer +on top. + +### Batteries included + +Envoy Gateway will simplify how Envoy is deployed and managed, allowing application developers to focus on +delivering core business value. + +The project plans to include additional infrastructure components required by users to fulfill their Ingress and API +gateway needs: It will handle Envoy infrastructure provisioning (e.g. Kubernetes Service, Deployment, et cetera), and +possibly infrastructure provisioning of related sidecar services. It will include sensible defaults with the ability to +override. It will include channels for improving ops by exposing status through API conditions and Kubernetes status +sub-resources. + +Making an application accessible needs to be a trivial task for any developer. Similarly, infrastructure administrators +will enjoy a simplified management model that doesn't require extensive knowledge of the solution's architecture to +operate. + +### All environments + +Envoy Gateway will support running natively in Kubernetes environments as well as non-Kubernetes deployments. + +Initially, Kubernetes will receive the most focus, with the aim of having Envoy Gateway become the de facto +standard for Kubernetes ingress supporting the [Gateway API][]. +Additional goals include multi-cluster support and various runtime environments. + +### Extensibility + +Vendors will have the ability to provide value-added products built on the Envoy Gateway foundation. + +It will remain easy for end-users to leverage common Envoy Proxy extension points such as providing an implementation +for authentication methods and rate-limiting. For advanced use cases, users will have the ability to use the full power +of xDS. + +Since a general-purpose API cannot address all use cases, Envoy Gateway will provide additional extension points +for flexibility. As such, Envoy Gateway will form the base of vendor-provided managed control plane solutions, +allowing vendors to shift to a higher management plane layer. + +## Non-objectives + +### Cannibalize vendor models + +Vendors need to have the ability to drive commercial value, so the goal is not to cannibalize any existing vendor +monetization model, though some vendors may be affected by it. + +### Disrupt current Envoy usage patterns + +Envoy Gateway is purely an additive convenience layer and is not meant to disrupt any usage pattern of any user +with Envoy Proxy, xDS, or go-control-plane. + +## Personas + +_In order of priority_ + +### 1. Application developer + +The application developer spends the majority of their time developing business logic code. They require the ability to +manage access to their application. + +### 2. Infrastructure administrators + +The infrastructure administrators are responsible for the installation, maintenance, and operation of +API gateways appliances in infrastructure, such as CRDs, roles, service accounts, certificates, etc. +Infrastructure administrators support the needs of application developers by managing instances of Envoy Gateway. + +[Gateway API]: https://gateway-api.sigs.k8s.io/ diff --git a/site/content/en/docs/v0.4.0/design/rate-limit.md b/site/content/en/v0.4.0/design/rate-limit.md similarity index 100% rename from site/content/en/docs/v0.4.0/design/rate-limit.md rename to site/content/en/v0.4.0/design/rate-limit.md diff --git a/site/content/en/docs/v0.4.0/design/request-authentication.md b/site/content/en/v0.4.0/design/request-authentication.md similarity index 100% rename from site/content/en/docs/v0.4.0/design/request-authentication.md rename to site/content/en/v0.4.0/design/request-authentication.md diff --git a/site/content/en/docs/v0.4.0/design/roadmap.md b/site/content/en/v0.4.0/design/roadmap.md similarity index 100% rename from site/content/en/docs/v0.4.0/design/roadmap.md rename to site/content/en/v0.4.0/design/roadmap.md diff --git a/site/content/en/docs/v0.4.0/design/system-design.md b/site/content/en/v0.4.0/design/system-design.md similarity index 100% rename from site/content/en/docs/v0.4.0/design/system-design.md rename to site/content/en/v0.4.0/design/system-design.md diff --git a/site/content/en/docs/v0.4.0/design/tcp-udp-design.md b/site/content/en/v0.4.0/design/tcp-udp-design.md similarity index 100% rename from site/content/en/docs/v0.4.0/design/tcp-udp-design.md rename to site/content/en/v0.4.0/design/tcp-udp-design.md diff --git a/site/content/en/docs/v0.4.0/design/watching.md b/site/content/en/v0.4.0/design/watching.md similarity index 100% rename from site/content/en/docs/v0.4.0/design/watching.md rename to site/content/en/v0.4.0/design/watching.md diff --git a/site/content/en/docs/v0.4.0/images/architecture.png b/site/content/en/v0.4.0/images/architecture.png similarity index 100% rename from site/content/en/docs/v0.4.0/images/architecture.png rename to site/content/en/v0.4.0/images/architecture.png diff --git a/site/content/en/docs/v0.4.0/images/extension-example.png b/site/content/en/v0.4.0/images/extension-example.png similarity index 100% rename from site/content/en/docs/v0.4.0/images/extension-example.png rename to site/content/en/v0.4.0/images/extension-example.png diff --git a/site/content/en/docs/v0.4.0/user/_index.md b/site/content/en/v0.4.0/user/_index.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/_index.md rename to site/content/en/v0.4.0/user/_index.md diff --git a/site/content/en/docs/v0.4.0/user/authn.md b/site/content/en/v0.4.0/user/authn.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/authn.md rename to site/content/en/v0.4.0/user/authn.md diff --git a/site/content/en/docs/v0.4.0/user/customize-envoyproxy.md b/site/content/en/v0.4.0/user/customize-envoyproxy.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/customize-envoyproxy.md rename to site/content/en/v0.4.0/user/customize-envoyproxy.md diff --git a/site/content/en/docs/v0.4.0/user/deployment-mode.md b/site/content/en/v0.4.0/user/deployment-mode.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/deployment-mode.md rename to site/content/en/v0.4.0/user/deployment-mode.md diff --git a/site/content/en/docs/v0.4.0/user/egctl.md b/site/content/en/v0.4.0/user/egctl.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/egctl.md rename to site/content/en/v0.4.0/user/egctl.md diff --git a/site/content/en/docs/v0.4.0/user/gatewayapi-support.md b/site/content/en/v0.4.0/user/gatewayapi-support.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/gatewayapi-support.md rename to site/content/en/v0.4.0/user/gatewayapi-support.md diff --git a/site/content/en/docs/v0.4.0/user/grpc-routing.md b/site/content/en/v0.4.0/user/grpc-routing.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/grpc-routing.md rename to site/content/en/v0.4.0/user/grpc-routing.md diff --git a/site/content/en/docs/v0.4.0/user/http-redirect.md b/site/content/en/v0.4.0/user/http-redirect.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/http-redirect.md rename to site/content/en/v0.4.0/user/http-redirect.md diff --git a/site/content/en/docs/v0.4.0/user/http-request-headers.md b/site/content/en/v0.4.0/user/http-request-headers.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/http-request-headers.md rename to site/content/en/v0.4.0/user/http-request-headers.md diff --git a/site/content/en/docs/v0.4.0/user/http-response-headers.md b/site/content/en/v0.4.0/user/http-response-headers.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/http-response-headers.md rename to site/content/en/v0.4.0/user/http-response-headers.md diff --git a/site/content/en/docs/v0.4.0/user/http-routing.md b/site/content/en/v0.4.0/user/http-routing.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/http-routing.md rename to site/content/en/v0.4.0/user/http-routing.md diff --git a/site/content/en/docs/v0.4.0/user/http-traffic-splitting.md b/site/content/en/v0.4.0/user/http-traffic-splitting.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/http-traffic-splitting.md rename to site/content/en/v0.4.0/user/http-traffic-splitting.md diff --git a/site/content/en/docs/v0.4.0/user/http-urlrewrite.md b/site/content/en/v0.4.0/user/http-urlrewrite.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/http-urlrewrite.md rename to site/content/en/v0.4.0/user/http-urlrewrite.md diff --git a/site/content/en/docs/v0.4.0/user/quickstart.md b/site/content/en/v0.4.0/user/quickstart.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/quickstart.md rename to site/content/en/v0.4.0/user/quickstart.md diff --git a/site/content/en/docs/v0.4.0/user/rate-limit.md b/site/content/en/v0.4.0/user/rate-limit.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/rate-limit.md rename to site/content/en/v0.4.0/user/rate-limit.md diff --git a/site/content/en/docs/v0.4.0/user/secure-gateways.md b/site/content/en/v0.4.0/user/secure-gateways.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/secure-gateways.md rename to site/content/en/v0.4.0/user/secure-gateways.md diff --git a/site/content/en/docs/v0.4.0/user/tcp-routing.md b/site/content/en/v0.4.0/user/tcp-routing.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/tcp-routing.md rename to site/content/en/v0.4.0/user/tcp-routing.md diff --git a/site/content/en/docs/v0.4.0/user/tls-passthrough.md b/site/content/en/v0.4.0/user/tls-passthrough.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/tls-passthrough.md rename to site/content/en/v0.4.0/user/tls-passthrough.md diff --git a/site/content/en/docs/v0.4.0/user/udp-routing.md b/site/content/en/v0.4.0/user/udp-routing.md similarity index 100% rename from site/content/en/docs/v0.4.0/user/udp-routing.md rename to site/content/en/v0.4.0/user/udp-routing.md diff --git a/site/content/en/v0.5.0/_index.md b/site/content/en/v0.5.0/_index.md new file mode 100644 index 000000000000..3772c64b1ccc --- /dev/null +++ b/site/content/en/v0.5.0/_index.md @@ -0,0 +1,10 @@ ++++ +title = "Welcome to Envoy Gateway" +description = "Envoy Gateway Documents" + +[[cascade]] +type = "docs" ++++ + +Envoy Gateway is an open source project for managing **Envoy Proxy** as a standalone or Kubernetes-based application +gateway. **Gateway API** resources are used to dynamically provision and configure the managed Envoy Proxies. diff --git a/site/content/en/docs/v0.3.0/api/_index.md b/site/content/en/v0.5.0/api/_index.md similarity index 87% rename from site/content/en/docs/v0.3.0/api/_index.md rename to site/content/en/v0.5.0/api/_index.md index 1d7c67c8c151..396d9ffcefcf 100644 --- a/site/content/en/docs/v0.3.0/api/_index.md +++ b/site/content/en/v0.5.0/api/_index.md @@ -1,4 +1,5 @@ --- title: "API" description: This section includes APIs of Envoy Gateway. +weight: 80 --- diff --git a/site/content/en/docs/v0.5.0/api/config_types.md b/site/content/en/v0.5.0/api/config_types.md similarity index 100% rename from site/content/en/docs/v0.5.0/api/config_types.md rename to site/content/en/v0.5.0/api/config_types.md diff --git a/site/content/en/docs/v0.5.0/api/extension_types.md b/site/content/en/v0.5.0/api/extension_types.md similarity index 100% rename from site/content/en/docs/v0.5.0/api/extension_types.md rename to site/content/en/v0.5.0/api/extension_types.md diff --git a/site/content/en/v0.5.0/contributions/CODEOWNERS.md b/site/content/en/v0.5.0/contributions/CODEOWNERS.md new file mode 100644 index 000000000000..9e596002bb33 --- /dev/null +++ b/site/content/en/v0.5.0/contributions/CODEOWNERS.md @@ -0,0 +1,18 @@ +--- +title: "Maintainers" +--- + +## The following maintainers, listed in alphabetical order, own everything + +- @AliceProxy +- @arkodg +- @Xunzhuo +- @zirain +- @qicz + +## Emeritus Maintainers + +- @danehans +- @alexgervais +- @skriss +- @youngnick diff --git a/site/content/en/v0.5.0/contributions/CODE_OF_CONDUCT.md b/site/content/en/v0.5.0/contributions/CODE_OF_CONDUCT.md new file mode 100644 index 000000000000..1f17c0889458 --- /dev/null +++ b/site/content/en/v0.5.0/contributions/CODE_OF_CONDUCT.md @@ -0,0 +1,5 @@ +--- +title: "Code of Conduct" +--- + +Gateway follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). diff --git a/site/content/en/v0.5.0/contributions/CONTRIBUTING.md b/site/content/en/v0.5.0/contributions/CONTRIBUTING.md new file mode 100644 index 000000000000..21dcd9a1941a --- /dev/null +++ b/site/content/en/v0.5.0/contributions/CONTRIBUTING.md @@ -0,0 +1,189 @@ +--- +title: "Contributing" +weight: 3 +--- + +We welcome contributions from the community. Please carefully review the [project goals](GOALS.md) +and following guidelines to streamline your contributions. + +## Communication + +* Before starting work on a major feature, please contact us via GitHub or Slack. We will ensure no + one else is working on it and ask you to open a GitHub issue. +* A "major feature" is defined as any change that is > 100 LOC altered (not including tests), or + changes any user-facing behavior. We will use the GitHub issue to discuss the feature and come to + agreement. This is to prevent your time being wasted, as well as ours. The GitHub review process + for major features is also important so that [affiliations with commit access](CODEOWNERS.md) can + come to agreement on the design. If it's appropriate to write a design document, the document must + be hosted either in the GitHub issue, or linked to from the issue and hosted in a world-readable + location. +* Small patches and bug fixes don't need prior communication. + +## Inclusivity + +The Envoy Gateway community has an explicit goal to be inclusive to all. As such, all PRs must adhere +to the following guidelines for all code, APIs, and documentation: + +* The following words and phrases are not allowed: + * *Whitelist*: use allowlist instead. + * *Blacklist*: use denylist or blocklist instead. + * *Master*: use primary instead. + * *Slave*: use secondary or replica instead. +* Documentation should be written in an inclusive style. The [Google developer + documentation](https://developers.google.com/style/inclusive-documentation) contains an excellent + reference on this topic. +* The above policy is not considered definitive and may be amended in the future as industry best + practices evolve. Additional comments on this topic may be provided by maintainers during code + review. + +## Submitting a PR + +* Fork the repo. +* Hack +* DCO sign-off each commit. This can be done with `git commit -s`. +* Submit your PR. +* Tests will automatically run for you. +* We will **not** merge any PR that is not passing tests. +* PRs are expected to have 100% test coverage for added code. This can be verified with a coverage + build. If your PR cannot have 100% coverage for some reason please clearly explain why when you + open it. +* Any PR that changes user-facing behavior **must** have associated documentation in the [docs](https://github.com/envoyproxy/gateway/tree/main/docs) folder of the repo as + well as the [changelog](../releases). +* All code comments and documentation are expected to have proper English grammar and punctuation. + If you are not a fluent English speaker (or a bad writer ;-)) please let us know and we will try + to find some help but there are no guarantees. +* Your PR title should be descriptive, and generally start with type that contains a subsystem name with `()` if necessary + and summary followed by a colon. format `chore/docs/feat/fix/refactor/style/test: summary`. + Examples: + * "docs: fix grammar error" + * "feat(translator): add new feature" + * "fix: fix xx bug" + * "chore: change ci & build tools etc" +* Your PR commit message will be used as the commit message when your PR is merged. You should + update this field if your PR diverges during review. +* Your PR description should have details on what the PR does. If it fixes an existing issue it + should end with "Fixes #XXX". +* If your PR is co-authored or based on an earlier PR from another contributor, + please attribute them with `Co-authored-by: name `. See + GitHub's [multiple author + guidance](https://help.github.com/en/github/committing-changes-to-your-project/creating-a-commit-with-multiple-authors) + for further details. +* When all tests are passing and all other conditions described herein are satisfied, a maintainer + will be assigned to review and merge the PR. +* Once you submit a PR, *please do not rebase it*. It's much easier to review if subsequent commits + are new commits and/or merges. We squash and merge so the number of commits you have in the PR + doesn't matter. +* We expect that once a PR is opened, it will be actively worked on until it is merged or closed. + We reserve the right to close PRs that are not making progress. This is generally defined as no + changes for 7 days. Obviously PRs that are closed due to lack of activity can be reopened later. + Closing stale PRs helps us to keep on top of all the work currently in flight. + +## Maintainer PR Review Policy + +* See [CODEOWNERS.md](CODEOWNERS.md) for the current list of maintainers. +* A maintainer representing a different affiliation from the PR owner is required to review and + approve the PR. +* When the project matures, it is expected that a "domain expert" for the code the PR touches should + review the PR. This person does not require commit access, just domain knowledge. +* The above rules may be waived for PRs which only update docs or comments, or trivial changes to + tests and tools (where trivial is decided by the maintainer in question). +* If there is a question on who should review a PR please discuss in Slack. +* Anyone is welcome to review any PR that they want, whether they are a maintainer or not. +* Please make sure that the PR title, commit message, and description are updated if the PR changes + significantly during review. +* Please **clean up the title and body** before merging. By default, GitHub fills the squash merge + title with the original title, and the commit body with every individual commit from the PR. + The maintainer doing the merge should make sure the title follows the guidelines above and should + overwrite the body with the original commit message from the PR (cleaning it up if necessary) + while preserving the PR author's final DCO sign-off. + +## Decision making + +This is a new and complex project, and we need to make a lot of decisions very quickly. +To this end, we've settled on this process for making (possibly contentious) decisions: + +* For decisions that need a record, we create an issue. +* In that issue, we discuss opinions, then a maintainer can call for a vote in a comment. +* Maintainers can cast binding votes on that comment by reacting or replying in another comment. +* Non-maintainer community members are welcome to cast non-binding votes by either of these methods. +* Voting will be resolved by simple majority. +* In the event of deadlocks, the question will be put to steering instead. + +## DCO: Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](https://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign-off when creating the git commit via `git commit -s`. + +If you want this to be automatic you can set up some aliases: + +```bash +git config --add alias.amend "commit -s --amend" +git config --add alias.c "commit -s" +``` + +## Fixing DCO + +If your PR fails the DCO check, it's necessary to fix the entire commit history in the PR. Best +practice is to [squash](https://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html) +the commit history to a single commit, append the DCO sign-off as described above, and [force +push](https://git-scm.com/docs/git-push#git-push---force). For example, if you have 2 commits in +your history: + +```bash +git rebase -i HEAD^^ +(interactive squash + DCO append) +git push origin -f +``` + +Note, that in general rewriting history in this way is a hindrance to the review process and this +should only be done to correct a DCO mistake. diff --git a/site/content/en/v0.5.0/contributions/DEVELOP.md b/site/content/en/v0.5.0/contributions/DEVELOP.md new file mode 100644 index 000000000000..a6fd3846f565 --- /dev/null +++ b/site/content/en/v0.5.0/contributions/DEVELOP.md @@ -0,0 +1,162 @@ +--- +title: "Developer Guide" +weight: 2 +--- + +Envoy Gateway is built using a [make][]-based build system. Our CI is based on [Github Actions][] using [workflows][]. + +## Prerequisites + +### go + +* Version: 1.20 +* Installation Guide: https://go.dev/doc/install + +### make + +* Recommended Version: 4.0 or later +* Installation Guide: https://www.gnu.org/software/make + +### docker + +* Optional when you want to build a Docker image or run `make` inside Docker. +* Recommended Version: 20.10.16 +* Installation Guide: https://docs.docker.com/engine/install + +### python3 + +* Need a `python3` program +* Must have a functioning `venv` module; this is part of the standard + library, but some distributions (such as Debian and Ubuntu) replace + it with a stub and require you to install a `python3-venv` package + separately. + +## Quickstart + +* Run `make help` to see all the available targets to build, test and run Envoy Gateway. + +### Building + +* Run `make build` to build all the binaries. +* Run `make build BINS="envoy-gateway"` to build the Envoy Gateway binary. +* Run `make build BINS="egctl"` to build the egctl binary. + +__Note:__ The binaries get generated in the `bin/$OS/$ARCH` directory, for example, `bin/linux/amd64/`. + +### Testing + +* Run `make test` to run the golang tests. + +* Run `make testdata` to generate the golden YAML testdata files. + +### Running Linters + +* Run `make lint` to make sure your code passes all the linter checks. +__Note:__ The `golangci-lint` configuration resides [here](https://github.com/envoyproxy/gateway/blob/main/tools/linter/golangci-lint/.golangci.yml). + +### Building and Pushing the Image + +* Run `IMAGE=docker.io/you/gateway-dev make image` to build the docker image. +* Run `IMAGE=docker.io/you/gateway-dev make push-multiarch` to build and push the multi-arch docker image. + +__Note:__ Replace `IMAGE` with your registry's image name. + +### Deploying Envoy Gateway for Test/Dev + +* Run `make create-cluster` to create a [Kind][] cluster. + +#### Option 1: Use the Latest [gateway-dev][] Image + +* Run `TAG=latest make kube-deploy` to deploy Envoy Gateway in the Kind cluster using the latest image. Replace `latest` + to use a different image tag. + +#### Option 2: Use a Custom Image + +* Run `make kube-install-image` to build an image from the tip of your current branch and load it in the Kind cluster. +* Run `IMAGE_PULL_POLICY=IfNotPresent make kube-deploy` to install Envoy Gateway into the Kind cluster using your custom image. + +### Deploying Envoy Gateway in Kubernetes + +* Run `TAG=latest make kube-deploy` to deploy Envoy Gateway using the latest image into a Kubernetes cluster (linked to + the current kube context). Preface the command with `IMAGE` or replace `TAG` to use a different Envoy Gateway image or + tag. +* Run `make kube-undeploy` to uninstall Envoy Gateway from the cluster. + +__Note:__ Envoy Gateway is tested against Kubernetes v1.24.0. + +### Demo Setup + +* Run `make kube-demo` to deploy a demo backend service, gatewayclass, gateway and httproute resource +(similar to steps outlined in the [Quickstart][] docs) and test the configuration. +* Run `make kube-demo-undeploy` to delete the resources created by the `make kube-demo` command. + +### Run Gateway API Conformance Tests + +The commands below deploy Envoy Gateway to a Kubernetes cluster and run the Gateway API conformance tests. Refer to the +Gateway API [conformance homepage][] to learn more about the tests. If Envoy Gateway is already installed, run +`TAG=latest make run-conformance` to run the conformance tests. + +#### On a Linux Host + +* Run `TAG=latest make conformance` to create a Kind cluster, install Envoy Gateway using the latest [gateway-dev][] + image, and run Gateway API conformance tests. + +#### On a Mac Host + +Since Mac doesn't support [directly exposing][] the Docker network to the Mac host, use one of the following +workarounds to run conformance tests: + +* Deploy your own Kubernetes cluster or use Docker Desktop with [Kubernetes support][] and then run + `TAG=latest make kube-deploy run-conformance`. This will install Envoy Gateway using the latest [gateway-dev][] image + to the Kubernetes cluster using the current kubectl context and run the conformance tests. Use `make kube-undeploy` to + uninstall Envoy Gateway. +* Install and run [Docker Mac Net Connect][mac_connect] and then run `TAG=latest make conformance`. + +__Note:__ Preface commands with `IMAGE` or replace `TAG` to use a different Envoy Gateway image or tag. If `TAG` +is unspecified, the short SHA of your current branch is used. + +### Debugging the Envoy Config + +An easy way to view the envoy config that Envoy Gateway is using is to port-forward to the admin interface port +(currently `19000`) on the Envoy deployment that corresponds to a Gateway so that it can be accessed locally. + +Get the name of the Envoy deployment. The following example is for Gateway `eg` in the `default` namespace: + +```shell +export ENVOY_DEPLOYMENT=$(kubectl get deploy -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Port forward the admin interface port: + +```shell +kubectl port-forward deploy/${ENVOY_DEPLOYMENT} -n envoy-gateway-system 19000:19000 +``` + +Now you are able to view the running Envoy configuration by navigating to `127.0.0.1:19000/config_dump`. + +There are many other endpoints on the [Envoy admin interface][] that may be helpful when debugging. + +### JWT Testing + +An example [JSON Web Token (JWT)][jwt] and [JSON Web Key Set (JWKS)][jwks] are used for the [request authentication][] +user guide. The JWT was created by the [JWT Debugger][], using the `RS256` algorithm. The public key from the JWTs +verify signature was copied to [JWK Creator][] for generating the JWK. The JWK Creator was configured with matching +settings, i.e. `Signing` public key use and the `RS256` algorithm. The generated JWK was wrapped in a JWKS structure +and is hosted in the repo. + +[Quickstart]: https://github.com/envoyproxy/gateway/blob/main/docs/latest/user/quickstart.md +[make]: https://www.gnu.org/software/make/ +[Github Actions]: https://docs.github.com/en/actions +[workflows]: https://github.com/envoyproxy/gateway/tree/main/.github/workflows +[Kind]: https://kind.sigs.k8s.io/ +[conformance homepage]: https://gateway-api.sigs.k8s.io/concepts/conformance/ +[directly exposing]: https://kind.sigs.k8s.io/docs/user/loadbalancer/ +[Kubernetes support]: https://docs.docker.com/desktop/kubernetes/ +[gateway-dev]: https://hub.docker.com/r/envoyproxy/gateway-dev/tags +[mac_connect]: https://github.com/chipmk/docker-mac-net-connect +[Envoy admin interface]: https://www.envoyproxy.io/docs/envoy/latest/operations/admin#operations-admin-interface +[jwt]: https://tools.ietf.org/html/rfc7519 +[jwks]: https://tools.ietf.org/html/rfc7517 +[request authentication]: https://gateway.envoyproxy.io/latest/user/authn.html +[JWT Debugger]: https://jwt.io/ +[JWK Creator]: https://russelldavies.github.io/jwk-creator/ diff --git a/site/content/en/v0.5.0/contributions/DOCS.md b/site/content/en/v0.5.0/contributions/DOCS.md new file mode 100644 index 000000000000..1abae95763c5 --- /dev/null +++ b/site/content/en/v0.5.0/contributions/DOCS.md @@ -0,0 +1,65 @@ +--- +title: "Working on the Envoy Gateway Docs" +--- + +The documentation for the Envoy Gateway lives in the `docs/` directory. Any +individual document can be written using either [reStructuredText] or [Markdown], +you can choose the format that you're most comfortable with when working on the +documentation. + +## Documentation Structure + +We supported the versioned Docs now, the directory name under docs represents +the version of docs. The root of the latest site is in `docs/latest/index.rst`. +This is probably where to start if you're trying to understand how things fit together. + +Note that the new contents should be added to `docs/latest` and will be cut off at +the next release. The contents under `docs/v0.2.0` are auto-generated, +and usually do not need to make changes to them, unless if you find the current release pages have +some incorrect contents. If so, you should send a PR to update contents both of `docs/latest` +and `docs/v0.2.0`. + +It's important to note that a given document _must_ have a reference in some +`.. toctree::` section for the document to be reachable. Not everything needs +to be in `docs/index.rst`'s `toctree` though. + +You can access the website which represents the current release in default, +and you can access the website which contains the latest version changes in +[Here][latest-website] or at the footer of the pages. + +## Documentation Workflow + +To work with the docs, just edit reStructuredText or Markdown files in `docs`, +then run + +```bash +make docs +``` + +This will create `docs/html` with the built HTML pages. You can view the docs +either simply by pointing a web browser at the `file://` path to your +`docs/html`, or by firing up a static webserver from that directory, e.g. + +``` shell +make docs-serve +``` + +If you want to generate a new release version of the docs, like `v0.3.0`, then run + +```bash +make docs-release TAG=v0.3.0 +``` + +This will update the VERSION file at the project root, which records current release version, +and it will be used in the pages version context and binary version output. Also, this will generate +new dir `docs/v0.3.0`, which contains docs at v0.3.0 and updates artifact links to `v0.3.0` +in all files under `docs/v0.3.0/user`, like `quickstart.md`, `http-routing.md` and etc. + +## Publishing Docs + +Whenever docs are pushed to `main`, CI will publish the built docs to GitHub +Pages. For more details, see `.github/workflows/docs.yaml`. + +[reStructuredText]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html +[Markdown]: https://daringfireball.net/projects/markdown/syntax +[latest-website]: https://gateway.envoyproxy.io/latest diff --git a/site/content/en/v0.5.0/contributions/RELEASING.md b/site/content/en/v0.5.0/contributions/RELEASING.md new file mode 100644 index 000000000000..617baf1933e0 --- /dev/null +++ b/site/content/en/v0.5.0/contributions/RELEASING.md @@ -0,0 +1,230 @@ +--- +title: "Release Process" +--- + +This document guides maintainers through the process of creating an Envoy Gateway release. + +- [Release Candidate](#release-candidate) +- [Minor Release](#minor-release) +- [Announce the Release](#announce-the-release) + +## Release Candidate + +The following steps should be used for creating a release candidate. + +### Prerequisites + +- Permissions to push to the Envoy Gateway repository. + +Set environment variables for use in subsequent steps: + +```shell +export MAJOR_VERSION=0 +export MINOR_VERSION=3 +export RELEASE_CANDIDATE_NUMBER=1 +export GITHUB_REMOTE=origin +``` + +1. Clone the repo, checkout the `main` branch, ensure it’s up-to-date, and your local branch is clean. +2. Create a topic branch for adding the release notes and updating the [VERSION][] file with the release version. Refer to previous [release notes][] and [VERSION][] for additional details. +3. Sign, commit, and push your changes to your fork. +4. Submit a [Pull Request][] to merge the changes into the `main` branch. Do not proceed until your PR has merged and + the [Build and Test][] has successfully completed. +5. Create a new release branch from `main`. The release branch should be named + `release/v${MAJOR_VERSION}.${MINOR_VERSION}`, e.g. `release/v0.3`. + + ```shell + git checkout -b release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +6. Push the branch to the Envoy Gateway repo. + + ```shell + git push ${GITHUB_REMOTE} release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +7. Create a topic branch for updating the Envoy proxy image to the tag supported by the release. Reference [PR #958][] + for additional details on updating the image tag. +8. Sign, commit, and push your changes to your fork. +9. Submit a [Pull Request][] to merge the changes into the `release/v${MAJOR_VERSION}.${MINOR_VERSION}` branch. Do not + proceed until your PR has merged into the release branch and the [Build and Test][] has completed for your PR. +10. Ensure your release branch is up-to-date and tag the head of your release branch with the release candidate number. + + ```shell + git tag -a v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} -m 'Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} Release Candidate' + ``` + +11. Push the tag to the Envoy Gateway repository. + + ```shell + git push ${GITHUB_REMOTE} v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} + ``` + +12. This will trigger the [release GitHub action][] that generates the release, release artifacts, etc. +13. Confirm that the [release workflow][] completed successfully. +14. Confirm that the Envoy Gateway [image][] with the correct release tag was published to Docker Hub. +15. Confirm that the [release][] was created. +16. Note that the [Quickstart Guide][] references are __not__ updated for release candidates. However, test + the quickstart steps using the release candidate by manually updating the links. +17. [Generate][] the GitHub changelog. +18. Ensure you check the "This is a pre-release" checkbox when editing the GitHub release. +19. If you find any bugs in this process, please create an issue. + +### Setup cherry picker action + +After release branch cut, RM (Release Manager) should add job [cherrypick action](../../../.github/workflows/cherrypick.yaml) for target release. + +Configuration looks like following: + +```yaml + cherry_pick_release_v0_4: + runs-on: ubuntu-latest + name: Cherry pick into release-v0.4 + if: ${{ contains(github.event.pull_request.labels.*.name, 'cherrypick/release-v0.4') && github.event.pull_request.merged == true }} + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + fetch-depth: 0 + - name: Cherry pick into release/v0.4 + uses: carloscastrojumo/github-cherry-pick-action@v1.0.9 + with: + branch: release/v0.4 + title: "[release/v0.4] {old_title}" + body: "Cherry picking #{old_pull_request_id} onto release/v0.4" + labels: | + cherrypick/release-v0.4 + # put release manager here + reviewers: | + AliceProxy +``` + +Replace `v0.4` with real branch name, and `AliceProxy` with the real name of RM. + +## Minor Release + +The following steps should be used for creating a minor release. + +### Prerequisites + +- Permissions to push to the Envoy Gateway repository. +- A release branch that has been cut from the corresponding release candidate. Refer to the + [Release Candidate](#release-candidate) section for additional details on cutting a release candidate. + +Set environment variables for use in subsequent steps: + +```shell +export MAJOR_VERSION=0 +export MINOR_VERSION=3 +export GITHUB_REMOTE=origin +``` + +1. Clone the repo, checkout the `main` branch, ensure it’s up-to-date, and your local branch is clean. +2. Create a topic branch for adding the release notes, release announcement, and versioned release docs. + + 1. Create the release notes. Reference previous [release notes][] for additional details. __Note:__ The release + notes should be an accumulation of the release candidate release notes and any changes since the release + candidate. + 2. Create a release announcement. Refer to [PR #635] as an example release announcement. + 3. Include the release in the compatibility matrix. Refer to [PR #1002] as an example. + 4. Generate the versioned release docs: + + ``` shell + make docs-release TAG=v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +3. Sign, commit, and push your changes to your fork. +4. Submit a [Pull Request][] to merge the changes into the `main` branch. Do not proceed until all your PRs have merged + and the [Build and Test][] has completed for your final PR. + +5. Checkout the release branch. + + ```shell + git checkout -b release/v${MAJOR_VERSION}.${MINOR_VERSION} $GITHUB_REMOTE/release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +6. If the tip of the release branch does not match the tip of `main`, perform the following: + + 1. Create a topic branch from the release branch. + 2. Cherry-pick the commits from `main` that differ from the release branch. + 3. Run tests locally, e.g. `make lint`. + 4. Sign, commit, and push your topic branch to your Envoy Gateway fork. + 5. Submit a PR to merge the topic from of your fork into the Envoy Gateway release branch. + 6. Do not proceed until the PR has merged and CI passes for the merged PR. + 7. If you are still on your topic branch, change to the release branch: + + ```shell + git checkout release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + + 8. Ensure your local release branch is up-to-date: + + ```shell + git pull $GITHUB_REMOTE release/v${MAJOR_VERSION}.${MINOR_VERSION} + ``` + +7. Tag the head of your release branch with the release tag. For example: + + ```shell + git tag -a v${MAJOR_VERSION}.${MINOR_VERSION}.0 -m 'Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION}.0 Release' + ``` + + __Note:__ The tag version differs from the release branch by including the `.0` patch version. + +8. Push the tag to the Envoy Gateway repository. + + ```shell + git push origin v${MAJOR_VERSION}.${MINOR_VERSION}.0 + ``` + +9. This will trigger the [release GitHub action][] that generates the release, release artifacts, etc. +10. Confirm that the [release workflow][] completed successfully. +11. Confirm that the Envoy Gateway [image][] with the correct release tag was published to Docker Hub. +12. Confirm that the [release][] was created. +13. Confirm that the steps in the [Quickstart Guide][] work as expected. +14. [Generate][] the GitHub changelog and include the following text at the beginning of the release page: + + ```console + # Release Announcement + + Check out the [v${MAJOR_VERSION}.${MINOR_VERSION} release announcement] + (https://gateway.envoyproxy.io/releases/v${MAJOR_VERSION}.${MINOR_VERSION}.html) to learn more about the release. + ``` + +If you find any bugs in this process, please create an issue. + +## Announce the Release + +It's important that the world knows about the release. Use the following steps to announce the release. + +1. Set the release information in the Envoy Gateway Slack channel. For example: + + ```shell + Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION} has been released: https://github.com/envoyproxy/gateway/releases/tag/v${MAJOR_VERSION}.${MINOR_VERSION}.0 + ``` + +2. Send a message to the Envoy Gateway Slack channel. For example: + + ```shell + On behalf of the entire Envoy Gateway community, I am pleased to announce the release of Envoy Gateway + v${MAJOR_VERSION}.${MINOR_VERSION}. A big thank you to all the contributors that made this release possible. + Refer to the official v${MAJOR_VERSION}.${MINOR_VERSION} announcement for release details and the project docs + to start using Envoy Gateway. + ... + ``` + + Link to the GitHub release and release announcement page that highlights the release. + +[release notes]: https://github.com/envoyproxy/gateway/tree/main/release-notes +[Pull Request]: https://github.com/envoyproxy/gateway/pulls +[Quickstart Guide]: https://github.com/envoyproxy/gateway/blob/main/docs/user/quickstart.md +[Build and Test]: https://github.com/envoyproxy/gateway/blob/main/.github/workflows/build_and_test.yaml +[release GitHub action]: https://github.com/envoyproxy/gateway/blob/main/.github/workflows/release.yaml +[release workflow]: https://github.com/envoyproxy/gateway/actions/workflows/release.yaml +[image]: https://hub.docker.com/r/envoyproxy/gateway/tags +[release]: https://github.com/envoyproxy/gateway/releases +[Generate]: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes +[PR #635]: https://github.com/envoyproxy/gateway/pull/635 +[PR #958]: https://github.com/envoyproxy/gateway/pull/958 +[PR #1002]: https://github.com/envoyproxy/gateway/pull/1002 +[VERSION]: https://github.com/envoyproxy/gateway/blob/main/VERSION diff --git a/site/content/en/v0.5.0/contributions/_index.md b/site/content/en/v0.5.0/contributions/_index.md new file mode 100644 index 000000000000..3255d996472a --- /dev/null +++ b/site/content/en/v0.5.0/contributions/_index.md @@ -0,0 +1,5 @@ +--- +title: Get Involved +description: "This section includes contents related to **Contributions**" +weight: 100 +--- diff --git a/site/content/en/docs/v0.5.0/design/_index.md b/site/content/en/v0.5.0/design/_index.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/_index.md rename to site/content/en/v0.5.0/design/_index.md diff --git a/site/content/en/docs/v0.5.0/design/accesslog.md b/site/content/en/v0.5.0/design/accesslog.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/accesslog.md rename to site/content/en/v0.5.0/design/accesslog.md diff --git a/site/content/en/docs/v0.5.0/design/bootstrap.md b/site/content/en/v0.5.0/design/bootstrap.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/bootstrap.md rename to site/content/en/v0.5.0/design/bootstrap.md diff --git a/site/content/en/docs/v0.5.0/design/config-api.md b/site/content/en/v0.5.0/design/config-api.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/config-api.md rename to site/content/en/v0.5.0/design/config-api.md diff --git a/site/content/en/docs/v0.5.0/design/egctl.md b/site/content/en/v0.5.0/design/egctl.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/egctl.md rename to site/content/en/v0.5.0/design/egctl.md diff --git a/site/content/en/docs/v0.5.0/design/envoy-patch-policy.md b/site/content/en/v0.5.0/design/envoy-patch-policy.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/envoy-patch-policy.md rename to site/content/en/v0.5.0/design/envoy-patch-policy.md diff --git a/site/content/en/docs/v0.5.0/design/extending-envoy-gateway.md b/site/content/en/v0.5.0/design/extending-envoy-gateway.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/extending-envoy-gateway.md rename to site/content/en/v0.5.0/design/extending-envoy-gateway.md diff --git a/site/content/en/docs/v0.5.0/design/gatewayapi-translator.md b/site/content/en/v0.5.0/design/gatewayapi-translator.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/gatewayapi-translator.md rename to site/content/en/v0.5.0/design/gatewayapi-translator.md diff --git a/site/content/en/v0.5.0/design/goals.md b/site/content/en/v0.5.0/design/goals.md new file mode 100644 index 000000000000..fd38b2004c61 --- /dev/null +++ b/site/content/en/v0.5.0/design/goals.md @@ -0,0 +1,91 @@ +--- +title: "Goals" +weight: 1 +--- + +The high-level goal of the Envoy Gateway project is to attract more users to Envoy by lowering barriers to adoption +through expressive, extensible, role-oriented APIs that support a multitude of ingress and L7/L4 traffic routing +use cases; and provide a common foundation for vendors to build value-added products without having to re-engineer +fundamental interactions. + +## Objectives + +### Expressive API + +The Envoy Gateway project will expose a simple and expressive API, with defaults set for many capabilities. + +The API will be the Kubernetes-native [Gateway API][], plus Envoy-specific extensions and extension points. This +expressive and familiar API will make Envoy accessible to more users, especially application developers, and make Envoy +a stronger option for "getting started" as compared to other proxies. Application developers will use the API out of +the box without needing to understand in-depth concepts of Envoy Proxy or use OSS wrappers. The API will use familiar +nouns that [users](#personas) understand. + +The core full-featured Envoy xDS APIs will remain available for those who need more capability and for those who +add functionality on top of Envoy Gateway, such as commercial API gateway products. + +This expressive API will not be implemented by Envoy Proxy, but rather an officially supported translation layer +on top. + +### Batteries included + +Envoy Gateway will simplify how Envoy is deployed and managed, allowing application developers to focus on +delivering core business value. + +The project plans to include additional infrastructure components required by users to fulfill their Ingress and API +gateway needs: It will handle Envoy infrastructure provisioning (e.g. Kubernetes Service, Deployment, et cetera), and +possibly infrastructure provisioning of related sidecar services. It will include sensible defaults with the ability to +override. It will include channels for improving ops by exposing status through API conditions and Kubernetes status +sub-resources. + +Making an application accessible needs to be a trivial task for any developer. Similarly, infrastructure administrators +will enjoy a simplified management model that doesn't require extensive knowledge of the solution's architecture to +operate. + +### All environments + +Envoy Gateway will support running natively in Kubernetes environments as well as non-Kubernetes deployments. + +Initially, Kubernetes will receive the most focus, with the aim of having Envoy Gateway become the de facto +standard for Kubernetes ingress supporting the [Gateway API][]. +Additional goals include multi-cluster support and various runtime environments. + +### Extensibility + +Vendors will have the ability to provide value-added products built on the Envoy Gateway foundation. + +It will remain easy for end-users to leverage common Envoy Proxy extension points such as providing an implementation +for authentication methods and rate-limiting. For advanced use cases, users will have the ability to use the full power +of xDS. + +Since a general-purpose API cannot address all use cases, Envoy Gateway will provide additional extension points +for flexibility. As such, Envoy Gateway will form the base of vendor-provided managed control plane solutions, +allowing vendors to shift to a higher management plane layer. + +## Non-objectives + +### Cannibalize vendor models + +Vendors need to have the ability to drive commercial value, so the goal is not to cannibalize any existing vendor +monetization model, though some vendors may be affected by it. + +### Disrupt current Envoy usage patterns + +Envoy Gateway is purely an additive convenience layer and is not meant to disrupt any usage pattern of any user +with Envoy Proxy, xDS, or go-control-plane. + +## Personas + +_In order of priority_ + +### 1. Application developer + +The application developer spends the majority of their time developing business logic code. They require the ability to +manage access to their application. + +### 2. Infrastructure administrators + +The infrastructure administrators are responsible for the installation, maintenance, and operation of +API gateways appliances in infrastructure, such as CRDs, roles, service accounts, certificates, etc. +Infrastructure administrators support the needs of application developers by managing instances of Envoy Gateway. + +[Gateway API]: https://gateway-api.sigs.k8s.io/ diff --git a/site/content/en/docs/v0.5.0/design/local-envoy-gateway.md b/site/content/en/v0.5.0/design/local-envoy-gateway.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/local-envoy-gateway.md rename to site/content/en/v0.5.0/design/local-envoy-gateway.md diff --git a/site/content/en/docs/v0.5.0/design/metrics.md b/site/content/en/v0.5.0/design/metrics.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/metrics.md rename to site/content/en/v0.5.0/design/metrics.md diff --git a/site/content/en/docs/v0.5.0/design/pprof.md b/site/content/en/v0.5.0/design/pprof.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/pprof.md rename to site/content/en/v0.5.0/design/pprof.md diff --git a/site/content/en/docs/v0.5.0/design/rate-limit.md b/site/content/en/v0.5.0/design/rate-limit.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/rate-limit.md rename to site/content/en/v0.5.0/design/rate-limit.md diff --git a/site/content/en/docs/v0.5.0/design/request-authentication.md b/site/content/en/v0.5.0/design/request-authentication.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/request-authentication.md rename to site/content/en/v0.5.0/design/request-authentication.md diff --git a/site/content/en/docs/v0.5.0/design/roadmap.md b/site/content/en/v0.5.0/design/roadmap.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/roadmap.md rename to site/content/en/v0.5.0/design/roadmap.md diff --git a/site/content/en/docs/v0.5.0/design/system-design.md b/site/content/en/v0.5.0/design/system-design.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/system-design.md rename to site/content/en/v0.5.0/design/system-design.md diff --git a/site/content/en/docs/v0.5.0/design/tcp-udp-design.md b/site/content/en/v0.5.0/design/tcp-udp-design.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/tcp-udp-design.md rename to site/content/en/v0.5.0/design/tcp-udp-design.md diff --git a/site/content/en/docs/v0.5.0/design/tracing.md b/site/content/en/v0.5.0/design/tracing.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/tracing.md rename to site/content/en/v0.5.0/design/tracing.md diff --git a/site/content/en/docs/v0.5.0/design/watching.md b/site/content/en/v0.5.0/design/watching.md similarity index 100% rename from site/content/en/docs/v0.5.0/design/watching.md rename to site/content/en/v0.5.0/design/watching.md diff --git a/site/content/en/v0.5.0/helm/_index.md b/site/content/en/v0.5.0/helm/_index.md new file mode 100644 index 000000000000..b4c6f79c6fda --- /dev/null +++ b/site/content/en/v0.5.0/helm/_index.md @@ -0,0 +1,5 @@ +--- +title: "Installation" +description: This section includes installation related contents of Envoy Gateway. +weight: 70 +--- diff --git a/site/content/en/docs/v0.5.0/helm/api.md b/site/content/en/v0.5.0/helm/api.md similarity index 99% rename from site/content/en/docs/v0.5.0/helm/api.md rename to site/content/en/v0.5.0/helm/api.md index ca33e2c5e1fe..130c82250ced 100644 --- a/site/content/en/docs/v0.5.0/helm/api.md +++ b/site/content/en/v0.5.0/helm/api.md @@ -1,5 +1,5 @@ --- -title: "Helm Chart Details" +title: "Helm Chart Values" --- ![Version: v0.0.0-latest](https://img.shields.io/badge/Version-v0.0.0--latest-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: latest](https://img.shields.io/badge/AppVersion-latest-informational?style=flat-square) diff --git a/site/content/en/docs/v0.5.0/images/architecture.png b/site/content/en/v0.5.0/images/architecture.png similarity index 100% rename from site/content/en/docs/v0.5.0/images/architecture.png rename to site/content/en/v0.5.0/images/architecture.png diff --git a/site/content/en/docs/v0.5.0/images/extension-example.png b/site/content/en/v0.5.0/images/extension-example.png similarity index 100% rename from site/content/en/docs/v0.5.0/images/extension-example.png rename to site/content/en/v0.5.0/images/extension-example.png diff --git a/site/content/en/docs/v0.5.0/user/_index.md b/site/content/en/v0.5.0/user/_index.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/_index.md rename to site/content/en/v0.5.0/user/_index.md diff --git a/site/content/en/docs/v0.5.0/user/authn.md b/site/content/en/v0.5.0/user/authn.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/authn.md rename to site/content/en/v0.5.0/user/authn.md diff --git a/site/content/en/docs/v0.5.0/user/customize-envoyproxy.md b/site/content/en/v0.5.0/user/customize-envoyproxy.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/customize-envoyproxy.md rename to site/content/en/v0.5.0/user/customize-envoyproxy.md diff --git a/site/content/en/docs/v0.5.0/user/deployment-mode.md b/site/content/en/v0.5.0/user/deployment-mode.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/deployment-mode.md rename to site/content/en/v0.5.0/user/deployment-mode.md diff --git a/site/content/en/docs/v0.5.0/user/egctl.md b/site/content/en/v0.5.0/user/egctl.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/egctl.md rename to site/content/en/v0.5.0/user/egctl.md diff --git a/site/content/en/docs/v0.5.0/user/envoy-patch-policy.md b/site/content/en/v0.5.0/user/envoy-patch-policy.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/envoy-patch-policy.md rename to site/content/en/v0.5.0/user/envoy-patch-policy.md diff --git a/site/content/en/docs/v0.5.0/user/gateway-address.md b/site/content/en/v0.5.0/user/gateway-address.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/gateway-address.md rename to site/content/en/v0.5.0/user/gateway-address.md diff --git a/site/content/en/docs/v0.5.0/user/gatewayapi-support.md b/site/content/en/v0.5.0/user/gatewayapi-support.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/gatewayapi-support.md rename to site/content/en/v0.5.0/user/gatewayapi-support.md diff --git a/site/content/en/docs/v0.5.0/user/grpc-routing.md b/site/content/en/v0.5.0/user/grpc-routing.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/grpc-routing.md rename to site/content/en/v0.5.0/user/grpc-routing.md diff --git a/site/content/en/docs/v0.5.0/user/http-redirect.md b/site/content/en/v0.5.0/user/http-redirect.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/http-redirect.md rename to site/content/en/v0.5.0/user/http-redirect.md diff --git a/site/content/en/docs/v0.5.0/user/http-request-headers.md b/site/content/en/v0.5.0/user/http-request-headers.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/http-request-headers.md rename to site/content/en/v0.5.0/user/http-request-headers.md diff --git a/site/content/en/docs/v0.5.0/user/http-request-mirroring.md b/site/content/en/v0.5.0/user/http-request-mirroring.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/http-request-mirroring.md rename to site/content/en/v0.5.0/user/http-request-mirroring.md diff --git a/site/content/en/docs/v0.5.0/user/http-response-headers.md b/site/content/en/v0.5.0/user/http-response-headers.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/http-response-headers.md rename to site/content/en/v0.5.0/user/http-response-headers.md diff --git a/site/content/en/docs/v0.5.0/user/http-routing.md b/site/content/en/v0.5.0/user/http-routing.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/http-routing.md rename to site/content/en/v0.5.0/user/http-routing.md diff --git a/site/content/en/docs/v0.5.0/user/http-traffic-splitting.md b/site/content/en/v0.5.0/user/http-traffic-splitting.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/http-traffic-splitting.md rename to site/content/en/v0.5.0/user/http-traffic-splitting.md diff --git a/site/content/en/docs/v0.5.0/user/http-urlrewrite.md b/site/content/en/v0.5.0/user/http-urlrewrite.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/http-urlrewrite.md rename to site/content/en/v0.5.0/user/http-urlrewrite.md diff --git a/site/content/en/docs/v0.5.0/user/installation.md b/site/content/en/v0.5.0/user/installation.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/installation.md rename to site/content/en/v0.5.0/user/installation.md diff --git a/site/content/en/docs/v0.5.0/user/proxy-observability.md b/site/content/en/v0.5.0/user/proxy-observability.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/proxy-observability.md rename to site/content/en/v0.5.0/user/proxy-observability.md diff --git a/site/content/en/docs/v0.5.0/user/quickstart.md b/site/content/en/v0.5.0/user/quickstart.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/quickstart.md rename to site/content/en/v0.5.0/user/quickstart.md diff --git a/site/content/en/docs/v0.5.0/user/rate-limit.md b/site/content/en/v0.5.0/user/rate-limit.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/rate-limit.md rename to site/content/en/v0.5.0/user/rate-limit.md diff --git a/site/content/en/docs/v0.5.0/user/secure-gateways.md b/site/content/en/v0.5.0/user/secure-gateways.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/secure-gateways.md rename to site/content/en/v0.5.0/user/secure-gateways.md diff --git a/site/content/en/docs/v0.5.0/user/tcp-routing.md b/site/content/en/v0.5.0/user/tcp-routing.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/tcp-routing.md rename to site/content/en/v0.5.0/user/tcp-routing.md diff --git a/site/content/en/docs/v0.5.0/user/tls-cert-manager.md b/site/content/en/v0.5.0/user/tls-cert-manager.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/tls-cert-manager.md rename to site/content/en/v0.5.0/user/tls-cert-manager.md diff --git a/site/content/en/docs/v0.5.0/user/tls-passthrough.md b/site/content/en/v0.5.0/user/tls-passthrough.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/tls-passthrough.md rename to site/content/en/v0.5.0/user/tls-passthrough.md diff --git a/site/content/en/docs/v0.5.0/user/tls-termination.md b/site/content/en/v0.5.0/user/tls-termination.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/tls-termination.md rename to site/content/en/v0.5.0/user/tls-termination.md diff --git a/site/content/en/docs/v0.5.0/user/udp-routing.md b/site/content/en/v0.5.0/user/udp-routing.md similarity index 100% rename from site/content/en/docs/v0.5.0/user/udp-routing.md rename to site/content/en/v0.5.0/user/udp-routing.md diff --git a/site/hugo.toml b/site/hugo.toml index d4adfb072610..6349a7b1115f 100644 --- a/site/hugo.toml +++ b/site/hugo.toml @@ -31,7 +31,6 @@ taxonomyCloudTitle = ["Tag Cloud", "Categories"] # set taxonomyPageHeader = [] to hide taxonomies on the page headers taxonomyPageHeader = ["tags", "categories"] - # Highlighting config pygmentsCodeFences = true pygmentsUseClasses = false @@ -145,9 +144,11 @@ navbar_logo = true # Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage. navbar_translucent_over_cover_disable = false # Enable to show the side bar menu in its compact state. -sidebar_menu_compact = false +sidebar_menu_compact = true # Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled) sidebar_search_disable = false +# Show expand/collapse icon for sidebar sections +sidebar_menu_foldable = true # Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events. # This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set. @@ -207,24 +208,41 @@ enable = true # Add your release versions here [[params.versions]] version = "latest" - url = "/docs/latest" + url = "/latest" # Add your release versions here [[params.versions]] version = "v0.5.0" - url = "/docs/v0.5.0" + url = "/v0.5.0" # Add your release versions here [[params.versions]] version = "v0.4.0" - url = "/docs/v0.4.0" + url = "/v0.4.0" # Add your release versions here [[params.versions]] version = "v0.3.0" - url = "/docs/v0.3.0" + url = "/v0.3.0" # Add your release versions here [[params.versions]] version = "v0.2.0" - url = "/docs/v0.2.0" + url = "/v0.2.0" + +[menu] + [[menu.main]] + name = "Documentation" + weight = -101 + pre = "" + url = "/latest" + [[menu.main]] + name = "Blog" + weight = -100 + pre = "" + url = "/blog" + [[menu.main]] + name = "GitHub" + weight = -99 + pre = "" + url = "https://github.com/envoyproxy/gateway"