[v1.13.x] Backport docs (#9499) (#9568)

* [v1.13.x] Backport docs (#9499)

* hugo theme bump

* istioIntegration.disableAutoinjection

* Doc fixes for week of 2024-05-06 (#9475)

* Add food bowl image

* Add files via upload

* Delete docs/content/img/portal/petstore-food-bowl.png

* Transformation fixes

* Revise how we describe OSS vs. EE

See question in Slack: https://solo-io-corp.slack.com/archives/CEDCS8TAP/p1715012663208689

* update support number, see slack: https://solo-io-corp.slack.com/archives/CHJV572TG/p1715092657711459

* changelog

* changelog

* version bump

* Update docs/content/introduction/faq.md

Co-authored-by: Rachael Graham <rachael.graham@solo.io>

---------

Co-authored-by: Nadine Spies <17709352+Nadine2016@users.noreply.github.com>
Co-authored-by: soloio-bulldozer[bot] <48420018+soloio-bulldozer[bot]@users.noreply.github.com>
Co-authored-by: Rachael Graham <rachael.graham@solo.io>

* Doc fixes (#9497)

* Update automatic_discovery.md

* changelog

* version bump

* changelog

* changelog

* Adding changelog file to new location

* Deleting changelog file from old location

* Doc fixes (#9521)

* doc fixes for the week

* clarification for kube services

* remove note

* version bumps

* Rename doc-fixes.yaml to doc-fixes.yaml

* update vault secrets

* kube services clarifications

* Update docs/content/installation/advanced_configuration/vault_secrets.md

Co-authored-by: Jacob Bohanon <jacob.bohanon@solo.io>

* Update docs/content/guides/traffic_management/destination_types/kubernetes_services/_index.md

Co-authored-by: Jacob Bohanon <jacob.bohanon@solo.io>

* Update docs/content/installation/advanced_configuration/vault_secrets.md

Co-authored-by: Jacob Bohanon <jacob.bohanon@solo.io>

* Update vault_secrets.md

---------

Co-authored-by: Nadine Spies <nadine.spies@solo.io>
Co-authored-by: soloio-bulldozer[bot] <48420018+soloio-bulldozer[bot]@users.noreply.github.com>
Co-authored-by: Jacob Bohanon <jacob.bohanon@solo.io>

* changelog

---------

Co-authored-by: Nadine Spies <17709352+Nadine2016@users.noreply.github.com>
Co-authored-by: soloio-bulldozer[bot] <48420018+soloio-bulldozer[bot]@users.noreply.github.com>
Co-authored-by: Rachael Graham <rachael.graham@solo.io>
Co-authored-by: changelog-bot <changelog-bot>
Co-authored-by: Nadine Spies <nadine.spies@solo.io>
Co-authored-by: Jacob Bohanon <jacob.bohanon@solo.io>

* rev istio

---------

Co-authored-by: Nadine Spies <17709352+Nadine2016@users.noreply.github.com>
Co-authored-by: soloio-bulldozer[bot] <48420018+soloio-bulldozer[bot]@users.noreply.github.com>
Co-authored-by: Rachael Graham <rachael.graham@solo.io>
Co-authored-by: Nadine Spies <nadine.spies@solo.io>
Co-authored-by: Jacob Bohanon <jacob.bohanon@solo.io>

changelog/v1.13.38/docs-backport.yaml

@@ -0,0 +1,5 @@
+changelog:
+- type: NON_USER_FACING  
+  description: >- 
+    Backports weekly docs, including fixes such as customer requests, links, typos, etc.
+    skipCI-kube-tests:true

docs/Makefile

@@ -14,7 +14,7 @@ VERSION ?= $(shell echo $(TAGGED_VERSION) | cut -c 2-)
 
 HUGO_VERSION := 0.69.2
 
-SOLO_HUGO_THEME_REVISION := v0.0.24
+SOLO_HUGO_THEME_REVISION := v0.0.29
 
 # The minimum version to maintain in our public docs
 SECURITY_SCAN_MIN_VERSION ?= v1.9.0

docs/content/_index.md

@@ -5,7 +5,6 @@ title: Gloo Edge
 
 # An Envoy-Powered API Gateway
 
-{{% notice note %}}[Gloo Gateway](https://docs.solo.io/gloo-gateway) is the latest open source-based, API gateway product by Solo.io. As part of Gloo Platform, you get observability, multitenancy, and multicluster support from Day 1, alongside seamless integration with Gloo Mesh and Gloo Network. Still want the Envoy-based Gloo Edge API gateway? Continue reading these docs!{{% /notice %}}
 
 ## What is Gloo Edge
 

docs/content/guides/graphql/automatic_discovery.md

@@ -8,6 +8,10 @@ description: Explore automatic schema generation with GraphQL service discovery.
 
 Gloo Edge can automatically discover API specifications and create GraphQL schemas. The generated `GraphQLApi` includes the configuration for REST or gRPC resolvers and schema definitions for the types of data to return to GraphQL queries.
 
+{{% notice warning %}}
+Automatic schema generation is recommended for use in development environments to quickly create initial GraphQLApi custom resources from existing APIs. Once these custom resources are generated, you must manage them in the same way as other Gloo custom resources, especially when deploying them into downstream environments. It is not recommended to use autogeneration in production.
+{{% /notice %}}
+
 Gloo Edge supports two modes of discovery: allowlist and blocklist. For more information about these discovery modes, see the [Function Discovery Service (FDS) guide]({{% versioned_link_path fromRoot="/installation/advanced_configuration/fds_mode/#function-discovery-service-fds" %}}).
 
 {{% notice note %}}

docs/content/guides/integrations/service_mesh/istio.md

@@ -35,7 +35,7 @@ Install the Gloo Edge gateway and inject it with an Istio sidecar.
    helm repo update
    ```
       
-3. Create a `value-overrides.yaml` file with the following content. To configure your gateway with an Istio sidecar, make sure to add the `istioIntegration` section and set the `enableIstioSidecarOnGateway` option to `true`. 
+3. Create a `value-overrides.yaml` file with the following content. To configure your gateway with an Istio sidecar, make sure to add the `istioIntegration` section and set the `enableIstioSidecarOnGateway` option to `true`.
    ```yaml
    global:
      istioIntegration:
@@ -49,7 +49,7 @@ Install the Gloo Edge gateway and inject it with an Istio sidecar.
          httpsPort: 8443
    ```
 
-4. Install or upgrade Gloo Edge. 
+1. Install or upgrade Gloo Edge. 
    {{< tabs >}} 
    {{< tab name="Install Gloo Edge">}}
 

docs/content/guides/traffic_management/destination_types/kubernetes_services/_index.md

@@ -8,18 +8,18 @@ To allow for optimal performance in Gloo Edge, it is recommended to use Gloo [st
 
 ## Option 1: Route to a Kubernetes service directly
 
-You can configure your VirtualService to route to a Kubernetes service instead of a Gloo Upstream. 
+You can configure your VirtualService to route to a Kubernetes service (`routeAction.single.kube`) directly instead of using Upstream resources.
 
 {{% notice note %}}
 Consider the following information before choosing a Kubernetes service as your routing destination: 
-- For Gloo Edge to route traffic to a Kubernetes service directly, Gloo Edge requires scanning of all services in the cluster to create in-memory Upstream resources to represent them. Gloo uses these resources to validate that the upstream destination is valid and returns an error if the specified Kubernetes service cannot be found. Note that the in-memory Upstream resources are included in the API snapshot. If you have a large number of services in your cluster, the API snapshot increases which can have a negative impact on the Gloo Edge translation time.
-- When using Kubernetes services as a routing destination, Gloo Edge relies on `kube-proxy` to perform load balancing which can have further performance impacts. Routing to Gloo Upstreams bypasses `kube-proxy` as the request is routed to the pod directly. 
-- Some Gloo Edge functionality, such as policies, might not be available when using Kubernetes services as a routing destination. 
+- For Gloo Edge to route traffic to a Kubernetes service directly, Gloo Edge requires scanning of all services in the cluster to create in-memory Upstream resources to represent them. Creating in-memory Upstream resources is automatically done for you if you set `disableKubernetesDestinations: false` in your Settings resource. 
+- Gloo Edge uses these resources to validate that the destination is valid and returns an error if the specified Kubernetes service cannot be found. Note that the in-memory Upstream resources are included in the API snapshot. If you have a large number of services in your cluster, the API snapshot increases as each Kubernetes destination is added as an Envoy cluster to each proxy in the cluster. Because of that, the API snapshot and proxy size increase, which can have a negative impact on the Gloo Edge translation and reconciliation time. In production deployments, it is therefore recommended to remove in-memory Upstream resources by setting `disableKubernetesDestinations: true`. For more information, see [Disable Kubernetes destinations]({{< versioned_link_path fromRoot="/operations/production_deployment/#disable-kubernetes-destinations" >}}). 
+- Some Gloo Edge functionality, such as outlier detection policies or customizing load balancing modes, might not be available when using Kubernetes services as a routing destination. 
 {{% /notice %}}
 
 To use Kubernetes services as a routing destination: 
 
-1. Get the default Gloo Edge settings and verify that `spec.gloo.disableKubernetesDestinations` is set to `false`. This setting is required to allow Gloo Edge to scan all Kubernetes services in the cluster and to create in-memory Upstream resources to represent them. If it is set to `true`, follow the [upgrade guide]({{% versioned_link_path fromRoot="/operations/upgrading/" %}}) and set `settings.disableKubernetesDestinations: false` in your Helm chart. 
+1. Get the default Gloo Edge settings and verify that `spec.gloo.disableKubernetesDestinations` is set to `false`. This setting is required to allow Gloo Edge to scan all Kubernetes services in the cluster and to create in-memory Upstream resources to represent them. If it is set to `true`, you cannot route to a Kubernetes service directly as the in-memory Upstream resources do not exist in your cluster. Follow the [upgrade guide]({{% versioned_link_path fromRoot="/operations/upgrading/" %}}) and set `settings.disableKubernetesDestinations: false` in your Helm chart to let Gloo Edge create the resources for you. 
    ```sh
    kubectl get settings default -n gloo-system -o yaml
    ```
@@ -46,11 +46,11 @@ routes:
 
 ## Option 2: Use Kubernetes Upstream resources
 
-Instead of routing to a Kubernetes service directly, you can create [Gloo Kubernetes Upstream]({{% versioned_link_path fromRoot="/reference/api/github.com/solo-io/gloo/projects/gloo/api/v1/options/kubernetes/kubernetes.proto.sk/" %}}) resources that represent your Kubernetes workload. With Kubernetes Upstream resources, you can route requests to a specific pod in the cluster. This process bypasses `kube-proxy` which improves load balancing times for your workloads. 
+Instead of routing to a Kubernetes service directly, you can create [Gloo Kubernetes Upstream]({{% versioned_link_path fromRoot="/reference/api/github.com/solo-io/gloo/projects/gloo/api/v1/options/kubernetes/kubernetes.proto.sk/" %}}) resources that represent your Kubernetes workload. With Kubernetes Upstream resources, you can route requests to a specific pod in the cluster. 
 
 To use Kubernetes Upstream resources: 
 
-1. Create a Kubernetes Upstream resource for your workload. The following configuration creates an upstream resource for the Petstore app that listens on port 8080 in the default namespace. 
+1. Create an Upstream resource for your Kubernetes workload. The following configuration creates an Upstream resource for the Petstore app that listens on port 8080 in the default namespace. 
    ```yaml
    apiVersion: gloo.solo.io/v1
    kind: Upstream
@@ -64,7 +64,7 @@ To use Kubernetes Upstream resources:
        servicePort: 8080
    ```
 
-2. Configure the Kubernetes Upstream as a routing destination in your VirtualService. The following example configuration forwards all requests to `/petstore` to the Petstore upstream in the `gloo-system` namespace.
+2. Configure the Upstream as a routing destination in your VirtualService. The following example configuration forwards all requests to `/petstore` to the Petstore upstream in the `gloo-system` namespace.
 
    {{< highlight yaml "hl_lines=6-8" >}}
 routes:

docs/content/guides/traffic_management/destination_types/static_upstream/_index.md

@@ -6,6 +6,24 @@ description: Routing to explicitly and statically defined Upstreams
 
 Let's configure Gloo Edge to route to a single, static Upstream. In this case, we'll route requests through Gloo Edge to the JSON testing API available at `http://jsonplaceholder.typicode.com/`. 
 
+{{% notice note %}}
+When you create a static upstream resource that points to a Kubernetes service address, such as in the following example, Gloo Edge relies on `kube-proxy` to perform load balancing which might impact performance. To avoid performance impacts, you can use [dynamic Upstreams]({{% versioned_link_path fromRoot="/guides/traffic_management/destination_types/discovered_upstream/" %}}) or manually create upstream resources that use label selectors to find the backing destination. 
+
+```yaml
+apiVersion: gloo.solo.io/v1
+kind: Upstream
+metadata:
+  name: httpbin-httpbin-static-8000
+  namespace: gloo-deployments
+spec:
+  static:
+    hosts:
+      - addr: httpbin.httpbin.svc.cluster.local
+        port: 8000
+```
+{{% /notice %}}
+
+
 {{< readfile file="/static/content/setup_notes" markdown="true">}}
 
 ## Create Upstream

docs/content/installation/_index.md

@@ -3,9 +3,15 @@ title: Setup
 weight: 20
 ---
 
-# Gloo Edge Open-Source
+Review the following setup paths for the open source and enterprise editions of Gloo Edge.
 
-Gloo Edge Open-Source runs in 3 different modes to enable different use cases:
+# Open Source
+
+Gloo Edge Open Source Software (OSS) runs in `gateway` or `ingress` modes to enable different use cases.
+
+{{% notice note %}}
+Note: The installation modes are not mutually exclusive. To run both `gateway` in and `ingress` modes of Gloo Edge OSS, install separate instances of Gloo Edge in the same or different namespaces.
+{{% /notice %}}
 
 <div markdown=1>
 <table>
@@ -14,7 +20,7 @@ Gloo Edge Open-Source runs in 3 different modes to enable different use cases:
       <a href="{{% versioned_link_path fromRoot="/installation/gateway/" %}}"><img src='{{% versioned_link_path fromRoot="/img/Gloo-01.png" %}}' width="60"/></a>
     </td>
     <td>
-     Run Gloo Edge in <code>gateway</code> mode to function as an API Gateway. This is the most fully-featured and customizable installation of Gloo Edge, and is our <a href="{{% versioned_link_path fromRoot="/installation/gateway/" %}}"><b>recommended install for first-time users</b></a>. Gloo Edge can be configured via Kubernetes Custom Resources, Consul Key-Value storage, or <code>.yaml</code> files on Gloo Edge's local filesystem.
+     Run Gloo Edge in <code>gateway</code> mode to function as an API Gateway. This is the most fully-featured and customizable installation of Gloo Edge, and is the <a href="{{% versioned_link_path fromRoot="/installation/gateway/" %}}"><b>recommended install for first-time users</b></a>. Gloo Edge can be configured via Kubernetes Custom Resources, Consul Key-Value storage, or <code>.yaml</code> files on Gloo Edge's local filesystem.
     </td>
   </tr>
   <tr height="100">
@@ -35,13 +41,13 @@ Gloo Edge Open-Source runs in 3 different modes to enable different use cases:
 </table>
 </div>
 
-{{% notice note %}}
-Note: The installation modes are not mutually exclusive, e.g. if you wish to run `gateway` in conjunction with `ingress`, it can be done by installing both options to the same (or different) namespaces.
-{{% /notice %}}
+## Enterprise
 
-# Gloo Edge Enterprise
+Gloo Edge Enterprise Edition (EE) has a single installation workflow.
 
-Gloo Edge Enterprise has a single installation workflow:
+{{% notice note %}}
+{{< readfile file="static/content/license-key" markdown="true">}}
+{{% /notice %}}
 
 <div markdown=1>
 <table>
@@ -50,7 +56,7 @@ Gloo Edge Enterprise has a single installation workflow:
       <a href="{{% versioned_link_path fromRoot="/installation/enterprise/" %}}"><img src='{{% versioned_link_path fromRoot="/img/gloo-ee.png" %}}' width="60"/></a>
     </td>
     <td>
-    Gloo Edge Enterprise is based on open-source Gloo Edge with additional (closed source) UI and plugins. See <a href="{{% versioned_link_path fromRoot="/installation/enterprise/" %}}">the Gloo Edge Enterprise documentation</a> for more details on the additional features of the Enterprise version of Gloo Edge.
+    Gloo Edge Enterprise is based on open-source Gloo Edge with additional, closed source features. For a comparison between open source and enterprise editions, see the <a href="{{% versioned_link_path fromRoot="/introduction/faq/#oss-enterprise" %}}">FAQs</a>. For installation instructions, see the <a href="{{% versioned_link_path fromRoot="/installation/enterprise/" %}}">Enterprise setup guide</a>.
     </td>
   </tr>
 </table>

docs/content/installation/enterprise/_index.md

@@ -9,13 +9,13 @@ Review how to install Gloo Edge Enterprise.
 ## Before you begin
 
 1. Make sure that you prepared your Kubernetes cluster according to the [instructions for platform configuration]({{% versioned_link_path fromRoot="/installation/platform_configuration/cluster_setup/" %}}).
+
    {{% notice note %}}
    Pay attention to provider-specific information in the setup guide. For example, [OpenShift]({{< versioned_link_path fromRoot="/installation/platform_configuration/cluster_setup/#openshift" >}}) requires stricter multi-tenant support, so the setup guide includes an example Helm chart `values.yaml` file that you must supply while installing Gloo Edge Enterprise.
    {{% /notice %}}
-2. Get your Gloo Edge Enterprise license key. If you don't have one already, you may request a trial license key [here](https://www.solo.io/products/gloo/#enterprise-trial).
-   {{% notice info %}}
-   You must provide the license key during the installation process. When you install Gloo Edge, a Kubernetes secret is created to store the license key. Note that each trial license key is typically valid for **30 days**. When the license key expires, you can request a new license key by contacting your Account Representative or filling out [this form](https://lp.solo.io/request-trial). For more information, see [Updating Enterprise Licenses]({{< versioned_link_path fromRoot="/operations/updating_license/" >}}).
-   {{% /notice %}}
+
+2. Get your Gloo Edge Enterprise license key. {{< readfile file="static/content/license-key" markdown="true">}}
+
 3. Check whether `glooctl`, the Gloo Edge command line tool (CLI), is installed.
    ```bash
    glooctl version

docs/content/installation/gateway/kubernetes/_index.md

@@ -5,11 +5,7 @@ description: How to install Gloo Edge to run in Gateway Mode on Kubernetes (Defa
 weight: 10
 ---
 
-Gloo Edge can be installed on a Kubernetes cluster by using either the [`glooctl` command line tool](#installing-on-kubernetes-with-glooctl) or a [Helm chart](#installing-on-kubernetes-with-helm). The following document will take you through the process of either installation, [verifying the installation](#verify-your-installation), and [how to remove Gloo Edge](#uninstall) if necessary.
-
-{{% notice note %}}
-Minimum required Kubernetes is 1.11.x. For older versions see our [release support guide]({{% versioned_link_path fromRoot="/reference/support/#kubernetes" %}})
-{{% /notice %}}
+Gloo Edge can be installed on a Kubernetes cluster by using either the [`glooctl` command line tool](#installing-on-kubernetes-with-glooctl) or a [Helm chart](#installing-on-kubernetes-with-helm). Follow this guide to install, [verify the installation](#verify-your-installation), or [uninstall](#uninstall) Gloo Edge.
 
 ---
 
@@ -19,10 +15,9 @@ Minimum required Kubernetes is 1.11.x. For older versions see our [release suppo
    {{% notice note %}}
    Pay attention to provider-specific information in the setup guide. For example, [OpenShift]({{< versioned_link_path fromRoot="/installation/platform_configuration/cluster_setup/#openshift" >}}) requires stricter multi-tenant support, so the setup guide includes an example Helm chart `values.yaml` file that you must supply while installing Gloo Edge Enterprise.
    {{% /notice %}}
-2. Get your Gloo Edge Enterprise license key. If you don't have one already, you may request a trial license key [here](https://www.solo.io/products/gloo/#enterprise-trial).
-   {{% notice info %}}
-   You must provide the license key during the installation process. When you install Gloo Edge, a Kubernetes secret is created to store the license key. Note that each trial license key is typically valid for **30 days**. When the license key expires, you can request a new license key by contacting your Account Representative or filling out [this form](https://lp.solo.io/request-trial). For more information, see [Updating Enterprise Licenses]({{< versioned_link_path fromRoot="/operations/updating_license/" >}}).
-   {{% /notice %}}
+
+2. **Enterprise Edition only**: Get your Gloo Edge Enterprise license key. {{< readfile file="static/content/license-key" markdown="true">}}
+
 3. Check whether `glooctl`, the Gloo Edge command line tool (CLI), is installed.
    ```bash
    glooctl version

docs/content/installation/platform_configuration/cluster_setup.md

@@ -6,28 +6,26 @@ description: How to prepare a Kubernetes cluster for Gloo Edge installation.
 
 Installing Gloo Edge will require an environment for installation. Kubernetes and OpenShift are common targets for the installation of Gloo Edge. In this document we will review how to prepare different Kubernetes and OpenShift environments for the installation of Gloo Edge. 
 
-Click on the links below for details specific to your Kubernetes distribution:
-
-- [Minikube](#minikube)
-- [Minishift](#minishift)
-- [Kind (Kubernetes in Docker)](#kind)
-- [OpenShift](#openshift)
-- [Google Kubernetes Engine (GKE)](#google-kubernetes-engine-gke)
-  - [Private clusters](#private-clusters)
-- [Azure Kubernetes Service (AKS)](#azure-kubernetes-service-aks)
-- [Amazon Elastic Container Service for Kubernetes (EKS)](#amazon-elastic-container-service-for-kubernetes-eks)
-- [Additional Notes](#additional-notes)
-  - [DNS Records](#dns-records)
-  - [Certificate Management](#certificate-management)
-- [Next Steps](#next-steps)
+---
 
-{{% notice note %}}
-Minimum required Kubernetes is 1.11.x. For older versions see our [release support guide]({{% versioned_link_path fromRoot="/reference/support/#kubernetes" %}})
-{{% /notice %}}
+## Before you begin
 
-{{% notice note %}}
-This document assumes you have `kubectl` installed. Details on how to install [here](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
-{{% /notice %}}
+1. Plan to install a [supported version of Kubernetes]({{% versioned_link_path fromRoot="/reference/support/#kubernetes" %}}).
+
+2. [Install `kubectl`, the Kubernetes CLI tool](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
+
+3. Follow the instructions for your Kubernetes distribution:
+   - [Minikube](#minikube)
+   - [Minishift](#minishift)
+   - [Kind (Kubernetes in Docker)](#kind)
+   - [OpenShift](#openshift)
+   - [Google Kubernetes Engine (GKE)](#google-kubernetes-engine-gke)
+   - [Azure Kubernetes Service (AKS)](#azure-kubernetes-service-aks)
+   - [Amazon Elastic Container Service for Kubernetes (EKS)]   (#amazon-elastic-container-service-for-kubernetes-eks)
+   - [Additional Notes](#additional-notes)
+     - [DNS Records](#dns-records)
+     - [Certificate Management](#certificate-management)
+   - [Next Steps](#next-steps)
 
 ---