[v1.14.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>
solo-io · Jun 3, 2024 · 64d945f · 64d945f
1 parent ae32b12
commit 64d945f
Show file tree

Hide file tree

Showing 26 changed files with 162 additions and 102 deletions.
diff --git a/changelog/v1.14.31/docs-backports.yaml b/changelog/v1.14.31/docs-backports.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
diff --git a/docs/Makefile b/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.27
+SOLO_HUGO_THEME_REVISION := v0.0.29
 
 # The minimum version to maintain in our public docs
 MIN_SCANNED_VERSION ?= v1.10.0

diff --git a/docs/content/_index.md b/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
 

diff --git a/docs/content/guides/graphql/automatic_discovery.md b/docs/content/guides/graphql/automatic_discovery.md
@@ -8,6 +8,10 @@ Gloo Edge can automatically discover API specifications and create GraphQL schem
 * gRPC and REST OpenAPI upsteams: The generated `GraphQLApi` includes the configuration for resolvers and schema definitions for the types of data to return to GraphQL queries. In this case, Gloo Edge uses _local execution_, which means the Envoy server executes GraphQL queries locally before it proxies them to the upstreams that provide the data requested in the queries.
 * GraphQL server upstreams (1.14.0 and later only): When you have a GraphQL server upstream that includes its own resolvers, the generated `GraphQLApi` includes only the schema definitions for the types of data to return to GraphQL queries. In this case, Gloo Edge uses _remote execution_, which means that Envoy proxies the requests to the GraphQL server without executing the request first, and the GraphQL upstream both executes the query and provides the requested data. Additionally, Envoy validates the schema of the GraphQL server.
 
+{{% 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 %}}

diff --git a/docs/content/guides/integrations/service_mesh/istio.md b/docs/content/guides/integrations/service_mesh/istio.md
@@ -30,16 +30,14 @@ Install the Gloo Edge gateway and inject it with an Istio sidecar.
    ```
 
 3. Create a `value-overrides.yaml` file with the following content:
-- To configure your gateway with an Istio sidecar, add the `istioIntegration` section and set `enableIstioSidecarOnGateway` option to `true`
-- Set `disableAutoInjection` to `true` in order to ensure Gloo components are not included in the Mesh
-- Set `global.istioSDS.enabled` to `true` to allow the Gateway Proxy to consume Istio certs despite not being in the Mesh 
+- Set `istioIntegration.disableAutoinjection` to `true` so that Istio does not automatically inject a sidecar to the gateway proxy pods. This way, Gloo can configure the sidecar.
+- Set `global.istioSDS.enabled` to `true` so that the Istio proxy is added to the gateway deployment. This way, the gateway proxy can use Istio certs despite not being in the mesh. Gloo uses a default sidecar configuration, which you can review in the [`gloo` project on GitHub](https://github.com/solo-io/gloo/blob/main/install/helm/gloo/templates/7-gateway-proxy-deployment.yaml). You can also use the `global.istioSDS.customSidecars[]` setting to provide your own sidecar configuration.
 - Specify image fields under `global.glooMtls.istioProxy.image` and `global.glooMtls.sds.image` corresponding with the version of Istio and Gloo Edge installed respectively
   - The default Istio version is 1.17.1
    ```yaml
    global:
      istioIntegration:
-       enableIstioSidecarOnGateway: true
-       disableAutoInjection: true
+       disableAutoinjection: true
      istioSDS:
        enabled: true
      glooMtls:
@@ -63,7 +61,7 @@ Install the Gloo Edge gateway and inject it with an Istio sidecar.
    Although the `istioProxy` values are defined in the `glooMtls` block, the values are also used to configure `istioMtls`.
    {{% /notice %}}
 
-4. Install or upgrade Gloo Edge. 
+1. Install or upgrade Gloo Edge. 
    {{< tabs >}} 
    {{< tab name="Install Gloo Edge">}}
 
@@ -80,9 +78,9 @@ Install the Gloo Edge gateway and inject it with an Istio sidecar.
    {{< /tab >}}
    {{< /tabs >}}
 
-5. [Verify your setup]({{< versioned_link_path fromRoot="/installation/gateway/kubernetes/#verify-your-installation" >}}). 
+2. [Verify your setup]({{< versioned_link_path fromRoot="/installation/gateway/kubernetes/#verify-your-installation" >}}). 
 
-6. Verify that your `gateway-proxy` pod now has three containers.
+3. Verify that your `gateway-proxy` pod now has three containers.
    ```shell
    kubectl get pods -n gloo-system
    ```
@@ -97,7 +95,7 @@ Install the Gloo Edge gateway and inject it with an Istio sidecar.
    gloo-resource-rollout-hhvf9      0/1     Completed   0          38s
    ```
 
-7. Describe the `gateway-proxy` pod to verify that the `istio-proxy` and `sds` containers are running.
+4. Describe the `gateway-proxy` pod to verify that the `istio-proxy` and `sds` containers are running.
    ```shell
    kubectl describe <gateway-pod-name> -n gloo-system
    ```

diff --git a/...ntent/guides/traffic_management/destination_types/kubernetes_services/_index.md b/...ntent/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:

diff --git a/docs/content/guides/traffic_management/destination_types/static_upstream/_index.md b/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

diff --git a/docs/content/img/portal/petstore-food-bowl-collar.png b/docs/content/img/portal/petstore-food-bowl-collar.png
diff --git a/docs/content/installation/_index.md b/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">
@@ -27,13 +33,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>
@@ -42,7 +48,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>

diff --git a/docs/content/installation/advanced_configuration/vault_secrets.md b/docs/content/installation/advanced_configuration/vault_secrets.md
@@ -24,10 +24,14 @@ Edit the `default` settings resource so Gloo Edge reads and writes secrets using
    ```
 
 2. Make the following changes to the resource.
-   * Remove the existing `kubernetesSecretSource` or `directorySecretSource` field, which direct the gateway to use other secret stores than Vault.
-   * Add the `vaultSecretSource` section to enable secrets to be read from and written to Vault.
-   * Add the `refreshRate` field, which is used for watching Vault secrets and the local filesystem of where Gloo Edge is run for changes.
-   {{< highlight yaml "hl_lines=16-23" >}}
+   * Remove the existing `kubernetesSecretSource`, `vaultSecretSource`, or `directorySecretSource` field, which directs the gateway to use secret stores other than Vault.
+   * Add the `secretOptions` section and define a Vault secret source as shown in this guide. Optionally, a Kubernetes and/or a Directory secret source can also be specified. 
+     {{< notice note >}}
+     If you specify both a Kubernetes and Vault secret source in your Settings resource, the Kubernetes secret is looked up first. Keep in mind that when you specify multiple secret sources, the name and namespace of each secret must be unique to avoid unanticipated behavior. 
+     {{< /notice >}}
+   * Add the `refreshRate` field to configure the polling rate at which we watch for changes in Vault secrets and the local filesystem of where Gloo Edge runs.
+
+   {{< highlight yaml "hl_lines=18-24" >}}
    apiVersion: gloo.solo.io/v1
    kind: Settings
    metadata:
@@ -54,9 +58,9 @@ Edit the `default` settings resource so Gloo Edge reads and writes secrets using
      # refresh rate for polling config backends for changes
      # this is used for watching vault secrets and by other resource clients
      refreshRate: 15s
-     requestTimeout: 0.5s
-   {{< /highlight >}}
 
+   {{< /highlight >}}
+
 For the full list of options for Gloo Edge Settings, including the ability to set auth/TLS parameters for Vault, see the {{< protobuf name="gloo.solo.io.Settings" display="v1.Settings API reference">}}.
 
 An example using AWS IAM auth might look like the following:

diff --git a/docs/content/installation/enterprise/_index.md b/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