Manages Envoy Proxy as a Standalone or Kubernetes-based Application Gateway
diff --git a/site/content/en/latest/contributions/RELEASING.md b/site/content/en/latest/contributions/RELEASING.md index 8f0bdf68a488..373026b39cb1 100644 --- a/site/content/en/latest/contributions/RELEASING.md +++ b/site/content/en/latest/contributions/RELEASING.md @@ -134,6 +134,27 @@ export GITHUB_REMOTE=origin make docs-release TAG=v${MAJOR_VERSION}.${MINOR_VERSION}.0 ``` + 5. Upate the `Get Started` and `Contributing` button refered link in `site/content/en/_index.md`: + + ```shell + + Get Started + + + Contributing + + ``` + + 6. Uodate the `Documentation` refered link on the menu in `site/hugo.toml`: + + ```shell + [[menu.main]] + name = "Documentation" + weight = -101 + pre = "" + url = "/v0.5.0" + ``` + 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. diff --git a/site/content/en/v0.5.0/contributions/DOCS.md b/site/content/en/v0.5.0/contributions/DOCS.md index 8266c9e9a2bf..ae19953a8b5c 100644 --- a/site/content/en/v0.5.0/contributions/DOCS.md +++ b/site/content/en/v0.5.0/contributions/DOCS.md @@ -4,26 +4,26 @@ description: "This section tells the development of Envoy Gateway Documents." --- -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. +{{% alert title="Note" color="warning" %}} +We migrated from ***Sphinx*** to ***Hugo*** for Envoy Gateway Documents. + +Read blog: [Welcome to new website!](/blog/2023/10/08/welcome-to-new-website/) +{{% /alert %}} + +The documentation for the Envoy Gateway lives in the `site/content/en` directory. Any +individual document can be written using [Markdown]. ## 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`. +the version of docs. The root of the latest site is in `site/content/en/latest`. 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, +Note that the new contents should be added to `site/content/en/latest` and will be cut off at +the next release. The contents under `site/content/en/v0.5.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. +some incorrect contents. If so, you should send a PR to update contents both of `site/content/en/latest` +and `site/content/en/v0.5.0`. 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 @@ -31,37 +31,39 @@ and you can access the website which contains the latest version changes in ## Documentation Workflow -To work with the docs, just edit reStructuredText or Markdown files in `docs`, +To work with the docs, just edit Markdown files in `site/content/en/latest`, 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. +This will create `site/public` with the built HTML pages. You can preview it +by running: ``` shell make docs-serve ``` -If you want to generate a new release version of the docs, like `v0.3.0`, then run +If you want to generate a new release version of the docs, like `v0.6.0`, then run ```bash -make docs-release TAG=v0.3.0 +make docs-release TAG=v0.6.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. +new dir `site/content/en/v0.6.0`, which contains docs at v0.6.0 and updates artifact links to `v0.6.0` +in all files under `site/content/en/v0.6.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 +## Reference + +Go to [Hugo](https://gohugo.io) and [Docsy](https://www.docsy.dev/docs) to learn more. + [Markdown]: https://daringfireball.net/projects/markdown/syntax -[latest-website]: https://gateway.envoyproxy.io/latest +[latest-website]: /latest diff --git a/site/content/en/v0.5.0/contributions/RELEASING.md b/site/content/en/v0.5.0/contributions/RELEASING.md index 013707d45694..373026b39cb1 100644 --- a/site/content/en/v0.5.0/contributions/RELEASING.md +++ b/site/content/en/v0.5.0/contributions/RELEASING.md @@ -131,7 +131,28 @@ export GITHUB_REMOTE=origin 4. Generate the versioned release docs: ``` shell - make docs-release TAG=v${MAJOR_VERSION}.${MINOR_VERSION} + make docs-release TAG=v${MAJOR_VERSION}.${MINOR_VERSION}.0 + ``` + + 5. Upate the `Get Started` and `Contributing` button refered link in `site/content/en/_index.md`: + + ```shell + + Get Started + + + Contributing + + ``` + + 6. Uodate the `Documentation` refered link on the menu in `site/hugo.toml`: + + ```shell + [[menu.main]] + name = "Documentation" + weight = -101 + pre = "" + url = "/v0.5.0" ``` 3. Sign, commit, and push your changes to your fork. diff --git a/site/content/en/v0.5.0/install/install-egctl.md b/site/content/en/v0.5.0/install/install-egctl.md new file mode 100644 index 000000000000..8534acb71271 --- /dev/null +++ b/site/content/en/v0.5.0/install/install-egctl.md @@ -0,0 +1,57 @@ +--- +title: "Install egctl" +weight: -80 +--- + +{{% alert title="What is egctl?" color="primary" %}} + +`egctl` is a command line tool to provide additional functionality for Envoy Gateway users. + +{{% /alert %}} + + +This guide shows how to install the egctl CLI. egctl can be installed either from source, or from pre-built binary releases. + +### From The Envoy Gateway Project + +The Envoy Gateway project provides two ways to fetch and install egctl. These are the official methods to get egctl releases. Installation through those methods can be found below the official methods. + +### From the Binary Releases + +Every [release](https://github.com/envoyproxy/gateway/releases) of egctl provides binary releases for a variety of OSes. These binary versions can be manually downloaded and installed. + +1. Download your [desired version](https://github.com/envoyproxy/gateway/releases) +2. Unpack it (tar -zxvf egctl_latest_linux_amd64.tar.gz) +3. Find the egctl binary in the unpacked directory, and move it to its desired destination (mv bin/linux/amd64/egctl /usr/local/bin/egctl) + +From there, you should be able to run: `egctl help`. + +### From Script + +`egctl` now has an installer script that will automatically grab the latest release version of egctl and install it locally. + +You can fetch that script, and then execute it locally. It's well documented so that you can read through it and understand what it is doing before you run it. + +```shell +curl -fsSL -o get-egctl.sh https://gateway.envoyproxy.io/get-egctl.sh + +chmod +x get-egctl.sh + +# get help info of the +bash get-egctl.sh --help + +# install the latest development version of egctl +bash VERSION=latest get-egctl.sh +``` + +Yes, you can just use the below command if you want to live on the edge. + +```shell +curl https://gateway.envoyproxy.io/get-egctl.sh | VERSION=latest bash +``` + +{{% alert title="Next Steps" color="warning" %}} + +You can refer to [User Guides](../../user/egctl) to more details about egctl. + +{{% /alert %}} diff --git a/site/content/en/v0.5.0/install/install-helm.md b/site/content/en/v0.5.0/install/install-helm.md new file mode 100644 index 000000000000..9e90a1057ade --- /dev/null +++ b/site/content/en/v0.5.0/install/install-helm.md @@ -0,0 +1,46 @@ ++++ +title = "Install with Helm" +weight = -100 ++++ + +[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes. + +Envoy Gateway can be installed via a Helm chart with a few simple steps, depending on if you are deploying for the first time, upgrading Envoy Gateway from an existing installation, or migrating from Envoy Gateway. + +## Before you begin + +{{% alert title="Compatibility Matrix" color="warning" %}} +Refer to the [Version Compatibility Matrix](/blog/2022/10/01/versions/) to learn more. +{{% /alert %}} + +The Envoy Gateway Helm chart is hosted by DockerHub. + +It is published at `oci://docker.io/envoyproxy/gateway-helm`. + +{{% alert title="Note" color="primary" %}} +We use `v0.0.0-latest` as the latest development version. + +You can visit [Envoy Gateway Helm Chart](https://hub.docker.com/r/envoyproxy/gateway-helm/tags) for more releases. +{{% /alert %}} + +## Install with Helm + +Envoy Gateway is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use `kind` to create one. + +{{% alert title="Developer Guide" color="primary" %}} +Refer to the [Developer Guide](../../contributions/develop) to learn more. +{{% /alert %}} + +When you run the Helm chart, it installs Envoy Gateway. + +1. Install the Gateway API CRDs and Envoy Gateway with the following command: + + ``` shell + helm install eg oci://docker.io/envoyproxy/gateway-helm --version v0.0.0-latest -n envoy-gateway-system --create-namespace + ``` + +2. Next Steps + + Envoy Gateway should now be successfully installed and running, but in order to experience more abilities of Envoy Gateway, you can refer to [User Guides](../../user). + +For more advanced configuration and details about helm values, please see the [Helm Chart Values](../api). diff --git a/site/content/en/v0.5.0/install/install-yaml.md b/site/content/en/v0.5.0/install/install-yaml.md new file mode 100644 index 000000000000..28f6bec4a76d --- /dev/null +++ b/site/content/en/v0.5.0/install/install-yaml.md @@ -0,0 +1,39 @@ ++++ +title = "Install with Kubernetes YAML" +weight = -99 ++++ + +In this guide, we'll walk you through installing Envoy Gateway in your Kubernetes cluster. + +The manual install process does not allow for as much control over configuration +as the [Helm install method](../install-helm), so if you need more control over your Envoy Gateway +installation, it is recommended that you use helm. + +## Before you begin + +Envoy Gateway is designed to run in Kubernetes for production. The most essential requirements are: + +* Kubernetes 1.25 or later +* The `kubectl` command-line tool + +{{% alert title="Compatibility Matrix" color="warning" %}} +Refer to the [Version Compatibility Matrix](/blog/2022/10/01/versions/) to learn more. +{{% /alert %}} + +## Install with YAML + +Envoy Gateway is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use `kind` to create one. + +{{% alert title="Developer Guide" color="primary" %}} +Refer to the [Developer Guide](../../contributions/develop) to learn more. +{{% /alert %}} + +1. In your terminal, run the following command: + + ```shell + kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/latest/install.yaml + ``` + +2. Next Steps + + Envoy Gateway should now be successfully installed and running, but in order to experience more abilities of Envoy Gateway, you can refer to [User Guides](../../user). diff --git a/site/hugo.toml b/site/hugo.toml index f978fdbb1229..bf2c6a90e935 100644 --- a/site/hugo.toml +++ b/site/hugo.toml @@ -166,6 +166,21 @@ no = 'Sorry to hear that. Please ../../docsy" + [module.hugoVersion] + extended = true + min = "0.110.0" + [[module.imports]] + path = "github.com/google/docsy" + disable = false + [[module.imports]] + path = "github.com/google/docsy/dependencies" + disable = false + [params.links] # End user relevant links. These will show up on left side of footer and in the community page if you have one. [[params.links.user]] @@ -190,27 +205,7 @@ enable = true icon = "fab fa-slack" desc = "Chat with other project developers" -# hugo module configuration - -[module] - # uncomment line below for temporary local development of module - # replacements = "github.com/envoyproxy/gateway -> ../../docsy" - [module.hugoVersion] - extended = true - min = "0.110.0" - [[module.imports]] - path = "github.com/google/docsy" - disable = false - [[module.imports]] - path = "github.com/google/docsy/dependencies" - disable = false - [menu] - [[menu.main]] - name = "Documentation" - weight = -101 - pre = "" - url = "/latest" [[menu.main]] name = "Blog" weight = -100 @@ -226,6 +221,11 @@ enable = true weight = -99 pre = "" url = "https://github.com/envoyproxy/gateway" + [[menu.main]] + name = "Documentation" + weight = -101 + pre = "" + url = "/v0.5.0" [[params.versions]] version = "latest"