diff --git a/changelog/v1.14.31/docs-backports.yaml b/changelog/v1.14.31/docs-backports.yaml new file mode 100644 index 00000000000..7b3d63cf56f --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile index 9867ab88b35..9265294960d 100644 --- 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 index 03aae44a7cb..0dcab2060f6 100644 --- 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 index 5c6b23815af..e65ccdb6818 100644 --- 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 index e2671834d43..fb50350db34 100644 --- 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 -n gloo-system ``` diff --git a/docs/content/guides/traffic_management/destination_types/kubernetes_services/_index.md b/docs/content/guides/traffic_management/destination_types/kubernetes_services/_index.md index 09125dbd123..1280b3e5ff2 100644 --- a/docs/content/guides/traffic_management/destination_types/kubernetes_services/_index.md +++ b/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: 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 index a41b0fa5778..e33cfa58e35 100644 --- 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 new file mode 100644 index 00000000000..0c80faff9d1 Binary files /dev/null and b/docs/content/img/portal/petstore-food-bowl-collar.png differ diff --git a/docs/content/installation/_index.md b/docs/content/installation/_index.md index 6be7c362e3d..4bf59ca3cab 100644 --- 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 %}}
@@ -14,7 +20,7 @@ Gloo Edge Open-Source runs in 3 different modes to enable different use cases: @@ -27,13 +33,13 @@ Gloo Edge Open-Source runs in 3 different modes to enable different use cases:
- Run Gloo Edge in gateway mode to function as an API Gateway. This is the most fully-featured and customizable installation of Gloo Edge, and is our recommended install for first-time users. Gloo Edge can be configured via Kubernetes Custom Resources, Consul Key-Value storage, or .yaml files on Gloo Edge's local filesystem. + Run Gloo Edge in gateway mode to function as an API Gateway. This is the most fully-featured and customizable installation of Gloo Edge, and is the recommended install for first-time users. Gloo Edge can be configured via Kubernetes Custom Resources, Consul Key-Value storage, or .yaml files on Gloo Edge's local filesystem.
-{{% 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 %}}
@@ -42,7 +48,7 @@ Gloo Edge Enterprise has a single installation workflow:
- Gloo Edge Enterprise is based on open-source Gloo Edge with additional (closed source) UI and plugins. See the Gloo Edge Enterprise documentation 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 FAQs. For installation instructions, see the Enterprise setup guide.
diff --git a/docs/content/installation/advanced_configuration/vault_secrets.md b/docs/content/installation/advanced_configuration/vault_secrets.md index aad30c97a5a..98ca4de51f3 100644 --- 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 index ec75849df44..3eb5afdff29 100644 --- 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 diff --git a/docs/content/installation/gateway/kubernetes/_index.md b/docs/content/installation/gateway/kubernetes/_index.md index 573ebb8f2f1..d6661acb998 100644 --- a/docs/content/installation/gateway/kubernetes/_index.md +++ b/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 diff --git a/docs/content/installation/platform_configuration/cluster_setup.md b/docs/content/installation/platform_configuration/cluster_setup.md index 291468d0d84..2188595bc17 100644 --- a/docs/content/installation/platform_configuration/cluster_setup.md +++ b/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) --- diff --git a/docs/content/introduction/faq.md b/docs/content/introduction/faq.md index 4f4cacd29ff..62f713cf049 100644 --- a/docs/content/introduction/faq.md +++ b/docs/content/introduction/faq.md @@ -4,11 +4,13 @@ weight: 80 description: Frequently Asked Questions --- -## Gloo Edge API Gateway +This page covers some of the high-level questions commonly asked in community meetings, on Solo's [public slack](https://slack.solo.io), or in [GitHub issues](https://github.com/solo-io/gloo/issues). -This section covers some of the high-level questions we commonly see in community meetings, on our [public slack](https://slack.solo.io), or on [GitHub issues](https://github.com/solo-io/gloo/issues). Gloo Edge is an API Gateway built on top of [Envoy Proxy](https://envoyproxy.io) that comes with a simple yet powerful control plane for managing Envoy as an edge ingress, API Gateway, or service proxy. Gloo Edge's control plane is built on a plugin model that enables extension and customization depending on your environment and comes with an out of the box Discovery plugin that can discover services running VMs, registered in Consul, running in Kubernetes, or deployed on a public cloud including Functions running in a Cloud Functions environment. The Envoy community moves fast and no two operational environments are identical, so we built Gloo Edge with this flexibility in mind. +## Questions about Gloo Edge as a product {#product} -#### What are Gloo Edge's primary use cases? +Gloo Edge is an API Gateway built on top of [Envoy Proxy](https://envoyproxy.io) that comes with a simple yet powerful control plane for managing Envoy as an edge ingress, API Gateway, or service proxy. Gloo Edge's control plane is built on a plugin model that enables extension and customization depending on your environment and comes with an out of the box Discovery plugin that can discover services running VMs, registered in Consul, running in Kubernetes, or deployed on a public cloud including Functions running in a Cloud Functions environment. The Envoy community moves fast and no two operational environments are identical, so we built Gloo Edge with this flexibility in mind. + +### What are Gloo Edge's primary use cases? Gloo Edge was built to support the difficult challenges of monolith to microservice migration, which includes being able to "gloo" multiple types of compute resources (those running on VMs/monoliths with those running on containers and Kubernetes with those running on cloud/on-prem FaaS) as well as security and observability domains. Operational environments are always heterogeneous and Gloo Edge bridges that world to provide "hybrid integration". @@ -18,7 +20,7 @@ Other use cases Gloo Edge can solve: * API Gateway functionality running *outside* Kubernetes * GraphQL endpoint for the services that Gloo Edge can discover -#### What's the difference between Gloo Edge and Envoy +### What's the difference between Gloo Edge and Envoy? Envoy Proxy is a data-plane component with powerful routing, observability, and resilience capabilities. Envoy can be difficult to operationalize and complex to configure. Gloo Edge adds the following: @@ -32,8 +34,7 @@ Envoy Proxy is a data-plane component with powerful routing, observability, and * [Rate-limiting service]({{< versioned_link_path fromRoot="/guides/security/rate_limiting/simple/">}}) with pluggable storage, multiple options for API (simplified, [or more flexible]({{< versioned_link_path fromRoot="/guides/security/rate_limiting/envoy/">}}), depending on what you need) - enterprise feature * [OIDC integration]({{< versioned_link_path fromRoot="/guides/security/auth/extauth/oauth/" >}}), pluggable [external-auth service]({{< versioned_link_path fromRoot="/guides/security/auth/extauth/" >}}) - enterprise feature - -#### What's the difference between Gloo Edge and Istio +### What's the difference between Gloo Edge and Istio? Gloo Edge is NOT a service mesh but can be deployed complementary to a service mesh like Istio. Istio solves the challenges of service-to-service communication by controlling requests as they flow through the system. Gloo Edge can be deployed at the edge of the service-mesh boundary, between service meshes, or within the mesh to add the following capabilities: @@ -47,11 +48,21 @@ Gloo Edge is NOT a service mesh but can be deployed complementary to a service m See our blog on [API Gateways and Service Mesh](https://medium.com/solo-io/api-gateways-are-going-through-an-identity-crisis-d1d833a313d7) as well as [Integrating Gloo Edge with Istio 1.1](https://medium.com/solo-io/integrating-istio-1-1-mtls-and-gloo-proxy-f84be943e65e) -### Functionality +### What are the differences between open source and enterprise Gloo Edge? {#oss-enterprise} + +Gloo Edge open source software (OSS) is an effective solution to operationalize Envoy proxies across your environment. Beyond basic Envoy proxy functionality, Gloo Edge OSS includes helpful management features like a user interface and telemetry. + +Gloo Edge Enterprise Edition (EE) hardens the OSS version further with advanced features and routing capabilities. These include features such as distributed gateways, the ability to route to other upstreams like AWS Lambda, support for GraphQL APIs built into the gateway, and a developer portal. + +For a comparison of features, refer to the [Gloo Gateway product page on solo.io](https://www.solo.io/products/gloo-gateway/). + +When you install Gloo Edge, you can provide an enterprise license to install Gloo Edge EE. If you do not have a license, the installation defaults to Gloo Edge OSS. For installation instructions, see the [Setup guides]({{< versioned_link_path fromRoot="/installation/" >}}). + +## Questions about Gloo Edge functionality {#functionality} We strive to write good documentation and lots of tutorials in our user guides. If you have a suggestion for how to improve, please tell us! In this section, we'll look at some frequent questions asked when getting started: -#### How to change the ports on which Gloo Edge gateway proxy listens? +### How to change the ports on which Gloo Edge gateway proxy listens? When considering changing the ports, it's important to understand that the Gloo Edge `gateway-proxy` (Envoy) listens on a port, and when running in Kubernetes, the Kubernetes service maps to a routable service:port as well. @@ -132,15 +143,15 @@ status: If you expose Gloo Edge's `gateway-proxy` outside your Kubernetes cluster with a Cloud loadbalancer or NodePort, you should keep in mind that you will route to port `80` and `443` as defined in the Kubernetes service. -#### How do VirtualServices get associated with Gateways/listeners +### How do VirtualServices get associated with gateway listeners? By default, when you create a VirtualService *without* TLS/SSL configuration, it will be bound to the HTTP port. If you create a VirtualService and assign it TLS/SSL configuration, it will be bound to the HTTPS port. -#### How can I associate a specific VirtualService to a specific listener/Gateway? +### How can I associate a specific VirtualService to a specific gateway listener? -In the event you have multiple Gateways/listeners or you want more fine-grained control over how a VirtualService gets associated with a Gateway, you can explicitly add the VirtualService name to the Gateway resource like this: +In the event you have multiple gateways or multiple listeners on a gateway, or you want more fine-grained control over how a VirtualService gets associated with a Gateway, you can explicitly add the VirtualService name to the Gateway resource like this: {{< highlight yaml "hl_lines=9-12" >}} apiVersion: gateway.solo.io/v1 @@ -181,11 +192,11 @@ spec: anotherlabel-name: anotherlabel-value {{< /highlight >}} -#### How do I configure TLS for Gloo Edge? +### How do I configure TLS for Gloo Edge? Gloo Edge can be configured with TLS and SNI for multiple virtual hosts. Please [see the documentation for how to do that]({{< versioned_link_path fromRoot="/guides/security/tls/server_tls/">}}) -#### I want to call my HTTP/HTTPS services; what URL do I use? +### I want to call my HTTP/HTTPS services; what URL do I use? The `gateway-proxy`, as discussed in this FAQ, listens on various ports and may be attached to a cloud load balancer. The easiest way to figure out what URL to use when calling your APIs through the `gateway-proxy` is to use the `glooctl` command line: @@ -207,11 +218,11 @@ glooctl proxy url --port https https://192.168.64.50:31767 ``` -### Debugging +## Questions about debugging {#debugging} There will be times when a configuration goes awry or you encounter unexpected behavior. Here are some helpful hints to diagnose these problems. -#### How can I see exactly what configuration the Gloo Edge gateway-proxy should see and is seeing? +### How can I see exactly what configuration the Gloo Edge gateway-proxy should see and is seeing? To show what configuration the `gateway-proxy` *should* see, check the Gloo proxy. Gloo uses the proxy configuration (which also reads in configuration from other Gloo resources such as gateways and virtual services) to translate to an Envoy proxy configuration. @@ -390,7 +401,7 @@ If you want to quickly get the logs for the proxy: glooctl proxy logs -f ``` -#### Why are the ports on my Gloo Edge gateway proxy not opened? +### Why are the ports on my Gloo Edge gateway proxy not opened? For Envoy to open the ports and actually listen, you need to have a Route defined in one of the VirtualServices that will be associated with that particular Gateway/Listener. For example, if have only **one** VirtualService and that has **zero** routes, the corresponding listeners on the `gateway-proxy` will not be active: @@ -408,11 +419,11 @@ glooctl get virtualservice default This is by design with the intention of not over-exposing your cluster by accident (for security). If you feel this behavior is not justified, please let us know. -#### Why am I getting error: multiple "filter chains with the same matching rules are defined" +### Why am I getting error: multiple "filter chains with the same matching rules are defined"? When you create multiple VirtualServices that have TLS/SSL configuration, Gloo Edge will use SNI to try and route to the correct VirtualService. For this to work, you need to specify the `domain` explicitly in your VirtualService as well as the SNI domains. [See the TLS documentation for more]({{< versioned_link_path fromRoot="/guides/security/tls/server_tls/">}}). If you don't do this, then you'll have multiple VirtualServices with different certificate information and Envoy will not know which one to use since the hosts are the same. -#### When I have both HTTP and HTTPS routes, why are they merged and only available on HTTPS? +### When I have both HTTP and HTTPS routes, why are they merged and only available on HTTPS? This is similar to the previous FAQ: if you use wildcard domains on all your VirtualServices, they will be merged. If you happen to have wildcard domain on both an HTTP-intended VirtualService (ie, one without TLS/SSL config) and wildcard on the HTTPS-intended VirtualService (ie, one WITH TLS/SSL config), then you need to be explicit about which Gateway should serve which VirtualService. Using the examples from another FAQ in this document, we can explicitly list the VirtualServices for a Gateway: diff --git a/docs/content/operations/production_deployment/_index.md b/docs/content/operations/production_deployment/_index.md index 8d2777f98ed..fffbe96a6db 100644 --- a/docs/content/operations/production_deployment/_index.md +++ b/docs/content/operations/production_deployment/_index.md @@ -46,9 +46,18 @@ gloo: ## 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 @@ -61,12 +70,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 diff --git a/docs/content/operations/updating_license/_index.md b/docs/content/operations/updating_license/_index.md index ea0d77f220a..33d70332f42 100644 --- a/docs/content/operations/updating_license/_index.md +++ b/docs/content/operations/updating_license/_index.md @@ -4,7 +4,7 @@ description: How do I replace an expired license for Gloo Edge Enterprise? weight: 50 --- -Gloo Edge Enterprise requires a time-limited license key in order to fully operate. You initially provide this license at installation time, as described [here]({{< versioned_link_path fromRoot="/installation/enterprise/" >}}). +{{< readfile file="static/content/license-key" markdown="true">}} This guide provides instructions for how to update the enterprise license. The license key is stored as a Kubernetes secret in the cluster. When the key expires, the pods that mount the secret might crash. To update the license key, patch the secret and restart the Gloo Edge deployments. During the upgrade, the data plane continues to run, but you might not be able to modify the configurations for Gloo custom resources through the management plane. diff --git a/docs/content/static/content/enterprise_only_feature_disclaimer b/docs/content/static/content/enterprise_only_feature_disclaimer index ceeb5af60e0..38acf004056 100644 --- a/docs/content/static/content/enterprise_only_feature_disclaimer +++ b/docs/content/static/content/enterprise_only_feature_disclaimer @@ -1 +1 @@ -This feature is available in **Gloo Enterprise** only. If you are using the open source version of Gloo, this tutorial will not work. +This feature is available in **Gloo Edge Enterprise** only. If you are using the open source version of Gloo, these instructions do not work. \ No newline at end of file diff --git a/docs/content/static/content/license-key b/docs/content/static/content/license-key new file mode 100644 index 00000000000..a74802a1cdb --- /dev/null +++ b/docs/content/static/content/license-key @@ -0,0 +1 @@ +To run the Enterprise Edition, you must [install](https://docs.solo.io/gloo-edge/latest/installation/enterprise/) or [upgrade](https://docs.solo.io/gloo-edge/latest/operations/upgrading/) Gloo Edge with an enterprise license key. Contact your Solo Account Representative for a license key. To request a trial, [fill out this request form](https://www.solo.io/free-trial/) and check **Gloo Gateway**. If your license key is expired, you can [update the license key](https://docs.solo.io/gloo-edge/latest/operations/updating_license/). \ No newline at end of file diff --git a/docs/content/static/content/version_gee_latest.md b/docs/content/static/content/version_gee_latest.md index 7b28bf5132a..1a4d16f29ec 100644 --- a/docs/content/static/content/version_gee_latest.md +++ b/docs/content/static/content/version_gee_latest.md @@ -1 +1 @@ -1.14.8 \ No newline at end of file +1.14.19 \ No newline at end of file diff --git a/docs/content/static/content/version_gee_n+1.md b/docs/content/static/content/version_gee_n+1.md index d19d0890128..82bc7734aee 100644 --- a/docs/content/static/content/version_gee_n+1.md +++ b/docs/content/static/content/version_gee_n+1.md @@ -1 +1 @@ -1.15.0 \ No newline at end of file +1.15.18 \ No newline at end of file diff --git a/docs/content/static/content/version_gee_n-1.md b/docs/content/static/content/version_gee_n-1.md index c2f9cc1f5c5..7e1486269dd 100644 --- a/docs/content/static/content/version_gee_n-1.md +++ b/docs/content/static/content/version_gee_n-1.md @@ -1 +1 @@ -1.13.23 \ No newline at end of file +1.13.34 \ No newline at end of file diff --git a/docs/content/static/content/version_geoss_latest.md b/docs/content/static/content/version_geoss_latest.md index 965a78161fc..8443018d7d4 100644 --- a/docs/content/static/content/version_geoss_latest.md +++ b/docs/content/static/content/version_geoss_latest.md @@ -1 +1 @@ -1.14.17 \ No newline at end of file +1.14.30 \ No newline at end of file diff --git a/docs/content/static/content/version_geoss_n+1.md b/docs/content/static/content/version_geoss_n+1.md index d19d0890128..9dc9fe37f11 100644 --- a/docs/content/static/content/version_geoss_n+1.md +++ b/docs/content/static/content/version_geoss_n+1.md @@ -1 +1 @@ -1.15.0 \ No newline at end of file +1.15.28 \ No newline at end of file diff --git a/docs/content/static/content/version_geoss_n-1.md b/docs/content/static/content/version_geoss_n-1.md index 4f14f48bd39..36b284f4a36 100644 --- a/docs/content/static/content/version_geoss_n-1.md +++ b/docs/content/static/content/version_geoss_n-1.md @@ -1 +1 @@ -1.13.25 \ No newline at end of file +1.13.37 \ No newline at end of file diff --git a/docs/content/support/about.md b/docs/content/support/about.md index 4728a714f23..b5dcb26b21e 100644 --- a/docs/content/support/about.md +++ b/docs/content/support/about.md @@ -18,7 +18,7 @@ All Solo customers have access to various channels for obtaining technical assis * Open a support ticket in the [Support Portal](https://support.solo.io). * Join the community of Solo users in [Slack](https://soloio.slack.com), or talk to your Account Executive to be added to the private Solo Slack space. * Contact Solo Support by sending an email to `support@solo.io`. -* Call the Support Hotline at `+1-601-476-5646` (for **urgent priority, production-related** issues only). +* For urgent priority issues that impact production, call the [Support Hotline](https://support.solo.io/hc/en-us/articles/25251551340692-Support-Number). For more information, see the following resources: * [Submit a request]({{% versioned_link_path fromRoot="/support/support-ticket/#submit-a-ticket" %}}): Learn how to create a ticket by using the Support Portal or email. @@ -63,7 +63,7 @@ All Solo.io customers have access to various channels for obtaining technical as * Open a support ticket in the [Support Portal](https://support.solo.io). * Join the community of Solo users in [Slack](https://soloio.slack.com), or talk to your Account Executive to be added to the private Solo Slack space. * Contact Solo Support by sending an email to `support@solo.io`. -* Call the Support Hotline at `+1-601-476-5646` (for **urgent priority, production-related** issues only). +* For urgent priority issues that impact production, call the [Support Hotline](https://support.solo.io/hc/en-us/articles/25251551340692-Support-Number). ### Istio-support only: Targeted time for initial response @@ -71,13 +71,13 @@ When you contact Solo Support, you can choose a priority for your request. For m |Priority level|Targeted time for initial response| |--|--| -|Urgent**|1 hour (24/7/365)| +|Urgent`**`|1 hour (24/7/365)| |High|4 business hours (Monday - Friday 9:00 am - 6:00 pm US Eastern Time)| |Normal|8 business hours (Monday - Friday 9:00 am - 6:00 pm US Eastern Time)| |Low|24 business hours (Monday - Friday 9:00 am - 6:00 pm US Eastern Time)| {{% alert context="danger" %}} -**To report Urgent priority, production-related issues, you must contact Solo’s Support Hotline at `+1-601-476-5646`. +`**`For urgent priority issues that impact production, call the [Support Hotline](https://support.solo.io/hc/en-us/articles/25251551340692-Support-Number). {{% /alert %}} {{% alert %}} diff --git a/docs/content/support/support-ticket.md b/docs/content/support/support-ticket.md index 25e460fe1e9..dc9356d5996 100644 --- a/docs/content/support/support-ticket.md +++ b/docs/content/support/support-ticket.md @@ -54,13 +54,13 @@ When you contact Solo Support, you can choose a priority for your request: |Priority Level| Standard Support Policy |Enhanced Support Policy| |--|----------------------------|--| -|Urgent**| 1 hour (24/7/365) |15 minutes (24/7/365)| +|Urgent`**`| 1 hour (24/7/365) |15 minutes (24/7/365)| |High|4 Business Hours Local Time |2 hours (24/7/365)| |Normal|8 Business Hours Local Time|4 Business Hours Local Time| |Low|24 Business Hours Local Time|12 Business Hours Local Time| {{% notice warning %}} -**To report Urgent priority, production-related issues, you must contact Solo’s Support Hotline at `+1-601-476-5646`. +`**`For urgent priority issues that impact production, call the [Support Hotline](https://support.solo.io/hc/en-us/articles/25251551340692-Support-Number). {{% /notice %}} {{% notice note %}}