Doc fixes

changelog/v1.17.0-beta33/doc-fixes.yaml

@@ -0,0 +1,5 @@
+changelog:
+  - type: NON_USER_FACING
+    description: >- 
+      Weekly doc fixes such as links, grammar, typos, and version updates.
+      skipCI-kube-tests:true

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/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/advanced_configuration/vault_secrets.md

@@ -25,9 +25,16 @@ 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`, `vaultSecretSource`, or `directorySecretSource` field, which directs the gateway to use secret stores other than Vault.
-   * Add the `secretOptions` section with a Kubernetes source and a Vault source specified to enable secrets to be read from both Kubernetes and Vault.
+   * Add the `secretOptions` section and define either a Kubernetes or Vault secret source.  
+     {{< 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=16-27" >}}
+
+   {{< tabs >}}
+   {{% tab name="Vault" %}}
+
+   {{< highlight yaml "hl_lines=18-24" >}}
    apiVersion: gloo.solo.io/v1
    kind: Settings
    metadata:
@@ -57,7 +64,37 @@ Edit the `default` settings resource so Gloo Edge reads and writes secrets using
      refreshRate: 15s
      requestTimeout: 0.5s
    {{< /highlight >}}
-
+   {{% /tab %}}
+   {{% tab name="Kubernetes secret" %}}
+   {{< highlight yaml "hl_lines=18-20" >}}
+   apiVersion: gloo.solo.io/v1
+   kind: Settings
+   metadata:
+     name: default
+     namespace: gloo-system
+   spec:
+     discoveryNamespace: gloo-system
+     gateway:
+       validation:
+         alwaysAccept: true
+         proxyValidationServerAddr: gloo:9988
+     gloo:
+       xdsBindAddr: 0.0.0.0:9977
+     kubernetesArtifactSource: {}
+     kubernetesConfigSource: {}
+     # Delete or comment out the existing *SecretSource field
+     #kubernetesSecretSource: {}
+     secretOptions:
+       sources:
+       - kubernetesSecrets: {}
+     # Add the refresh rate for polling config backends for changes
+     # This setting is used for watching vault secrets and by other resource clients
+     refreshRate: 15s
+     requestTimeout: 0.5s
+   {{< /highlight >}}
+   {{% /tab %}}
+   {{< /tabs >}}
+
 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:

docs/content/operations/production_deployment/_index.md

@@ -52,9 +52,18 @@ When you use header manipulation to add headers to or from requests and response
 ## Performance tips
 
 ### Disable Kubernetes destinations
-Gloo Edge routes to upstreams by default, but it can alternatively be configured to bypass upstreams and route directly to Kubernetes destinations. Because routing to upstreams is the recommended configuration, you can disable the option to route to the Kubernetes destinations with the `settings.disableKubernetesDestinations: true` setting. This setting saves memory because the Gloo Edge pod doesn't cache both upstreams and Kubernetes destinations.
+When you install Gloo Edge, the Settings resource is configured with `disableKubernetesDestinations: false` by default. This setting allows you to use both a Kubernetes service (`routeAction.single.kube`) or Upstream (`routeAction.single.upstream`) as a routing destination in your VirtualService. To enable routing to a Kubernetes service destination, Gloo Edge must scan all services in the cluster to create in-memory Upstream resources to represent them. Gloo Edge uses these in-memory resources to validate that the destination is valid and returns an error if the specified Kubernetes service cannot be found. 
 
-You can set this value in the default `Settings` CR by adding the following content:   
+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` in your Gloo Edge deployment. This setting decreases the size of the API snapshot and proxy, and improves translation and reciliation time in Gloo Edge. 
+
+{{% notice note %}}
+When setting `disableKubernetesDestinations: true`, Kubernetes service destinations (`routeAction.single.kube`) cannot be used as the in-memory Upstream resources that represent the Kubernetes service do not exist in your cluster. You must use Upstream destinations in your VirtualService instead (`routeAction.single.upstream`). 
+{{% /notice %}}
+
+
+You can set `disableKubernetesDestinations: true` in the default `Settings` CR by adding the following content:   
 ```yaml
 apiVersion: gloo.solo.io/v1
 kind: Settings
@@ -67,12 +76,24 @@ spec:
     ...
 ```
 
-You can set this value in your Helm overrides file by adding the following setting:
+You can set `disableKubernetesDestinations: true` in your Helm overrides file by adding the following setting:
 ```yaml
 settings:
   disableKubernetesDestinations: true
 ```
 
+In your VirtualService make sure to use Upstreams as your routing destination: 
+{{< highlight yaml "hl_lines=4-8" >}}
+routes:
+- matchers:
+   - prefix: /petstore
+  routeAction:
+    single:
+      upstream:
+        name: petstore
+        namespace: gloo-system
+{{< /highlight >}}
+
 
 ### Configure appropriate resource usage
 

docs/content/static/content/version_geoss_latest.md

@@ -1 +1 @@
-1.16.13
+1.16.14

docs/content/static/content/version_geoss_n+1.md

@@ -1 +1 @@
-1.17.0-beta28
+1.17.0-beta32