[v1.16.x] Backport docs

changelog/v1.16.15/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

@@ -8,7 +8,7 @@ VERSION 	?= 1.0.1-dev    # a basic version that can be overidden
 
 HUGO_VERSION := 0.81.0
 
-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.12.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 @@ 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 %}}

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

@@ -30,15 +30,13 @@ 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.18.2
    ```yaml
    global:
      istioIntegration:
-       enableIstioSidecarOnGateway: true
        disableAutoinjection: true
      istioSDS:
        enabled: true
@@ -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
    ```

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/guides/traffic_management/request_processing/transformations/_index.md

@@ -272,31 +272,18 @@ Extracted values can be used in two ways:
 
 ##### Extractor Modes
 
-Starting with Gloo Edge 1.15, extractors support multiple different modes of operation. These modes enable more powerful and flexible extraction capabilities. You can specify the mode of operation for an extractor using the `mode` field. The supported modes are:
- - `Extract` (default): Extracts the value of the specified capturing group from the source. This is the standard behavior of extractors prior to this version.
- - `Single Replace`: Replaces the value of the n-th capturing group, where n is the value selected by `subgroup`, with the text specified in `replacement_text`.
- - `Replace All`: Replaces all occurrences of the pattern specified in the `regex` field within the source with the text specified in `replacement_text`.
+Starting with Gloo Edge 1.15, extractors support multiple different modes of operation. These modes enable more powerful and flexible extraction capabilities. You can specify the mode of operation for an extractor by using the `mode` field. The supported modes are:
 
-{{% notice warning %}}
-The semantics of the `regex` field vary by mode and must be carefully considered.
-{{% /notice %}}
-
- - `Extract`: The `regex` must match the entire source. Only the specified `subgroup` is extracted.
- - `Single Replace`: The `regex` must match the entire source for replacement to occur. The `subgroup` specifies which part of the match to replace.
- - `Replace All`: The `regex` can match any part of the source. All matches are replaced, and configuration which specifies a `subgroup` will be rejected.
-
-##### Extractor Configuration Validation
-
-To ensure correct configuration, Gloo Edge performs validation based on the extractor's mode:
- - For **Extract** mode, the `replacement_text` must not be set. If set, the configuration will be rejected.
- - For **Single Replace** and **Replace All** modes, the `replacement_text` must be set. If not set, the configuration will be rejected.
- - For **Replace All** mode, the `subgroup` must not be set, as it is not used. If set, the configuration will be rejected.  
+|Mode|Description|Configuration validation|
+|--|--|--|
+|`EXTRACT` (default)|Extract the value of the specified capturing group from the source. This is the standard behavior of extractors prior to this version. The `regex` expression must match the entire source. Only the value in the specified `subgroup` is extracted. |If the extractor mode is set to `Extract`, the `replacement_text` must not be set. If set, the configuration is rejected.|
+|`SINGLE_REPLACE`|Replace the value of the n-th capturing group, where n is the value selected by `subgroup`, with the text specified in `replacement_text`. The `regex` expression must match the entire source for the replacement to work. The `subgroup` specifies which part of the match to replace.|The `replacement_text` must be set. If not set, the configuration is rejected.|
+|`REPLACE_ALL`|Replace all occurrences of the pattern specified in the `regex` field within the source with the text specified in `replacement_text`. The `regex` can match any part of the source. All matches are replaced.|The `subgroup` field must not be set. If set, the configuration is rejected. In addition, the `replacement_text` must be set. If not set, the configuration is rejected.  |
 
 ##### Extractor Example - Single Replace Mode
 
 Define an extractor that replaces the first occurrence of the item `banana` with `orange` in a list of fruits. The exact composition of the list is unknown, but the format is the same, such as a comma-separated list.
 Fruits: `[apple, pear, banana, pineapple, etc.]`
-```
 
 ```yaml
 extractors:
@@ -306,20 +293,24 @@ extractors:
     replacement_text: 'orange'
     regex: '.*(banana).*'
     subgroup: 1
+body: 
+  text: '{{ BananaToOrange }}'
 ```
+
 In this configuration:
  - `BananaToOrange` is the name of the extractor.
  - `body: {}` indicates that the request/response body will be used as input to the extractor.
  - `regex: '.*(banana).*'` is designed to match the entire source, and capture the word `banana` in the first capturing group.
  - `mode: SINGLE_REPLACE` specifies the operation mode, indicating a single replace operation.
  - `replacement_text: 'orange'` replaces the content in the first capturing group with the text `orange`.
  - `subgroup: 1` specifies that the replacement should only apply to the first captured group, which is banana in this case.
+ - `body.text` adds the string with the `replacement_text` text back to the body.
 
 In this case, if the extractor processes a body containing the text `Fruits: [apple, pear, banana, pineapple]`
 
 The result will be `Fruits: [apple, pear, orange, pineapple]`
 
-#### Extractor Example - Replace All Mode  
+##### Extractor Example - Replace All Mode  
 
 Define an extractor that replaces all occurrences of the pattern `foo` with the text `bar` in the source.
 ```yaml
@@ -329,6 +320,8 @@ extractors:
     regex: 'foo'
     mode: REPLACE_ALL
     replacement_text: 'bar'
+body: 
+  text: '{{ FooToBar }}'
 ```
 
 In this configuration:
@@ -337,6 +330,7 @@ In this configuration:
  - `regex: 'foo'` specifies the pattern to match.
  - `mode: REPLACE_ALL` specifies the mode of operation.
  - `replacement_text: 'bar'` specifies the text to replace the matched pattern with.
+ - `body.text` adds the string with the `replacement_text` text back to the body.
 
 In this case, if the extractor processes a body containing the text `foo foo foo`, the result will be `bar bar bar`.