From 002689d0c5ab94cc6206804d25a8745c73aad9c9 Mon Sep 17 00:00:00 2001 From: fykaa <97490463+fykaa@users.noreply.github.com> Date: Tue, 26 Sep 2023 00:58:10 +0530 Subject: [PATCH 01/19] Initial skeleton for L7 waypoint proxy user guide --- .../docs/ops/ambient/usage/waypoint/index.md | 420 ++++++++++++++++++ 1 file changed, 420 insertions(+) create mode 100644 content/en/docs/ops/ambient/usage/waypoint/index.md diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md new file mode 100644 index 000000000000..10da22d54198 --- /dev/null +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -0,0 +1,420 @@ +--- +title: L7 - waypoint proxy Layer +description: User guide for L7 Processing. +weight: 2 +owner: istio/wg-networking-maintainers +test: n/a +--- + +{{}} +Before you start with this guide, please make sure that you have already read the Ztunnel Networking sub-guide and have a basic understanding of Istio Ambient Mesh. This guide assumes that you have already completed the Installation, set up the ztunnel and enabled mtls. + +If you have not yet done these things, please go back to the Ztunnel Networking sub-guide and follow the instructions before proceeding with this guide. + +Once you have completed the Ztunnel Networking sub-guide, you will be ready to start setting up the L7 Waypoint Proxy layer in Istio Ambient Mesh. + +{{}} + + +## Introduction + +This guide provides instructions on how to set up and use the L7 Waypoint Proxy layer in Istio Ambient Mesh. It assumes that you have already read the Ztunnel Networking sub-guide and have a basic understanding of Istio Ambient Mesh. + +L7 traffic routing is based on L4 with the addition of the Waypoint proxy, which is more complex to handle in Envoy. We can also create HPAs to scale it dynamically. + +**Overview of the Layer 7 Waypoint proxy** + +TODO + +**Benefits of using the Layer 7 Waypoint proxy** + +TODO + +## Pre-requisites & Supported Topologies + +Before you begin, make sure that you have the following prerequisites in place: +1. Istio Ambient Mesh installed and configured +2. Ztunnel proxy is installed and running +3. Mutual TLS (mtls) enabled and configured + +## Understanding the L7 Waypoint Proxy Default Configuration + +<< Consider breaking this out into bullets for easier reading TODO >> + +The L7 Waypoint Proxy layer in Istio Ambient Mesh is designed to provide a usable configuration out of the box with a fixed feature set that does not require much, or any, custom configuration. Currently, there are no configuration options that need to be set other than the `waypoint` profile setting. Once this profile is used, this in turn sets two internal configuration parameters within the Istio Operator which eventually set the configuration of the L7 Waypoint Proxy. + +In the future, there may be some additional limited configurability for L7 Waypoint Proxies. However, for now, the following are all configured with fixed default configurations that are not customizable: + +* Networking between pods and L7 Waypoint Proxies +* Networking between L7 Waypoint Proxies +* Networking between L7 Waypoint Proxies and sidecar proxies + +In particular, the only option for pod to L7 Waypoint Proxy networking setup is currently via the `istio-cni` and only via an internal ipTables based L7 Waypoint Proxy traffic redirect option. There is no option to use `init-containers` unlike with sidecar proxies. Alternate forms of L7 Waypoint Proxy traffic redirect such as eBPF are also not currently supported, although may be supported in future. + +Of course, once the baseline L7 Waypoint Proxy layer is installed, features such as Authorization Policy (both L4 and L7) as well as other Istio functions such as PeerAuthentication options for mutual-TLS are fully configurable similar to standard Istio. In future release versions, some limited configurability may also be added to the L7 Waypoint Proxy layer. + +#### Additional Notes + +* The L7 Waypoint Proxy layer can coexist with sidecar proxies in the same cluster. This allows you to use the L7 Waypoint Proxy for services that require L7 functionality and sidecar proxies for services that do not. +* The L7 Waypoint Proxy is implemented using Envoy. This means that you can use all of the features of Envoy in your L7 Waypoint Proxies. +* The L7 Waypoint Proxy is still under development, but it is already a powerful tool for managing L7 traffic in Istio Ambient Mesh. + +For the examples in this guide, we used a deployment of Istio Ambient on a `kind` cluster, although these should apply for any Kubernetes cluster version 1.18.0 or later. Refer to the Getting started guide on how to download the `istioctl` client and how to deploy a `kind` cluster. It would be recommended to have a cluster with more than 1 worker node in order to fully exercise the examples described in this guide. + +## Functional Overview + +A figure showing an architecture summary of the L7 waypoint proxy. + +TODO + +## Install Gateway CRDs + +**Before Deploying the Waypoint proxy: Install Gateway CRDs** + +In L7 networking, a waypoint proxy is a lightweight Envoy proxy that runs on each node in the cluster. It is used to implement L7 functionality in Istio Ambient Mesh. + +Waypoint proxies are dependent on Gateway API CRDs to provide features such as traffic routing and service discovery. + +1. Install Kubernetes Gateway CRDs, which don’t come installed by default on most Kubernetes clusters: + + {{< text bash >}} + $ kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \ + { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref={{< k8s_gateway_api_version >}}" | kubectl apply -f -; } + {{< /text >}} + + {{< tip >}} + {{< boilerplate gateway-api-future >}} + {{< boilerplate gateway-api-choose >}} + {{< /tip >}} + +2. Verify the installed components using the following commands: + + {{< text bash >}} + $ code + {{< /text >}} + +## Deploying an Application + +Lets first deploy a sample application composed of four separate microservices used to demonstrate various L7 feature without making it part of the Istio ambient mesh. We can pick from the apps in the samples folder of the istio repository. Execute the following examples from the top of a local Istio repository or istio folder created by downloading the istioctl client as described in istio guides. + +{{< text bash >}} +$ code for bookinfo +{{< /text >}} + +## Deploying a Waypoint Proxy + +Let's see how you can Deploy a sample application bookinfo to use the Waypoint proxy + +**How to deploy a Waypoint proxy using istioctl** +TODO + +**How to deploy a Waypoint proxy using Helm** +TODO + +## Verify the waypoint proxy is deployed + +{{< text bash >}} +$ code for verification +{{< /text >}} + +This indicates the L7 waypoint proxy is working. In the next section we look at how to monitor the confuguration and data plane of the L7 waypoint proxy to confirm that traffic is correctly using the L7 waypoint proxy. + +### Verify that the Waypoint proxy is routing traffic to the application + +## Configuring the Waypoint Proxy + +How to create a Virtual Service + +How to configure a Virtual Service for L7 routing + +How to configure a Virtual Service for load balancing + +How to configure a Virtual Service for rate limiting + +How to configure a Virtual Service for fault injection + +### Overview + +This section describes how to configure the waypoint proxy for the Bookinfo application. The Bookinfo application is a sample application that requires a virtual service to route traffic to its different services. + +Link to add: https://istio.io/latest/docs/reference/config/networking/virtual-service/ + +FOR EACH SECTION: + +### Creating a Virtual Service + +To create a virtual service for the Bookinfo application, you can use the following YAML manifest: + +{{< text bash >}} +$ yaml file +{{< /text >}} + +This virtual service will route all traffic to the `bookinfo-v1` service. + +### Deploying the Virtual Service + +To deploy the virtual service, you can use the following command: + +{{< text bash >}} +$ command +{{< /text >}} + +### Verifying the Waypoint Proxy Configuration is working + +Once the virtual service is deployed, you can verify the waypoint proxy configuration by running the following command: + +{{< text bash >}} +$ command +{{< /text >}} + +This will output the configuration of the waypoint proxy, including the virtual service that is mapped to it. + +### Configuring L4 and L7 Virtual Services + +You can configure both L4 and L7 virtual services for waypoint proxies. L4 virtual services are used to route traffic to services based on port number. L7 virtual services are used to route traffic to services based on more complex criteria, such as HTTP method and path. + +### Example L4 Virtual Service + +The following YAML manifest shows an example of an L4 virtual service: + +{{< text bash >}} +$ YAML +{{< /text >}} + +This virtual service will route 100% of traffic to the `bookinfo-v1` service and 50% of traffic to the `bookinfo-v2` service. + +### Example L7 Virtual Service + +The following YAML manifest shows an example of an L7 virtual service: + +{{< text bash >}} +$ YAML +{{< /text >}} + +This virtual service will route traffic to the `bookinfo-v1` service for requests to the `/productpage` path and traffic to the `bookinfo-v2` service for requests to the `/reviews` path. + +### Verifying the Virtual Service + +Once the virtual service is set up, the HTTP route is mapped to the waypoint configuration. This means that all traffic that matches the virtual service's hosts and HTTP routes will be routed to the waypoint proxy. + +You can verify this by using the `istioctl proxy-config` command to dump the waypoint configuration. This will show you the virtual services that are mapped to the waypoint proxy. + +For example, the following command would dump the configuration for the waypoint proxy named `bookinfo-waypoint`: + +{{< text bash >}} +$ istioctl proxy-config bookinfo-waypoint +{{< /text >}} + +The output of this command would include a list of the virtual services that are mapped to the waypoint proxy. For example: + +{{< text bash >}} +$ virtual_services: + - name: bookinfo + routes: + - match: + uri: + prefix: /productpage + - match: + uri: + prefix: /reviews +{{< /text >}} + +This output shows that the `bookinfo` virtual service is mapped to the `bookinfo-waypoint` waypoint proxy. All traffic that matches the `bookinfo` virtual service's hosts and HTTP routes will be routed to the `bookinfo-waypoint` waypoint proxy. + +By understanding how virtual services are mapped to waypoint proxies, you can configure your Istio mesh to route traffic in the way that you need. + +## Monitoring the L7 waypoint proxy + +This section describes how to monitor the L7 waypoint proxy for the Bookinfo application. + +### Viewing the Waypoint Proxy Status + +You can use the following command to view the waypoint proxy status: + +{{< text bash >}} +$ command +{{< /text >}} + +This will output the status of the waypoint proxy, including its readiness and liveness probes. + +### Viewing the Waypoint Proxy Configuration + +You can use the following command to monitor the waypoint proxy configuration: + +{{< text bash >}} +$ command +{{< /text >}} + +This will output the configuration of the waypoint proxy, including the virtual services that are mapped to it. + +### Monitoring the Virtual Service Mapping + +You can use the following command to monitor the virtual service mapping to the waypoint proxy: + +{{< text bash >}} +$ command +{{< /text >}} + +This will output the virtual services that are mapped to the waypoint proxy. + +### Checking the Waypoint Proxy Traffic + +You can use the following command to monitor the waypoint proxy traffic: + +{{< text bash >}} +$ command +{{< /text >}} + +This will output the pods in your cluster. You can then use the `istioctl __` command to get the traffic statistics for each pod. + +### Verifying L7 proxy load balancing + + +### Monitoring the AB Deployment and Canary Deployment + +You can use the following command to monitor the AB Deployment and Canary Deployment traffic: + +{{< text bash >}} +$ command +{{< /text >}} + +This will output the traffic split configuration for the virtual service. + +### Conclusion + +This section has described how to monitor the L7 waypoint proxy for the Bookinfo application. For more information on waypoint proxies, please see the Istio documentation. + +### Additional Details on Monitoring the Virtual Service Mapping + +You can also use the following methods to monitor the virtual service mapping to the waypoint proxy: + +* **Use the Istio telemetry dashboards:** The Istio telemetry dashboards provide a graphical view of the traffic flowing through your Istio mesh. You can use these dashboards to monitor the traffic flowing to your waypoint proxies and to identify any problems with the virtual service mapping. +* **Use Prometheus and Grafana:** You can use Prometheus and Grafana to collect and visualize metrics from your Istio mesh. You can use these tools to monitor the metrics associated with the waypoint proxy configuration and the virtual service mapping. + +**Monitoring the Waypoint Configuration for How Those Virtual Services Get Mapped to the Waypoint** + +You can use the following methods to monitor the waypoint configuration for how virtual services get mapped to the waypoint: + +* **Use the Istio telemetry dashboards:** The Istio telemetry dashboards provide a graphical view of the traffic flowing through your Istio mesh. You can use these dashboards to monitor the traffic flowing to your waypoint proxies and to identify any problems with the virtual service mapping. +* **Use the Istio `istioctl` command:** You can use the Istio `istioctl` command to view the waypoint configuration. This configuration includes the virtual services that are mapped to the waypoint. +* **Use Prometheus and Grafana:** You can use Prometheus and Grafana to collect and visualize metrics from your Istio mesh. You can use these tools to monitor the metrics associated with the waypoint proxy configuration and the virtual service mapping. + +By monitoring the waypoint proxy and the virtual service mapping, you can ensure that your Istio mesh is operating as expected. + +## L7 Authorization Policy +TODO + +## Monitoring and Telemetry with L7 Waypoint Proxy +TODO + +## How to use the Waypoint proxy for hairpinning +TODO + +## Co-existence of Ambient/ L7 with Side car proxies +How to use the Waypoint proxy with sidecar proxies +TODO + +## Control Traffic towards L7 waypoint Proxy + +Deploy a waypoint proxy for the review service, using the `bookinfo-review` service account, so that any traffic going to the review service will be mediated by the waypoint proxy. + +{{< text bash >}} +$ istioctl x waypoint apply --service-account bookinfo-reviews +waypoint default/bookinfo-reviews applied +{{< /text >}} + +Configure traffic routing to send 90% of requests to `reviews` v1 and 10% to `reviews` v2: + +{{< tabset category-name="config-api" >}} + +{{< tab name="Istio APIs" category-value="istio-apis" >}} + +{{< text bash >}} +$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-90-10.yaml@ +$ kubectl apply -f @samples/bookinfo/networking/destination-rule-reviews.yaml@ +{{< /text >}} + +{{< /tab >}} + +{{< tab name="Gateway API" category-value="gateway-api" >}} + +{{< text bash >}} +$ kubectl apply -f @samples/bookinfo/platform/kube/bookinfo-versions.yaml@ +$ kubectl apply -f @samples/bookinfo/gateway-api/route-reviews-90-10.yaml@ +{{< /text >}} + +{{< /tab >}} + +{{< /tabset >}} + +Confirm that roughly 10% of the traffic from 100 requests goes to reviews-v2: + +{{< text bash >}} +$ kubectl exec deploy/sleep -- sh -c "for i in \$(seq 1 100); do curl -s http://$GATEWAY_HOST/productpage | grep reviews-v.-; done" +{{< /text >}} + +## Configuring AB Deployment and Canary Deployment + +To send traffic to an AB deployment for the sidecar model using a waypoint proxy, you can follow these steps: + +TODO + +Once you have completed these steps, traffic will be routed to the two versions of your application according to the traffic splitting configuration. + +Here is a concrete example of how to send traffic to an AB deployment for the sidecar model using a waypoint proxy for the Bookinfo application: + +{{< text bash >}} +$ YAML file +{{< /text >}} + +Once you have deployed these resources, traffic will be routed to the `bookinfo-v1` and `bookinfo-v2` versions of the Bookinfo application according to the traffic splitting configuration. You can adjust the weight of each route to control how much traffic is routed to each version of the application. + +By using waypoint proxies and traffic splitting, you can implement AB deployments for sidecar models in Istio. This allows you to gradually roll out new versions of your application to users and to monitor the performance of the new version before rolling it out to all users. + +You can use Istio's AB Deployment and Canary Deployment features to deploy and manage multiple versions of your application at the same time. To do this, you would create a virtual service for each version of your application. Then, you would use Istio's traffic splitting features to route traffic to the different versions of your application. + +For more information on AB Deployment and Canary Deployment, please see the Istio documentation. + +### Traffic splitting with Canary development +TODO + +**Conclusion** + +This section has described how to configure the waypoint proxy for the Bookinfo application. For more information on waypoint proxies, please see the Istio documentation. + + +## Remove L7 waypoint proxy layer + +To remove the `productpage-viewer` authorization policy, waypoint proxies and uninstall Istio: + +{{< text bash >}} +$ kubectl delete authorizationpolicy productpage-viewer +$ istioctl x waypoint delete --service-account bookinfo-reviews +$ istioctl x waypoint delete --service-account bookinfo-productpage +$ istioctl uninstall -y --purge +$ kubectl delete namespace istio-system +{{< /text >}} + +The label to instruct Istio to automatically include applications in the `default` namespace to ambient mesh is not removed by default. If no longer needed, use the following command to remove it: + +{{< text bash >}} +$ kubectl label namespace default istio.io/dataplane-mode- +{{< /text >}} + +To delete the Bookinfo sample application and its configuration, see [`Bookinfo` cleanup](/docs/examples/bookinfo/#cleanup). + +To remove the `sleep` and `notsleep` applications: + +{{< text bash >}} +$ kubectl delete -f @samples/sleep/sleep.yaml@ +$ kubectl delete -f @samples/sleep/notsleep.yaml@ +{{< /text >}} + +If you installed the Gateway API CRDs for L7 waypoint proxy, remove them: + +{{< text bash >}} +$ kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref={{< k8s_gateway_api_version >}}" | kubectl delete -f - +{{< /text >}} + + +## Troubleshooting \ No newline at end of file From 7fcdfa3f707425dbcf677ce47c17fe356f5fd060 Mon Sep 17 00:00:00 2001 From: fykaa <97490463+fykaa@users.noreply.github.com> Date: Fri, 29 Sep 2023 22:56:48 +0530 Subject: [PATCH 02/19] Initial skeleton of L7 Waypoint Proxy --- .../docs/ops/ambient/usage/waypoint/index.md | 50 ++++++------------- 1 file changed, 15 insertions(+), 35 deletions(-) diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index 10da22d54198..8e910a6e5ba9 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -7,7 +7,7 @@ test: n/a --- {{}} -Before you start with this guide, please make sure that you have already read the Ztunnel Networking sub-guide and have a basic understanding of Istio Ambient Mesh. This guide assumes that you have already completed the Installation, set up the ztunnel and enabled mtls. +Before you start with this guide, please make sure that you have already read the Ztunnel Networking sub-guide and have a basic understanding of Istio Ambient Mesh. This guide assumes that you have already completed the Installation, set up the ztunnel and enabled mTLS. If you have not yet done these things, please go back to the Ztunnel Networking sub-guide and follow the instructions before proceeding with this guide. @@ -35,7 +35,7 @@ TODO Before you begin, make sure that you have the following prerequisites in place: 1. Istio Ambient Mesh installed and configured 2. Ztunnel proxy is installed and running -3. Mutual TLS (mtls) enabled and configured +3. Mutual TLS (mTLS) enabled and configured ## Understanding the L7 Waypoint Proxy Default Configuration @@ -49,10 +49,6 @@ In the future, there may be some additional limited configurability for L7 Waypo * Networking between L7 Waypoint Proxies * Networking between L7 Waypoint Proxies and sidecar proxies -In particular, the only option for pod to L7 Waypoint Proxy networking setup is currently via the `istio-cni` and only via an internal ipTables based L7 Waypoint Proxy traffic redirect option. There is no option to use `init-containers` unlike with sidecar proxies. Alternate forms of L7 Waypoint Proxy traffic redirect such as eBPF are also not currently supported, although may be supported in future. - -Of course, once the baseline L7 Waypoint Proxy layer is installed, features such as Authorization Policy (both L4 and L7) as well as other Istio functions such as PeerAuthentication options for mutual-TLS are fully configurable similar to standard Istio. In future release versions, some limited configurability may also be added to the L7 Waypoint Proxy layer. - #### Additional Notes * The L7 Waypoint Proxy layer can coexist with sidecar proxies in the same cluster. This allows you to use the L7 Waypoint Proxy for services that require L7 functionality and sidecar proxies for services that do not. @@ -67,9 +63,9 @@ A figure showing an architecture summary of the L7 waypoint proxy. TODO -## Install Gateway CRDs +## Install Waypoint Proxy -**Before Deploying the Waypoint proxy: Install Gateway CRDs** +**Install Gateway CRDs** In L7 networking, a waypoint proxy is a lightweight Envoy proxy that runs on each node in the cluster. It is used to implement L7 functionality in Istio Ambient Mesh. @@ -121,23 +117,13 @@ This indicates the L7 waypoint proxy is working. In the next section we look at ### Verify that the Waypoint proxy is routing traffic to the application -## Configuring the Waypoint Proxy - -How to create a Virtual Service - -How to configure a Virtual Service for L7 routing - -How to configure a Virtual Service for load balancing - -How to configure a Virtual Service for rate limiting - -How to configure a Virtual Service for fault injection +## Configuring the Waypoint Proxy - ### Overview This section describes how to configure the waypoint proxy for the Bookinfo application. The Bookinfo application is a sample application that requires a virtual service to route traffic to its different services. -Link to add: https://istio.io/latest/docs/reference/config/networking/virtual-service/ +The core functionality of the waypoint L7 traffic management is identical to sidecar mode, hence to add more features refer to this link: https://istio.io/latest/docs/reference/config/networking/virtual-service/ FOR EACH SECTION: @@ -169,26 +155,18 @@ $ command This will output the configuration of the waypoint proxy, including the virtual service that is mapped to it. -### Configuring L4 and L7 Virtual Services +### Configuring Virtual Services -You can configure both L4 and L7 virtual services for waypoint proxies. L4 virtual services are used to route traffic to services based on port number. L7 virtual services are used to route traffic to services based on more complex criteria, such as HTTP method and path. +You can configure both L4 and L7 virtual services for waypoint proxies. If you want to do a Virtual Service with TCP that is effectively a L4 virtual services. This is used to route traffic to services based on port number. L7 virtual services are used to route traffic to services based on more complex criteria, such as HTTP method and path. In a Virtual service you can have only TCP, or only HTTP or Both. -### Example L4 Virtual Service +<< Considered merging L4 (TCP) and L7 (HTTP) virtual service >> -The following YAML manifest shows an example of an L4 virtual service: - -{{< text bash >}} -$ YAML -{{< /text >}} - -This virtual service will route 100% of traffic to the `bookinfo-v1` service and 50% of traffic to the `bookinfo-v2` service. - -### Example L7 Virtual Service +### Example The following YAML manifest shows an example of an L7 virtual service: {{< text bash >}} -$ YAML +$ yaml file {{< /text >}} This virtual service will route traffic to the `bookinfo-v1` service for requests to the `/productpage` path and traffic to the `bookinfo-v2` service for requests to the `/reviews` path. @@ -202,7 +180,7 @@ You can verify this by using the `istioctl proxy-config` command to dump the way For example, the following command would dump the configuration for the waypoint proxy named `bookinfo-waypoint`: {{< text bash >}} -$ istioctl proxy-config bookinfo-waypoint +$ command {{< /text >}} The output of this command would include a list of the virtual services that are mapped to the waypoint proxy. For example: @@ -223,6 +201,7 @@ This output shows that the `bookinfo` virtual service is mapped to the `bookinfo By understanding how virtual services are mapped to waypoint proxies, you can configure your Istio mesh to route traffic in the way that you need. + ## Monitoring the L7 waypoint proxy This section describes how to monitor the L7 waypoint proxy for the Bookinfo application. @@ -417,4 +396,5 @@ $ kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimen {{< /text >}} -## Troubleshooting \ No newline at end of file +## Troubleshooting +TODO \ No newline at end of file From 99750d36e477da9f509521850af933b3b5c49da2 Mon Sep 17 00:00:00 2001 From: fykaa <97490463+fykaa@users.noreply.github.com> Date: Tue, 10 Oct 2023 02:52:24 +0530 Subject: [PATCH 03/19] reviews updated v1.0 --- .../ops/ambient/usage/{index.md => _index.md} | 0 .../docs/ops/ambient/usage/waypoint/index.md | 110 ++++++++++-------- 2 files changed, 59 insertions(+), 51 deletions(-) rename content/en/docs/ops/ambient/usage/{index.md => _index.md} (100%) diff --git a/content/en/docs/ops/ambient/usage/index.md b/content/en/docs/ops/ambient/usage/_index.md similarity index 100% rename from content/en/docs/ops/ambient/usage/index.md rename to content/en/docs/ops/ambient/usage/_index.md diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index 8e910a6e5ba9..bef21f2a8a3a 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -1,26 +1,26 @@ --- -title: L7 - waypoint proxy Layer +title: Waypoint proxy Layer description: User guide for L7 Processing. weight: 2 owner: istio/wg-networking-maintainers test: n/a --- -{{}} + ## Introduction -This guide provides instructions on how to set up and use the L7 Waypoint Proxy layer in Istio Ambient Mesh. It assumes that you have already read the Ztunnel Networking sub-guide and have a basic understanding of Istio Ambient Mesh. +This guide provides instructions on how to set up and use Waypoint proxy layer in Istio Ambient Mesh. -L7 traffic routing is based on L4 with the addition of the Waypoint proxy, which is more complex to handle in Envoy. We can also create HPAs to scale it dynamically. +L7 traffic routing is handled via the Waypoint proxy. The waypoint proxy is currently based on Envoy. The waypoint proxy can be deployed to scale dynamically using HPAs. **Overview of the Layer 7 Waypoint proxy** @@ -32,34 +32,42 @@ TODO ## Pre-requisites & Supported Topologies +This guide assumes that you have already completed the [Ztunnel Networking sub-guide](../ztunnel/). + Before you begin, make sure that you have the following prerequisites in place: 1. Istio Ambient Mesh installed and configured 2. Ztunnel proxy is installed and running 3. Mutual TLS (mTLS) enabled and configured -## Understanding the L7 Waypoint Proxy Default Configuration -<< Consider breaking this out into bullets for easier reading TODO >> + + +## Deciding if you need A Waypoint proxy +TODO + +## Deciding the scope of your Waypoint proxy +TODO -* Networking between pods and L7 Waypoint Proxies -* Networking between L7 Waypoint Proxies -* Networking between L7 Waypoint Proxies and sidecar proxies #### Additional Notes -* The L7 Waypoint Proxy layer can coexist with sidecar proxies in the same cluster. This allows you to use the L7 Waypoint Proxy for services that require L7 functionality and sidecar proxies for services that do not. -* The L7 Waypoint Proxy is implemented using Envoy. This means that you can use all of the features of Envoy in your L7 Waypoint Proxies. -* The L7 Waypoint Proxy is still under development, but it is already a powerful tool for managing L7 traffic in Istio Ambient Mesh. +* The Waypoint Proxy layer can coexist with sidecar proxies in the same cluster. This allows you to use Waypoint proxy for services that require L7 functionality and sidecar proxies for services that do not. +* Waypoint proxy is implemented using Envoy. This means that you can use all of the features of Envoy in your Waypoint Proxies. +* Waypoint proxy is still under development, but it is already a powerful tool for managing L7 traffic in Istio Ambient Mesh. -For the examples in this guide, we used a deployment of Istio Ambient on a `kind` cluster, although these should apply for any Kubernetes cluster version 1.18.0 or later. Refer to the Getting started guide on how to download the `istioctl` client and how to deploy a `kind` cluster. It would be recommended to have a cluster with more than 1 worker node in order to fully exercise the examples described in this guide. +For the examples in this guide, we used a deployment of Istio Ambient on a `kinD` cluster, although these should apply for any Kubernetes cluster version 1.18.0 or later. Refer to the Getting started guide on how to download the `istioctl` client and how to deploy a `kinD` cluster. It would be recommended to have a cluster with more than 1 worker node in order to fully exercise the examples described in this guide. ## Functional Overview -A figure showing an architecture summary of the L7 waypoint proxy. +A figure showing an architecture summary of Waypoint proxy. TODO @@ -67,11 +75,11 @@ TODO **Install Gateway CRDs** -In L7 networking, a waypoint proxy is a lightweight Envoy proxy that runs on each node in the cluster. It is used to implement L7 functionality in Istio Ambient Mesh. +In L7 networking, a waypoint proxy is a lightweight Envoy proxy that can be configured for your entire namespace or for a service account. It is used to implement L7 functionality in Istio Ambient Mesh. -Waypoint proxies are dependent on Gateway API CRDs to provide features such as traffic routing and service discovery. +The reference implementation of a waypoint proxy is managed by the Kubernetes Gateway API `istio-waypoint` GatewayClass. -1. Install Kubernetes Gateway CRDs, which don’t come installed by default on most Kubernetes clusters: +1. Install Kubernetes Gateway API CRDs, which don’t come installed by default on most Kubernetes clusters: {{< text bash >}} $ kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \ @@ -99,7 +107,7 @@ $ code for bookinfo ## Deploying a Waypoint Proxy -Let's see how you can Deploy a sample application bookinfo to use the Waypoint proxy +Let's see how you can Deploy a sample application bookinfo to use Waypoint proxy **How to deploy a Waypoint proxy using istioctl** TODO @@ -107,21 +115,21 @@ TODO **How to deploy a Waypoint proxy using Helm** TODO -## Verify the waypoint proxy is deployed +## Verify Waypoint proxy is deployed {{< text bash >}} $ code for verification {{< /text >}} -This indicates the L7 waypoint proxy is working. In the next section we look at how to monitor the confuguration and data plane of the L7 waypoint proxy to confirm that traffic is correctly using the L7 waypoint proxy. +This indicates Waypoint proxy is working. In the next section we look at how to monitor the confuguration and data plane of Waypoint proxy to confirm that traffic is correctly using Waypoint proxy. -### Verify that the Waypoint proxy is routing traffic to the application +### Verify that Waypoint proxy is routing traffic to the application -## Configuring the Waypoint Proxy - +## Configuring Waypoint proxy - ### Overview -This section describes how to configure the waypoint proxy for the Bookinfo application. The Bookinfo application is a sample application that requires a virtual service to route traffic to its different services. +This section describes how to configure Waypoint proxy for the Bookinfo application. The Bookinfo application is a sample application that requires a virtual service to route traffic to its different services. The core functionality of the waypoint L7 traffic management is identical to sidecar mode, hence to add more features refer to this link: https://istio.io/latest/docs/reference/config/networking/virtual-service/ @@ -145,15 +153,15 @@ To deploy the virtual service, you can use the following command: $ command {{< /text >}} -### Verifying the Waypoint Proxy Configuration is working +### Verifying Waypoint proxy Configuration is working -Once the virtual service is deployed, you can verify the waypoint proxy configuration by running the following command: +Once the virtual service is deployed, you can verify Waypoint proxy configuration by running the following command: {{< text bash >}} $ command {{< /text >}} -This will output the configuration of the waypoint proxy, including the virtual service that is mapped to it. +This will output the configuration of Waypoint proxy, including the virtual service that is mapped to it. ### Configuring Virtual Services @@ -175,7 +183,7 @@ This virtual service will route traffic to the `bookinfo-v1` service for request Once the virtual service is set up, the HTTP route is mapped to the waypoint configuration. This means that all traffic that matches the virtual service's hosts and HTTP routes will be routed to the waypoint proxy. -You can verify this by using the `istioctl proxy-config` command to dump the waypoint configuration. This will show you the virtual services that are mapped to the waypoint proxy. +In classic mode you can use `istioctl proxy-config cmds` to dump the envoy configuration. While `istioctl proxy-config cmds` will still work in ambient there are some differences because the envoy proxy is no longer configured for every sidecar. For example, the following command would dump the configuration for the waypoint proxy named `bookinfo-waypoint`: @@ -202,13 +210,13 @@ This output shows that the `bookinfo` virtual service is mapped to the `bookinfo By understanding how virtual services are mapped to waypoint proxies, you can configure your Istio mesh to route traffic in the way that you need. -## Monitoring the L7 waypoint proxy +## Monitoring Waypoint proxy -This section describes how to monitor the L7 waypoint proxy for the Bookinfo application. +This section describes how to monitor Waypoint proxy for the Bookinfo application. -### Viewing the Waypoint Proxy Status +### Viewing Waypoint proxy Status -You can use the following command to view the waypoint proxy status: +You can use the following command to view Waypoint proxy status: {{< text bash >}} $ command @@ -216,7 +224,7 @@ $ command This will output the status of the waypoint proxy, including its readiness and liveness probes. -### Viewing the Waypoint Proxy Configuration +### Viewing Waypoint proxy Configuration You can use the following command to monitor the waypoint proxy configuration: @@ -224,19 +232,19 @@ You can use the following command to monitor the waypoint proxy configuration: $ command {{< /text >}} -This will output the configuration of the waypoint proxy, including the virtual services that are mapped to it. +This will output the configuration of Waypoint proxy, including the virtual services that are mapped to it. ### Monitoring the Virtual Service Mapping -You can use the following command to monitor the virtual service mapping to the waypoint proxy: +You can use the following command to monitor the virtual service mapping to Waypoint proxy: {{< text bash >}} $ command {{< /text >}} -This will output the virtual services that are mapped to the waypoint proxy. +This will output the virtual services that are mapped to Waypoint proxy. -### Checking the Waypoint Proxy Traffic +### Checking Waypoint proxy Traffic You can use the following command to monitor the waypoint proxy traffic: @@ -261,7 +269,7 @@ This will output the traffic split configuration for the virtual service. ### Conclusion -This section has described how to monitor the L7 waypoint proxy for the Bookinfo application. For more information on waypoint proxies, please see the Istio documentation. +This section has described how to monitor the Waypoint proxy for the Bookinfo application. For more information on waypoint proxies, please see the Istio documentation. ### Additional Details on Monitoring the Virtual Service Mapping @@ -283,19 +291,19 @@ By monitoring the waypoint proxy and the virtual service mapping, you can ensure ## L7 Authorization Policy TODO -## Monitoring and Telemetry with L7 Waypoint Proxy +## Monitoring and Telemetry with Waypoint Proxy TODO -## How to use the Waypoint proxy for hairpinning +## How to use Waypoint proxy for hairpinning TODO -## Co-existence of Ambient/ L7 with Side car proxies -How to use the Waypoint proxy with sidecar proxies -TODO +% ## Co-existence of Ambient/ L7 with Side car proxies +% How to use the Waypoint proxy with sidecar proxies +% TODO -## Control Traffic towards L7 waypoint Proxy +## Control Traffic towards Waypoint Proxy -Deploy a waypoint proxy for the review service, using the `bookinfo-review` service account, so that any traffic going to the review service will be mediated by the waypoint proxy. +Deploy a waypoint proxy for the review service, using the `bookinfo-review` service account, so that any traffic going to the review service will be mediated by Waypoint proxy. {{< text bash >}} $ istioctl x waypoint apply --service-account bookinfo-reviews @@ -359,10 +367,10 @@ TODO **Conclusion** -This section has described how to configure the waypoint proxy for the Bookinfo application. For more information on waypoint proxies, please see the Istio documentation. +This section has described how to configure Waypoint proxy for the Bookinfo application. For more information on waypoint proxies, please see the Istio documentation. -## Remove L7 waypoint proxy layer +## Remove Waypoint proxy layer To remove the `productpage-viewer` authorization policy, waypoint proxies and uninstall Istio: @@ -389,7 +397,7 @@ $ kubectl delete -f @samples/sleep/sleep.yaml@ $ kubectl delete -f @samples/sleep/notsleep.yaml@ {{< /text >}} -If you installed the Gateway API CRDs for L7 waypoint proxy, remove them: +If you installed the Gateway API CRDs for Waypoint proxy, remove them: {{< text bash >}} $ kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref={{< k8s_gateway_api_version >}}" | kubectl delete -f - From 60cd1563ad1c58ce03f45d407c6885e143da3b15 Mon Sep 17 00:00:00 2001 From: fykaa Date: Tue, 31 Oct 2023 23:53:06 +0530 Subject: [PATCH 04/19] added initial intro --- .../docs/ops/ambient/usage/waypoint/index.md | 259 ++++++++++-------- 1 file changed, 152 insertions(+), 107 deletions(-) diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index bef21f2a8a3a..6c3218f8f4cf 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -1,101 +1,122 @@ --- -title: Waypoint proxy Layer -description: User guide for L7 Processing. +title: L7 Networking & Services with Waypoint +description: User guide for Istio Ambient L7 networking and services using waypoint proxy. weight: 2 owner: istio/wg-networking-maintainers -test: n/a +test: no --- - + +Before you begin, make sure that you have already read the [Ztunnel Networking sub-guide](../ztunnel/). This guide assumes that you have the following prerequisites in place: +1. Istio Ambient Mesh installed and configured +2. Ztunnel proxy is installed and running +3. Mutual TLS (mTLS) enabled and configured -## Introduction +{{}} -This guide provides instructions on how to set up and use Waypoint proxy layer in Istio Ambient Mesh. + -L7 traffic routing is handled via the Waypoint proxy. The waypoint proxy is currently based on Envoy. The waypoint proxy can be deployed to scale dynamically using HPAs. +## Introduction -**Overview of the Layer 7 Waypoint proxy** +This guide provides instructions on how to set up and use the Waypoint proxy layer in Istio Ambient Mesh. -TODO +Istio Ambient Mesh is a new way to deploy and manage microservices. In Ambient Mesh, workloads are no longer required to run sidecar proxies to participate in the service mesh. Ambient splits Istio’s functionality into two distinct layers, a secure overlay layer and a Layer 7 processing layer. -**Benefits of using the Layer 7 Waypoint proxy** +Ztunnel proxy is used to handle L3 and L4 networking functions, such as mTLS authentication and L4 authorization. For workloads that require L7 networking features, such as HTTP load balancing and fault injection, a waypoint proxy can be deployed. The waypoint proxy is an optional component that is Envoy-based and is responsible for terminating workload HTTP traffic and parsing workload HTTP headers. They also enforce L7 policies and collect L7 metrics. -TODO +This guide describes the functionality and usage of the waypoint proxy and L7 networking functions using Istio Ambient Mesh. We use a sample user journey to describe these functions hence it would be useful to go through this guide in sequence. However we provide links to the sections below in case the reader would like to jump to the appropriate section. -## Pre-requisites & Supported Topologies +* [Introduction](#introduction) +* [Deciding if you need A Waypoint proxy](#deciding-if-you-need-a-waypoint-proxy) +* [Current Challenges](#current-challenges) +* [Differences between Sidecar Mode and Ambient Mode for Waypoint Proxy](#differences) +* [Deciding the scope of your Waypoint proxy](#differences-between-sidecar-mode-and-ambient-mode-for-waypoint-proxy) +* [Functional Overview](#functional-overview) +* [Deploying an Application](#deploying-an-application) +* [Configuring Waypoint proxy](#configuring-waypoint-proxy) +* [Monitoring the Waypoint Proxy & L7 Networking](#monitoring-the-waypoint-proxy--l7-networking) +* [L7 Fault Injection](#l7-fault-injection) +* [L7 Observability](#l7-observability) +* [L7 Authorization Policy](#l7-authorization-policy) +* [Control Traffic towards Waypoint Proxy](##control-traffic-towards-waypoint-proxy) +* [Remove Waypoint proxy layer](#remove-waypoint-proxy-layer) -This guide assumes that you have already completed the [Ztunnel Networking sub-guide](../ztunnel/). +## Deciding if you need A Waypoint proxy -Before you begin, make sure that you have the following prerequisites in place: -1. Istio Ambient Mesh installed and configured -2. Ztunnel proxy is installed and running -3. Mutual TLS (mTLS) enabled and configured +<> +### Benefits of using the waypoint proxy and L7 networking features - +You should consider using the waypoint proxy and L7 networking features if your microservices architecture requires any of the following: -## Deciding if you need A Waypoint proxy -TODO +1. L7 load balancing and routing: You need to distribute traffic across multiple instances of a workload based on factors such as request path, header values, or cookies. +2. Waypoint provides a variety of L7 load balancing and routing algorithms, including round robin, weighted round robin, and least connections. It also supports path-based routing and other advanced routing rules. +3. L7 fault injection: You need to simulate faults in your microservices architecture such as delays, errors, and circuit breaks to test its resilience and prepare for real-world failures. +4. Rate limiting: You need to protect workloads against denial-of-service attacks and improve performance. +5. L7 observability: You need to collect metrics and traces from your microservices architecture to monitor its performance and troubleshoot problems. -## Deciding the scope of your Waypoint proxy -TODO +### Getting started with the waypoint proxy and L7 networking features +To get started with the waypoint proxy and L7 networking features, you will need to deploy a waypoint proxy for each workload that requires L7 networking. You can do this using the Kubernetes Gateway resource. Once the waypoint proxy is deployed, you can configure L7 policies using the VirtualService, DestinationRule, and ServiceEntry resources. -#### Additional Notes +This guide will provide more detailed instructions on how to deploy and configure the waypoint proxy and L7 networking features. -* The Waypoint Proxy layer can coexist with sidecar proxies in the same cluster. This allows you to use Waypoint proxy for services that require L7 functionality and sidecar proxies for services that do not. -* Waypoint proxy is implemented using Envoy. This means that you can use all of the features of Envoy in your Waypoint Proxies. -* Waypoint proxy is still under development, but it is already a powerful tool for managing L7 traffic in Istio Ambient Mesh. +## Current Challenges -For the examples in this guide, we used a deployment of Istio Ambient on a `kinD` cluster, although these should apply for any Kubernetes cluster version 1.18.0 or later. Refer to the Getting started guide on how to download the `istioctl` client and how to deploy a `kinD` cluster. It would be recommended to have a cluster with more than 1 worker node in order to fully exercise the examples described in this guide. +<> -## Functional Overview +### Environment used for this guide -A figure showing an architecture summary of Waypoint proxy. +For the examples in this guide, we used a deployment of Istio version `1.19.0`` on a `kinD` cluster of version `0.20.0 running Kubernetes version `1.27.3`. However these should also work on any Kubernetes cluster at version `1.24.0` or later and Istio version `1.18.0` or later. It would be recommended to have a cluster with more than 1 worker node in order to fully exercise the examples described in this guide. Refer to the installation user guide or Getting started guide information on installing Istio in ambient mode on a Kubernetes cluster. -TODO +## Differences between Sidecar Mode and Ambient Mode for Waypoint Proxy -## Install Waypoint Proxy +## Deciding the scope of your Waypoint proxy -**Install Gateway CRDs** + -In L7 networking, a waypoint proxy is a lightweight Envoy proxy that can be configured for your entire namespace or for a service account. It is used to implement L7 functionality in Istio Ambient Mesh. +<< per workload level or Namespace or service account >> -The reference implementation of a waypoint proxy is managed by the Kubernetes Gateway API `istio-waypoint` GatewayClass. +In ambient, all policies are enforced by the destination waypoint. In many ways, the waypoint acts as a gateway into the namespace (default scope) or service account. Istio enforces that all traffic coming into the namespace goes through the waypoint, which then enforces all policies for that namespace. Because of this, each waypoint only needs to know about configuration for its own namespace -1. Install Kubernetes Gateway API CRDs, which don’t come installed by default on most Kubernetes clusters: - {{< text bash >}} - $ kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \ - { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref={{< k8s_gateway_api_version >}}" | kubectl apply -f -; } - {{< /text >}} +#### Additional Notes - {{< tip >}} - {{< boilerplate gateway-api-future >}} - {{< boilerplate gateway-api-choose >}} - {{< /tip >}} +* The Waypoint Proxy layer can coexist with sidecar proxies in the same cluster. This allows you to use Waypoint proxy for services that require L7 functionality and sidecar proxies for services that do not. +* Waypoint proxy is implemented using Envoy. This means that you can use all of the features of Envoy in your Waypoint Proxies. +* Waypoint proxy is still under development, but it is already a powerful tool for managing L7 traffic in Istio Ambient Mesh. -2. Verify the installed components using the following commands: +For the examples in this guide, we used a deployment of Istio Ambient on a `kinD` cluster, although these should apply for any Kubernetes cluster version 1.18.0 or later. Refer to the Getting started guide on how to download the `istioctl` client and how to deploy a `kinD` cluster. It would be recommended to have a cluster with more than 1 worker node in order to fully exercise the examples described in this guide. - {{< text bash >}} - $ code - {{< /text >}} +## Functional Overview + +<> + +<> ## Deploying an Application @@ -105,7 +126,7 @@ Lets first deploy a sample application composed of four separate microservices u $ code for bookinfo {{< /text >}} -## Deploying a Waypoint Proxy +### Deploying a Waypoint Proxy Let's see how you can Deploy a sample application bookinfo to use Waypoint proxy @@ -115,7 +136,7 @@ TODO **How to deploy a Waypoint proxy using Helm** TODO -## Verify Waypoint proxy is deployed +### Verify Waypoint proxy is deployed {{< text bash >}} $ code for verification @@ -123,12 +144,36 @@ $ code for verification This indicates Waypoint proxy is working. In the next section we look at how to monitor the confuguration and data plane of Waypoint proxy to confirm that traffic is correctly using Waypoint proxy. +### Install Waypoint Proxy + +**Install Gateway CRDs** + +In L7 networking, a waypoint proxy is a lightweight Envoy proxy that can be configured for your entire namespace or for a service account. It is used to implement L7 functionality in Istio Ambient Mesh. + +The reference implementation of a waypoint proxy is managed by the Kubernetes Gateway API `istio-waypoint` GatewayClass. + +1. Install Kubernetes Gateway API CRDs, which don’t come installed by default on most Kubernetes clusters: + + {{< text bash >}} + $ kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \ + { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref={{< k8s_gateway_api_version >}}" | kubectl apply -f -; } + {{< /text >}} + + {{< tip >}} + {{< boilerplate gateway-api-future >}} + {{< boilerplate gateway-api-choose >}} + {{< /tip >}} + +2. Verify the installed components using the following commands: + + {{< text bash >}} + $ code + {{< /text >}} + ### Verify that Waypoint proxy is routing traffic to the application ## Configuring Waypoint proxy - -### Overview - This section describes how to configure Waypoint proxy for the Bookinfo application. The Bookinfo application is a sample application that requires a virtual service to route traffic to its different services. The core functionality of the waypoint L7 traffic management is identical to sidecar mode, hence to add more features refer to this link: https://istio.io/latest/docs/reference/config/networking/virtual-service/ @@ -153,6 +198,41 @@ To deploy the virtual service, you can use the following command: $ command {{< /text >}} +### L7 Load Balancing + +<> + +### Configuring AB Deployment and Canary Deployment + +<> + +To send traffic to an AB deployment for the sidecar model using a waypoint proxy, you can follow these steps: + +TODO + +Once you have completed these steps, traffic will be routed to the two versions of your application according to the traffic splitting configuration. + +Here is a concrete example of how to send traffic to an AB deployment for the sidecar model using a waypoint proxy for the Bookinfo application: + +{{< text bash >}} +$ YAML file +{{< /text >}} + +Once you have deployed these resources, traffic will be routed to the `bookinfo-v1` and `bookinfo-v2` versions of the Bookinfo application according to the traffic splitting configuration. You can adjust the weight of each route to control how much traffic is routed to each version of the application. + +By using waypoint proxies and traffic splitting, you can implement AB deployments for sidecar models in Istio. This allows you to gradually roll out new versions of your application to users and to monitor the performance of the new version before rolling it out to all users. + +You can use Istio's AB Deployment and Canary Deployment features to deploy and manage multiple versions of your application at the same time. To do this, you would create a virtual service for each version of your application. Then, you would use Istio's traffic splitting features to route traffic to the different versions of your application. + +For more information on AB Deployment and Canary Deployment, please see the Istio documentation. + +### Traffic splitting with Canary development +TODO + +**Conclusion** + +This section has described how to configure Waypoint proxy for the Bookinfo application. For more information on waypoint proxies, please see the Istio documentation. + ### Verifying Waypoint proxy Configuration is working Once the virtual service is deployed, you can verify Waypoint proxy configuration by running the following command: @@ -167,7 +247,7 @@ This will output the configuration of Waypoint proxy, including the virtual serv You can configure both L4 and L7 virtual services for waypoint proxies. If you want to do a Virtual Service with TCP that is effectively a L4 virtual services. This is used to route traffic to services based on port number. L7 virtual services are used to route traffic to services based on more complex criteria, such as HTTP method and path. In a Virtual service you can have only TCP, or only HTTP or Both. -<< Considered merging L4 (TCP) and L7 (HTTP) virtual service >> +<> ### Example @@ -179,7 +259,7 @@ $ yaml file This virtual service will route traffic to the `bookinfo-v1` service for requests to the `/productpage` path and traffic to the `bookinfo-v2` service for requests to the `/reviews` path. -### Verifying the Virtual Service +### Verifying Virtual Service Once the virtual service is set up, the HTTP route is mapped to the waypoint configuration. This means that all traffic that matches the virtual service's hosts and HTTP routes will be routed to the waypoint proxy. @@ -210,7 +290,7 @@ This output shows that the `bookinfo` virtual service is mapped to the `bookinfo By understanding how virtual services are mapped to waypoint proxies, you can configure your Istio mesh to route traffic in the way that you need. -## Monitoring Waypoint proxy +## Monitoring the Waypoint Proxy & L7 Networking This section describes how to monitor Waypoint proxy for the Bookinfo application. @@ -256,7 +336,6 @@ This will output the pods in your cluster. You can then use the `istioctl __` co ### Verifying L7 proxy load balancing - ### Monitoring the AB Deployment and Canary Deployment You can use the following command to monitor the AB Deployment and Canary Deployment traffic: @@ -288,18 +367,18 @@ You can use the following methods to monitor the waypoint configuration for how By monitoring the waypoint proxy and the virtual service mapping, you can ensure that your Istio mesh is operating as expected. -## L7 Authorization Policy -TODO -## Monitoring and Telemetry with Waypoint Proxy -TODO +## L7 Fault Injection: #l7faultinjection + +## L7 Observability: #l7observability + +## L7 Authorization Policy +<> ## How to use Waypoint proxy for hairpinning -TODO +<> -% ## Co-existence of Ambient/ L7 with Side car proxies -% How to use the Waypoint proxy with sidecar proxies -% TODO +## Co-existence of Ambient/ L7 with Side car proxies ## Control Traffic towards Waypoint Proxy @@ -340,36 +419,6 @@ Confirm that roughly 10% of the traffic from 100 requests goes to reviews-v2: $ kubectl exec deploy/sleep -- sh -c "for i in \$(seq 1 100); do curl -s http://$GATEWAY_HOST/productpage | grep reviews-v.-; done" {{< /text >}} -## Configuring AB Deployment and Canary Deployment - -To send traffic to an AB deployment for the sidecar model using a waypoint proxy, you can follow these steps: - -TODO - -Once you have completed these steps, traffic will be routed to the two versions of your application according to the traffic splitting configuration. - -Here is a concrete example of how to send traffic to an AB deployment for the sidecar model using a waypoint proxy for the Bookinfo application: - -{{< text bash >}} -$ YAML file -{{< /text >}} - -Once you have deployed these resources, traffic will be routed to the `bookinfo-v1` and `bookinfo-v2` versions of the Bookinfo application according to the traffic splitting configuration. You can adjust the weight of each route to control how much traffic is routed to each version of the application. - -By using waypoint proxies and traffic splitting, you can implement AB deployments for sidecar models in Istio. This allows you to gradually roll out new versions of your application to users and to monitor the performance of the new version before rolling it out to all users. - -You can use Istio's AB Deployment and Canary Deployment features to deploy and manage multiple versions of your application at the same time. To do this, you would create a virtual service for each version of your application. Then, you would use Istio's traffic splitting features to route traffic to the different versions of your application. - -For more information on AB Deployment and Canary Deployment, please see the Istio documentation. - -### Traffic splitting with Canary development -TODO - -**Conclusion** - -This section has described how to configure Waypoint proxy for the Bookinfo application. For more information on waypoint proxies, please see the Istio documentation. - - ## Remove Waypoint proxy layer To remove the `productpage-viewer` authorization policy, waypoint proxies and uninstall Istio: @@ -401,8 +450,4 @@ If you installed the Gateway API CRDs for Waypoint proxy, remove them: {{< text bash >}} $ kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref={{< k8s_gateway_api_version >}}" | kubectl delete -f - -{{< /text >}} - - -## Troubleshooting -TODO \ No newline at end of file +{{< /text >}} \ No newline at end of file From 945fad90787a82b7331fe43720e85da6ac96d431 Mon Sep 17 00:00:00 2001 From: fykaa Date: Sat, 2 Dec 2023 23:48:44 +0530 Subject: [PATCH 05/19] added functional overview --- .../docs/ops/ambient/usage/waypoint/index.md | 293 +++++++++++++++--- 1 file changed, 242 insertions(+), 51 deletions(-) diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index 6c3218f8f4cf..c8b22b503768 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -13,6 +13,14 @@ Please **do not run ambient in production** and be sure to thoroughly review the In particular, there are known performance, stability, and security issues in the `alpha` release. There are also functional caveats some of which are listed in the [Caveats section](#caveats) of this guide. There are also planned breaking changes, including some that will prevent upgrades. These are all limitations that will be addressed before graduation to `beta`. The current version of this guide is meant to assist early deployments and testing of the alpha version of `ambient`. The guide will continue to get updated as `ambient` itself evolves from alpha to beta status and beyond. {{< /warning >}} +## Introduction + +This guide provides instructions on how to set up and use the Waypoint proxy layer in Istio Ambient Mesh. + +Istio Ambient Mesh is a new way to deploy and manage microservices. In Ambient Mesh, workloads are no longer required to run sidecar proxies to participate in the service mesh. Ambient splits Istio’s functionality into two distinct layers, a secure overlay layer and a Layer 7 processing layer. + +Ztunnel proxy is used to handle L3 and L4 networking functions, such as mTLS authentication and L4 authorization. For workloads that require L7 networking features, such as HTTP load balancing and fault injection, a waypoint proxy can be deployed. The waypoint proxy is an optional component that is Envoy-based and is responsible for terminating workload HTTP traffic and parsing workload HTTP headers. They also enforce L7 policies and collect L7 metrics. + {{}} @@ -24,26 +32,13 @@ Before you begin, make sure that you have already read the [Ztunnel Networking s {{}} - - -## Introduction - -This guide provides instructions on how to set up and use the Waypoint proxy layer in Istio Ambient Mesh. - -Istio Ambient Mesh is a new way to deploy and manage microservices. In Ambient Mesh, workloads are no longer required to run sidecar proxies to participate in the service mesh. Ambient splits Istio’s functionality into two distinct layers, a secure overlay layer and a Layer 7 processing layer. - -Ztunnel proxy is used to handle L3 and L4 networking functions, such as mTLS authentication and L4 authorization. For workloads that require L7 networking features, such as HTTP load balancing and fault injection, a waypoint proxy can be deployed. The waypoint proxy is an optional component that is Envoy-based and is responsible for terminating workload HTTP traffic and parsing workload HTTP headers. They also enforce L7 policies and collect L7 metrics. - This guide describes the functionality and usage of the waypoint proxy and L7 networking functions using Istio Ambient Mesh. We use a sample user journey to describe these functions hence it would be useful to go through this guide in sequence. However we provide links to the sections below in case the reader would like to jump to the appropriate section. * [Introduction](#introduction) -* [Deciding if you need A Waypoint proxy](#deciding-if-you-need-a-waypoint-proxy) +* [Deciding if you need A Waypoint Proxy](#deciding-if-you-need-a-waypoint-proxy) * [Current Challenges](#current-challenges) -* [Differences between Sidecar Mode and Ambient Mode for Waypoint Proxy](#differences) -* [Deciding the scope of your Waypoint proxy](#differences-between-sidecar-mode-and-ambient-mode-for-waypoint-proxy) + +* [Deciding the scope of your Waypoint Proxy](#Deciding-the-scope-of-your-Waypoint-Proxy) * [Functional Overview](#functional-overview) * [Deploying an Application](#deploying-an-application) * [Configuring Waypoint proxy](#configuring-waypoint-proxy) @@ -51,30 +46,37 @@ This guide describes the functionality and usage of the waypoint proxy and L7 ne * [L7 Fault Injection](#l7-fault-injection) * [L7 Observability](#l7-observability) * [L7 Authorization Policy](#l7-authorization-policy) +* [Co-existence of Ambient/ L7 with Side car proxies](#Co-existence-of-Ambient/-L7-with-Side-car-proxies) * [Control Traffic towards Waypoint Proxy](##control-traffic-towards-waypoint-proxy) * [Remove Waypoint proxy layer](#remove-waypoint-proxy-layer) -## Deciding if you need A Waypoint proxy +# Deciding if you need A Waypoint proxy + +It's possible that the features offered by the secure overlay doesn’t meet your requirements. For instance, you need a rich Layer 7 authorization policy that sets up access based on a certain method and path. Alternatively you may like to conduct a canary test on the updated version of your service or introduce a new version without affecting current traffic. Or, you would like to receive metrics, HTTP access logs, and distributed tracing for some of your services. In order to accomplish these common cases, we'll go over how you can choose to enforce L7 processing with ambient mesh in this section. -<> +## Benefits of using the waypoint proxy and L7 networking features -### Benefits of using the waypoint proxy and L7 networking features +In summary, the waypoint proxy approach for the L7 processing layer offers the following three main advantages: + +- Security - Rich L7 authorization policy +- Observability - HTTP metrics, access logs, and tracing +- Traffic management - Dark launch, canary test The waypoint proxy and L7 networking features provide a number of benefits, including: -1. Improved performance and scalability: Waypoint proxies are designed to be lightweight and efficient, which can improve the performance and scalability of your microservices architecture. -2. Increased flexibility: The waypoint proxy allows you to implement a wide range of L7 networking features, such as HTTP load balancing, fault injection, and observability. -3. Simplified operations: By deploying a waypoint proxy, you can simplify the operation of your microservices architecture by reducing the number of components that need to be managed. +- Improved performance and scalability: Waypoint proxies are designed to be lightweight and efficient, which can improve the performance and scalability of your microservices architecture. +- Increased flexibility: The waypoint proxy allows you to implement a wide range of L7 networking features, such as HTTP load balancing, fault injection, and observability. +- Simplified operations: By deploying a waypoint proxy, you can simplify the operation of your microservices architecture by reducing the number of components that need to be managed. -### When to use the waypoint proxy and L7 networking features +## When to use the waypoint proxy and L7 networking features You should consider using the waypoint proxy and L7 networking features if your microservices architecture requires any of the following: -1. L7 load balancing and routing: You need to distribute traffic across multiple instances of a workload based on factors such as request path, header values, or cookies. -2. Waypoint provides a variety of L7 load balancing and routing algorithms, including round robin, weighted round robin, and least connections. It also supports path-based routing and other advanced routing rules. -3. L7 fault injection: You need to simulate faults in your microservices architecture such as delays, errors, and circuit breaks to test its resilience and prepare for real-world failures. -4. Rate limiting: You need to protect workloads against denial-of-service attacks and improve performance. -5. L7 observability: You need to collect metrics and traces from your microservices architecture to monitor its performance and troubleshoot problems. +- L7 load balancing and routing: You need to distribute traffic across multiple instances of a workload based on factors such as request path, header values, or cookies. +Waypoint provides a variety of L7 load balancing and routing algorithms, including round robin, weighted round robin, and least connections. It also supports path-based routing and other advanced routing rules. +- L7 fault injection: You need to simulate faults in your microservices architecture such as delays, errors, and circuit breaks to test its resilience and prepare for real-world failures. +- Rate limiting: You need to protect workloads against denial-of-service attacks and improve performance. +- L7 observability: You need to collect metrics and traces from your microservices architecture to monitor its performance and troubleshoot problems. ### Getting started with the waypoint proxy and L7 networking features @@ -82,45 +84,234 @@ To get started with the waypoint proxy and L7 networking features, you will need This guide will provide more detailed instructions on how to deploy and configure the waypoint proxy and L7 networking features. -## Current Challenges +# Current Challenges: #current-challenges -<> +<> -### Environment used for this guide +Waypoint only supports Ambient workloads. It does not support sidecar proxy workloads. In addition to this general caveats, there are also some specific caveats to be aware of when using Waypoint with certain protocols: -For the examples in this guide, we used a deployment of Istio version `1.19.0`` on a `kinD` cluster of version `0.20.0 running Kubernetes version `1.27.3`. However these should also work on any Kubernetes cluster at version `1.24.0` or later and Istio version `1.18.0` or later. It would be recommended to have a cluster with more than 1 worker node in order to fully exercise the examples described in this guide. Refer to the installation user guide or Getting started guide information on installing Istio in ambient mode on a Kubernetes cluster. +- HTTP: Waypoint does not support all HTTP features, such as HTTP/2 and chunked encoding. +- gRPC: Waypoint does not support all gRPC features, such as HTTP/2 transport and protocol multiplexing. +- WebSocket: Waypoint does not support WebSocket. -## Differences between Sidecar Mode and Ambient Mode for Waypoint Proxy +Despite these caveats, Waypoint is a powerful tool for enabling L7 networking and services for Istio Ambient workloads. It is a good choice for users who are looking for a way to run microservices-based applications in Ambient mode. -## Deciding the scope of your Waypoint proxy +Here is a table summarizing the caveats of Waypoint: - +| Caveat | Description | +| ------------- | ------------- | +| Maturity | Waypoint is still under development | +| Features | Waypoint only supports L7 load balancing and routing | +|Integration | Waypoint is not yet fully integrated with the Istio control plane | Support | Waypoint only supports Ambient workloads | HTTP | Waypoint does not support all HTTP features | +gRPC | Waypoint does not support all gRPC features | Websocket | Waypoint does not support WebSocket | -<< per workload level or Namespace or service account >> +In addition to these caveats, it is also important to note that Waypoint is a new feature, and it is not yet as mature as Istio's sidecar proxy. As a result, users may experience some performance or stability issues when using Waypoint. However, the Ambient mesh team is actively working to address these issues, and they are committed to making Waypoint a production-ready feature. -In ambient, all policies are enforced by the destination waypoint. In many ways, the waypoint acts as a gateway into the namespace (default scope) or service account. Istio enforces that all traffic coming into the namespace goes through the waypoint, which then enforces all policies for that namespace. Because of this, each waypoint only needs to know about configuration for its own namespace +Overall, Waypoint is a powerful tool for enabling L7 networking and services for Istio Ambient workloads. However, users should be aware of the caveats and limitations listed above before deploying Waypoint in production. +## Environment used for this guide -#### Additional Notes +For the examples in this guide, we used a deployment of Istio version `1.19.0` on a `kinD` cluster of version `0.20.0` running Kubernetes version `1.27.3`. However these should also work on any Kubernetes cluster at version `1.24.0` or later and Istio version `1.18.0` or later. It would be recommended to have a cluster with more than 1 worker node in order to fully exercise the examples described in this guide. Refer to the [Installation user](https://deploy-preview-13635--preliminary-istio.netlify.app/latest/docs/ops/ambient/usage/install/) guide or [Getting started guide](https://deploy-preview-13635--preliminary-istio.netlify.app/latest/docs/ops/ambient/getting-started/) on installing Istio in ambient mode on a Kubernetes cluster. -* The Waypoint Proxy layer can coexist with sidecar proxies in the same cluster. This allows you to use Waypoint proxy for services that require L7 functionality and sidecar proxies for services that do not. -* Waypoint proxy is implemented using Envoy. This means that you can use all of the features of Envoy in your Waypoint Proxies. -* Waypoint proxy is still under development, but it is already a powerful tool for managing L7 traffic in Istio Ambient Mesh. +# Deciding the scope of your Waypoint proxy -For the examples in this guide, we used a deployment of Istio Ambient on a `kinD` cluster, although these should apply for any Kubernetes cluster version 1.18.0 or later. Refer to the Getting started guide on how to download the `istioctl` client and how to deploy a `kinD` cluster. It would be recommended to have a cluster with more than 1 worker node in order to fully exercise the examples described in this guide. +Waypoint proxies can be deployed at the namespace or service account level. The scope you choose depends on your specific needs and requirements. -## Functional Overview +## Namespace-level scope -<> +Deploying Waypoint proxies at the namespace level provides a number of benefits, including: +- Simplified policy management: Policies are enforced at the namespace level, so you only need to define them once for all workloads in the namespace. +- Improved performance: Waypoint proxies can cache routing and policy information, which can improve performance for workloads in the namespace. +- Increased security: Waypoint proxies can enforce authorization policies at the namespace level, which can help to protect your workloads from unauthorized access. -<> +However, deploying Waypoint proxies at the namespace level also has some drawbacks, including: +- Limited granularity: You cannot apply different policies to different workloads in the same namespace. +- Increased resource consumption: Each namespace will require its own Waypoint proxy, which can consume more resources. + +## Service account-level scope + +Deploying Waypoint proxies at the service account level provides a number of benefits, including: +- Increased granularity: You can apply different policies to different workloads based on their service account. +- Reduced resource consumption: You only need to deploy a Waypoint proxy for each service account that has workloads that require L7 routing or policy enforcement. + +However, deploying Waypoint proxies at the service account level also has some drawbacks, including: + +- Increased complexity: Managing policies at the service account level can be more complex, especially if you have a large number of service accounts. +- Reduced caching: Waypoint proxies cannot cache routing and policy information at the service account level, which can reduce performance. + +## How to choose the right scope for your Waypoint proxies + +The best scope for your Waypoint proxies will depend on your specific needs and requirements. If you have a simple application with a small number of workloads, then namespace-level scope may be a good choice. However, if you have a more complex application with a large number of workloads or if you need to apply different policies to different workloads, then service account-level scope may be a better choice. + +Here are some factors to consider when choosing the scope for your Waypoint proxies: +- The number of workloads in your application +- The complexity of your application +- The need to apply different policies to different workloads +- The performance requirements of your application +- The resource requirements of your application + +# Functional Overview + +The functional behaviour of the waypoint proxy is dynamically configured by Istio to serve your applications configurations. This section takes a brief look at these functional aspects - detailed description of the internal design of the waypoint proxy is out of scope for this guide. The detailed functional overview from the Secure Overlay Networking was already discussed in the [Ztunnel L4 Networking Guide](https://deploy-preview-13635--preliminary-istio.netlify.app/latest/docs/ops/ambient/usage/ztunnel/#functionaloverview) hence this section only focuses on functionalities and features that Waypoint Proxy provides. + +<> + +What is unique about the waypoint proxy is that it runs either per-namespace (default) or per-service account. By running outside of the application pod, a waypoint proxy can install, upgrade, and scale independently from the application pod, providing a centralized approach to managing L7 traffic and enforcing policies as well as reduce operational costs. + +Upon deployment of a gateway resource using the `kubectl apply` command, Istio's control plane, IstioD, assumes the role of the Waypoint controller. Recognizing the gateway resource with the "istio.io/waypoint" gateway class name, istiod automatically deploys the Waypoint proxy based on the specified configuration in the gateway resource. + +The waypoint proxy's data plane operates at Layer 7, enabling it to fully parse connections into individual requests and apply policies based on request properties such as headers and credentials. This granular control over L7 traffic extends to a comprehensive suite of capabilities, including: +- HTTP 1.x, 2, or 3 +- Request routing +- Advanced load balancing +- Request mirroring +- Fault injection +- Request retries +- gRPC-specific capabilities + +Waypoint proxies are deployed either per-namespace or per-service account, providing granular control over L7 traffic management. This deployment model allows for independent scaling of waypoint proxies based on the request load for individual workloads. Unlike the traditional sidecar deployment approach, waypoint proxies can be scaled independently to better fit the incoming traffic for a service and match the actual workload usage, optimizing resource utilization and improving performance. You can think of these waypoint proxies as individual gateways per workload type as shown here - + +<> + +The deployment of waypoint proxies can be handled by namespace owners, platform operators, or automated systems. Once a waypoint proxy is deployed, and a corresponding L7 policy is configured for a destination represented by the waypoint proxy, the secure overlay layer ensures that connection is routed to the correct L7 waypoint proxy for processing and policy enforcement as shown here - + +<> + +Tenancy for Layer 7 capabilities in the Istio ambient mesh is similar to the sidecar deployment model. L7 capabilities are not shared across multiple identities within a single L7 proxy. Each application has its own dedicated waypoint proxy, ensuring isolation of configuration and extensions (plug-ins, extensions, etc.) specific to individual workloads. This isolation prevents interference between workloads and facilitates independent management of L7 configurations. + +Functionally, the Waypoint proxy resembles the sidecar proxy but operates independently of application pods. It has its own CA client and XDS client, enabling secure communication with istioD. To obtain its identity certificate, the Waypoint proxy establishes a secure connection with istioD, requesting certification. Upon validating the presented token, istioD signs the Waypoint proxy's certificate, granting it access to the Istio control plane. + +Subsequently, the Waypoint proxy initiates communication with istioD, requesting XDS configuration to govern its operation. This configuration defines the L7 routing rules, policy enforcement mechanisms, and other parameters essential for managing L7 traffic. + +In essence, the Waypoint proxy serves as an L7 traffic management hub, decoupled from application pods and centrally managed by istioD. This architecture simplifies L7 configuration and policy enforcement, enabling efficient and scalable L7 services within Istio Ambient deployments as shown in the figure - + +<> + +## Destination Only Waypoint + +In contrast to traditional sidecar proxies, which reside alongside application pods, Waypoint proxies operate solely on the server-side, acting as reverse proxies for L7 traffic. This approach streamlines L7 traffic management by centralising policy enforcement to the destination workload's namespace or service account. + +When a request originates from an application pod, it bypasses the client-side Waypoint proxy and directly reaches the server-side Waypoint proxy associated with the destination workload's namespace or service account. Istio enforces that all traffic coming into the namespace goes through the waypoint, which then enforces all policies for that namespace. Because of this, each waypoint only needs to know about configuration for its own namespace. Thus Waypoint proxy assumes responsibility for enforcing all L7 policies and routing rules applicable to the destination workload. + +<> + +Destination-only Waypoint simplifies the configuration process by eliminating the need for sidecar proxies and "exportTo" configurations. Waypoint proxies only need to be aware of the endpoints, pods, and workloads within their respective namespaces or service accounts. This streamlined approach reduces the complexity of L7 management and enables a more efficient use of resources. + +<> + +- **Policy Enforcement**: In traditional Istio deployments, both source-side and destination-side policies were employed, which often led to confusion for users regarding policy enforcement and troubleshooting. Destination-only Waypoint simplifies this process by enforcing all policies exclusively at the destination workload's namespace or service account. This centralized approach eliminates the need to track policies across multiple locations, making it easier to understand, manage, and troubleshoot L7 security configurations. + +<> + +- **Mixed Environment**: In a mixed environment where clients may reside inside or outside the Istio mesh, destination-only Waypoint ensures consistent policy enforcement regardless of the client's location. Since all policies are applied at the destination workload, users can be confident that security measures are consistently applied to all incoming traffic. + +<> + +## Handling Destinations without Waypoint Proxies + +While destination-only Waypoint offers centralized policy enforcement and simplified configuration, there may be instances where the destination workload doesn't have a waypoint proxy deployed. This could arise when connecting to external services beyond the control of the Istio mesh. + +To address this scenario, the Istio community is actively developing mechanisms to route traffic to the egress gateway and enable policy enforcement for destinations without waypoint proxies. This functionality will allow users to configure resilience-enhancing policies, such as timeouts, for external services. + +Please stay tuned for future blog posts and documentation updates that will provide detailed information on this evolving feature. + +# Deploying an Application + +When someone with Istio admin privileges sets up Istio mesh, it becomes available for all users in specific namespaces. The examples below shows how Istio can be used transparently once it's successfully deployed in ambient mode and the namespaces are annotated accordingly. + +## Basic application deployment without Ambient + +In this guide, we'll work with the sample [bookinfo application](https://istio.io/latest/docs/examples/bookinfo/) that comes with Istio. If you've downloaded Istio, you already have it. In ambient mode, deploying apps to your Kubernetes cluster is just like doing it without Istio. You can have your apps running in the cluster before turning on ambient mesh. They can seamlessly join the mesh without any need for restarting or reconfiguring. + +{{< warning >}} +Make sure the default namespace does not include the label `istio-injection=enabled` because when using ambient you do not want Istio to inject sidecars into the application pods. + {{}} + +1. Deploy Sample Services + +{{< text bash >}} +$ kubectl apply -f samples/bookinfo/platform/kube/bookinfo.yaml +{{< /text >}} + +{{< text bash >}} +$ kubectl apply -f samples/sleep/sleep.yaml +$ kubectl apply -f samples/sleep/notsleep.yaml +{{< /text >}} + +2. Deploy an Ingress Gateway and a Virtual Service - +This allows you to access the bookinfo app from outside the cluster + +{{< tip >}} +To get IP address assignment for `Loadbalancer` service types in `kinD`, you may need to install a tool like [MetalLB](https://metallb.universe.tf/). Please consult [this guide](https://kind.sigs.k8s.io/docs/user/loadbalancer/) for more information. +{{< /tip >}} + +{{< tabset category-name="config-api" >}} + +{{< tab name="Istio APIs" category-value="istio-apis" >}} + +Create an Istio [Gateway](/docs/reference/config/networking/gateway/) and +[VirtualService](/docs/reference/config/networking/virtual-service/): + +{{< text bash >}} +$ kubectl apply -f @samples/bookinfo/networking/bookinfo-gateway.yaml@ +{{< /text >}} + +Set the environment variables for the Istio ingress gateway: + +{{< text bash >}} +$ export GATEWAY_HOST=istio-ingressgateway.istio-system +$ export GATEWAY_SERVICE_ACCOUNT=ns/istio-system/sa/istio-ingressgateway-service-account +{{< /text >}} + +{{< /tab >}} + +{{< tab name="Gateway API" category-value="gateway-api" >}} + +Create a [Kubernetes Gateway](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io%2fv1beta1.Gateway) +and [HTTPRoute](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRoute): + +{{< text bash >}} +$ sed -e 's/from: Same/from: All/'\ + -e '/^ name: bookinfo-gateway/a\ + namespace: istio-system\ +' -e '/^ - name: bookinfo-gateway/a\ + namespace: istio-system\ +' @samples/bookinfo/gateway-api/bookinfo-gateway.yaml@ | kubectl apply -f - +{{< /text >}} + +Set the environment variables for the Kubernetes gateway: + +{{< text bash >}} +$ kubectl wait --for=condition=programmed gtw/bookinfo-gateway -n istio-system +$ export GATEWAY_HOST=bookinfo-gateway-istio.istio-system +$ export GATEWAY_SERVICE_ACCOUNT=ns/istio-system/sa/bookinfo-gateway-istio +{{< /text >}} + +{{< /tab >}} + +{{< /tabset >}} + + +3. Test your bookinfo application, it should work with or without the gateway: + + {{< text syntax=bash snip_id=verify_traffic_sleep_to_ingress >}} + $ kubectl exec deploy/sleep -- curl -s "http://$GATEWAY_HOST/productpage" | grep -o ".*" + Simple Bookstore App + {{< /text >}} + + {{< text syntax=bash snip_id=verify_traffic_sleep_to_productpage >}} + $ kubectl exec deploy/sleep -- curl -s http://productpage:9080/ | grep -o ".*" + Simple Bookstore App + {{< /text >}} + + {{< text syntax=bash snip_id=verify_traffic_notsleep_to_productpage >}} + $ kubectl exec deploy/notsleep -- curl -s http://productpage:9080/ | grep -o ".*" + Simple Bookstore App + {{< /text >}} -## Deploying an Application +## Enabling Ambient Mesh -Lets first deploy a sample application composed of four separate microservices used to demonstrate various L7 feature without making it part of the Istio ambient mesh. We can pick from the apps in the samples folder of the istio repository. Execute the following examples from the top of a local Istio repository or istio folder created by downloading the istioctl client as described in istio guides. + \ No newline at end of file From cc65453f45e94af0b536aa878fe410c5541ed217 Mon Sep 17 00:00:00 2001 From: fykaa Date: Mon, 4 Dec 2023 05:06:13 +0530 Subject: [PATCH 06/19] func overview --- .../waypoint/destination-only-waypoint.svg | 1 + .../usage/waypoint/destinationonly.svg | 1 + .../docs/ops/ambient/usage/waypoint/index.md | 462 ++---------------- .../usage/waypoint/mixed-environment.svg | 1 + .../usage/waypoint/policies-enforced (1).svg | 1 + .../usage/waypoint/policies-enforced.svg | 1 + .../waypoint-architecture-deep-dive.svg | 1 + .../usage/waypoint/waypoint-architecture.png | Bin 0 -> 83375 bytes .../waypoint-gateway-architecture.svg | 1 + .../usage/waypoint/waypoint-traffic-flow.svg | 1 + 10 files changed, 41 insertions(+), 429 deletions(-) create mode 100644 content/en/docs/ops/ambient/usage/waypoint/destination-only-waypoint.svg create mode 100644 content/en/docs/ops/ambient/usage/waypoint/destinationonly.svg create mode 100644 content/en/docs/ops/ambient/usage/waypoint/mixed-environment.svg create mode 100644 content/en/docs/ops/ambient/usage/waypoint/policies-enforced (1).svg create mode 100644 content/en/docs/ops/ambient/usage/waypoint/policies-enforced.svg create mode 100644 content/en/docs/ops/ambient/usage/waypoint/waypoint-architecture-deep-dive.svg create mode 100644 content/en/docs/ops/ambient/usage/waypoint/waypoint-architecture.png create mode 100644 content/en/docs/ops/ambient/usage/waypoint/waypoint-gateway-architecture.svg create mode 100644 content/en/docs/ops/ambient/usage/waypoint/waypoint-traffic-flow.svg diff --git a/content/en/docs/ops/ambient/usage/waypoint/destination-only-waypoint.svg b/content/en/docs/ops/ambient/usage/waypoint/destination-only-waypoint.svg new file mode 100644 index 000000000000..20232b10d063 --- /dev/null +++ b/content/en/docs/ops/ambient/usage/waypoint/destination-only-waypoint.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/content/en/docs/ops/ambient/usage/waypoint/destinationonly.svg b/content/en/docs/ops/ambient/usage/waypoint/destinationonly.svg new file mode 100644 index 000000000000..6ac9f713cc04 --- /dev/null +++ b/content/en/docs/ops/ambient/usage/waypoint/destinationonly.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index f4f6b710c0eb..6883ae9fb55d 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -154,7 +154,10 @@ Here are some factors to consider when choosing the scope for your Waypoint prox The functional behaviour of the waypoint proxy is dynamically configured by Istio to serve your applications configurations. This section takes a brief look at these functional aspects - detailed description of the internal design of the waypoint proxy is out of scope for this guide. The detailed functional overview from the Secure Overlay Networking was already discussed in the [Ztunnel L4 Networking Guide](https://deploy-preview-13635--preliminary-istio.netlify.app/latest/docs/ops/ambient/usage/ztunnel/#functionaloverview) hence this section only focuses on functionalities and features that Waypoint Proxy provides. -<> +{{< image width="100%" +link="waypoint-architecture.png" +caption="Waypoint architecture" +>}} What is unique about the waypoint proxy is that it runs either per-namespace (default) or per-service account. By running outside of the application pod, a waypoint proxy can install, upgrade, and scale independently from the application pod, providing a centralized approach to managing L7 traffic and enforcing policies as well as reduce operational costs. @@ -171,11 +174,17 @@ The waypoint proxy's data plane operates at Layer 7, enabling it to fully parse Waypoint proxies are deployed either per-namespace or per-service account, providing granular control over L7 traffic management. This deployment model allows for independent scaling of waypoint proxies based on the request load for individual workloads. Unlike the traditional sidecar deployment approach, waypoint proxies can be scaled independently to better fit the incoming traffic for a service and match the actual workload usage, optimizing resource utilization and improving performance. You can think of these waypoint proxies as individual gateways per workload type as shown here - -<> +{{< image width="100%" +link="waypoint-gateway-architecture.svg" +caption="The waypoint proxy is deployed per service account/ workload identity and can be thought of as a “gateway per workload”" +>}} The deployment of waypoint proxies can be handled by namespace owners, platform operators, or automated systems. Once a waypoint proxy is deployed, and a corresponding L7 policy is configured for a destination represented by the waypoint proxy, the secure overlay layer ensures that connection is routed to the correct L7 waypoint proxy for processing and policy enforcement as shown here - -<> +{{< image width="100%" +link="waypoint-traffic-flow.svg" +caption="Traffic will flow through L7 waypoint proxies when there are L7 policies that need to be enforced for a particular service" +>}} Tenancy for Layer 7 capabilities in the Istio ambient mesh is similar to the sidecar deployment model. L7 capabilities are not shared across multiple identities within a single L7 proxy. Each application has its own dedicated waypoint proxy, ensuring isolation of configuration and extensions (plug-ins, extensions, etc.) specific to individual workloads. This isolation prevents interference between workloads and facilitates independent management of L7 configurations. @@ -185,7 +194,10 @@ Subsequently, the Waypoint proxy initiates communication with istioD, requesting In essence, the Waypoint proxy serves as an L7 traffic management hub, decoupled from application pods and centrally managed by istioD. This architecture simplifies L7 configuration and policy enforcement, enabling efficient and scalable L7 services within Istio Ambient deployments as shown in the figure - -<> +{{< image width="100%" +link="waypoint-architecture-deep-dive.svg" +caption="Waypoint Architecture Deep Dive" +>}} ## Destination Only Waypoint @@ -193,19 +205,31 @@ In contrast to traditional sidecar proxies, which reside alongside application p When a request originates from an application pod, it bypasses the client-side Waypoint proxy and directly reaches the server-side Waypoint proxy associated with the destination workload's namespace or service account. Istio enforces that all traffic coming into the namespace goes through the waypoint, which then enforces all policies for that namespace. Because of this, each waypoint only needs to know about configuration for its own namespace. Thus Waypoint proxy assumes responsibility for enforcing all L7 policies and routing rules applicable to the destination workload. -<> +{{< image width="100%" +link="destinationonly.svg" +caption="Waypoint Proxies" +>}} Destination-only Waypoint simplifies the configuration process by eliminating the need for sidecar proxies and "exportTo" configurations. Waypoint proxies only need to be aware of the endpoints, pods, and workloads within their respective namespaces or service accounts. This streamlined approach reduces the complexity of L7 management and enables a more efficient use of resources. -<> +{{< image width="100%" +link="destination-only-waypoint.svg" +caption="Waypoint Proxies" +>}} - **Policy Enforcement**: In traditional Istio deployments, both source-side and destination-side policies were employed, which often led to confusion for users regarding policy enforcement and troubleshooting. Destination-only Waypoint simplifies this process by enforcing all policies exclusively at the destination workload's namespace or service account. This centralized approach eliminates the need to track policies across multiple locations, making it easier to understand, manage, and troubleshoot L7 security configurations. -<> +{{< image width="100%" +link="policies-enforced (1).svg" +caption="Policy Enforced on Destination Waypoint" +>}} - **Mixed Environment**: In a mixed environment where clients may reside inside or outside the Istio mesh, destination-only Waypoint ensures consistent policy enforcement regardless of the client's location. Since all policies are applied at the destination workload, users can be confident that security measures are consistently applied to all incoming traffic. -<> +{{< image width="100%" +link="mixed-environment.svg" +caption="Waypoint Proxies" +>}} ## Handling Destinations without Waypoint Proxies @@ -221,424 +245,4 @@ When someone with Istio admin privileges sets up Istio mesh, it becomes availabl ## Basic application deployment without Ambient -In this guide, we'll work with the sample [bookinfo application](https://istio.io/latest/docs/examples/bookinfo/) that comes with Istio. If you've downloaded Istio, you already have it. In ambient mode, deploying apps to your Kubernetes cluster is just like doing it without Istio. You can have your apps running in the cluster before turning on ambient mesh. They can seamlessly join the mesh without any need for restarting or reconfiguring. - -{{< warning >}} -Make sure the default namespace does not include the label `istio-injection=enabled` because when using ambient you do not want Istio to inject sidecars into the application pods. - {{}} - -1. Deploy Sample Services - -{{< text bash >}} -$ kubectl apply -f samples/bookinfo/platform/kube/bookinfo.yaml -{{< /text >}} - -{{< text bash >}} -$ kubectl apply -f samples/sleep/sleep.yaml -$ kubectl apply -f samples/sleep/notsleep.yaml -{{< /text >}} - -2. Deploy an Ingress Gateway and a Virtual Service - -This allows you to access the bookinfo app from outside the cluster - -{{< tip >}} -To get IP address assignment for `Loadbalancer` service types in `kinD`, you may need to install a tool like [MetalLB](https://metallb.universe.tf/). Please consult [this guide](https://kind.sigs.k8s.io/docs/user/loadbalancer/) for more information. -{{< /tip >}} - -{{< tabset category-name="config-api" >}} - -{{< tab name="Istio APIs" category-value="istio-apis" >}} - -Create an Istio [Gateway](/docs/reference/config/networking/gateway/) and -[VirtualService](/docs/reference/config/networking/virtual-service/): - -{{< text bash >}} -$ kubectl apply -f @samples/bookinfo/networking/bookinfo-gateway.yaml@ -{{< /text >}} - -Set the environment variables for the Istio ingress gateway: - -{{< text bash >}} -$ export GATEWAY_HOST=istio-ingressgateway.istio-system -$ export GATEWAY_SERVICE_ACCOUNT=ns/istio-system/sa/istio-ingressgateway-service-account -{{< /text >}} - -{{< /tab >}} - -{{< tab name="Gateway API" category-value="gateway-api" >}} - -Create a [Kubernetes Gateway](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io%2fv1beta1.Gateway) -and [HTTPRoute](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRoute): - -{{< text bash >}} -$ sed -e 's/from: Same/from: All/'\ - -e '/^ name: bookinfo-gateway/a\ - namespace: istio-system\ -' -e '/^ - name: bookinfo-gateway/a\ - namespace: istio-system\ -' @samples/bookinfo/gateway-api/bookinfo-gateway.yaml@ | kubectl apply -f - -{{< /text >}} - -Set the environment variables for the Kubernetes gateway: - -{{< text bash >}} -$ kubectl wait --for=condition=programmed gtw/bookinfo-gateway -n istio-system -$ export GATEWAY_HOST=bookinfo-gateway-istio.istio-system -$ export GATEWAY_SERVICE_ACCOUNT=ns/istio-system/sa/bookinfo-gateway-istio -{{< /text >}} - -{{< /tab >}} - -{{< /tabset >}} - - -3. Test your bookinfo application, it should work with or without the gateway: - - {{< text syntax=bash snip_id=verify_traffic_sleep_to_ingress >}} - $ kubectl exec deploy/sleep -- curl -s "http://$GATEWAY_HOST/productpage" | grep -o ".*" - Simple Bookstore App - {{< /text >}} - - {{< text syntax=bash snip_id=verify_traffic_sleep_to_productpage >}} - $ kubectl exec deploy/sleep -- curl -s http://productpage:9080/ | grep -o ".*" - Simple Bookstore App - {{< /text >}} - - {{< text syntax=bash snip_id=verify_traffic_notsleep_to_productpage >}} - $ kubectl exec deploy/notsleep -- curl -s http://productpage:9080/ | grep -o ".*" - Simple Bookstore App - {{< /text >}} - -## Enabling Ambient Mesh - - +This section is Under Construction... \ No newline at end of file diff --git a/content/en/docs/ops/ambient/usage/waypoint/mixed-environment.svg b/content/en/docs/ops/ambient/usage/waypoint/mixed-environment.svg new file mode 100644 index 000000000000..1e15d5a6f390 --- /dev/null +++ b/content/en/docs/ops/ambient/usage/waypoint/mixed-environment.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/content/en/docs/ops/ambient/usage/waypoint/policies-enforced (1).svg b/content/en/docs/ops/ambient/usage/waypoint/policies-enforced (1).svg new file mode 100644 index 000000000000..c79afd97d580 --- /dev/null +++ b/content/en/docs/ops/ambient/usage/waypoint/policies-enforced (1).svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/content/en/docs/ops/ambient/usage/waypoint/policies-enforced.svg b/content/en/docs/ops/ambient/usage/waypoint/policies-enforced.svg new file mode 100644 index 000000000000..8331921578dc --- /dev/null +++ b/content/en/docs/ops/ambient/usage/waypoint/policies-enforced.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/content/en/docs/ops/ambient/usage/waypoint/waypoint-architecture-deep-dive.svg b/content/en/docs/ops/ambient/usage/waypoint/waypoint-architecture-deep-dive.svg new file mode 100644 index 000000000000..76a544dbee76 --- /dev/null +++ b/content/en/docs/ops/ambient/usage/waypoint/waypoint-architecture-deep-dive.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/content/en/docs/ops/ambient/usage/waypoint/waypoint-architecture.png b/content/en/docs/ops/ambient/usage/waypoint/waypoint-architecture.png new file mode 100644 index 0000000000000000000000000000000000000000..38066816a0d2028ce3e6c1a43657600778a3ac92 GIT binary patch literal 83375 zcmeFZXIPV2_cw~;<1mWAC<-zNj0KSz6s3lsqM{;#A_CIH2uKGbC4?k4Ktzd!CM6LO zkls5a3POe&r1uyQ0t5&UQb$JTI;ueYwfl6 zO_b#&Q}JzoY!eX?5kG(K^c4{iQId$rX7AsA1%Bxpp4}uOa!=&^>62GOoaVGLlDYj_U2rTJfb1L)Tl!0(Y?WKHfPlSsP6uwdGE$XPRtgb zu-JI}Dz?=5yeNmJ(k7}(?9rX4i@(r~`ay%oe-*t9^4pw2XfR6Ml^j3k;g`sIa^Y@s z?A;rfcVNZ$>K5b=9^>l&n4$5)aJ_h};K^#)X&XTN1<||crZt*IThCFx#(5O_G5`LL z6Fi=`?k@0o^Dfnq-r)FJqIzNzKeUYj$ylo;uP+*dzdkn+@Ru4Tg*1z>2`PF96}eVt z+#>p;{-@u)g9|B`Ey;c@Tb|Nr(@qK!X!Rn-kJlnXeRK|$JQFhW*y(Nb*09(-(|_o-diXH zD;6C?vjLSv*K|jX`KwvRMkwZ7-@x6wcP}o?%?(SRn%Vw+Q+&Yp#tjs~sGV^83h(NL z7{f(QvpaBR_?%eRuprHmH#yIj2> z>WR*PUk(s_#-LUkUmY^%TD!Zu2MWyl;_z+XrQUn;d8I)N1P-0c&Qe%oRT9=ouxbbT z&iddNPKnO|aYh=SMU$cmPG{|Zx4De4QkSKNrX$Ea)2!5>;jBXzSiX0dR0du3yR4g$!l3=^nVW}OD)(d(Zg z+D~YAMXHkGW&m;b<_p1es}wR|BjsZ{I-T3&Jw(6Bxp%~i+L>w{JPxOZ1J0-wXaaKB z4#D>o+~3N$rOCtxV6?lS5lQz8!0uPgM8Do^TH7SLcPW0vw{~GBGcz;$WPrr?1wozc z?d|(CDo5}18v=OT47hdV&X`iDiwe8p=wiUHq3!3~-!wvANPHUqX8Ha~Jk#7Ahh#-o zcn_^y6&RIhBYVD!5`kI)y7Hqzc+S_#`UM|!T-%huy`c64#;p496;141JYv#u!se}Z z&b!V2T`T;@2VywU`mkw-7ihoUEI;Y*l5Sk2In)L%z)bfBd~zW$3<(UGYKKMi*BbW? z)hyiK5L|;}saGG}6=6B$)LR4yWYEhpeuBP26mu#jCMIsS_Fvxx?co_18YU~C`O9q* zfd2@jKoSJAB{T)8Ahz0I)HS(If~u1*ojEW1<;2t)JvC$^N?4ndqpCUZw{_;Tu3x`? zEsP47hHp>i_HXPaG*%5S%01CmsYa5G>%Ol$b7x_VKMnwGp{KT{Cg`2t-(znGKlk;O zd(HJ`6GBOdahRoM0s^sNjnXbLz{Ry;h+&sgcJDU(y;%XPbxInocCkBC^cnY8pZ%Tk z%%iW{+YhAPX;mTCPigqAwu ztCE_UI?}DX<+}}voaaJUKbxYtF~N0{^gGp~&eIImC>HUCI7AKD%5GR$Ko=Rt`?&+V zYxLgKny4}7qcMCc&ZhI3-@R4&|FssJr>CbA_k$?J|2Ck9DWHc%f*;1Ll32yoPrq*P zrF&{vjBSAKNx-jWpgjP-c#fC-KL5RS8(@?6*x*;eFZvF;ng_L z0p9ukxkTA`TRCx6vvcwuvMoCc%Pr?u`B{*E`#$>zfe+vT8zIwK$UIr?pxFuezHYV? zzTThC&|QcD=2w-!{V<*?y4U}MVvM4(VC3U^=XbsDeVXn_b`IHa-#LJ%ovRl&W-kD5 zkcSW8w@yIg9j1Gisn*uk3Ge)V`CH@Z>FKx)Qi%cJBKnmfq}C+(fkt_J!a}Day;E_q zGdWoK(#$iJSZZJX~pH^5|B-4Z)4b~tKeMf}QSKD{Z?ML;pA?n9dkWAoc@(?C2f@a+a7Thn0sF?rQ^Pmy ziDu~iIr-(OSq0H`=lC5U3J?m5ivz;A8wZ4q=dlDZvlKucSMuOq#s0j-1l}{+3qa z81NQD|4+d2LTdnYLR>8)tJdl;35^CAVBV?~_Wi{-w*WrK`Pj-3rqC2p{8|GOsA&Ju z0Af7>k9YcCO0Lr0Je1&u0r<7>omt@%<~wN`0MXX%i=}>-a-!uhDf=qI9!va~1OCpm zBERq)}DoMp~W1Ux@cRD(zLEYU4hgjV1zBtGg=UKsl z^I+n~yYus^25wcex9JxZ@t6?J*&_#{XtqgJF&Qm0H8D-Z?Yhgwzgo@F_WX+Qa4eV{ zZw^#9cOZ7((pq+RuMwU*`ZdrS1aYg1Lc57K2aeW0?W65+9U$ic;K23M5Q1`I_!-dF_{FItv$YZ;1sl-A+WNnJ6KK;XHKZZo9uW zZ!Kw+!W%5hDH|xxhd-xPm6qNXzPPnsvaevWEu%ID=Cp@z;H$nI=zUgrnpM> z+-Urw@ykyz#fxDJvqu^`M)_>OCWs^j?U&nwg&alCcE5#2BnP;I&H>=yv~j;J(D_{Rl>>m?UUNTv87S5|bm7Gax=stp zf!u`00_ykrd0F7zn%bLr6i%)x>t$`w& zntL8P6A_xW4uJn)RFZUtB$+r*^?DK`dp>C{DAVF|dPZ8=K)|%0sPF@6j2Z_>3S9g$ z5YS(m9KG=lO%xv!U=Lt%Ckd&wT%NUIF2vEq*Q8jMLGuya=X%#Rj5$P-6l{v-I97r#tHysX^{6j zg#|A+d`U17ce^g2-}pYh`w6=8A{$*_{q>7q?PT5EGXR{~_lpP0(*S$=UTfbApg-4F#lY>L3N>)Fra%b*{ue~PE|@^%JENu4$gSmp2`h*Q*|)_CrFW$jNA^&dT07& z7ed28;)n1uJpfiX+BX4exCo?VM+YyGIi=bFP@;@SM5Tn@=Qd1_vwJvn<>SB+fg@CF znXdW`{D!?ZCdePZZI1YNnD6F{auv3*3&bRyijS$wP0*V~rj9*b;Y)7NJ&@>q$M;Uh zR7aQ3pL{5DR_+mMc(BnZUy;%Hs5YlW>7Z!xCLq7+!c~==;om!B28~3dZ+1-sXLY~Z zoEr=m;O>lVzOuo&ymNJgwO(RwX~v0UQM-oSA|f{q2iOT|1c+MQQ515pChfRAa@&_@ z@4gK+`r*2{pzX$i-+*SrINIHy9&J~sPdt`IC7b6|f7 zgI)T2)b8xuTs8GDA1_WvFg1b^gWZK%uZO!VG=yq*-PhfSZmZ$I$s$;PN`Lo$dE1S+ zF(^8*-T}nh12@ z5q~jXyj;${#~cV6evdPHJR3omaPpmNtM8ULOtn)8TEShJdpoSKRvz8=Gk`F1@96N* zxa>5(O3C3)L+?_%$+#?Ztel8;0}>M;%e{NpH>W-GZ4i0Fk&@JkuzMdLTZWb6AN zE3c|q9;3k(hm&@aC1{QTC%&bK(CO(uN*z==l7V@>%QH7WVoPlNO3H;--#r(5-W1`U zsOw@Dg!^cSD$zPNK))CaXc=PCB$TWc$dxwgn_k+EAs4BRZP(i03R5*VDB6gBmWP=3 zBMlwyosu>vcxd8!n0bw?h{zjtH*md5O7QAC|M4TQOsrBRnZIPD|Jz@#ztfefJOZtB zX#4~+Rw}3>FtZlWE%pqxpunGL<93S;K`-2A&br-m`OzScUDwK#b;HGCQuivbR)8X?yYyN}Zf!vHaU!Ga5-2uXkJ{<(ugONn)(E)q1D5Yn~WH zTfeMw{(|o2?a@Ds`52?&Ln#4W6w?iZ1`U??yj&0w`GA*+X24=n_T)(SWhIM5ocY1r zZwfLs95_QNlnCwVcgcVjtSCcNjTV0%V0CM@k?4ifKfHW{H{I`j{`5vH(7N6p5(?!E z?T~6jCa9YOEC0tTSkLl@Kp7h*{&2fE?5qzcLz3=9!;{fQlRj%K5N%VKO zPUL)vSmOJ5H5ySt5*vZrA_^%eepRY8=8OUIaQ4i33f?SU!XVmlW6%2mg!n(^-#n#X zM6fmTGp#DKIif%h#AoE_AEOVx*2o>dDnqv(Pg-ElYj~AR@P~Wc!sm8Bn>7(v)gVD9 z)L99{LNW6->KtZcYmWoY{GW~YE8tM{a&O@^*YFVj>)?%jw%*UWn{csiAf%DSDhg|6 z6@^^znVGxD-s6Ctf?rf8%2*6Z2LuH-m? zvCL8A_=NxX=P@94&*+`>W_nS z78zj0MzzTSS9Ty_gSM(lWgcarOAWloy1HSbIdH=U=s@9bl_|%K5e0^*3az@k^qQ`5 zgQdVIYCYWCDrBzNn$kIjNll&H5)Fi!+!azSb(vS{8(LGz%ETcWG6X!=74j4PXaO@$6fgotMR|pf&Ov^4X zLci!fP}2mnk2TgASN&3<2x^a!XQzi#?zhE<%aXho+2xx>iZ;p-e`h0awoicOM(l&a zQ+-SlHi^W|my7B=5;Gogyd_kZ9s*{iB^-ZO`^=WU!j~Z@$}7~OTv;RznJTZX0@n34 z*D0;9OlxIuN<(LRhx0Dh&%g7a@S%qyVUV%)llM5+CnA5*)OYc`_NXw$ae(%sHs8@! z(UT zf>FdQHgNXPJ(tV>!)YQS7Y>d0@LNIVbd~qeVp+3JXQaDt6}>ydg;_Vz4c7}zpy~>E zDMhzDeL_&9!+Cl!&e0i*6D`ODKgAp{eQ;=Z0k^dsdsJ8YbMZMm<>?TmffNWjhcrB#@Jm<>d$pB*fw){FczLjsRgpV7N0^{sS*MHY3@ScOs7ZOI+2anj`3}7Dyq@|)~ZJSs7$7|Hu`3uu|VHm0cJK7Zq zrsgsR>e z-B*hm!cL62|DG)H&%u2cBfh2k*$y0TbfPPJjl!VxQl+{HDK6Bo@)$SYx!In#Om zF(VVG<>Q|iUS31Hhm#CXIhxxi#u<~UjN%)EQ)>?kYwQs*IKkIU?CarxUqkBLmizY? zgR{x~@%cObfx}C<3g()-Gd({Tu0X(n#;kUG<|H9Hk@kW=nqXpM$+U#H^!fjg7|6{R|FJbE~SaOjvXpU~nfzMVyc~Oy1ko zQuhLmZQr)Sp*-5HUFlBlc|i5EAJMKg#x_>)1J%X{tTf+Obm#TbYB{UZuQdip@Y z46_|5y7Jc)(TmU8gbu$R-tzBICGzIoM12vpz6>~tj$(J}nX8*lw$JG?;A1bjtNS8) zo#6^*D^uFE261vq4`Xk!$g?T$V^`q{FFWWtF{-7R~b`7#Q{Mp=>zKY z()wUHifQ8>@tWi-VTc$b8I7CqKC0EUQ4*^@@wge{$Zg}PKD7;nczO2-nFQ)G)5w3Q zd!AN2`mC*nIMkax&5iN4AEmc~EJ%w4g{BAZ*n!d7eOAk%yB6KCaL6o0JWU^K zUt+;8I_dBL&-=q%0wcWXid!(WH!Pj%O%9rGZ(SXqV7>-Y+$w(bn3~MDlgS+1Ftmc` zwL9S>D5dc$QD@q@rvSpX!B7>WIU2O&(zt(x;<3U3Gh<^7Lru+SGPz_v04J{YM`N6F zurXSlqMN^H$WyqHcNx1mYOHFoW>5Ou9>?1@E3ERhOQ*H5f?A zU|LdFRecqhurM!ZV^r}&DTB68h#92Gi}QjjiAY5$I!!)78B>D5;vlu|_I&@3XNcw< zZmvWndcvjr4mTJ(3)sqqQzvu^Jm<$jLS#KFSDWV@O->FWGdRd94rh@jCxsKH<;J@! zzJ0vq5*X6ScY;7I;0o@o?rbxXU$TF&wT=nOujw@>-0Kgz49=-=Jc^AX6?C{CiZm@K zzH6vep+dTU<=+P%;7qq)y011U$aQMIA!?){u6_|CpU{eBG)%8P-z0twYZ_3!pa-ii zA{7!0LCM)*TllzbrMANzelJ$32Rifz8^b1Q#?~!E=E5i20GJG1)zdkIrQVxmQXYjk zGxci0Pt4LmsZPned%_Woba>tQp>`I{0+)*H+Sge@_wj3Eu=+c(>ji?=r`SRwo%b$M z=MivNPT5Uc-V2n~Z4@4}FJR0l8-a_`ie3;X0DN6qSupz=E)2C%t)f0?8lsKldR6jx ziX_H;wfGFlEn1m}|Doi)qqhNub%T_us3(;HDQJ=NlZ-&-lL&u7@tEuFl=Db(6S8gQ z<92H-(Y1O~eYxQ%xi}BW=k6Z5G8I1A4HVT;An#gr^k|LJ82bPwswp(AGdhSA7NZgj z#|N62k%|MFLmU*=i)q&+UbkSbvfII=yMZ7Jg~B1|K>lB?DO+DzXY?V+7O2C7dXGT8V1W6WWU_WUrVCa+iRYH^`ZqsyZH2w*{W0;o+44JDrH@?i zys0@!*21sTO;J)w;H^HI4DLLP2NI51&CNh90aQh8XtFy(w%X3Va2-p`Xq+6F?EWI= ztR^V3QZJb_DiR|m)PgZ=7tmh01cgGoo?hDf7emDv8g;BM5qa~PVB$N|oKn|*F;*rR zqqG)X8I1OuXkVe>A!@u(VrOU3QeVCik-WMNU&phoVZp0;d!ENr3r8#Q)JDl=4%197 zR9?Tz8b%9kKAAEraYA=W-_rBv^GGogW*=n1P{SWP;BDLgyFpM8^L4#L*XMCrY4g$H z(%2w}0>g1JgdcELP!Jo=d%95m6u!>`?v%J&UTnRp4z4P_{guLa7c8v0jS(X6$34lO z=jbu`+0KQnZr*I=#bh5doyy9^)(f2bG0DK;L4eS$Co^b{SWs$>5pO(mg3T-$Q#|#! zkW#>qc6BBX^~<^$IrqTA>MBFflQ+jEA~wR;s2Ik<*bqKn*?=>MvezW(#_CWv1TPI`z@UEXx$B4B-iLZ(56oOtJ)+V9j zMvPfF@l!@kmT`G@R$k1R89%%(NG*unKORs0%ulF{$i1|v`3M1EMT~s|WA@Mjea8xS zQ%4%83@uRB0=y70Ab?%+lS*5onlT;K zQl1SPxrVlmNVDpHgUau1Bm~IzWn9hdMY?UQ^Lm^tg__m=n+(dAgd{>gDwuWIEIQ*L zqi>u5?lcOSD#3P_KQ99d7tFm%7*QiYPdHlHPppF}Z+CyM*_SMIeT_ToPCNcE3Hp)u zWp`U>{GS+M-BkP9P~Q4fk5}U-(Sb;N2GM!xwaSoJqQ8wbsd$<6)^;0lV2`43xUgdz zX|(Q;dJCa*cWFf=wK;#Q&AL}`fC7C1e|w?=qWI?wz?<~tY8-Y?fncuPpYd9(#I+Zs zAHZIpVnivy>wc|oLR66bo9D-j(r6MII}DWn ztSK^Cq|O2o(;2tBUvu;`?e(VSL;uaNI}&QKtWVAU0Fjj4vhu4v3mLJ=^S+G<<*l9PEAZY0_}^X?lIaaXrUeL zGJPeC^2x{U^Ioyl)gu#7BJT~x42bUA>l zMoJG6u56Tpcqh(M8YSwb3ddZX6QzOjX@^@KTUrQ?VFT^>FQ3UY8|9&7+ulp4TP9W0xup$#&adraZRf|)E!~!c^86Y6DB^%7$SEYRw$pJ}jzuy`D=7X#V5IP2>N%37*r8DdQyEoULMo;u=sW@% zI4u=pKu4wsWoLq0_^hqF0G}UNB>$ciysGg&T@>UjT`-0mo2aklNtsdlV8M@^fg>3X z_N;o5>=tQSXt%>N*Pg3xuh2ALZ`HR8Tjk}0B?MPu zjf{D3PLrTth3hSRDDiEb@etfy@n|BM3Wx3xb{o-3y!ann+e!+@kb;T%&0E(!{Ak-j z5l)DFLJf!K2V8LO<37``1rq%Acui!nMfQ^q1R&l zoFV{jwVVZNqEMh5_Mbx*qvWnd0G+YFx-CbrzQ4Zt<-edpL?qqZo&gk@fhhmbM&0bE zvg`egGTR=XpuoG~aFEYdHTQvxpUS-_zI6_s2L3bh0cGDCdH>GXz5x*U4VwBxVfmYE zkv+5@L;trH@(0_jf1ih4Ei0=vQqc2XmuU2MpehVVdAjw-$?~7cQ-JzQxGZ5T))%-s zFsKYf*$5lDv*L99M&k5ieHa*Ar0D50_m?l|_+q43_fJP}px3hRpA7PC08kP9$6@CG z@oSd9E+~>&AP|uKLhk8k$a!d{{QFY8iU$~h^c2TBN6d;r9KpW?=gKZ z-W~?JnIiX!e{2H%zYEhjoyu@AV?!nWG=c$u2za0mesIA_GpK3Ea%Ya#Ld&z+%$J_z zKH0eu!-n|yR2L`|VN32(=gCd!L2hteHNPS?iI;rdI>uAV{(L-lM3KA>=B3%DrT_@ZhMw68|EP z9yJW(EUr-oBNHAeUbK~J?kL(ap^}fgt<98eAr2B1lFh2OW;W9YZ{uDzr*#AnG|D+jBjW z8$EZ(O4${ctF({x{_f;tFXNk9s}jbXouWJzm3B22orrXYuxDN_4Rg6g8E|(lbhF5t z$Nyx?_gc#kqD5hjIMKM~Ab%{sw2=bLr>&f~RjR)?d`>>!#S5DJc;3{mF5}3kR;fYQ zbXpUoescPjzTZSm(IFuN*u+{tQTc;Uh-C6nKbYR?_!f$yA5QKP>ZVDZQ(JQ zA#&**dzc<0<2Xf%4cbn}y9VhoE7clW7q;CMxpCtsS*MPb(YIBC-nT5e3P`~nVpM#E zPCL2R^6HzYzXZu0;`x+HHLu2ENzkHZ7tU$NwSJYZP4@&p5&fN+Z9vZKJ~P_)+IL88 zVQmt7z1(Oovuk20t#&%REi11r-t$tl_Kp`x5fxhSu^9i00%{X^%s@Ge7jErhWrg5E zw}=2cC>FRs^*;^LlZdtgEnanpOUqZE+01=`Q`#^qC}-tWTf@mpk~o!cZMSsa;m$L+ zzIYe-iGvCX#Bp`#%N(NNbOg=qT4aR_DnwLdPwme%Fk`fKQdt>%V6>sW;KGbL+{uGAHj zA8^p}a13EWjFrHNt%I31%ocKzzpsK?vmrtFg&FiuWV5dV=;f6CWD7aJQJZu+kxgBCye@F*Zd zkPJ_5+}PM^_;_CrRn?}`rz2XMx&2Fn-T4%{U#irl(3^GuJ)A@L0x?SE=g0xvOt&{Q zXgsc+Q>rvlh$~Ke|GS!NMbuvq3oc&W)y?}oDc;AJo7Utq9-p~N6bEeiQ{;2iN?EDP z!E2cbrS(dG!wH5t-Hhw% zmlnB?pXPjGyG|}1t-q?oZT0D(OtjD%j7N{?I_TFMtOslsna}zeQrok@=$mJJI5S3K z4J{U$VujcG0KtX2Bgr*pu<+`0Q}41f5Qn(u5(1rV26p$~pkzoH+d zcJ`C&Xr%oc;!0Q@kddAH8DE1oQ}8e_Zhm_R~9Dq zqV-ap5Y9y@s%|t*-|YP%U~Ffd0jhebYNRvGPD%F8!g^91(5^qB|6^#51xhkaNr=?w zr(>Vul)BmLH~w=z%f*$tifoPK)Ff%&{YQ1K2n`Z^ZT@3b8*dd1t#_VjzVnCuw|fCI zKi;V5>aSA+E)-bVa)$fw_S`#r1xvKcZiT%lP7bk;7=V#s8+QaOC4S5#9Ub?TRW5GZ zXy}`7zJiVZ>%_*|GPAU%#f z_SzOG)gQscp$}a}&Mg$_>Mf3R}G(R~(*8zQ#cI_M=vcEn&>OuCh!W#OPb<&g^>|fW7h){Q^4G z9apQAi}&4{48pzW*h^Y;#Y#_{??+7(7cCPt!FCda9TvaFka-jl5%G5Y=5%Lj!h&|-a9L5{NX6TQBc*Pntt7(I z%?f9}yOq_NvsJaWAMo`{J{<*0VKI9ezp7Y0slYJ*+xlELfOZk>2>@+w186MTN?o?n zd`O_uPL6Ujgbs?3dF@A^a9 zZ)<*sMiX`U*Noz9l~HX}7$;H^b-0a90;{Pz*5utL*gg=>WEr=y^j8w0jlCW{(X1%_ z^`~e_;VK1liMTGo6XZa$7+gv$GBbH zSMW!cL(_pvRTobFbRhT$v=V@OHokh$OEn%Rc#d#|Hk!P-%ZOuiV~rHb-r+7g;h~}g z4I;ca7(|-rstYh(hBhBN=C0j7fLtEhWX7?r^Q%Q(zCC{I1GH`ve0qr5pd7=$t2cua z=%<8qCp5r7b(UqMcP+0P6D-y)RFEQ#L(hdw^$k2>MQx!6D5LhNy_`guC1}X?W%y;U ze6_NO6t1VCw<@j;x=^@sXuC2b5UgXZN>4!`tQh$zImtp@fQa7g`kD0)lSD17m@$^H zruL%gCDSKQ7T)gV``hxCO&cT7$-mDX%G;{J1n@iH{Kr6VL{gi3M2>~gi!ol^OaNnO zsa(cneRZy@CVfqupvYaBQft7VLoZzmQRGHhMAR-;XWho>rE^Ub_4P)Sr>E_S;TrZ8 zt3&Q{tFx3>IEd;9aA!Q}7SGmvfwkarT~JPx+~qx1Q+}K0zhQKi@=rNx8e9aGOy2~DX#Z{{E&C}*Z|$<7j9E0_WD#no~}#KB$% zodd`6bHww_5jO3T$|IG2k_7zhH1;M~dTQA#d?A3vS(9;0**#JG*E1n_J(;}CEM9Yg zp=V5(u336vBGI8RsZC7%y@FW-3azUQ4Qmf6T(#BmYf%xg(j@*iUX3qg@Iy$kTr(w3}Jh zr(qrClXUwC`%1f@0SMtk$#6;J>hnB~;G>=Kywy{`!J>WqFYToz-Tc@>tTcoB#ehJ{%bKu8JK1Z^}Y-FrHi&jq2^ zljpsR^=R|_0k=mqRDg*dx0L9*Wz|&DNZtOL;I%t$0ggXb`~`R1{gU47SG0H}a>8mT zK*)dbu<`Jcy{2rl))=xeP8M6?y+LRKjxx=(4 zop9%G(dNNF&r3itYVCuELy`VfBsc19cimi~a$^L@SZ2=Yy4>|Su5^~td6=1?+N&W` z(R`aVE;LV=G0Jex6?Cel?Gx7D9y-ElpQYU5K9#j|k!u^CG)7+uSzMzcDvVYJp_DTj7f^5}`{w+Aw}xIgIiSJ4EvuxaR7N3HMi@oZLPqiQ*ifOyUfV zs*OWE91=4W%qF5i_23a*w~2Qxl;@4cFXUnU7}VamxhKZ&mnI%1G|1rZ-U(8mrUak7 z=1DA+iN_hQ%s@+r=*90KU}4IUW&UJ^?PE;sdQ6eg>n3^U#z5WCE~8oju7$np6L`ifntiS`$d#D{<(1ecxa=DGm20!(U825Xs-eEj$ph8_ zMML$`AgW^;oPBX7x3CtX7HR>WHKWAYIE#}7i|o?%iK7e4RaGRfSBJt6#6S-5xB&3L zS8Z(EoiVN<4iiS5*Myi-)E;Tg>nR;vCxVL!r|B7?z4dFzMfD6Z;?;b68BP3Z$vn*& zycU~xk&Y}_uJh&h6(X>-kC6(CL)U=5gM{$w4oY4rdN1(xj|>oUljFLJV==CQDdrGm zA#+@b1GuZ#%1v>7h!oyd$c5Y1c-ti&gWut>>0yP`K@jear!D^G8Bzf7fd+9ez`U;7 z6Iqv%72-7=r8{ev-U5)0bRU5r_*-3CUM>y^5}Z(HbW9*v07xMaV%TDpHw!^0DvJNN z{G{~+9O4fY*K=cLoOJ43Opt>|GY%c|_Wmuuqlp-QRAb~1la8jI#u^fMcmLi|lKN_x zPO70&S#O;0uc0Y{NSaS2TOGJ^v)d*jDJf|lODQgTR{8p+g%DQ&^T%cjlBLuw`WO%6a9Dz5!s6?8q z1~2zo*|{jTO>qY6=~noP9Mu$DQQ z{wyP`t|9=Z52Ld5Szq}~jZsF}v2j}6??8HNx$QsWRDJj8&Lmn=LyUDGMOegE7{Bb` zQA-yFkgCbmv=l_Y5e)B#f35wIrRS0&u2XSDLQhUk?x}Xg$6rV8!S*0h{P#oeT>IDg zKmWDu&$JZSwOsrB#cRr2|Aq3cw=Yw-K7Xn#C!?UBVNbJjtI5f&JziVmMR#5Z7DYTr zZ)4m5%_|#Tu3FlzYJ4~{_pO}3myoSZFntmmMYj#Tc|)Ehd-ndK-yZnbqCZUC$gx92 z=7pNqU7M>{_tP&5Zs@Zg1}u9L-Ze%ZVc!?E)@O{4f|Xu4BN!bYuS{+^bEeVlZuAFD z4UkO+rL+X*KiBKAYnODk?DWx6d+dQz*DoYQVy!Y42%ILFz6u#<_->}S_`{K)#o>In z`_WgO2mzB?#R@N}!K74o+gFY^ONX@F7m=R0H4Fq&#ey@N*!xPjaT$Jlu*xsks!9v4 z1ov`6R3pU_gE7UD14*MU8A~QR?kip&0ctG2pZaZIk8CUK)Z-ybtW<8ApKUDl(Z-Jl zZ}R(TM0jQD=WgpUoj*x3RN0DW@%ip^%T)0#M-Gr43jPcmruxSPryJpSXP8A(3IZB! zdcvpm546FEDx%wPkn}5c??mzu_FoEM2fnO3?le7k|IfW-nYXhsCcnZLHHu!VE@kXm z8==>wpI+R|P(15-{f`RzVD^QAHt&V6jgfsQ;8W}nx6e1r$yg+>_u|s?y9D29^Y{6= zR@!Z@&O1g-uUzRHo-A>^@S?5wG>TBn*C@ww&#lz8&0eLwjMkIBj6SUCB;PYM_6&{W zjh*mdRx_R_#)9Xy9WG$a6yRYu^6$P@A@}uVD7+%=BfXLn*%tjoob=*c_8PlC>}<0X91K=nYu;QKI;ie(@jNjeF_8ZT!0b ztlt?42L$0p*)d=KHSr5b#_cCABe&OFMbH)B&%@Hfi$u+s{6rwqynCYvufsqWo1 zv7hvCm^F=%ifm(yNUEG1bDZBhYBTj(`!KrpU#yF@sz)+C0DL`q{@Y2wWJly$VKLtauG?b95L8Mb7c+5H3u z+N0TU2J1C)=5*!E*Xq+TlLY~3^URw{9gz@=7;B-4cujQ5l3|Da!?4@8d>AdysV|YD z67QMBGt)qA4MbqoaM?9Xx!5|11vXQcoINyobdujUK;D~Thtkr#ls_duOn>I;mu)w` z|9++K2xPweRzI7FLqc-Eex9D!?$}|4?XYP7xm6GEac=I;(W72rBP{s{Hd+O)sZGJz zEQ%z>?et{?^r9HH0m@)yyuJX_5czFnO_a z@ydSWF}T8#XxEGGm>i6%Wyx2zEG^A$#?^0Ex<*0ZjrF^Q)ummoXTxaFR|iNI)M?64 zlUZzgsu5K|sr$^A#qnCdqFuEIC%>L=N8HA%!cfFiSgf9Oi@mL0SUqFJjhqpq^uShl z{bf?p@a3uMyg1Zhh*K1N#~8i9>EUiVKI;~j0m46h&~U18`P7QTxK+@l&LXzDO5ytt z>I<+Ih=ozTWk-b#J-tH0#tU~crr!VaP3Eu(PPyArpaYxkv_eb1c2T?zN?if#OjR$m zZSnjyl#sqlYlE(iyug2e^Svmt^Srm$2~oeFY5SL?jFdmnJvaY0zhhxB(B0P_qRG4|)+=5SwRl z?!qY;EIJf(B@#XyN{vVB~gon%|B*aE35ygSH+=rO<`qO0p8icGWVI0s2=zOp5C3(gnVF+1Qr9 z-!z~ieOKT49=-6wBW3m=$?%GyCHHLc62+{ zaB98v`}};l3f#FV-FOX~2E8(Ju-AY@{7FfrBPwwJ4u&o{R8Co2`$g~}#Vi?UOW?yP=W$Y_1MD7rbo?f@uzF|zjd{5HA%GXTDK(BD? zH}lRuJw!4jprjq`$Iq}ANtup+=!B(zUDL&6?g7H8GiofxIKQnt1uS#K314?Baj?L_ zDyG?-IiouBfIOw!KI&TyYWXw!;TWW`cnS_lwu$pB6ukfC3`qjC6(qEG$~DRsH+r_Y zbXc6Y$NlUp>SFA#JyX?R&v~jUgm7M*w9{A_UeJjbC)Wk4`4Vj79q*{GSG}AwVZV?i zn~`lZ-<7tru-a@0SkT)O@^x8xY37yKQft%kKGRp!mr}|W6L?XoB)-!W7q%_yQg`Ih zGH+g6A%3GeVbd`xVPrGj$R{cg@#~@y`5l@&Uf`JnJ|UizC0S+~bu5gho@cwJc?kzG znuou5N!1^wjbBI;Tx384Yr0)8Jv@IoX#D;H%V*)|; zXG7NZgG`E6|HZ8}%yg{DxgHA^qAnKzL3Sv~CeqmNa8Vr?6ne-Rk!RJhcYrQ;p$(i4 zX7>fjvc!~TBpa+}Pc?!9-`igHOq_D!pW2tCqx)gxNSOFSTg$CBMh!Rgcq6t= ztJ(*Zl;yB$*?D=NlH15vRyh53!4m@uhG)a%&!5ARje-?o+*3YO$Qv$oB662&SV>12 zj{WAw@mOEm9`G)GUndlP*l+Dg+%ThzUCZ~$3ki->?Hljvx)E{-b@D!UJFw4pyp&W_ zs8~36;mI(okAT0XG{Ypt9Uq%=6JfHwypMT1SGpV+cUp_#*0zu>1edtTOarMGRI$mn z?POi6*D#hF$D&CNrTsTFe=AmqrGE09kpn(j`v%@4sle8R^;}5tQSG5aH2jA`MZd1S zJhh&AdFa~W2b`|-^;6jBJ;Bz2jXhs={(_wc>gAg%6(Nx}QGV+TkPS9+g3ih<@AM+% zoLYYQz@<>-${4oKBcwA#YWu%Fb3>j`kY_GnP51B5ke3i09v*Qi4a^DrWGeNA`}pog zb`ra5BayMRw)PoRj!jzu>(ZZw0{@jEtv-EoYEW&G4+J~Fq!Ia z?#x{Qe_3vf?~BP%Y`whH>{0efH%66IFK_gIt@;;nLoZ6HB<}v+0&v1(2j(%jr4Tk& zG@uTz{%v8aPsBP%`9Le9vHt}%L9Vv(e#y$6-hlz=f`##9=E$NY?YZ#HIzs(E_$AnV zKalBsoAcDUW2gRe6%&i|jXYTCa!>9Vu6g>-@)ZZeAd6&CjjhiP^U8ixrW-z~5>|-* zUzELdT$Jq+H~v_lQVL3kf=Eb6Hz?iRDbgKFEwQK|NK5x3-JMH{bS_ADvve(8`@4BO zPn_pHzxSN?KR=otf+ILV+J0O?1q* z*s307^QT+_vH!2Nr2)-Ce~-uFuvcK=`rbnFTef1?;qrhH1aN|xOnUVyXL9DWLq3_n zxOv%#{I84kd>(Wmca&-J1Pch6;0k>6o1|Y6saNF`J#RDuM98XFAnE+OT{c|x{-vy1 z2lXBrYO>uREdzn=H5OfumXMl*giZUa5U!7G|Z$n9GOWA=BeNL)iV1E&FRJ62Z`jl$)$yuh zkQ;=m_=*Uw1T5?ZKiU3MiX!WOFio1K2hF~wx+V4sPWyaTZ$)%K=vkDW$xP05CoTLA z^uuH}TZi8PJSg173pZhj`0*N%7L>1AT{k9UvzIYTO)yvbRn0{hb zZ#L7{y~jr!JbP~Zuy!>1``j{XeQbDIEFvPSFqX?hFC}~#w$!nh6N?~M!1)F`P?txc^Yz%+3cXZfnQ2ACm$M!av+huO{e&>=xXj}(W_X9N$ z<>ClkKgpE{BZk67y?+7hd$b#yE&pdcpa@MAVdz4x>dEc#c=~yvr>Gcf8>}W`%Ln?Cu^)2 zSEC~4-p|SU`%La*)7_#7%&#YTx*HQu32%tTb}D2R%a4j|GOQV>PT)@g?Rt$j8X?|Q z+01>U@V>sMAXF!5)3hMd}|g`^Pc3QHCk7FaJc}#j2Bq$g}KH$iyjn zCSa5);FTwy^68IoB%lNhAhf>yko)5ed&U*tuPvZ&q4~YzVXGdv?{u6W?hG%ypH^dW z0Pl3!e!lAQtYDUsK|ZlTcm%$*eg8$HQ~u480WJ={BuB z*Ry#$m*!|)AW6q2S*{e7&aD=7zZ<&y@Uc0C8_te4SDsKIDHFV!{TU&ljuX1ar9D~R zXB#za?G#zDAsh5T?v~SpRBi~Z_%3xQ&j=Ac{3dratP_24o_gw539n=`U7S(NN3UK< z?&{EaHP@VgBP2XIXhciL*e29;PAoI08@k*g;YXHT)JQ&u+DospA<~CzJJ+X)U0)U3 zHHukTP3;zs4f!xPUOu$5>WDU~c6Gw!lYdPp>MR#BS#{8$HeO?re|)K4j~eXQD6JH_ zz8l+Pa!MMJl%%3rx$0FpckSaZKEoXI-@rw(pc@3gf1vxbrW6v_%A_3^78sprKCN18 znzeZX2QP9jUfXajqEZC7!FI&F@)cBT7(a9dJ{EJI z2b$kBOt=ytHll-Rm$$%;uv^VarU5++u837fr+Sy$j3+c9m&COd)3NvMU}Oz%m-f@> zmckJq-~5&>kH9YSx*qLzMX#oQNt2J5sL6B#sMrxKjHIyagVw2 zfZn#z3%{s-mDjo8RZ*k*)kV9GUB?hy(ElLtA$9u|MCh1;+c&YIV}(0ky{ULsWKEN) zTBk1}_QY|w9$isYHF&g&le*OeC6VIxu#KA95B{9%mi2gz*356Of!pKMEZo72SCCTt zUr|6DZ~@TsR_lKzSy2e_tVI55vh6n$Ww=iSk#%okp9mRz=;l}{F>|J$Ae$5dyhAIh zTEM5nc3g?8hH-r5Gr~BCK2uPc$QfJ!w!O_O)TOqWb-~-P)?1Q#9{G^nj*JPuGS`^L z#NEjBW(p)R$gr6YCtQdV`RTNDtAddi%~hMKUMyM3piGaI96Xz`UA~+dJ0i$tTTevc zbucks<=gt=sD^Z@Hl8b&|9JVf=jnbncYJ*2F%Kx~H|F}wyoi}H+gi!PJO0>)Cyici zp3Or(#i(I6jKKkJMZvjsr^SX5tKljlu9;6!73@bfa72rTm7wCqoISE|yw=MfcT-#F z$pa}VAJ*%9yGAui$Qpw76?4Z=u9#dzH-e6Vfz@+V6Z5~p+mIaeA{kPXr<-$8g(epC z(C>kh)C5Ue&P5h6l((8be^zh1b$=@K*-q0A`B%i0r9XwrRENgQ=N&H&^G2G%XEo8w zjYrQWq4GW;BcjX6iw%pNkJWworUB?P5I6Y>%qUZD{(Ew+q^$e~DXUXBsh~c(L*vRH z0OP4Y*GY{?XAxOBYY7whcz*8J3|t?%U~HNdF*By??K6pJmLM0?hg{DiMGkaL!-X35 zc#fL#^YT=QTw;5$0G5uq=^AYeUjJaMH!i@g$slNBgO~$Dw@OV-W2s?e_tjgb#S4HD zpmkvCz_;*5i6BQxccFYZ06E&p9iMx*A!3iY>7j&1?4*V$SWJw1Rp`8iw||j9U)anH zF@N!-88ScroO)Vp(fexKbwgkcMP5qy-%Rkm7_{Rm_7;q>3&MY=pVi;6Nm0~OI>1H8 z5}kgQP9<~7KibioiDJbrHccS)DWsZWCR%>Dpjh;P0*817Cir3eYZf<$F;Bj=SV>us zcPoMgwT)v=>d_HKSM7akYb9775Fo|$oFdb#HuPCIEgL-pO0sFkXX~-fYqi|@x+w^J zW+k?E6LqkcNXz^ZTaYJPfh6>Kc@GGLv~moZL0pz;n984Tp-?x`EzvcE#Ae!7!6 zoqVR3bN)Mrk@A_zDm|8oQG6-O{d7zJZhebMebW@q6blKEO}tsjb3EGp)`4RXeMe6y z_S;#Jo6jQ(g#@#X<|VYBbNTEzxz7F~88j^DalFIU%Zp=jbU{H+$K+U7)Cd``IzD!pcD!J4#+(p5xkewJ zM4TH*E_*QHLVHI|2J9l|9{|B`V21i z;iTdy=jVpS*h_336#s(vmYP+}m|eafoTu!!=(|^U*gB@LE5999QUaW{^x{i;X}~&g~|je3&%btlC~9QaTh7!_)K)ij(`WGiFF}8J+*br{{M()V7U)<28}rJug{EDyCun2X97s_4}F~VzMiyz zHwTV@#0bQW!2=^es;lO@J<*{rI9|Fn%$e;CgWrFZJ{;gft-?IE_1VeH-?SG*8I}($ z0U=Q6<;o-aYpqXEeE9e4>t_jg315-sXv)|4{+Ak#^A=980(Lq}(+^iDeMraP(qlo$ zjWGI!URTQbTFpEi;|8wZ3}9r(VU8oU2-X>MZEzM z2D6yPfj4=)enrE%z7Emfl18Afih}Hgci6w+7%A~C_^%tT3GfeJo}945lnx-ba8V^F z*MMsSv{4Zu7Zp}VDF4TFt`}4bsF`fj?EK1~C>tE*Yx1xxAFRE)t3Btlfr`q(8vI(O zHaNjILlLs+Bip;~x1|?1=OVxCzpKV+++aFfuDq!>e&``6FYlF*&H%~|4onxmFHUXB zcYjpR6^n@&r6(9(cbTQ+AN86{RdP*#Nn2cOb{?G5y&j$S-~-|pa)SNqK3A&|Bi6)A zz`q8cCTLCYt%Xfp2r(EbkSB1v{7M-w+YoW)y;@KIzyqI_@%Nrx08@mQEjMk~?FB(NV=-O0cMo!9zeOVSyN83^p}@uQl3${&(p2O5>Xc#TsEH}qoa|@a&*sI#w1F*s7AmrhPkrzD^}MFOTW)pQn2lrw5O#E(|bui}*0h=9Uic{4~pS-JQz z?qn+eVW$x-6P?)nBC4a(*}3MbpT{z>SJM?XyH%+4%MM$8u$Sn z50u$0LqPG)Ol(7dfSg-GdjCpvgzpE4{|DV=<@1}x1!VQCi+aANgq*I^cpk22TeicN z8#s1Jj+5nql>cTEfTAYVe@Muq5SV!S+S)p$K;BiexM4M-y{25|H5ftg)j-jF+?Dt9 zFH`}@tq?${zg6a2ooL}9HQQdN_WIZmE$xCic6xyGEP6w+!h?rrVP)5WFo1jp;|Th8 zq-cKtZV4y+EGFi6m8Ij^tlt6_0=i{>uSnc~9tor%f3IBM&_a^M#T4sPI$vXrhwO-> z0bbtLo8mUreJ(%4_f*Py!rrrCPk#lE!L4>pw{F=9o!>_M=WW~4Mqebf8*dR+=-zd_B1#&WaA_m6)da9(4!yv9s# zqqv_|y~}V8PwB98yx=Qk_}An2(O^3~Ev@e_8)Bh6BFrx|b zp3u)QE}+%oWN~I9Uh_n})R3e_cC3>lwuS_TR%gHP>G~j8_x2y8oF^{Nm^Zn83I&rZ zj`oxdEq$Tz>bfwgfCF)E2MBl)p{X_v~18Xo~q(eSCV4I{wL#)#&?>SUyC*)QO4;dlZ_)gt@C9|u7T zzJ|AH`PpEy>4CPEEsT?yge}AvCnvYpT#j;B@*2w#hp{%scmJ?Iq|_U1s7MIlp_5Jp*d;KTzvCG>4=2Rr!BO| z_V6e9Ha*5V<$cyQ3{kYlk zA)W(|@yXeMh(KaMBdzA*QsH%8VreHQDPySR2wGshq`hAex)(`??`aM^ z=$=v^BF@}^%Zq1{_*}8&W6?9CD<_ZO4>%x?Vv~yU4vdYH->Ta_&jYR^SzlAn6g?VK zy0I@j+uFKIX=t&5y7hSb>md&8Y?7mpLR#9Q?*U1kYF9KoHsALOA6xyk03UGr$frC#(c9y)gyDI^bL6=XVQz|c5K4E`O zE#j=d>>4A=1#G}OKcJ>yjl35^8EQzlDT=nwf4yg#ECWn_D7~l=h>uCP=G$EI4N5J2D{KiJI-~x==c$WD z-}A1lfTOK>dF}JT^cVIqfNr;M^u8SP^~g`Ev6Nxam&_GO?X&u77#nGedIK|S_-aJ> z@|;b{fyn}SxH$Gx{?brS5T7D<=%x%aqz3JIRxq=mTHYhVH6xSjk~q_~e+PJFBpMJr z$NEoC$LT0?x?#D#UXMEv(x)&>_5ZWzCnt)wcXj>jp-jH&S!l+vEcKvIv*1_^2B69%s>Z$BeIMS57z*jkTlriKZxK{idi29V65ULm+3BDN4kR=_v{*L zXGu@U&>XtmyEm=tE2J&22V=kC=Mq1*%{@-Fa6#W!d5eAx61g=iX*c})+LfRuN6BJF zGJFw3tffK=w5(;w!GU2v5aRr(4i}K&F@V!w_r6Mz!Ok+j2zl!2!IMX?x1C@-^7jB# z5xD7WnHDvERQ4?c_hL~cJOY~T?5P8;<_406_pE(|oRtiL_Yb$Gg=Z&7G8LgD4ioMp z--b_Q9v&r%Q`gM|q2s6-_Rl)Ds_|j5GECQ8HteCHo2CUNMXqI%wY-i@891Z$k_lgh zes48R#F0y8`w&*9W4{tZ=@~y&gsP2K2G}H=yPtCMY!s~$X-K=?=)aA35m-XJc?C4! z(0#mFdUybNG)IUe-}9c6ti|yzUGAirq3c@UlJ#Hh6I=o1i2l@!dU34fY| zjGKf1Bqmkig6!qsJ)l-(zYNYlVThry`!UBwu!#79?Sq+UZp@kA z2_t7@rAju8%MD2ia+I&F01Yu%kV{)+;{;)kEoLQWa%=KkKO~H7c8WkWHwvnyGF?mh zB{=It9Q1C=X2yAdNf^J^t=S{l3bjq@r6Z&q&^w>WdisZFg+1t;5tC!w-Uwo0Im)1K z5C{D3*UtCluDQ577mLbDT2nc5vRMH2LAB6{gcRak>p{@3jl6DMM^B;okI}XQnARSt zQYcUZHly2_G5B~;w3au?s<(VLQI1g58_Q_N!p=5Ht!gClG6Uav20T0WX5#~>*!pJ3 zndO(4jl6}4SIc@&3-|vW%B}sQqZ0gMP`aH;F?D8`}c`t+7V>n4A`2&5V zI_B3BW?hfONdW5aM>yh#A1)tYf6rsc3pLmzj)a2^30IXZP7dF@e!kv*J^$} zsK~i8+lN1vdL}`e*M8X?A6G^GTW#nf&_X5Y1QcGr@aUdyb2-%saEF7$L)5y6*UCtT zoPf&AuPse^c6EhNQdUYgP41ZyZSXQXs=EPz7s8!bR%U_ps%OV|6K8p<_yO2JpyB%p z4w`I;qtFN;agBPf@ww$$8=xwtXlZ{6=Iqg>Kt{1s%4)_9+fyj^P3v9zJ_C`YKvs+= zMwu!fpe0(s#vUQRlDy3H_2}LwZ6y;74NP!9Oc5%cV_f~SCPMRNj6jjCf2orBM-_G* zgzd(_D1(I_sggx_?OUvs@Ej&~Jpugd3tcezR?`P&$Ep1etb1;J>5rdc_Y0a4nqHP3 z9a5H#26$UDw(EJkQe6B}6tOK_05o!z5S)oU<^F2_ga_QVwts&3yQnHRz_Ut;$3&7a zIjpHB?H;P_Vqg1bZCK$qtl$P=%`jyudR?z2Dshnk6>QeW;2k~>a#XKPivicu#q|tg<4QNo2*7s4Q%p4;q4;M4 zg=}cQd!f@S%|15+?N(ST8FxL++2pQ`IQ-;l*j#+7;@UvBpCdq!`|;ZR0{YZ&JQdc%#Lg#g zz_!L|2fAz9O&?AtZF?s)ite6c&^dQnyR_`A5U*jjV2VmtdMC}KwVoMp;x85ki?f5z z4-IIP#0t8RMYdd_W-GbM$u?xk=Y7D#B~^i=F1dXFu1C0m?neMg6qWVU>1pKA{|psh zukQ+lMIBlLrw*HWO#Mc+S)_E{)CZn`ttAQc#OtYGt-v0$EyLyoJjer_nR@vY1BC1t zT7A&-OJEsz9C{G$dhzh~*S&|5+0_I*jO6^@8TcC3Ov-HiLj4wE$#ohi4qWF}pb^sC zQtWbJi96Zgc5&De+RYwDBCncK*K)|5?+ux$Gdz#{toqv4w%iba$udyTfRLPYwaOo9 zjUgq_ti~HA6!Ec~;dkH`y;l|*%st?HRXec2mybICBK=+o z+7tIyN-RWsqp-eAU#*zxW{;i^;oKZdciav(nI#HGC5dyRnp)l1ecz+tnfKrs;B7g!uc&meSV3$s^GPnY~|_fG47^2b&)+z;mk zJh7iwGloqfee!#GW8$3i@k3J|LAP@F$rF~s9oZGLWyU_P*~P1B|RaW-%L{X-pz z(e^a{6ZB7=eavcXaFWES!^Gc{wodlcj!lWtT;Ug)$)X~lItWM>NKt>4RQ(_P&P3vR zk;?a|9!vv%$c{1+6WHGJ74Usm1ED}Nh&4l{(cAZh2?5tlV^8NPbb{&)ugUK zex?#%Sx3rc{i->I^U1vTRYdV97wTEvy?7e|^Ywt8qdo~r{1sTwb~6yH0}0W?WbEu; zIDJ3<<>7I%+S7mx?e~UKng6yVDfUieIl@~+MS()z)y*NT(%&#k?10ZJ?{b-^@Ji=_ z#x9R4_nl5##96m&m?Y1-wg$8N`AgSPk`?eFa9Ca_AMlI9Cy+VLCzfM=g4VBG=UcYa z>*KV;K6h2R0f}8)ce(#&$)YIR=<1YxL6?uR#Ba&hpwm9>*iN6;H2&&|y00#mPgoV6 z%4>;{60w=@A6t0QHZ5p}7-mt%+vq=;x?_KL`GVfPspPx@ls)2se=k|E#q3>N?w4Td zuDFP4cB^~KClc*D#+V8yEke^gTw;}&W1fkmCi`1heKzAD+Iz5jnMzkA=708|fa7GN z`CX5Wm)^;7shd>IceN7t3Mi(U5=}SO1p~qxA5YiciN0|T6o?AShKY3Jw-pXMKkR6$ zF800N`r{HP3%m9=KAbM?IE^QKiO(i;VN+}7eUCh}_(y&RaY<@xk+FM5Dt{O`a3}!U z2uEyGH1;Dfg(t}FPUsg<$!@W}m!jsgM)3aK79;)&SjV3XNZS^M<8j@*AXlqj7KYBn z1CE#qx~Y^N`v6YI*m7PjO&fV(tv%Jd1z5^Tfha zk84(7!qcI?P&q_sP3TUGteB|<%){Uwd0_sJAd92Z)bD<{67Qs6%$vJa&ZPw7;|TJM zXkX)B5ash;G#-9OGi*eZs ztj`;NZnb)8p~iB$q~VG8#ETVf6my+;5|iZ+gYu=Zk6tYQ13Zi zUmcg|#rO>Et)eYuu2@+P%D&9@z1nsX<6QpRf_yy;EenaPOpwX^py3TyEzb^j9oK9(32$qbaELQH7Z6 zvT3IaPfG#i#OXXCf%wjR=W{rH07`PY4TM-c;5wM&1Mj?6!d;g!fMrUCFkU${Fu+xV zCp=!29BTS#m#u6)nf>r{#sk|UuU6G0NyjB7x0IKtJaR5&$~D^X`uP&VFs`d#WO5hY zH|cumZE1rPs?bfX9Ga>)KAT?PB`t9H!S+CnY|;jMOM#pB8JyY`604=R=IJfFw3Nf{1H}wvA*xgmx<_Ng7KzlcuqX1c#KA z&<^i89oKj7#Ieu}ZJM&1t%>@0?Ti!3QB#uM8%m(E5p@|!GGaHQ7RaI1m*a461nYUE z80zz!eO`-ycBG}lOfj{kwe9LLZUOIv?;SPlBy&fqCZl%@3Meq4X&F_M5NlS_;Ii^I zat2SX2BH&iz7vb;j*t{{5$cyPPxA-dI#@o9 z)LU_RVo5+QH+e6-Zz_n%fTBgVj=SEght5IWDJzs}Fwca6qvA;<3Z4=JJy7tYA|pZ`73@nm26B z_khbzCCMBs`>W#rbsRD%AVs^k&*AcYa{2%-SqN-Lv7KdG>ax=^fyOs3;RF70?^`L! zmTke?)Td$2_bkOnW*?#-Of{HqVdn`(9wr}-nPIYxgu6`atc!&Vg>9*a)w1Z{t?E@x zE-xnS!Ycam5YucgNqh25`;;;1P2Rgz>`43e26_5eeq5Nw<;t&3=WZNOrFVrqB?_r= zvW0B(A|G~0&F2$llZt^IyVrj}H*3i3>?S1An9h?p><&=Ii5M_vK z0RX^|e`W`9Wl##G+JQ@<%Pr;Ub&8fl;Mzn)M4k&l!Ne08nkQ4{E?pO%gHf8XSBtyS!6+RlvWXKlnrYe_j7bc!oHDl(W z%_P}D6k-s#hYd)c_JzTav%_P9?-5b%BdD{@EMd>2nLJZ<=R-yH*Q0@w8{!(j(dh7N zI%deLDbyHB&@EO#oL}5^*O({8H@`XtB5=h%cNBZ}JrfrSI9a=6sfUNs9GN0lt`NRK zVS9$@7HzY`wr=e-TlUyo*odo{Au>?rWT@8TqO__+Bsw$}xfVUl>%1hDuj32b_hOZ; z5TCRP8nw-&>`rT`+(2W}g4i1ckj<8_VmNh!xpgg`vKk7O`X;&| zoUdc#Ugv#-gPZuaKMbvKs05g4s`b!C`wF;i)qDPu5vsdCDknF)A|CdHa(w%_AVRZS zWD>_Rw6HFw9z+sU*&m>)9$q)BLOgvw^a>bExPb;BZd>|%aCz|6IWRtpC~izb~T64rZHH)i&Okonc7RrOPO8@t*UF(v}b;$m#TXLa~#219OojQyoDmSLWBO(`>ZJJXTQ z?=$dv>kNoYF9DA1y;T4impLLVNkU57td3dO>KldKdUIi2_uj5{hrYB4N8QA_Y23az zT1S6{$H*4$<28&3%aLdEue(cJFx&EiVJ z_PlVdwO4Ej!^#TE(kGhb5{zDKO2#3`u`tfO37F&bkPSIC*-zJHx$5N7e~Jd=@v5yM)Wrnf3_OqV3s!prqM`e%??4fwwhW*lMRzFw9jk< zOE(G;g?Ldr2#kp!UkCW|qvS4FXBFRTl$#b$DhDU8UhA+y#)>d~s$26EqQCH)IkbLYGK;=ere#H6Bw4aKVef@6{Y4<|xDx zO>s+hM%pxOeg1TRo`$TfxU>?pfOhfueFY1z&t*j)u2pLojQOAC_jxGM6(TF zv`Mb~Y?H|Np(9AHP#_-iDo2P+d>NRF5g+cZMDAH`UxrJE*-_Z3S`}{^q!<=JT@)16 z@S`^i0P#dYVc;?Qe@Mq%ak1|vT)9Dd`E{;nbb7%1BO4}Lu@^f%4{v*Z{+%f46h^<9VM7PXd7IznZ>7e=185Qxbk=3H+Z;)d zU;JXE?l60{=3f!^;l2JPRb6!HP}g;?$HJWzeg~I7lj`;oYvplo)ui{@*2KJz(+pNM z_GHPF?{m4z?ev4bHcd$pK#^S6g5O! zorgiPK*^-QWJ37Libb|Se6m5;Lm*N$2>O7D1qeV@ppk3hHv>d1t+HSygJ>ZF*Tvn* z&zC)xqdYQi*n+ikL1^|DMXVg1!#jNWLRUe*h-3u$0Rf;^}^lS}pOH3mM@a+7$N~Cf|nNg-sd4K$Rr1+ z(Wa&oSZSp00KVtP!s9Tamxq}Y)!uE3+)!w8_;q|pZiBCk4aW&xlQyA$xYc1BlZ1$K=HF7S}a_ z=`54>^D0OGyz6Hji)HA&PCYht-NRU#4jeO z;6k3PBdS0Tj-{8%_Rx050sGI-Cbeo2=jzoO%2 z`d5g1Q>kZVjY7nVcdtkb`C9d{4zcuvaV;v4JS@!}#-1~Y>VL}RFf#g{!>TGkrif*T zA$eAxBVH83hds~vOU4AeKHFcy$mG*}iJy`g*+SaOyv5LK1_2B&mWDOm zk8GYozcHW)x(H@0B=^>gEgltU3YMbw`B!*&Q&~0!*c#@LP9%V#?7Dm`y-uAcXWN$R z6>x>>T*#T*<3XlH#a90>qE`+?z#^qwUKLI2`r?%9w3FhH$U%GD5#`5G`I&eRVZF3$ zSSmYvxhpufb9ydXTy`OMSAb8!1=!wHRQP3kqYzCoeD;;c)R*UjXi-k`JD0SluRxh)FiFw782PO#Uo0xFHZ!&6+S=S`|BiRs48;PuJunhl*2Cw_R!{ z(jbs;0V~}IC>sJE=TD=eNGwM%(}E!_$G9z(Dj7c-(LuSGhua}GG`JI5wi;J^2$c;c zmuR(R@5jo-#>UMZ=`y8j?dCw}-3K}lq`@-hzjh~#n{Pq7Ssno2-) zc|AUr!0woD9;bEfh-pUgfa z&E4dz7k}}7m*|vlVj9BE$M4rf(;`Zb#Yvz|sz1*E@gqphD(L)}D8Msn=2MdmeQQDi zzSF71?sOR1FFNM;(GGFH15fLR+Yq&~^HDt$KPwux^!A6Ub5tMHvk5{bkG@?KhZ_oq zU#|}|dc6=6FB?TQTG{cC%jEp-f5pV98~ZbDd%d`ey6t7zsFsL*5b_#f8#3!CeM~&* za=m`C-Har@>`8YZ9pnK>5Ah(^!?`rTz!Ogjc>RrK3n!k!SZ+N|OKpXoN0i!H{{0^K-vRaq0^tgTz>8R z>{*_U&QYkBW9#s`H%ffcFle;&2^~Qf23dgC!KGF>;)4FGHiZ_LiNG89(uU46}qa7BzkP|d<@J=*jIY{ zWs+pwV+&HcfX9Ugx*4z}KFXdWZ#+LDh2`l7GrqV1Ae!nzbXWN|P?>w;MCFY}u0)gk zt6}$iZ6_m09-dyb_(o1vF;#H$Kj!lXJOj{%^)KofFTV?PcFSV@;6T_np!>_Sn0PE! z^K`p9(>8kGR-=~$LK~BGeer9uULMs6Aw|I70bk$(5ca=!xKN3J1v$f`5ROJKGVd9w zXV}fnZgVx*QP>=KzB#=&FucABYl(~CEleQ;)|apX^Bl#O2#ZKLZ$fX;wH+QWOZaB8 z!y^hN7yOGi)s%wv+!NUSWRfQEb0Nxwep_wMukXv#Wth`<;M27(jqy2Q6-v3m-|SjU zegBV@L?C{iMEtBdw-WG+m&_=BMm^J4p!rnpK=*u`%(jW1q5!pp$rg^8#3zu|4-HWV zlN0B!o)Q?DW(agShr~AlLt+bmPMY`!s4c^Kx$V}zahnz3Q4h$~cRrw=T!A@-YHN{w zDpg!A(kEj7S-leA_kS$oE5ebiBXKKUQtZ644D*B5ZK{N2*tDpuL%%3}YNA3f?%E(N zoTn=&z<78!EZ{aUpYHh=^#Sz@HWi&9X(3ZqN|Rol+$6JqEOc3%+8660-6Wu+8G9$f@b%=#TFTAl7klr}4ylxB@=?v-`jh zcl$thXW7UsuGEp(W_9{Gp)`9BX#E4y)1-jdqRz2ArcuwI1o%et$AjtnH>qzh=E~W4 z934DU*F&#v$X>4Fb$DR!Ff^zB3mSNKCj#Wp)xZ`RNzBM9;*o~vcUw6-LpG)Imt%xv zLJh+b>EP(}TzjPNUou--3_PgP=|=ATS!!%~F}VWvsD|(PG{064oPIvO!ESd9uINU7 z)IyNfzb{BW4-LTi@)__2e1G=^B<0Iz-wTA8?WO_0;ry~!FvSwwABfefn$eg}!gagZK9RoAe^|2ig2`@-{6 z^0^{#kMV}M9mXQ|k=|4*;I|0X8cG>Z~XZ`A@2lfm^H zN*0ri$YLvL90t5h7vil+9UULod4P_m#S5Uu-%eYADVWKMcGH`dustwb>#^g!|Q>%pQ2pWAJk}g(Dls`glw5 z?9UOS)0>xvXL7!O3$5lg=@RY+nI2GW%NKbc0>4S+$D#P6Ym8qOIA5+cSAG-^{Yu}z zbpOc4e$(7H!9M;HA}{%`P2K4i^t3m?hCm86Z~EP`IHC|nBH(^af#3T8fr*Q1C$QF; zZ+t|K30ktgNFu4-zvKJw>ZFAewetd|><+O1hvygJuwtyw7A`k~rSYRc!Ua@njeu@d zHd(iLKrru}+dr$T&99zxlyuO+iSqpqJU9L#eF5iaNC}AGS1J#H7Wp59iYG9Vbo0|B z!yi4yT_9MOMojEvO}*3jQWPS11n?8ie;sOJaR2LYpiv-Yp#^KYB;zpVW4%|t*-u6^U>|DU$zrtws`v-969>wnSnUoP!03;$n4{tNm6 z{j1+tmM;Nd5%HR|@ND4v++TC){IbBKULFAJAlw9ucn#=(_$!F{zl(<)mzP(fuG*Rm zi?$MMUs4bX^4LuYI}2m{p151k+`jGMAU##&-EU4;XeDB4%H%>Wt;`dy@hQ)=&QPcw zXdN=mc%sfZKfhpfdbnAsdHB;RjtiwUeKJ7hcD<5$x^a;b9ux21oh9Fb^b_xI{*foX z6(G}|7be)D0%vM(!0GLvQV{g1*6{wqScgMdT+qMAZ+c^300jI6NkACl7!GO9U8FCV zs>Lg=-^V9+-|7mw`jlO|m8_(sA(HRU{3bKXS+=%G>pRvss=*XO0_ZJYT9|b%oi&;~q3zP9&3*A;l9djs$kmI>c`)w?)#de)tMS^40$yGJd~^1nEWVMaoASe z2zhB+bH+IhLCk2@EK_d<@bNF!#7=)_^4j-Lannww8k=!L&O0nOv97)}aySt>;D*eA z?q^mSg~8qS_$WF*zn^t^-DasPqb$nl=R0=CI}=SCZgdQ6<{ zfx2Hi+qz_mnJJD!HP^qO>P=`&X9QeJ?l7GpT!q5M1KtG#$5gnBu}~@cnJsLosJZ`0 zGyG$5-Rf*{|7Pm#hKwq)K1G5q@(s=4m{*l!u+7Gc{i|9=zmpb10ONtP@mDeq+@67? z^76%LJS8Y<+Q%0WdPA|!rORfN6|pdN+(r~i&7-Fr@-$ya`3L1;Js&W#(%7on(m2Et zg%}N0h19Kt@-a{N$6PMe62*C)=z1O(?_4`P9)r-bJE3q5ci#)N1M$$7(8rt3ub&_RKD!wwmd;hy|D&Z{C*cJ$aKA~XEt^F6$$(uzHK4Kt0{*Fk+I9_X%?N$eAE|# z2Xxw@IS(C+8NJQM`;LB&jhA?ZEof#3p|`@m1gCm=cO&OSz_#1H@h9Kk)ir8cA$sOK zD5j1(3`k$`eNm(EPVEmH5Ol=r(%JQT%{`@dzSv|v5s+AM?P{K)V>b7hOT9ijMtnLk z?o(kM&SGX}&v3|2D)OKRhV$&m7`kvJn+@2wc!q3UFC~BgT0Tpy2XhlAy=@%^ko_dGj1+GvHJ%wfZ_Q{+)M6rq+S4zo zOM^K42Y02jfI{#;LxEB}Se&oSWyH_D%5c2nujcUK8pfnIvgOThe>bHWDqbgz3@gFcD+6RDJS}+8v zGth)=r?a}{gi7rnI|kDGlVyKPyJaPKrc5Rhqb0)^Z^j+k%Zj>8q!^af8cAtd<-M%2 zsLOkn?QJkb4P=*(_~e(LE>+d-5M6pbdVbxEFj$b)Dm>SFkc`gSeuOGNnKe+>1%KK# z*oU~Aooqp?cei_;;JrJ&TTb~a4bAr-31gqdh@mYvNC@lSmU{Mp`Rksz+inBhH(D9+ zuGdrOZqP2HiLx`*tFFM_yui*&&;GNdouc4gRV7STY@VBC%76@vS6qCXz8FYnophKP6o4s*DIy1x(6Pqwx5nW2XIVC_$1?UVlYjI|ZH z_6Uw=XO8_wXjABH3qv3j<8YG~m}T9~A?>H%I*#)L>G_?P3H^W-MP;6R!Vb~?6aIIPKgdo`F1ec-JiFesK{ zW*1A33-__pc1hLhVt-P0GyX!SFrU8gM==-Ff{2GiN!v%!-707pMJe;auwc?m8*Hx8{ z;4rwaTA98DSL2WqANgTY5J3t{i|e1OAbMl##Dxg2iTC+k0ubESNV_^l4Gxo4-7ya#D5d>M2{t&Wqs79f1gH4QJTBFa3`@ z4xs5%Yh5q2#CG05a+f4WUX9zWJ62w7$nhDu>z7IKQ*eJlJYwG>3v%0eya;xzG3_a` zHCvE_a?%u)6jBJUGUzgKP4h}ZJzbKlr(8wx3w0IvPiXh~D@RP`oOr4SO4&@Odraf$ zJn94$Ebg)!K}{!e>PjKp|6=4Bi27GS~DzG zbL7?35fq-fd(!T)Wa8~!WL2kH+O!B(cm!W!OaG>ub;T-FFErX;QPwSoFslQEz|izRHECC-XhpCzhemx z9*RN1XCRxzAW;^iJ4HRYwMc*FydM}OW66UO_dGvxE!r-rYXy}&ht@p@zN8`Q=SEJp z2wv2KIn=@Ww8v<3EY006<4aA|c=T-KTO=xYZhPrgV}$GnAi{wYF=b_2)8$;S<_6v? z;p?rR9Gre%ey&pw(sM76yL70X<~KJ#^;jF{kI8q6R9gg>j7;5cyc+b~b71ov7FZ=; zId<76tQG$M*n9JEDEs$s++AZ zVVDst*GbV|m?g?>jNt}`%>y3#Y$o~cXELF+C3Ux*TZ#E5El z;yGen>Cr{d(CoHDrh4r2!3E6|3!Hs=mCPAUatAOgm7;wdw!hW(;iwXh=xa0+a(jIB z?Kx2NlUsD_7HIMwLfQu+iTj7r#)Op1Y)YOZQDgC+8#Owa|8j?we0*A1q}9Xo?rI$qLrZ z7dI6H>YioPSUS<;3f)dhdorUGI@x(V*Fn?vvg-V&BJ9k<7~3GBd< z=v-?g(?xoO9W4!fP8ELki4E8iveZ>VM$%*bALc~`Bz z#ELFx9}@yOpAS88cAeQ-KJ|b|&TztOuo&m}5snyxO!d0YgmUy&-;0)j*H_H_C%mJk zRH-7{=Ql!CJL|ZH_JkUUzHf?#>l}{a5g36W6@+x{RL0ds7}|}L6t*yKmb0ZJrz+U* zu@6WLyUL68^~S}abK$IcwyN_={+G13QsRv8g07Nn=l+8PWKFL$aUaRwd3zWWT@YcZ zx>zdd7^0*Ou%);mE7EV$It0vej*aCQNlB`o(dj(=soQ^}C^;IF?BIty9Kkupzcyq) zt~IoWFqY?~BR_KBapyaj1xufgPj2@jNV|n`_nQ8P$D&Y|p825r*d5wF*7e?%o+FQ1 z814HAX(I{ucGxug#DkWH%)g{v^$|O5(44Q@UF&^GGF}4+HP7UtITxibwTu?vVyRvza4yBg_Z#8eVh_ zDmtK>avyT)z}ElJ+Dxe{4GIC%AGnJ8KAP|FB)ladX)IE~N>GZ>I4K}BjtYvUmR1P9 z1+UL}3fC})dM#w0^Hj;Z^ya+1h1~XM9U~Pg3I`o6v8E{9I2`pb@pNV7hM-*p_p0hb zZM}2k+IAvKf^y@MN64n}(ECIhWDUjc8xB&ycG(Xn&x8*@ zOX|4dmTMa=D1?!XIQ7Mts-;UvIaUs^Eh<>>+y_!s3{?uy&&h!48V`>_9bUgR{(*qW z(9d2)&Yz!+PP^JDnBx*e;@!FTlH9C3+lT+AJ^W^7ulm!Yk{>2Z>&kOC?fThwB#mN0 z1-*jP7dD+wny4lTtJtMOsNWT*u1S)R8lq({hF}}tF(C^Mb72B{N!W+4dnB@kRGQ$qz z^1PQ3xP}c#$UJii2?Y&}%<1GfQCgRGjP_I&T485n8KHD22WCFTi=&3NuIfYub|w(} z8aIiE(Z&{+pL}TYI|``Q&eje?*z}D7+dy`G#l4@Rgrvc94v*xs%X$`p=91o!s;iAc z7XikhywR5w0`kzzci3xWdaA|GB4@}wtIuLkMmNVFKD1WGHzmAt=dEcc*T^t{IyKMn;8(Ra}5>#xjO}=8+QkO71b@ zSb%ZxTiz7#G7s;7S4g&IBr{*=J+?{krjOKV1JcIiPPbQxsU{zUv3+&Qghs-hv6k>JUb%HM`XXt<*u!m#p)GrNUtw_VuvjQB`N_UIs%SlnK$qBJ_~u1*43&AC@*X;XN`jr@Vju1QOCel4Qrh zZacE3-H_^ZQp)&eBxi=gW@8!`c1E^aMJG1lMz=()HdItQay6ikNjWu2fGx$Ij$MB5 z>D%!x0YvnCcy!YyB$biE)~7Vd>E%ewnYYc0gYTAj_m#WOo=Y}GyM1hWRz6iqh5V+> zK$76t7e4HxAItmb5!2)8bF(h^vjzfEbkmi-ym_gP8H|$ZFJrvnuZ2HzKv@jBKuhCPYjPECJRk$acVcjD=oWW+>-i8Fc8g$2=u*-wnG`8Njpq=<*4}3CS1@9(fc`*CpC1CntxHn%L9nlc5ST9d^>; zYw3U=Yz@4Mrfq~@hmh~Cq|_TChZeKPAd|_HAQnYH8V3;MJ+=tB@2OQb&3n5(+4uvO zRAhrJkl%mwCr5HMuQB);=v81k&uM&LlLs|_31xK)dJ+3io=g#pcORbQ4TEPd0D z)_OSlhW5l}@ykP7ewa?jl&ah33ad=Wj6~6fyJTa-$@^_E^e51=HYaH+aOAipYYplAFy7ja;JYm zA4#O0Tm)4EhPBLT#LhqT5WDnkoe1TF@iqU(KkF)VR7ATAK~4@U_m~^ z!9~#G?7sSf2u2iWsYL{O>?5&Dw zB9Yfqf)RGJ`{s=;eIH}M%$K{w0u6(~^~ogw*DL@pH|q*QV`MACr}Ek#K9(0F*0ZVI z`={)!%(jh#;1op(D#1T{k`P%AAyzkWTK?qE;AhgRQx3Oom zpa+g9Gq!t>)Jj_E76Rj*c73!zsdV5Q=7ON_M5PO~A{_7tEno0fzDIrE)Gb}7zk2!d zTla;k4e5#aOj59+Yq#xqsDr6VZp|Uk!(dL7sq+MW3)0){+IYy<0l*m`gtA(Rqu6)` z8Rqh^vYB&D(9OZF3|-!EGEWzubOD{*K*9{e(VIleo3)sJ%8qwy)57)-#bf)`@Qcec zM6$hq>jQm!73;%mNY}i<{KU27-ugWD6SQHCy=--H&QD762n*c;ZTWoZTbPz>K2LQf z$L%m8TYCO`6WAw!U0OcAD50YFlUrpt7Zyv6d6)7%bl;sW+g<#T?bJ6H&BtdZHXafX zLlp@C{(y88aimRlG5qr(gnrMfAcb+1VGK1ULK(Q@nQy3D*aY4l(f?lY|7%*!RR+Ts z=C)}yv}#%Qi*0&kN#`3Wb3>clW#d*M5f7@9uX2*GR5U>zi{*n#-{_t#tMZ1Y-4u_mJ;4u;2 zO;8-*RR4R!@FZ&4_q*X}&kCP**G7i*CNJ6zkb8OPy;08*9k$oUCO=`&mw@!-51B*R zYl}@y&580Gcg}WI#wha%27r_+y#2T)G2Ew!Vktt^L}su9spn+KR10)2k~vusOvwOZ z!NY$M&q~BCTS@Hjj6Ks6M7;ZlPbnwJa93(R?xuPp%U2l)=mdVq>lj@J5j&jFzv6fb z(L=-omKqH#Ea^U$ub)WfC%F{f$RGSFdtLu${bm!s&c^T#mS_I%-{vdf90)P z=!rhH968u3$|sx=$E&#wd2%nuA@Ac*-Qn1R<|uw zy6!hl{XZDmz0EB=oU$CE6-H^|?%_LoSs#>aQaFyfK}o2xZjj`dOVTYh+JXw_&te%l z8RlkoA0h}eUk#mVvZH#_dLdRTvGOl6f!B{imMKCgBP$L(m$6*`H$urL< zSD#r3Lhd7=_5YQuTG2(&1j6`RM4Xu~7lQG-UIQGmGS2&DD^{N0Vl0Ts%Vxpnf!yEH z*?;;%vMGyAg;iIVI%)O=GkZ9fcmK(P57`3bDGwdl!nOa#kkbsuy{uM}h$jd<9B4@r zZ!mU64@cx>vuIrU7Cm;zYF6cU`uy3yU}as3V8OlVi*Y~1|IPpcL#}B7tJ7N0 zjX5`92P2J>D$$p}q4OWX-BDFUx%S}rr2U)_vy2hEpf27g1Rz?NJWt+RrF^Bug6iQr z{_oICHwE}|!1N95Fe^It&8!`ew~78&w7UH~h?w<`>wN0=>`{{@c2R6`!33(z>d#l< z`}wct?}}$DIN1J$484nXV9ZPwj^`DfbxDU#9G&~L(KMYIjKrGU+HZw-B$xFnUpx4C zMG=u3R$!%m+2=l4T;17@Z-*D<8&}m4(I2N~P=9U}z6I%41cKs!<9@3m@ZDWM zzpH5>`c-7-JsjIHA!85QwbLyRcA0^MY%Ix_4GhUIdhIG-y<+zp0J*kJrD#%@pJs22 zJLYYk_%8v4v@sr8T%D(QD9Z4Ms#G@l7GAgn27Z^16}0Lp)Kt%5PgPB@gOUC+JKBoi zKE1Y*(;ob+=JenGg8Y4=1X(GCOt6+T1^mfEW*aj?`uKHwG20_Ch%Y57_TcFwtmLb% zH=kHpjc{BbIWK~FEz*nO5#Scaqfr054+GFLEnGmzbzlYkHDu1j*33r`fOq`ksN9F0 zX|86o92NI}CD)=khk?x#B3zMA>Mq2UXUo4u44{gu8wTN`BOEQ@E2omes>BeDrebc$ z+}zHyAi4*YBLszr*mJ}CAlN;BVW-T*sxr2Gsv45iDQ>&tSdI3g@$#W@Ikn#6C`#~n z$TfzXXk+PFA3q1rTds+;utSdP%?;1a@=h~fUD3X-v>Q-dP5TJkAI;hI*ZHX%>PN03 zIf`S<;q5B>?XqoUqYk*XZz&HwNU)mHYzOng+gtQG>U+)KsmsnzJ`b5$>M666^PE|o zTt^z%%?uYRbqN1c4Vi`1tGHPq4|96~N`% zZ(KU!7;dRv@R*kW?jAo1Sh~xI=;}?YQoEV(+d1JcMwtQXQHQ=6%QyZ0T%nb0ex0Q-N&hUy#|`#eJ9CQ`KOH(0ov_Ix+ar6AFzk}*r!+Pv)uui^PjC!^KrV1n#WEaNxxQ^GcSiA2Ii$S zX1d|jffE4c>TV?cZq^*KvmyR& z5x(k~m4&zb;sH!7m3KGzpMk*YGn6A<1-fls#z*>roU6NeGzi7Izux~*zxrssiAjEZ z1nguYwV|&F5nhdXoGztOtKdF&>I=uTUl1qgwgEnPY>@doLH$kS>&BL@QgjpQ&;1go zrouh!5diIWMbu)NtmxpBpEgpG9~lfDvGuq&8m$vQWgyAcHN5f|Na}^}g_+ z7w;3?FP?D{=cxVesM=Wi>fA%+j??v~BUZg0(qh+odpB%H;=2?_r6ADv%ug{Lb9IIM zqD`mteX@e={AYFMJ`{=TwnBF=aO7`X`BS?3gnpd3wjEhO#b!Xu1?_!TBX{&+8s+}W z;Gg!>ne!`kOCsZNi^3QJLdXt}*}lZi(}t!$D=|ADDKX9#SotAJ~O|av|cympbn5Fi_ylG&N z(lC$3lBw}`^6lk-JXd)A-bja;|FLT>gBmF$mxtfcXaC{LS=b?nO{ zOJNRZ8&p+&o*(~WLqIJexbPQ*?J>ubZ%SSpJygb@mQ9p+;f0#qU(-7tf}4S=F8+bi z>b18DRPefq7fU0ruLYvqNq#l6goNeUH!rd8RP~t>6Q8_HrKkfE znNwP|cD->T(H8hc2K2^**iqtohEl7dZ1;V0nG-&G$9%nLpy4SLb2Sx*ChVP9ic!lV zazuEH<S<h3w70N&@?nt?Rw;4^@Tkf<~5+v^S zqMe*SDbmOG(P1mR*75$nlh4W?Xn9_7U~X-t3uWLSuF@&zcB&O0|3yCgFuLoJn`C7MOKq{>u*i7< zvJNh%Ti^tm-TnB(ezVc`h=M)n7sj&9jTM)8VwkIZJBs0k?tn z&ksZ?al@sCWsc3Jj73Rx*Su=4@$H?KbNFO;f~g{7!?Vm)*%QJu>L(Zq4U{Dp81RrZc!D=lcA14feDvUbHeJ!1@ z2r~3&dGm+Sk|yPzsS)s~g(LqlKzIwTIXOPzLJvCz!R~36Kfiihy6jOdRXVerB9-Qj zb(9`5jQR`W*-1qM-u@hED8I7L$w#`!8a(njY6l&A6g+Ncx@gs^de~%$_G9X5|5(yh zBKklV-ftU*^q#C&Xg?*d*SyfgdROgQ`eo?d(Lbn#2V4iURwprCdMD}g3K@MFL*%eP zWyMS*Q^}0=*9gUFWfu^5VtoR2sL}GFwsi2agX@F_1ve|qG<$DR5u;mX3|8(y z`suZ}<(^~N<7!+A)J_dflqz>X`3327Co(WR|LZ>XckG&Vtd$JqZO?EHR0-hnf9Yth zJ}!zWw?^`qS$4YYEWl?=d3A34ci}jFJ^wK~dO-##Jh9$G2#Xf>izg^ux<7si>KOrTfqX9=7WUrHmon zUshbL$a4|V|84@WIx*!$BdJoWyqORF3s)Q$a{2il?E>hSY%=Ym?42QCNy(8f23%CD ztJ;4k+3pnY<`&Kq9An_8U&{={jcP+_?{Se@9wx6Mf()yi2Wznbl@wAT8w{aK$Ob7B zRAdWw*<{^X*jrIPq(Xjp?iw{``F`57;aW;zIR>xi=<|TpfiRQvxV#=_VueRw4!I9_ zFTGGh5^d$}Hf$Rb$QClWJH(DwCJl(FoSA)KExtsX+CtT(=Af`$orMIi_OxAYU_GLM zU+#|}gn_J-&P06~b5W!uypyL$sO{yFriN9g?mSR{>PgHiduEvNw`Se*I7MFA<;8R` zfh;Jh8$YL|UaMDXf5grgnj79NxgD(Y)$C(HUJ69j!+Ek#VO5iAJ@D?s$Vi;CPiVRg z%TRXfa>7kc(77wF>RB}OR_5gw*@op^)rFY^Esu~A< z&=xqlBX+N=K_!+fZLDB9xRCsD5$1ZeJT@ZKY%SMzXZL6t{#@dX3`MA_NAYuAKiTJo z`s7HHGuZZ(v16*YpCTvkSU=Rk(o4cFciWBO$1kb{xorr>Y^gweu4)b0=pB&=Zz?z7 zSDtIatoB^Uro4ago?;#m$T1z)T9jB%{8nPvC%p)|PugNh-^S_U*G>ESLiCSm)q2wk z-NWPs8jmxr&1fkv4W939AilVTCnvNX4pu4 zcdS$cs1fm7W&NSxFvBXZlOB(gYPdDp$p~M_K;T8!5-VIkjWHFcmCx`FmFaZy^q;~- zNa#!p>0|Me`umqCbuyw063W`d;)6D0Ri};hhAd~6^ z`?J!gmPPu6Dbm&{PL?qrwLs8a7go@FIJh2_Vonh<^$vT<3mU&=48ojD&eS;AzV@Eq zU2Cj9G5SXlaRXT`pIin&wbY+-lJRu%AL0Au5t@_Ss(g1YRO~P zhYA)H(-JQv_5~iVk~eFOlhSGJE^%(F@(}(Clk>>;ofwKGfDN?+;Q>kcrR%z3oV+dch`Xau|=zFI($Rx2+p6@EisnGT-}VeDb(GP^sXo-39Pfh&;9Ut z%V1uHlzuco!2o68=M`fVei+QW{~8(Hg+0^gw3Om_kM5ht>?X3@nRxh6Ri?<%D=PgAUF3sP#g z?N(j9`G6MmwwW=^l%3q*d6dwsxylfFfOmWZO(n~(m5&ukx1$k}6R+aP1<6A|5|8&1vLyzHtVy@tMsxpmy*h^6HmVWhW8Ak4?z z`&`lW`uv%iXV1`uV0E?G@&1$0hDg*0wvY&?gk?ozFBbzK0e0>!GiGn!GfP9 z0cqJx-FxLiPD&?^9sz@LkGq-V*K7VF4Ln=#hZqegg=HQ>Y}qO>9x{6##QtY~Q)^}K zxYnOQdX{IPzq;TuwKP1Ehrs_xp)l$rs??SHZOzqPxY*wbVnY0!*_NG$fNvY zC*e1HPdTIx$k5ylbUdyyoc!>majJ&H!VQuy7gwzn+g-YQ=OA$A{C}X6PQbnL+QkIt z1!UTT0#_Wih}BL^mUyg1cWG~Me~?;R@9@cXrE5E1$9BLp|F$UcRtGpTf7(1=JjX@b zWkiIXhr?%Hg!>a6LVTx{vKjD)5@R=x%y+w?#zBYvPuw0Ar{e8Sv30?96&DYL=O}JM zPCEIMd>R6zP(#*JVt_j`S|O92sg?fS#Y0O*Dc&!Wq&xzZPC|9D<=CLXPs-%PC|a2v zVR818`?kL8{S3NgHklG?0=md?=wxkshNK3oJ6Yv(m&VS#sq14(R3dX7L|_(CaZQ#) z=y;V}C)=#9Tiy@28}OE*(}FLJM#+BMg!AsDVDHHIQ&Y10I6+=W+G?0wsCqV6qSAFf zmKQXN(Y_mr&3@2#qkqr|M99`5GxLHISR2{ZEi5>591vUDdsbrejc<&Gz>jY7nUgjR)kX6cr zP22l?wXxgco7+=DCTg5Nm1Db3T1xLCE7Apr<@z0rG9&O+_7+3O-AoJWBPG77v@j;4 zesCiI$ODS$?43i15~c4dRVZ;fbm|i6%f;c^H&@^iK?WpDL?+6Al6$LhYKx&geDTBH zl!4m^6K#AYf`A>0c@;ht4rM``)&`CU6suy!cn5Bsel(vvG5zW+(`9>M%e_BU7nV;2eWh{~HuA7BsCzYuitZ=E`1nG<6>%=z4v( zaxLb9CM6giJT3De^ z<2Z{hGCygIw&*8Df~SFns;AQ4oW*Vz!;wW__mA>lHr?7sIJ{=V3czYnrCm9)zW^TA z|7-}cx84+* z-f#YmDQvUl9o`%*heVCV%8$RxF42b^kNbwne2K)KARG6l>CRDuYrz{y&ukR^k9X3a z3p0VM7E>d!qg#2BkoWLVmi8E$dQ*2$5Ly-hZj!x?pvuc1GBoQ&n^JVfFXekW|uR_6VQ#AxTK=l(<} zT4bL7!s=@#<@Fmt_>8%d%+Bk;N(a&f@raq#p#JoobJUiJ>=RZWb1+VU0DYgP$%o4H zMj9q==%!3#oL`!nLQ@o9Z!p0gU$%nK$aM-4yxeFwvcuGEWJfEB6pooL< zlH9_0WBYhP2}>K-ey%B4lSDFl@-^I;fbON+q&lgnbLpMk<9KA=wGzZZP3$N4+r{+CMs#S&1e z^;a?`^|_XNwF-t*t0>cupJJ)B z0eBF>NR^0N7t=j$=g@05rC@5=?>|K6edNXU1P0e5_fv6Gol#u5*ilTAiNCSu(UPqk zTtcCTP52vYy`e|*OVlx-4Qa36=g|~%r2?-`Kgn`o4eFb^)|OmamX)Raw*5>qv$5Ov zLZP~+JnrB3arkaHpVkF_=$%bIOG#F?{tb3&dHxO_}V z3WMTddjq#|Fa};-_S7csh(!6CdYJ8%CUra+Q;ocKxr}zKvZ;=NE-xe*EDt7`Q{rAU z-}{z}{Z>i`^_}hvNUV@_-S_5I;W?AXgE_*YOfUndvX_!Ea4GZ}Oj9i`ALExDW^2&& zBI%bgtV!)^0~+8Ztz&U;s}XF0*sYUa0G(6KXDy=A9HQO&uPGCve~ zaQ6~S3$)zu5(G7?Y~p1j3-m|z+Dqo1jj!wKjl&G10}jc^to78f1l`>|GoNQ@l=|Gx zcprynR~L5jLuo0^+T}o*CvY77y#kN~UFs5*EBDR_=O$S6g%mov*w>ssU7JII!~h?W z;fq*ps+#!)@1ox`h#j$DJ!6ZHwe6*9)MDj6jUN&qGqhm%(z2*r5Px&%f$MkGLP$hClfXM(ZO{$(;*e#9<>g1ke!xUnv{Em!9@>8!0dY{S z-L2R+`pL({VJ_yY&91$`r?EW0)o!Kt({XiXw=428^<`Wh!CJBef2r``)uTU9Cqk59 zs#9riLv-X-DIv=;A5tu#`wO^2AQ>6QM_!(^Q}q(PoTpTssMLoUfm#Khdw=_v9~wig z>W42Spj0nsiYbB9lO!vN<#jV_En@a6UZ?D67M`RrP zN^y=BA5Z7hgp`ZjnCwD9StC!~etb@1YS~3$e7yW@H&u?K_U$okC5XHi2i0fYkZ}#J z&?QHiAANM7Mv*CfHSxDlS92G8;iy{%23KwXFA@SeeM4MeeIG;n;Ks|lejr-rMLN1v zRti|~WlwSFwoPh9xIjG{QDaZw3)(PkmHEFU?=OISbwX}@Q!Ov?qtsEJq4?gtDmEXd zUM=&eq3^A|ojl*;Cy#BWyuR0HuJ=twSN`eYAAvk?U|`VFa^uF>ZOY3|kDPt`8e@N` z+JLk$)+m9{Z4LlfU)MtEs=&g1#B**ud(wo@J2MDhdd;ny-u?sPloLsxuFg+?E`x5~ zx490D{$LjYFMMf>9#LJ&ny#AOW=2Cmr?2l`*iKBD?j^-^r5d`s^kqNzct8W>_f0n?8xa2Q3W5P?-%@GzK5ZKK>`HGRRT%VfA)_h z0c0H7_)F>a_eK5XmWL4lXJlBIzZC8R-3SIPD?lBr^1td}ftDBG!&UyV5)()-0#F1h z(mQqnV^TKL(!eN)Z_C>-{_pbsKcJr9ley{XM}2)}Hg)Sk6B!jiZ}}nq3qQkRDALlx z3Wv9E><-7xs(U_r^5kvpZkgu~e}X_u%P@(gw0rk%GaDN@3kwShW@O~^1zTHN7uw+b zQlwJj=*rs<$qjYqcEtgiLf}Z^pUrm?dnc+&OO49P%e(X9@%7UZ3FzGp%k8~IOI<+c zemHJ-{pfK_rS;4w{=MeiZi+loA4i!HWCf)=z((DBa z;eROS2A(f0yVw-8kD!u$^e0}6B)2d~Kx0nJqn~JMP~Wg@yap^3!m5#P{mu}N}V1P(wrk?V$wUfE| ziYGSd8P1n+uss=Unog#4XC5(3$|_Llqv>o&J%s4fC7(lx^pNSETiG0%?^6Fq_v+vo z)ebyfo7GlppOl{WEoiZI6V_5 zWDbAK)?4{w0k!dq+No9Aeyff#cB00})zuj{t;ZP$;M@of8&{v!td=}KT8rD?HqhC5 z+3n^T`E~T=muhA8-sHmtk*nz;UZrZEJMnmx%GJ>~2fLn3gEs;njNV~X;Lp0h>M zgrLmyHfB9TCaYxMlOx+-?WIsxmuS9M4C)2$w?MBP|4E}ddgMa>_?%-kW0ddIyHfro zWMFoH;+d?w`WhJFkm$-gOLZV|KkGA?%gf7mo{&(U_1VPfJb9Y~i|6?gXA2@0pAEY% zC4*5?{g))yv?$7UC!+iNCUaxcy4E{^*)kp!9Usxt25so&>g|1Eb@TM9+l#4RJ#SBv z>%1F7cIT_1W*fx2Ja;ujylGm+H&*)(%*HUzm*GE5hvQbZ7j%9|)>YCZYgqFF2h>%^ z@z<8tcPi)nR>{7X9MHS!Sz^X*&TF)y>!^u6bx>sGRDKPo{Ju^ z%`Y(D5=Nw2X+`Ns9(`DcqLF%+CbQfotK};Lbs>`6&mXFtN*?kSez6nCFfSoI`VvHP zF%ju0`0{*&Kl|B7WaG>MwL>4NU>#rr6pTOKzQFiz1%e|aai?1ykcg_6)~L>xS?n(> z$@a-Xu=xhqm!15}v&+DsfsSx)ttKfUn2F+_!SS*g9!II(+zzdyPDtcHy_D-lxOCYb(P3s}{sJh)R;mtWW97vbYr}96V(x3a6f^$;YEc z14eE_Q$7Iq_G*4ED-6qq~b~nBJ@CSdQX66 zNxi9Qx$+lUTbD@D(pt%2>aMRBbFk_%LZa~K5a3slj(9skG`w&EScZcy-VQ#KZq-fe z&f~_5+Brb=sefJ*u-3jgyB4m4pwWv`xE5}ARvE8nmKe)3OMT^)T3~9$7c!MPqt>fh42!4aWL*tf)s zmJ%dLzG#RW>vh6*HQgoA?COE>mA(G0>cniUue3^E*Sl#VUI&1)=-wG1#6jLG8uT$8#;VSRrp5V;oR;R8Ni|w?NVRB3?2=SxtNY7T2!Mt~oAk zjX9KE+5uV>J#Q&(wgMfMm~OQ#TDrp8^76)Y^dY%Q46`o8PC&V`iT5xBsWk6kZ!Qey z8epM`lQpgzGFUa$ZqJ#e=}_`Zdfwf1!R3zv(%i6m>c}E60gIi@@o~|LvXLw=JzL2pBK zU1U)r%_xx?vhA6fm4l3%Sox%v6U@%X0e!<#(dIa_brp$y6{%|vKc8c168K=xW>hf* zoVZ}bk0_2%8c9y~ZoXSAst#PG`#TeS+{;hGbV=fje7|cxe(FHC>4kw2>@ZYuwr+l8 zDzTod!Z@L=d1`4P%z2eA-(?q%SN{Fr!QA=g{L@B0yot$({IKC>r|8v&wy!-P1E7u^ zdGw5Tn}V8YG2^Iq^3!r5k2iwd=}iotKxzS`XC4MHFbo*OOHsByv2EM7<4fh(Wa&%+ zY53`;d!KcSq<`BGe5xghma&)aUoE;|oDtBNj%a@9(51pl+wO{-y6BeM0p^X)XGHv+ zi;!^DzIwgxaDDE%XoTcC&^v$WYUUwiMn-x^2_)RTuJ=_%)i7LAy?1eav83&izP^4v z7WOJVJA1!W*Ni7DVl;`W{YNd~@!&Dc=@-%X7lSp$3-k=Yk>C_JERu zm(NtmNE44@o0^t3;+>0JTqlMwo{@5DuE9)>2QX0%=cMAOVr@)4>KaV<=~>@?;?U4^ zXfu9zj#Oi{&_IU^_h8X0X7w?qf8zkP7~7iNaD9&yJOjMcfsmNKes95Te>sr+BL~wY zi3|(0>bkELOz=15{REhM2xqm7ByTT}){rPkfbkuSV?e^0=`TlKozw6g6T7Cn^G1E+ z(kI&0D@3X=;Dvn*c4+cTxqcMaCh5VW{^EXIJkC$U2^2<9LPFAZ*XqdO281N+M@vu(f5XxLAn9CUf4 z=m{O_A4n9wt91yfaQL8-gN$iX$e>rbG1-^gd}Mv??@-nBTDfUGPSk7qrce9Vy{Und zF`nY;q7x{kbd7Lls_5rH5Hal04B0?hTw}=u<+jY#6*EepuWKu&T{QD6zmVcBR1~_OpW<>M=Id(U1Z}bG20>b6;auM z7Y=JI39>R*M1XZzj-ccLjMkQqt;QKS|6Evx1yJ>&m`m+MQM5Tld-(W@RjGuI>?L6{ zO{y+2Od#+w$k4!oYTBH=oS*I1yZUFNAz8Vch@1~3_>5eSqZTbl&gYn-9Y9s{-7!-z$1d4;c=PTthyT**2?Xyxush853Db6n61}NxZ7tU~y{QRA z46F+TNpEy)C2Eu@7446sIw2w)1WRC;=mx>Z&rJ%HG=;<@q`X#D5VY<5LFAwf=`Cn+ z=j+ynfkGkV2Mr(txzMO)E&?e0T5+qqv>i{q);dhpG zXu~M`t-h<^Svr;5#c;C!f|6})V+G8eFYe-l5<+7KceXLG&+eze<7_B+6x zgYyQ6)xH~dzcK>e7D9IJ{uK)%ing((&)hx_z1{c>mx23yD}Rfgu?K}t?e zF&)5QhkPaaFhI0@QYT7*#b{4|EKpyr7gP1RzrNB>Ff%iA1R6J<4V^46a|S|{c65>S z9sb9@L1EtGTF2AG2&Rt*FGoNd?cVI!_dEZEd$#jWVuSQbU>y3gNz?C!%3TBeTtw8`VW&& z;cAmbU{))R+c1EprH6#9ZpM8%WTtWwksJ^|3ZqZsS2H*Zn#N?BM1mggD_L3-_vL>_ zpZNy6(9^K5RX2ObeF)uMov9^lpb>B2oi6W&u?6r0f>^OcAa1<85Ww&Iv`5NJzX1Wb zu1qnvvma4M8)k{Y$O8xV14)x``FcUo*|mu4l8YeBVOEZu zm8U#qW#(SkGAmbQj$D+M<|K3BKpK|i;xrsNz%(^?<`$JQk;;^uxRBHo6%`Q>0fFbX zalYT@_gv5a&vRYh&($AbaF6$XzuxcrhBI$Wp6@pOZVv%IBld9>vfDl(T)WPh`A6qU z*dWWFNYYO#!)5M(95;FCdR8e-vr|6?xWZ3DOHFdU~z!8qhIiDM*DfNOiS zUG-b~*{9!HP5cF(MXEb*T!GdIMV|DgyR(HIP45ErZ8dGQDbAnq_JP{kGW6a^TWD`2 zlZVLE(D$@BlA7Unbl<&qI{Q?gKDA8T^C)Z6-@7*K-o5*;Xh;1bDM$VCNh7C>N!E=2 zSu)mXhRhQbqTftc5FuWfIaMSiy-GZHa#G4~Ufsz4T(3EN1koH=xDV#g%=F)eR_kp_ zOH1pDr#B6GwHN!5I(e77^DNc2RF@Vg9s?KomrUbRT+dS4GoJTpE3C&Kr+h2J9qu#1 zar;bUx-lla{_S2XGSHX!I2jq6o9)jv^V#K#?BLkFIMqCw z?v#VY-Fv;)Jh^fnIht)cH?Q0~41Qj3ob5Npo)|iH$ff#V`zzzVp{jf3sr8U8M__y! zwA%y<-)&i-*wQ*qwRwoYbG1Q&P5sBjEVuAdbD&t33D`kyc%fT8BhvZ0Syj+QN^MP0hR$Lc0eO}fw2)gyjVphYS}!Qb$L!C8p%}@s5|4`N z$2Hs*Ghp}G0H21w5y@$TJ?+w85Aa0SWI3z-ut&yI1_|n7J zfTwT>rN@|-yR(HoH&(5;)$z?WuYj*T@arMH z2gKiv-S*=yPVPxXk*eN2C6!)6s*UQ4eNo;(OuC3D85_GhH~zPI?6KOMfM;{6w6X)$ zj~vV0uICc=jn#qQkiG2MfaW>an3cKg&t3dKXWyTDiMtIzd4k6a&iiwpT`U~jYea{P z>f1imJvbVsyE?4%)?GXYK40~JN)h9t?f~>(wu8^xV!`05M)}^055SuDeP5kzQ#4iV81l!I&k94p;MQ=f z-fx@1nk~Ptt}t=~am{VvneS8Xx1IYRLH<8O5Ym&$-f5>*At0__mAn5_2yColsOdg@ zr`Nv04EN!NbE_=$roS?6FY0F1nRmzTF(QhBXAM>dkYNSEl?1uLv?0!_L;|U$_WK7y|*Ovd@;}ijD5yCL*(?QF-lXC zPajpJ6%w~9z#GGl8e!^ghDoB!d@m1`n*10&Jb%V~^I_*E13$Gee9VF~+=`O?U4PhM z8Mwwa`!aLQNp6fmsOvv+k@ehd@H`EePe2@YREbj! zq}};-!_+;$K>)K#{@2hW>xnh~4lE7H?HnEdynd;k2=W+!8B!`|_WsZH6}T{Qe|IIpSln5z#FeBZ$SUd^iT z_WHh}4yQi+v$=`){-bpZ8BK@2d%2mCg-DR)cujxO_G(?Z?$t3iS?S&G*!^ae2f9`M z0$ybher9afUslp_Pg}zm|2e*D$^I}_L=$%TAjs|a&F%BpwDwE+t76pKE!AD6{)%0- zM-R0TvZri%!+-C_X*8_A*2_E%7sNMsZF+m;O`p^h;N1aefY=*f{ES;j(t2XLeHra> zL7CjD5o*fHf6sgkIPaFRD-Q-8ZusvV~ zE9v+SW=u+X>K(ESl-ADAZ7(Xhv6QZ}xKoU7kx>p`o%{RW-+HI?~4=F)9uzRtdm z2w-zVnaO$g+w6C$o?o49=1%PO0BQWTd(0FmRkhO?A14V5lB=qb47$5!;=A2!R7A(H z<#qG#177$vN7?f`(KXjh9jo8uhTQZ;XaY7PaAV%DlC^!hvnOrw76$?rG<>cG2H?YB zzf*sZvr!67koDg*DQ%xcbV{34cX^y#=Btr_{jQq22YBZn*L`+s7>iNx2=n&8Od4NP z^Iu9dm$+c$J6x$<;#>h~cdSJCRXnd!rq@*|FLKT8rKP$b{=K?{0_np}wkz^dny*@B z_XjLUYU7qT+BDs~5~m1{##f2!zZ2YRX@%9X?tQn+(52{Q>d zo#2O!@?mY?-Fb*TT*)o`9|x#P$6*Zi+VudbaD`oFy=yms1s0ZFa^4^%I*q?$rf|FE z;DJLloxFr9q&klNZhx7<5ACdDO6T6W2eEWlwKyz(Bf^pO$}Qsxcc!XJXct(%CEP;O zAOg^}8F9h-pk7o8&Xza%z| z(&(Gcx#LnBhFU)?{q=8DG52Vp;lfHo>&|md)&4eM5Z)zF4e~=NuK&)ZD~u--ULPJ3 zyFK0a%_c{k4QkZ!8*t3Hsl4`WfNgk2%d793mn-Zui){jyOozm?!n&^ce>X@>Y{^Pq$JgR%o`p56Nw;^9kh)>krJR6vpTakAoioYr_CCiZs3 zb9zx~T7WXK#KiOVlw8I_aCOjazv3Soh2Pe?> z-Y;IfMr`Tj^NPvbP!om65Ruz0$BGb_C`~aj!Em+TP}gkO#@Ou#%n~wFt7rF)+y0vZ z#2)8bn^~V(JEENC(Sc5wPM)I-Nj+1a7g&D zJ=ao94D0gQLD%aOi`6P&Qv<91CNK8Z_4>eK(sZW8gZvkmcuO_=(hk^s&9CTjZ!r|N zyOA-UrFHX5zL&cG)%9Y$;^XhlWK^r#(<*l1Hi%t8r5YkH@NO=6Rz-bEt%Q38e&2V` zgU#~YEg!qP<>_0jatM|O4u2SSTK_ZRH1Dqr3zW8m5%RNykXC(v)bEr?*qLxnj-*%TSR-wAH;6ynsVX zrhwePORJ)F{UeEy5j05Vw92$?nlJe!Q^tR7f#)L(i)t7Bz(Tr!;{Guu_GRN3g;Yh; zc?mSgRpFmVgYah8h<)l}=MQzFo@-qX*GTeoeykNd__;Csij-K^jGKjbZ(;9rBg$ld zpFZmPAEZ(z46NE-@~6gfvJ&KVb2mI~Ity#6F+K)M(=_qZ-YhT1O4ZwSxykK1@5+~a z)0+@@3$<_4A7Te`m9hwnFpYcU+6^{cGs#s|QHk3Z)`%5eV@|ev37hfLC7c*(LH#Hu z(VW(I+3x(WoaTLB8O7oEDTe#bbM?6ywqOAX%iX+SXdRXH?|MB(af zh9l2_Qu2cYj~##hl5*GA0o{|V_8Lo|uj2<7-+A?Wx_95jx5cV;TdHjo!yXn#jZ=E1 z)a>)EPa`g@VC7Wv6XXmFmN=H&Nine`NkPW-cC|Qd4N5rjOgOV~w^z#thS$IwDX$v} zil@ZHOkK~OI(|v;U~{Vkkl@tXhwkKh_H_DAORu+YU*L-$Y8Z}vE1&?E&L+?N;%4Jt z9Y$%mn`Z--;2FU??g;=Hu5@-)g79!`)60@A(QC3YQ%m;##$4tc&AWlhGV%x-Xgc^Q z-)pJiezNHrF|=^o3t*L%n(cFkbB(?OfHVz05LyPB@P zZ|!*l0)wh>OPX+)^k$RB;Eb*+W!)t(m2B`<~lODJiZ&`36DFBtuY=tw*z zw;=q&8lXb+!Zu3FnAEQNOppf1q&(+Z6*~Lbu$D@(p5*at&13ZuNVXOEH zo8=$|hny=9UiQs*|Fs~kuCWe}B8{f77p~&_9UtKjMGKRsSb?Kpg(3c;E5U|Ct>i3;#2^ z-?9Gxxf~!1|8uzCOA-GIH-Ies|0meGqOKXSG^@of9_FZzR7_4zMv@f0FIVhC=mvUV z5ka|Q9JjXQL)_AVJG=-Pzu=JuF1KAwtkL`ZgUwzY8FkZf8=%qzr2yX}@DE?c`rT)1 z8D5j0^Bk3th^QJJyJCk6EJK^8f1>~Xw&6gEVES&H=zLGEy>n8UM|+3v z^rcM?d+73P&}?1x;I1S~FwK)68XoDbUnwk#JK_hrk>~tr-U6;V(tLYUMn7+ufPQuGV6*_Mr3#p(cR&9kD2wAL7|)E1cLd9E>KH;yv2aEz^Z`Gr3(f5Cf0n# zpfd)G{o`GARA}lv^6Lw&p#BA|(D{Z)8S=I@-qEPFCd)_2!WzRadKA*bVCuC>R})`3 zRfrRn83P<&^$jdljU`)9GFS(1L9~Q?tTdVqphq2HzG` zx~-91TK1CR)YqV%azeiO;YK54?xop?OOo~Tv)^vh{2L0|`749+u=$0?k|6+m$r(>F zbvOv#0J3^upVcn-%Ex?1nCSg=`5HG3L8lx!27 znfZw0_wMd}ul|SDU27$bGdi$evxAl|5MELg;5R!HqqymU?yF`>nNi3-{pqH4N*4DX zY}$W<)ygp(e4j*e9-1%5f(BYazS}~ey+xXlKKa(r+}u)UQhoJOgrutJYuXH*Y>KSa zGQQwb0ieQ@87w(fc+(P3ewvr=e^xa!+%aHQk{~W(Frm_dK6mS7zxo+#Ql1PnO5gJN zVlY-1L|$;j=<+hzQSDv1=Aq#V$E$upero_)8`!~>c`4$kiZ1u4M+wqdz2Ek8_hs_F zzDGF%v7io#((Foym7*FMlTOoL-zVM(jIgJr;0DTS7k8E3B*JLknKu^;ycYhsT0#_b z5->Mv+B;@QfNlP@)5%&PD>90%yRjbaX{<6CSBrH@;czT}l5HX!&!2vKa*KJ*NK^#R ztvULly~C;XuF65Y-l%mu_#MjX$XOMXF~nFjX6`lGY|5Q?#Ao#`PEN8qBIx-h&f#G^ zd=tNF$lg_QUMY0!?DS(ZWou2(j@bo7p&{!-&fu`F_`ukow9H3p;GmoK2nUeLzrxb_ z4+I-i>QiA^$%dC1)?YLXZ4V~pi&pUJPIP&UUk>P0td5w&I_6`7LwJ$1{W|=jxR8a3 zmPgYtB(7rphw+w}6=4|u>`so!^7(+fClOg1Rwo{EG%3|;?DVx;4h()MeOMIdc3X>L zW<|jjlj_hlrWFWyA+m%L)%E!HC`lgTgWhvFY@GQuBzNqhX{2cc~Rb>@G`zha-0D zQXLWkjdo!BsVp0Pdzcfe7ELtZGz9eosJ_Ik%*yyJah?t?rML!Mm(&U+q=C8=4d{#+ z=+wt%X_u}?seK_f0?BPYn_n5`e?g-^m}AVz16?ds?4eWt?6iNP9K|a4!vxN0E8J>% zJk9aM*!Y;pNb@`Hu`$9$dtfzS2l8BJ4;~}FXTIw0(5sOBXXx?#11e(x-#d>zifu-( zC+fmRG9dEWg-c;BsX`SW)qpDQqbeN*%=OPVw$ek#&u(K3KtpZkjQzK${5v#?C zkQmS&lZQ0oIT(EXdUA+0o~)~ofD0ZrH#Ms9m&{J7cqylbEZx@u- z&ZGrV$(-t;!+GaWTaPq%tyG7T;cXZvjty=`pR#Xe04XeTFfThSK_u!?hgmg-bnj4{ zA-%2!?vil)T68j_rjei0D}Ocu7qcb-Xo~v3=i5&bp|7lp>dv zr(4ruXU$f&o*@JZ$0zKi?KOgIGaRT~Y4_b?8m- zQ@2SM@JW3M96kst_N?!y@!52qi6g0fA%DGw1(&8u}I$aa?u9;C0GhSXT z`IyP{xhEPJl%*>AmUsGBqvjb0VndGhA8}s&DY`OiFSF0DsG9Ii>!&1;2m7?khTa7G zNG>afj-l+g$=H0Rgha^cMn&eAsrBtdPWO_!7&zlPw!Y~NIh$Ali(Uu#I3_4E&bRmG zPg^`+FgoztwBGY8W;PR{+D54DvVEmaB)~{J?(MIkly-|0XmD^k@n}=}+L5q)a`@zK zVZ_{E@H7`#WC9v~(MM0wrcoW#kPiq~G-y(^5?u%unXCI~ zj-S|6I5`x=X7rZ|(SL&4@yHI<&4fp96WVMPFY!eIkw-#?m&c;1&MSu!_xm?+`}*8b zQx&Zn($wVgU@~Y9^1ovdmL0rFCB-GcHl1(UKSaJ0lb3h7g#V~W&cB{biA*weQ)YfN5VI)k1wZU0a-@2_}f(Yke2yA4B6(ieooft^F5HvohFNo60`Npb zdZT@1ui~SfvT~S+1{v(49+@3ut`6IdMrw?w?6PfyE1lM`O+%s5=+Hh1+8IROn{bmiIZc;V z4)Kk?_v4IQQIEzV?#7a@Yz(XEba!UkJ}MF6*~fP(7t=#GC2# zJm|4rUUT0er@kDiu^IZ~py9U)-%4Em5W$Q7_(rK7a~2R{vOY7CJ^ z$Jj%WDuT(k%IiY*z>7@i4ybw|$H6@E%h%n83hVd#%+>~&UU5Wz1_4CV`t(pXBEIOQ ziM)Ox*>(>jgMid{5p1xqK7**o&tL)9?pHnZICW7_7CJoOp~zCjL>crZstoz2#83lz zBaOcbIT+zVmlcBf5Lvb5?FIYy%+wB1%Tw$99;&Z!rFz^eBP)sPRzf`CN;b8GD{cs= zWHt_*B{B3v1v8#Y$V0N*kN#%Zl>)vtG5UOvGlS+UpW(DFiou$aU|rrGbDD|oI{I}E zc(~or!YvInu|5@*)L1_^&_3i``*))=-)YklnuYC-y}V}+95Pco?t_CO&%!ptv9d?n z@t#f;;P?DyMgt2ja_H zcbh5LvTVj{C!(KP?N8kAmRy>;zhI;WMTpz`%nhTl8R3r8;YBhysa`&#&G-G3)LH`C zrZhlxvN07g_m4{AL0&{agRE-XX%Vx1&DyRpd>j)iz1p#g7Lb@FW#0q;X45L+Y*Cps z0(TN+R6j+Zp9y%6-t%wCA}ic`T^|KD&=A^Fz0^ILwAYB@irt3BEibB>zO}_!yThZ% zn{}&%#wRMbTS4{;Xn2{pD_Y`~;TJdUBL~wP{hFs8l%pmJGjSZl?e|Ur16mV|3+N5o z)H6Hv=hws*&q3LF<=|O{X%_i!38Jd?^Cwoug7`jBB9ZyROvz7XAym}}rFPvF&d3ew z2$QK4XKCDE5983*prb%yDip}g9Y2eR%M?-)X{8`FDXWGxv0&t3thW?B*Y-yXXR6s; zm> zLRf|9c+5+1UQ@>JCoQ`ft)EBml)f^~& zMn5w?zS`SF>IMZ@8jU)nZFkU6J8bcrGRDGE z!Q|9y0l%WdzXsv17~XPWdOm_~-tAqc$zf!@!#@E*tTKFRbTu5SoF=x~&KepflDq#? zSi02FH)-m{CJ<+(ssc_Ej$7eJa3sY}m-70%9z)+CG@JF_x30a;QyLQ+wVZu7X@XXjDWFuvb-*2t17>Hn1Z3sIm@aF~#MyCEi_ncisq~kjw8bcgRl01&UHkZCjJ{6kmIEz> z>H@zI@S8=(SH_h&BvD_~%wj6v;|MDn&kHt`u0ppo+{sGhsYBVf5w!D>cPr~HlChwja zl$ig>${!_b4JDlk2BV5DrgHZ*HEJdAkgIfu9X7SZD{1Bp*~gX@7!zBy*P--BYvxL4 z=1WumuDU;&;!s}@U?DVndWZej~q3rJM$$-%}P^OX{+XXyiP#&wTw$flT4xy;`0O^LMm~BHk9g#8&B45kD8(@ zx*jC=z)u7zq0R8Kt^o(-ZKfrZ8E4bLEn_vP+)$bS)U=aSjMVcrjMSZMw-DXy7vy1e zRqNl%(;k47E5$kdGLJ3vE3<0k0C)Icv)@{Rejqh3f{w$jZ&~EzmAlomYrA&$xhNTi zM5ZHVW7jVp7LH#p;TzJ1nOzzBeq|S@O4rxQ=Vv!9JTci}|0#q3>|Xz5V?W^isq+Y$ zUrmkBSp1dS0j8|)pVyn2TWzulv_d3WGI<0+M1ZD_>m?kzH+&>%6{D%XOnR+hgetOg z6D*EY0zQ+RBM`h>V=qI@xB7xs74jl=C@$nYr5fmBx}V&8=6V85L{qGy4-e}MMFRj8 z|Mdo9=tgLQ%>v=8$3ez<%;Vir?rwfdi7mV|$%iECV~=+3UMz~8L8*X5I@~;?hx7D7 z)37Z7opKNaGU(PWVZTrc|Ms|VC>z>4U@)$+-Cm(4DCq9n?bgQRNr!?Q_x`Ce-~|Qv zxlW96Zb-&ulPw=h9LnFMKK{Ep&i$$0q?gft0|{adM&GyP;htASPu-ce|FY7F3k?bY zrJ!}Gm0DDIw0nn2-FPUblcz7DQRoNrLOSR}4jK!$LgobYnaZhv`=^`_U7%Q7WXirn zSU)Uim&dqUm}NrmV~ggI3-4G(f_h*Bj-9u$u`wtg{d2i?Ml@=sd}#3Oz=BZ=Ye7{s z&*~c*|1_>kk^5qxy#(?TcW*}R-Iuy^B_L{Xs*4iv0E&xP?li;qeq;MF3(m-csLV9G zV!Of^B65zcJJe94@zqK9+SKb+5M)OUeg~btS)qTFeun&3!o*_T%8^EXQx*MKvHsvI zq2B7DiyDjNTW&rWl>@vt+>Z~h&w`d*{|Mdy)zSKj(O9Z`-2NUyqCBY-gHr(^2cg^s zv6Q9f#Y@D_k6ittsQCnM;l!p&(cX|IK;Bx$`WAu1{s)+Q1t_NvRNFahr)QG{oS*4Z zI3!%G>EoYfa~6#HQm{;PMBLU8Gg_RPZ1v5~Y%Tv4ndy=miWP7Ks34)KOg>cT!M`+` zAhlMH>Uy(t%UZm%xw(1$w=U&;KU5VLv};~>3by{eC`R~N2YRUz1=6npJM1KIhW?q& z2Hqgj-Aac==a_JJ2PLR!xE0b;<-j!~Oxd7tZm<1NLmvp2a%+$3D`CM!A{OJK85*pT zpBQw>osj6WeN5*8Rq|PD5311%wwajI?mK(!bwE$5hF|ja{tNJ^g{x*S%f}5d8hi4{ zut*r-13)YH&PBXkB0PFWS>B8o%}p^ZN$oN|!Q=_u{`}JVj>MyYZqsA1=SJ7hrAJ+K z7Gw|~*t7ym^nMk6-eNM7+BcMg3Z9w9sh2J#x;MzUh8Ms~0*X7IyKEqiUnB750uJur z6Z!CjV9`kl8Jlv#l4P|BKo?8+AkTzvHZ)+oDf`t}x>oGGelznHP&mC>lp1I*9Cs-Q zr6~7fV}vL|XU>Ke(f)p>vlkWR&f3x+9{ZvVHW0*at3BFObD;t`rVKHS@`X;PG=)mg%}O zYk~wbiLXkdsk_BX$NqfGn=|1KsK=_YRlXjUN5`a!L-J^)>sBQDTF-9SD1Gn@Fc~f> z&CK^GNS=d)h6pggsoK|%c^Nd?GExIfKPFmr{0)xzjLiQ@R7Nfq^wCch*X>kwX%QL} z)qZMZ820pNt)5bvwJZOut$0i1M`(f&jtNE4{;U$BcNc z`I!NBbEyl-Zpnp-Cs?HqsGXPuQZk3JD0CITzfpXKOfE;n8?2r+FjfI)4M69|0need zBrkHy)d*8R*X41Zr*W=^k;rr|OHlODX3^4s{Vv92i`6MxeIp$GP7FAB=aKivMw#j& z&@d-$|7XhPeD^Gs6a8iRR+gOM2&6{pHk9I89m%oNyRd3*CJ8=T1i|>9_Y?ajXoa=0 z-`KiQ86gIF3M*zZcLntTblXAuK;mq-anpV9@G1yl8z=#9nyW}6*-65c-Xvtbj(~Pw zW@xy^5ag&x9t+k@2he3O7H+K^{;e};6rU2b-^gTa%DtPnMZ7=6)H&cHCTSO>E#1HI zQ2TR3bxJW|J#lErWi%|~ukPiM(5h^gjUa+1dv#`;;x+6VDUyg6Q@EvPWGQsa`f3w- z?E~Zhstca>f$w-B!02Z4$NaqG_hKq(6oA{%t?-Ykf>+N@M4bN7L3D}88S3Js>&`1y zRSDjOU2bO1vBA;Myei|Z5PGca!m{tTSAA6r*=}=hBaO!ucN+M@4VGHwcDr9HE`tPm z*rfa>OdMgt{TX3B9QidK#bqN}J|RuhTR>QF5--JI3tDc8mD@$+WZtLlE`6IA+%KWO z@}Y0ejkhBE#k&C(3j7xz75oYXnUC)C1M&TrO3Lw=O7!s7-gFQ}4J2r8P=HTe^;-Dy zBG;s?;|C$Qfuisx2bz(;;nbJ+aa5!5&s3~4t*^?ZqVcEEY?11R;h6qDI2GOv5(RFP zl9;)tf8N(47qsQaOz9Ff)NfZs*eW~)As#uXJy^F=UnkBWuTNFr!DHzVbAh>0sA;)q z7l!dS(+2QQA7TUXK6Q5I>XEo#C_(rhBOI@u))lImzGxD9V|bZiddvyABJW?HYmUNs zvuA*TOsO0(5iegoov0}OrB1e1P78ih0}n z1auI{>YxxK_hs_;L#^9&=e|^edev%0hb$x+cBNGrLXj7LXeb3C61c^RY7doqhlA87 zmhQgk)BL%KU;dkQ+>M({L5Dl~P*hIL0&r{}rP4;j1vs2cs54t}cW4e-5lzCow=m8s zY;5s$XUKu`q7+Adbf>C%qK$lFQoS6SP`wIwg&^uPZ8O1Xk`DCaU#NIAb*RV}4tc%g z+M-3l8Bc`bzn+Ku-SfBjjgd&&T;DN`6V13021jS@Uc>D}TjU{o6a!aKqoe9efJ8UD z+r1cL_{@2=5$gI53B$!Hw_|_*Hg0|x+t5x`A{vW(&k)tUDQmY_aEzDFV~Ys#rt4+b z8swved>u|g(U)|?^{qeyBp9{8d)>sI$GU>p>9rd^)-Ao2N_J=jf&ugVd;g7nm zR*z^9w+Drmn+d^T@R3dp%1m-{-{stF6Hs!<&npYPb|$#;5(*zy{VsqnIs%+ndkcfAhc1V0n;e1kuym>g9JqJ-Y^7gi?$^v%kJ*hwmtIdm@l6@5cQ zmsrVazqInbO1U;332sdp1Nrsqk;KW4Os9;Sl0yVf2ORNEj1pR!G&r2Nih@|ZsU0iy zajZ$8x2m8_T%9wO-F8*w=I-4Lr)CC$bh;*N&K9I1!7W)nktt(KdZQC)03vMkrt})^ zLcQxxeUUAD1+85~o_q1r@R;feQXEAU;1}m%C88a>gIN`zT;v)(OY`n^HcW<#?n!j* zO>wpJwZU1lF1v|{`1mhH>8u@WI@kkgTiUg>k_V#NyJlgk?}J#?0=_s)Mw)>1w z$FtWL%X4Jbo|5!lg`My{U6Qw2rK%(!^xdm?C3}ersy;hLokLp$ZlCC_U)2u?4V4U) zG?ffX&zr2ga_>T}tPr*`DLyE~;7-rnyn(s0$b>tY>sfBQR8I`^5K)WW7#aKL3cE?&4e)BTD+kxX0t)g>x6lalu zSU3^O6Yn^&PBCQJO3ms@Dkz`o@HYk=ZKlDRE=RzS&Pd|}eIFpjO9Obmb7XQAM*yND zbCWUzRDPYhik`9vA02YtK9am^1)NLzsv8e2<3^d%!V7^8*Um!8k zv=1>(D?0&Kn*5xZURpQL>s!+cM=*>5)VVHpVso~ik!UQgiZZ#;hw?Zljx%2`??1ax zQ}wSfD41Vb&9DYDuE-;j^d7UO9F;>NpzNCIsd4MSd9wjd2y88p%o)K*tGjmP;p!_E zjP5S4Fvj|6D{<-tY>BeNiJoJ6s)>KdgEA6vweIKNFwvJy+@Y$j1Zt(GliXaD9L8t>>UG~r_|C*4wCAE3l z5FRqFPYEA_c4fUg=_6=VkK6vFtZs?trp(9~<4zLBe#Hp@5ErTQ!4Wag7%z#2l^q3j zu2(I+O_Dc*gL-dyO1)rB*t=wc{*0&eH|DGPcv%C_QSvj@=T4}dNb=5bg07T(eyEPv zb|e&_T;cOvs^O+*;222#o<0lFt*)0k-3pVyZ^YD|n*f(?_~UQI%Q&amI)bC?j<$452yhdj4vii`%ld9<|J>8>s5esURWm94kb1oM6FcHy&>KYqO$G1H8!)drsdURWOhrDF|N0 z@?)zS4GoX)Ds8R>KiHTHV#t>uSP!lBhvv*jQ`u@`uu?=v0%xuO@&5RVz6pP z5*o*9g9hHP2IXNdH9H{rH%MGaw%g=w8!J8nm^)J3Q-zQ!#Z_Llz~0pcKr7SRcOMX! zB|_+TwQhX)$IXvZD~F46vITJ=CBdOuUmWfLdIRB4mcjwCPMBQp54S$8~#n(@=}l^TYW$?kEs@UggG0nIdtFZ_Oad zctohB-&q$YTmToeeF=900H@%aUSFJhmfqnT85@erv#pn~njID=A8b~uCSuHHsUYX| z3S@@~!ZN~^>Z+n(`Nw&HB`Ff$DIXHXJqLUY~nZf7=%%0K=b z`BI>L>?^dF8@Qcyx!5+NCM3hY4RA$lgrg{N0C&Uuq0vCIjD1 zf>K}^-#SB-onkrlQ4x_8gNV%XvSmRLEFH7lxg2JOC3jLu%UD^uUsG9qzh_3}>xQLF z-dNkCX>jf2!P4Yd;&KUa8@k>3GB~etOHU$}foQj00Nk)FA*^dlmO@mn_Di5k6_t&I z-)yGYj<{eJ6_XEgLutb4Om@r(RnkF68wld!zjRrn@y{0GOD+5jK15TZg>_yj_3Dx(h{Stvk>z9 z3fsT_Ejfuz?bZ<6wpL5y%C@!23><@!`Nvh`f*eBPyBsupwiQ8w+E~w}FO4A*I5oPE zwx;4761g+W4S8NY@oGjystyN=1U3 z(7r#(2QM#9Bl$4VTowW>=Dd9~Q&eRq8hY-D4tobq!Q%Fc_Wb;4M9tZ!`;0j-(Gm=^-9ddJ1hRT%4ua7$bO2be^?0-of<0g%asxNHFpHskRXtIeXxD{(&um?fhl7eCTO zG^C(RPx;uWc_LcW>TYdu3k*zhk|DoxNv)qO-Z)u*#^;Fo(S6-v7ySCzH<8`?d_elLm<9rc;h`{ zpo`X=kJmz*Van2!Z^Tm>@6hBMt;U?;iYPdI`3wZyi?{l`eW|sw!X%m;4V@pBFPyvy z!Fg|?LQB)$b7xP>)EMAwcM{#>;^V3D1vYX-`x3|CaiM@OdSVT(hFg7(a5rt)vSm1! z!gj4NTI@Ul!;r8424&wYO~_U5PE!&*13J_yoHa)z-=tR>g6&TI`xa}%bL9C zBaQ0Rr$2@fvrsZiRM5XkL2&$1HQZarRu_;=U@ng0;YyYTY06X2Z3B;qPV|P?Bl?Oj z%Rm?{+d0aHA+yIIyS}eO>}`v#kqQ6OhmB~B+B`O?EF~~cQ%fDn#|ASELxrUQe~UAZ|6JF;%25|= zNaLGG?xJCy#q({rV5RrmyI^m`A~1RecmeI2YPM?)48JJ+@(J#WKK78h)$JH6f5`n9 z#;zCbZ$c}s@F<1iqI%KB5g{$3AM*eBvEbCyEs6$}oEI@l;aO#6ba`7_L8}c8qg6-1SftL)2*G>fdlZH#~~q69z}o-8PFc zeO^W=s-)X7jAL&8kbEYxU7Ped3OF4ly`ZTtPNLwoia!S5SDa&p+TuI#W1wqH1Ii=$V9@kQy*LBLckT zRE6L_z^$y?l%01H$8(A$rWl>oScDQ$&ACVKFMA{Ix2K%BfeLEU=;&w;_sCC%j(06! z=}r7TaP1er=gD64PdCvRA9Y-CR9Npy~M@%NrtOaJ5mB$Cx>76a6gON>#D zT9yI0>_dv4x^9P|F$s;N8HKcLESxNr#dpZ!=VbwRcM_*JaPJkFP+XP2jGI7C*CUja zql~aed_eV&G5{h675>uPkcO64&|k_&f6S2;x>-U3sR!tXp`s(^QM!~!rb~CewJ1Dz zEP)9xH1^LV*vtjcjL_aFC#sfRHV>f&Y=Fw9{q9GZA63IUDlo{LQ zd=x2M3FC}J(9=MxzHn*P62&}tu!VZ^=Rr?a;)@qA-mQM1T?QJ-7{KTpbgZ0e)$GvA z8P-9KHmtOU)deV7R}o5nEFgtC2qbRqNJz`8A@JMMXwAISazxtNaHEueV3?FO#{L-6 zIu`uy?k)J)T=SH}&fp52G;khVI0NKE#N^X)B6ZxOpQk_?cl$pFMW1z83Vb{P2NAHk zt^N96j|yp}*mjEbu!IZ*#@NxpPdT zED{E$zBYVC^{hhdGVzJ#O9Cx89?=iWC@#)_6^ipqr3_hnp{1@0*0CE8|rot4>S zC;!XA6G`?X=Mj-d)U7KCH(b$P>bL+jEQ5sc0VFb6m5azqd1`B5>nWia6Al>!(C!*z z;nTmin67w!6v49W+fQ!C1s(|{g0T zwsH`-ezV4-UGCq-d3~;*s~+;l6@>Yxphm6PSn$@ z_H(OY0yPs2Q`h}6zO@DU_?i6F1bB(FTzse$qZWHl8victQ>xOsqn~oZYm(L;{&!!N z$%`I+1#jLZebPx;$6P!WfzYCtr42!6Z);>w<*Ay5lOg@n->3P$lU+2GaO@gm$fE2Q znsqJVwyQtbQcBC!{WV{h50&sww_MoSJuY^7!XvyOo)&g3<==huxP%3&IXTxYI9Asm zO(i7Cq>s$bEU$7AwfRW(+sN^i*_jr3>O|ert?}W&x%iFTd%n78Al{3S5s@sm{1k)o z*MxYuLh@pK#0vE+_Yg~H7j_DDQa0({5*vPvBC&LjI81jKF z?u|!FsgGU$71E2L6YV9w0TazW12ep$?cZsJ?KIMP*Dns(!*MnozbHInKIflBrI-)_ z3vTvc0#NU_6SZ5e#*W=I4fv9MG@GzH{?ogINo$=xjo1H6p_h-_(wzpzcuq+rrQ{o~ zQA0*LxPIX$AX%+pzR~^}nxo$&DkEz%#aaGltXtcSV@0R;*L2c!yV_p4`sY#QXa3*F z4M-8yZA8&RZGH``jNd{KEJL0+eU`h{?>m7*YQBtb;P7rMt@}GxbZozFXItRBO2QQP zLHK?Y?cZ%bIei%B&n|D+G&y&gc{GF2LGsu8cPuaN$r9Amod1g&`A!<{z7qa;>|&~` z|I3v3GV97+cMdT7|08e(*u}|Y-8!RZDNd7_;>`Zv5+*JFrcY3+HhPnyMQr}=M=d+m{a0A``MxG}=Df=sZ88V(2nXmZ*Ry}c+vsfGv zHrNO$Oc7n#pY&f`>r%BD`8IPh3~`WnFKlPK`$nxa&4Obw?tk_*`q|sOS<@fx*%Od!lOA+ZzNpqiU;e*Ga@CaMUp~#( zoa^@0W*x${zfw-kj;YnKzq|2H#<`Yh_Ai1Z&%Zvuv)^RVbHmy#pAJrgN4i>dW$^2e zdoMm+e)IMD&EDq$lkMO9>bUoI#=Xpt^N)XJO#O(I@_v6hc5UUJn^)aG`6chXILA}B z{=u \ No newline at end of file diff --git a/content/en/docs/ops/ambient/usage/waypoint/waypoint-traffic-flow.svg b/content/en/docs/ops/ambient/usage/waypoint/waypoint-traffic-flow.svg new file mode 100644 index 000000000000..8811e037da6a --- /dev/null +++ b/content/en/docs/ops/ambient/usage/waypoint/waypoint-traffic-flow.svg @@ -0,0 +1 @@ + \ No newline at end of file From 1f6e726788d888aa84fcac7c949c872bdfbe2dd5 Mon Sep 17 00:00:00 2001 From: fykaa Date: Mon, 4 Dec 2023 16:13:22 +0530 Subject: [PATCH 07/19] ambient issue --- .../docs/ops/ambient/usage/waypoint/index.md | 23 ++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index 6883ae9fb55d..1b3c17d75463 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -84,12 +84,29 @@ To get started with the waypoint proxy and L7 networking features, you will need This guide will provide more detailed instructions on how to deploy and configure the waypoint proxy and L7 networking features. -# Current Challenges: #current-challenges +# Current Challenges -<> +Unlike Ztunnel proxies, Waypoint proxies are not automatically installed with Istio ambient mesh. Waypoint proxies are deployed declaratively using Kubernetes Gateway resources or the helpful `istioctl` command. The minimum Istio version required for Istio ambient mode is `1.18.0`. In general Istio in ambient mode supports the existing Istio APIs that are supported in sidecar proxy mode. Since the ambient functionality is currently at an alpha release level, the following is a list of feature restrictions or caveats in the current release of Istio's ambient functionality (as of the `1.19.0` release). These restrictions are expected to be addressed/removed in future software releases as ambient graduates to beta and eventually General Availability. -Waypoint only supports Ambient workloads. It does not support sidecar proxy workloads. In addition to this general caveats, there are also some specific caveats to be aware of when using Waypoint with certain protocols: +1. **Kubernetes only:** Istio in ambient mode is currently limited to deployment on Kubernetes clusters, excluding non-Kubernetes endpoints like virtual machines. +2. **Single Cluster Support:** Multi-cluster deployments are not supported in Istio ambient mode; only single-cluster configurations are currently viable. + +3. **K8s CNI Restrictions:** Istio in ambient mode does not currently work with every Kubernetes CNI implementation. Additionally, with some plugins, certain CNI functions (in particular Kubernetes `NetworkPolicy` and Kubernetes Service Load balancing features) may get transparently bypassed in the presence of Istio ambient mode. The exact set of supported CNI plugins as well as any CNI feature caveats are currently under test and will be formally documented as Istio's ambient mode approaches the beta release. + +4. **TCP/IPv4 only:** In the current release, TCP over IPv4 is the only protocol supported for transport on an Istio secure overlay tunnel (this includes protocols such as HTTP that run between application layer endpoints on top of the TCP/ IPv4 connection). + +5. **No Dynamic switching to Ambient mode:** Enabling ambient mode is only possible during the deployment of a new Istio mesh control plane using an ambient profile or helm configuration. An existing Istio mesh deployed using a pre-ambient profile for instance can not be dynamically switched to also enable ambient mode operation. + +6. **Restrictions with Istio `PeerAuthentication`:** as of the time of writing, the `PeerAuthentication` resource is not supported by all components (i.e. waypoint proxies) in Istio ambient mode. Hence it is recommended to only use the `STRICT` mTLS mode currently. Like many of the other alpha stage caveats, this shall be addressed as the feature moves toward beta status. + +6. **`PeerAuthentication` Limitations:** As of now, not all components (i.e. Waypoint proxies), support the `PeerAuthentication` resource in Istio Ambient mode. Hence it is recommended to use the `STRICT` mTLS mode currently, this caveat shall be addressed as the feature moves toward beta status. + +7. **istioctl CLI Gaps:** Minor functional gaps may exist in the Istio CLI's output displays related to ambient mode. These will be addressed as the feature matures. + +In addition to this general caveats, there are also some specific caveats to be aware of when using Waypoint with certain protocols: + +- Waypoint only supports Ambient workloads. It does not support sidecar proxy workloads. - HTTP: Waypoint does not support all HTTP features, such as HTTP/2 and chunked encoding. - gRPC: Waypoint does not support all gRPC features, such as HTTP/2 transport and protocol multiplexing. - WebSocket: Waypoint does not support WebSocket. From d13d0767091a1208946ea4af8edab224bb0ac905 Mon Sep 17 00:00:00 2001 From: fykaa Date: Mon, 4 Dec 2023 16:40:06 +0530 Subject: [PATCH 08/19] ambient issue --- .../docs/ops/ambient/usage/waypoint/index.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index 1b3c17d75463..b9197dd0467c 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -50,11 +50,11 @@ This guide describes the functionality and usage of the waypoint proxy and L7 ne * [Control Traffic towards Waypoint Proxy](##control-traffic-towards-waypoint-proxy) * [Remove Waypoint proxy layer](#remove-waypoint-proxy-layer) -# Deciding if you need A Waypoint proxy +## Deciding if you need A Waypoint proxy It's possible that the features offered by the secure overlay doesn’t meet your requirements. For instance, you need a rich Layer 7 authorization policy that sets up access based on a certain method and path. Alternatively you may like to conduct a canary test on the updated version of your service or introduce a new version without affecting current traffic. Or, you would like to receive metrics, HTTP access logs, and distributed tracing for some of your services. In order to accomplish these common cases, we'll go over how you can choose to enforce L7 processing with ambient mesh in this section. -## Benefits of using the waypoint proxy and L7 networking features +### Benefits of using the waypoint proxy and L7 networking features In summary, the waypoint proxy approach for the L7 processing layer offers the following three main advantages: @@ -68,7 +68,7 @@ The waypoint proxy and L7 networking features provide a number of benefits, incl - Increased flexibility: The waypoint proxy allows you to implement a wide range of L7 networking features, such as HTTP load balancing, fault injection, and observability. - Simplified operations: By deploying a waypoint proxy, you can simplify the operation of your microservices architecture by reducing the number of components that need to be managed. -## When to use the waypoint proxy and L7 networking features +### When to use the waypoint proxy and L7 networking features You should consider using the waypoint proxy and L7 networking features if your microservices architecture requires any of the following: @@ -84,7 +84,7 @@ To get started with the waypoint proxy and L7 networking features, you will need This guide will provide more detailed instructions on how to deploy and configure the waypoint proxy and L7 networking features. -# Current Challenges +## Current Challenges Unlike Ztunnel proxies, Waypoint proxies are not automatically installed with Istio ambient mesh. Waypoint proxies are deployed declaratively using Kubernetes Gateway resources or the helpful `istioctl` command. The minimum Istio version required for Istio ambient mode is `1.18.0`. In general Istio in ambient mode supports the existing Istio APIs that are supported in sidecar proxy mode. Since the ambient functionality is currently at an alpha release level, the following is a list of feature restrictions or caveats in the current release of Istio's ambient functionality (as of the `1.19.0` release). These restrictions are expected to be addressed/removed in future software releases as ambient graduates to beta and eventually General Availability. @@ -126,15 +126,15 @@ In addition to these caveats, it is also important to note that Waypoint is a ne Overall, Waypoint is a powerful tool for enabling L7 networking and services for Istio Ambient workloads. However, users should be aware of the caveats and limitations listed above before deploying Waypoint in production. -## Environment used for this guide +### Environment used for this guide For the examples in this guide, we used a deployment of Istio version `1.19.0` on a `kinD` cluster of version `0.20.0` running Kubernetes version `1.27.3`. However these should also work on any Kubernetes cluster at version `1.24.0` or later and Istio version `1.18.0` or later. It would be recommended to have a cluster with more than 1 worker node in order to fully exercise the examples described in this guide. Refer to the [Installation user](https://deploy-preview-13635--preliminary-istio.netlify.app/latest/docs/ops/ambient/usage/install/) guide or [Getting started guide](https://deploy-preview-13635--preliminary-istio.netlify.app/latest/docs/ops/ambient/getting-started/) on installing Istio in ambient mode on a Kubernetes cluster. -# Deciding the scope of your Waypoint proxy +## Deciding the scope of your Waypoint proxy Waypoint proxies can be deployed at the namespace or service account level. The scope you choose depends on your specific needs and requirements. -## Namespace-level scope +### Namespace-level scope Deploying Waypoint proxies at the namespace level provides a number of benefits, including: - Simplified policy management: Policies are enforced at the namespace level, so you only need to define them once for all workloads in the namespace. @@ -145,7 +145,7 @@ However, deploying Waypoint proxies at the namespace level also has some drawbac - Limited granularity: You cannot apply different policies to different workloads in the same namespace. - Increased resource consumption: Each namespace will require its own Waypoint proxy, which can consume more resources. -## Service account-level scope +### Service account-level scope Deploying Waypoint proxies at the service account level provides a number of benefits, including: - Increased granularity: You can apply different policies to different workloads based on their service account. @@ -156,7 +156,7 @@ However, deploying Waypoint proxies at the service account level also has some d - Increased complexity: Managing policies at the service account level can be more complex, especially if you have a large number of service accounts. - Reduced caching: Waypoint proxies cannot cache routing and policy information at the service account level, which can reduce performance. -## How to choose the right scope for your Waypoint proxies +### How to choose the right scope for your Waypoint proxies The best scope for your Waypoint proxies will depend on your specific needs and requirements. If you have a simple application with a small number of workloads, then namespace-level scope may be a good choice. However, if you have a more complex application with a large number of workloads or if you need to apply different policies to different workloads, then service account-level scope may be a better choice. @@ -167,7 +167,7 @@ Here are some factors to consider when choosing the scope for your Waypoint prox - The performance requirements of your application - The resource requirements of your application -# Functional Overview +## Functional Overview The functional behaviour of the waypoint proxy is dynamically configured by Istio to serve your applications configurations. This section takes a brief look at these functional aspects - detailed description of the internal design of the waypoint proxy is out of scope for this guide. The detailed functional overview from the Secure Overlay Networking was already discussed in the [Ztunnel L4 Networking Guide](https://deploy-preview-13635--preliminary-istio.netlify.app/latest/docs/ops/ambient/usage/ztunnel/#functionaloverview) hence this section only focuses on functionalities and features that Waypoint Proxy provides. @@ -216,7 +216,7 @@ link="waypoint-architecture-deep-dive.svg" caption="Waypoint Architecture Deep Dive" >}} -## Destination Only Waypoint +### Destination Only Waypoint In contrast to traditional sidecar proxies, which reside alongside application pods, Waypoint proxies operate solely on the server-side, acting as reverse proxies for L7 traffic. This approach streamlines L7 traffic management by centralising policy enforcement to the destination workload's namespace or service account. @@ -248,7 +248,7 @@ link="mixed-environment.svg" caption="Waypoint Proxies" >}} -## Handling Destinations without Waypoint Proxies +### Handling Destinations without Waypoint Proxies While destination-only Waypoint offers centralized policy enforcement and simplified configuration, there may be instances where the destination workload doesn't have a waypoint proxy deployed. This could arise when connecting to external services beyond the control of the Istio mesh. @@ -256,10 +256,10 @@ To address this scenario, the Istio community is actively developing mechanisms Please stay tuned for future blog posts and documentation updates that will provide detailed information on this evolving feature. -# Deploying an Application +## Deploying an Application When someone with Istio admin privileges sets up Istio mesh, it becomes available for all users in specific namespaces. The examples below shows how Istio can be used transparently once it's successfully deployed in ambient mode and the namespaces are annotated accordingly. -## Basic application deployment without Ambient +### Basic application deployment without Ambient This section is Under Construction... \ No newline at end of file From 38afb98781d63cb6be9d1a7222216884116572d7 Mon Sep 17 00:00:00 2001 From: fykaa Date: Tue, 5 Dec 2023 00:24:52 +0530 Subject: [PATCH 09/19] reviews_addressed --- .../docs/ops/ambient/usage/waypoint/index.md | 55 +++---------------- 1 file changed, 9 insertions(+), 46 deletions(-) diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index b9197dd0467c..2620e33f6e1a 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -19,7 +19,7 @@ This guide provides instructions on how to set up and use the Waypoint proxy lay Istio Ambient Mesh is a new way to deploy and manage microservices. In Ambient Mesh, workloads are no longer required to run sidecar proxies to participate in the service mesh. Ambient splits Istio’s functionality into two distinct layers, a secure overlay layer and a Layer 7 processing layer. -Ztunnel proxy is used to handle L3 and L4 networking functions, such as mTLS authentication and L4 authorization. For workloads that require L7 networking features, such as HTTP load balancing and fault injection, a waypoint proxy can be deployed. The waypoint proxy is an optional component that is Envoy-based and is responsible for terminating workload HTTP traffic and parsing workload HTTP headers. They also enforce L7 policies and collect L7 metrics. +Ztunnel is used to handle L3 and L4 networking functions, such as mTLS authentication and L4 authorization. The waypoint proxy is an optional component that is Envoy-based and is responsible for L7 service mesh functionalities. For workloads that require L7 networking features, such as HTTP load balancing and fault injection, a waypoint proxy must be deployed. It can also enforce L7 policies and collect L7 metrics. {{}} @@ -28,7 +28,6 @@ Ztunnel proxy is used to handle L3 and L4 networking functions, such as mTLS aut Before you begin, make sure that you have already read the [Ztunnel Networking sub-guide](../ztunnel/). This guide assumes that you have the following prerequisites in place: 1. Istio Ambient Mesh installed and configured 2. Ztunnel proxy is installed and running -3. Mutual TLS (mTLS) enabled and configured {{}} @@ -56,18 +55,13 @@ It's possible that the features offered by the secure overlay doesn’t meet you ### Benefits of using the waypoint proxy and L7 networking features -In summary, the waypoint proxy approach for the L7 processing layer offers the following three main advantages: +In summary, the waypoint proxy approach for the L7 processing layer offers the following four main advantages: +- Traffic Resiliency - Timeout and retry, circuit breaking - Security - Rich L7 authorization policy - Observability - HTTP metrics, access logs, and tracing - Traffic management - Dark launch, canary test -The waypoint proxy and L7 networking features provide a number of benefits, including: - -- Improved performance and scalability: Waypoint proxies are designed to be lightweight and efficient, which can improve the performance and scalability of your microservices architecture. -- Increased flexibility: The waypoint proxy allows you to implement a wide range of L7 networking features, such as HTTP load balancing, fault injection, and observability. -- Simplified operations: By deploying a waypoint proxy, you can simplify the operation of your microservices architecture by reducing the number of components that need to be managed. - ### When to use the waypoint proxy and L7 networking features You should consider using the waypoint proxy and L7 networking features if your microservices architecture requires any of the following: @@ -77,6 +71,7 @@ Waypoint provides a variety of L7 load balancing and routing algorithms, includi - L7 fault injection: You need to simulate faults in your microservices architecture such as delays, errors, and circuit breaks to test its resilience and prepare for real-world failures. - Rate limiting: You need to protect workloads against denial-of-service attacks and improve performance. - L7 observability: You need to collect metrics and traces from your microservices architecture to monitor its performance and troubleshoot problems. +- Rich Authz Policy: Enforce granular authorization control and manage authorization policies centrally as well as enhanced Security ### Getting started with the waypoint proxy and L7 networking features @@ -86,53 +81,21 @@ This guide will provide more detailed instructions on how to deploy and configur ## Current Challenges -Unlike Ztunnel proxies, Waypoint proxies are not automatically installed with Istio ambient mesh. Waypoint proxies are deployed declaratively using Kubernetes Gateway resources or the helpful `istioctl` command. The minimum Istio version required for Istio ambient mode is `1.18.0`. In general Istio in ambient mode supports the existing Istio APIs that are supported in sidecar proxy mode. Since the ambient functionality is currently at an alpha release level, the following is a list of feature restrictions or caveats in the current release of Istio's ambient functionality (as of the `1.19.0` release). These restrictions are expected to be addressed/removed in future software releases as ambient graduates to beta and eventually General Availability. - -1. **Kubernetes only:** Istio in ambient mode is currently limited to deployment on Kubernetes clusters, excluding non-Kubernetes endpoints like virtual machines. - -2. **Single Cluster Support:** Multi-cluster deployments are not supported in Istio ambient mode; only single-cluster configurations are currently viable. - -3. **K8s CNI Restrictions:** Istio in ambient mode does not currently work with every Kubernetes CNI implementation. Additionally, with some plugins, certain CNI functions (in particular Kubernetes `NetworkPolicy` and Kubernetes Service Load balancing features) may get transparently bypassed in the presence of Istio ambient mode. The exact set of supported CNI plugins as well as any CNI feature caveats are currently under test and will be formally documented as Istio's ambient mode approaches the beta release. - -4. **TCP/IPv4 only:** In the current release, TCP over IPv4 is the only protocol supported for transport on an Istio secure overlay tunnel (this includes protocols such as HTTP that run between application layer endpoints on top of the TCP/ IPv4 connection). - -5. **No Dynamic switching to Ambient mode:** Enabling ambient mode is only possible during the deployment of a new Istio mesh control plane using an ambient profile or helm configuration. An existing Istio mesh deployed using a pre-ambient profile for instance can not be dynamically switched to also enable ambient mode operation. +Unlike Ztunnel proxies, Waypoint proxies are not automatically installed with Istio ambient mesh. Waypoint proxies are deployed declaratively using Kubernetes Gateway resources or the helpful `istioctl` command. The minimum Istio version required for Istio ambient mode is `1.18.0`. In general Istio in ambient mode supports the existing Istio APIs that are supported in sidecar proxy mode. Since the ambient functionality is currently at an alpha release level, the following is a list of feature restrictions or caveats in the current release of Istio's ambient functionality (as of the `1.20.0` release). These restrictions are expected to be addressed/removed in future software releases as ambient graduates to beta and eventually General Availability. -6. **Restrictions with Istio `PeerAuthentication`:** as of the time of writing, the `PeerAuthentication` resource is not supported by all components (i.e. waypoint proxies) in Istio ambient mode. Hence it is recommended to only use the `STRICT` mTLS mode currently. Like many of the other alpha stage caveats, this shall be addressed as the feature moves toward beta status. +1. **`PeerAuthentication` Limitations:** As of now, not all components (i.e. Waypoint proxies), support the `PeerAuthentication` resource in Istio Ambient mode. Hence it is recommended to use the `STRICT` mTLS mode currently, this caveat shall be addressed as the feature moves toward beta status. -6. **`PeerAuthentication` Limitations:** As of now, not all components (i.e. Waypoint proxies), support the `PeerAuthentication` resource in Istio Ambient mode. Hence it is recommended to use the `STRICT` mTLS mode currently, this caveat shall be addressed as the feature moves toward beta status. - -7. **istioctl CLI Gaps:** Minor functional gaps may exist in the Istio CLI's output displays related to ambient mode. These will be addressed as the feature matures. - -In addition to this general caveats, there are also some specific caveats to be aware of when using Waypoint with certain protocols: - -- Waypoint only supports Ambient workloads. It does not support sidecar proxy workloads. -- HTTP: Waypoint does not support all HTTP features, such as HTTP/2 and chunked encoding. -- gRPC: Waypoint does not support all gRPC features, such as HTTP/2 transport and protocol multiplexing. -- WebSocket: Waypoint does not support WebSocket. +2. **No HTTP/3 support**: Waypoint supports HTTP/2, but there are some limitations with HTTP/3 support when using HBONE (HTTP-Based Overlay Network Encapsulation). HBONE is currently limited to HTTP/2 transport, so while Waypoint can handle HTTP/2 traffic, it cannot yet fully support HTTP/3 Despite these caveats, Waypoint is a powerful tool for enabling L7 networking and services for Istio Ambient workloads. It is a good choice for users who are looking for a way to run microservices-based applications in Ambient mode. -Here is a table summarizing the caveats of Waypoint: - -| Caveat | Description | -| ------------- | ------------- | -| Maturity | Waypoint is still under development | -| Features | Waypoint only supports L7 load balancing and routing | -|Integration | Waypoint is not yet fully integrated with the Istio control plane | Support | Waypoint only supports Ambient workloads | HTTP | Waypoint does not support all HTTP features | -gRPC | Waypoint does not support all gRPC features | Websocket | Waypoint does not support WebSocket | - -In addition to these caveats, it is also important to note that Waypoint is a new feature, and it is not yet as mature as Istio's sidecar proxy. As a result, users may experience some performance or stability issues when using Waypoint. However, the Ambient mesh team is actively working to address these issues, and they are committed to making Waypoint a production-ready feature. - -Overall, Waypoint is a powerful tool for enabling L7 networking and services for Istio Ambient workloads. However, users should be aware of the caveats and limitations listed above before deploying Waypoint in production. - ### Environment used for this guide -For the examples in this guide, we used a deployment of Istio version `1.19.0` on a `kinD` cluster of version `0.20.0` running Kubernetes version `1.27.3`. However these should also work on any Kubernetes cluster at version `1.24.0` or later and Istio version `1.18.0` or later. It would be recommended to have a cluster with more than 1 worker node in order to fully exercise the examples described in this guide. Refer to the [Installation user](https://deploy-preview-13635--preliminary-istio.netlify.app/latest/docs/ops/ambient/usage/install/) guide or [Getting started guide](https://deploy-preview-13635--preliminary-istio.netlify.app/latest/docs/ops/ambient/getting-started/) on installing Istio in ambient mode on a Kubernetes cluster. +For the environment used in this guide, refer to the [Installation user](../install/) guide or [L4 Networking & mTLS with Ztunnel](../ztunnel/) guide on installing Istio in ambient mode on a Kubernetes cluster. ## Deciding the scope of your Waypoint proxy -Waypoint proxies can be deployed at the namespace or service account level. The scope you choose depends on your specific needs and requirements. +Waypoint proxies can be deployed at the namespace(default) or service account level. The scope you choose depends on your specific needs and requirements. ### Namespace-level scope From 4e11fd5a9f66cf9172ffd1a2417f2a653dc11046 Mon Sep 17 00:00:00 2001 From: fykaa Date: Wed, 6 Dec 2023 18:01:41 +0530 Subject: [PATCH 10/19] lint_fixed --- content/en/docs/ops/ambient/usage/_index.md | 2 +- .../docs/ops/ambient/usage/waypoint/index.md | 57 +++++++++---------- 2 files changed, 29 insertions(+), 30 deletions(-) diff --git a/content/en/docs/ops/ambient/usage/_index.md b/content/en/docs/ops/ambient/usage/_index.md index 2aacc56434e3..648b7cca628c 100644 --- a/content/en/docs/ops/ambient/usage/_index.md +++ b/content/en/docs/ops/ambient/usage/_index.md @@ -5,4 +5,4 @@ weight: 2 owner: istio/wg-networking-maintainers test: n/a --- -This page is under construction. \ No newline at end of file +This page is under construction. diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index 2620e33f6e1a..eb3bdd998fcf 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -9,8 +9,7 @@ test: no {{< warning >}} Ambient is currently in [alpha status](/docs/releases/feature-stages/#feature-phase-definitions). -Please **do not run ambient in production** and be sure to thoroughly review the [feature phase definitions](/docs/releases/feature-stages/#feature-phase-definitions) before use. -In particular, there are known performance, stability, and security issues in the `alpha` release. There are also functional caveats some of which are listed in the [Caveats section](#caveats) of this guide. There are also planned breaking changes, including some that will prevent upgrades. These are all limitations that will be addressed before graduation to `beta`. The current version of this guide is meant to assist early deployments and testing of the alpha version of `ambient`. The guide will continue to get updated as `ambient` itself evolves from alpha to beta status and beyond. +Please **do not run ambient in production** and be sure to thoroughly review the [feature phase definitions](/docs/releases/feature-stages/#feature-phase-definitions) before use. In particular, there are known performance, stability, and security issues in the `alpha` release. There are also functional caveats some of which are listed in the [Caveats section](#caveats) of this guide. There are also planned breaking changes, including some that will prevent upgrades. These are all limitations that will be addressed before graduation to `beta`. The current version of this guide is meant to assist early deployments and testing of the alpha version of `ambient`. The guide will continue to get updated as `ambient` itself evolves from alpha to beta status and beyond. {{< /warning >}} ## Introduction @@ -57,21 +56,21 @@ It's possible that the features offered by the secure overlay doesn’t meet you In summary, the waypoint proxy approach for the L7 processing layer offers the following four main advantages: -- Traffic Resiliency - Timeout and retry, circuit breaking -- Security - Rich L7 authorization policy -- Observability - HTTP metrics, access logs, and tracing -- Traffic management - Dark launch, canary test +* Traffic Resiliency - Timeout and retry, circuit breaking +* Security - Rich L7 authorization policy +* Observability - HTTP metrics, access logs, and tracing +* Traffic management - Dark launch, canary test ### When to use the waypoint proxy and L7 networking features You should consider using the waypoint proxy and L7 networking features if your microservices architecture requires any of the following: -- L7 load balancing and routing: You need to distribute traffic across multiple instances of a workload based on factors such as request path, header values, or cookies. +* L7 load balancing and routing: You need to distribute traffic across multiple instances of a workload based on factors such as request path, header values, or cookies. Waypoint provides a variety of L7 load balancing and routing algorithms, including round robin, weighted round robin, and least connections. It also supports path-based routing and other advanced routing rules. -- L7 fault injection: You need to simulate faults in your microservices architecture such as delays, errors, and circuit breaks to test its resilience and prepare for real-world failures. -- Rate limiting: You need to protect workloads against denial-of-service attacks and improve performance. -- L7 observability: You need to collect metrics and traces from your microservices architecture to monitor its performance and troubleshoot problems. -- Rich Authz Policy: Enforce granular authorization control and manage authorization policies centrally as well as enhanced Security +* L7 fault injection: You need to simulate faults in your microservices architecture such as delays, errors, and circuit breaks to test its resilience and prepare for real-world failures. +* Rate limiting: You need to protect workloads against denial-of-service attacks and improve performance. +* L7 observability: You need to collect metrics and traces from your microservices architecture to monitor its performance and troubleshoot problems. +* Rich Authz Policy: Enforce granular authorization control and manage authorization policies centrally as well as enhanced Security ### Getting started with the waypoint proxy and L7 networking features @@ -85,7 +84,7 @@ Unlike Ztunnel proxies, Waypoint proxies are not automatically installed with Is 1. **`PeerAuthentication` Limitations:** As of now, not all components (i.e. Waypoint proxies), support the `PeerAuthentication` resource in Istio Ambient mode. Hence it is recommended to use the `STRICT` mTLS mode currently, this caveat shall be addressed as the feature moves toward beta status. -2. **No HTTP/3 support**: Waypoint supports HTTP/2, but there are some limitations with HTTP/3 support when using HBONE (HTTP-Based Overlay Network Encapsulation). HBONE is currently limited to HTTP/2 transport, so while Waypoint can handle HTTP/2 traffic, it cannot yet fully support HTTP/3 +1. **No HTTP/3 support:** Waypoint supports HTTP/2, but there are some limitations with HTTP/3 support when using HBONE (HTTP-Based Overlay Network Encapsulation). HBONE is currently limited to HTTP/2 transport, so while Waypoint can handle HTTP/2 traffic, it cannot yet fully support HTTP/3. Despite these caveats, Waypoint is a powerful tool for enabling L7 networking and services for Istio Ambient workloads. It is a good choice for users who are looking for a way to run microservices-based applications in Ambient mode. @@ -116,23 +115,23 @@ Deploying Waypoint proxies at the service account level provides a number of ben However, deploying Waypoint proxies at the service account level also has some drawbacks, including: -- Increased complexity: Managing policies at the service account level can be more complex, especially if you have a large number of service accounts. -- Reduced caching: Waypoint proxies cannot cache routing and policy information at the service account level, which can reduce performance. +* Increased complexity: Managing policies at the service account level can be more complex, especially if you have a large number of service accounts. +* Reduced caching: Waypoint proxies cannot cache routing and policy information at the service account level, which can reduce performance. ### How to choose the right scope for your Waypoint proxies The best scope for your Waypoint proxies will depend on your specific needs and requirements. If you have a simple application with a small number of workloads, then namespace-level scope may be a good choice. However, if you have a more complex application with a large number of workloads or if you need to apply different policies to different workloads, then service account-level scope may be a better choice. Here are some factors to consider when choosing the scope for your Waypoint proxies: -- The number of workloads in your application -- The complexity of your application -- The need to apply different policies to different workloads -- The performance requirements of your application -- The resource requirements of your application +* The number of workloads in your application +* The complexity of your application +* The need to apply different policies to different workloads +* The performance requirements of your application +* The resource requirements of your application ## Functional Overview -The functional behaviour of the waypoint proxy is dynamically configured by Istio to serve your applications configurations. This section takes a brief look at these functional aspects - detailed description of the internal design of the waypoint proxy is out of scope for this guide. The detailed functional overview from the Secure Overlay Networking was already discussed in the [Ztunnel L4 Networking Guide](https://deploy-preview-13635--preliminary-istio.netlify.app/latest/docs/ops/ambient/usage/ztunnel/#functionaloverview) hence this section only focuses on functionalities and features that Waypoint Proxy provides. +The functional behavior of the waypoint proxy is dynamically configured by Istio to serve your applications configurations. This section takes a brief look at these functional aspects - detailed description of the internal design of the waypoint proxy is out of scope for this guide. The detailed functional overview from the Secure Overlay Networking was already discussed in the [Ztunnel L4 Networking Guide](https://deploy-preview-13635--preliminary-istio.netlify.app/latest/docs/ops/ambient/usage/ztunnel/#functionaloverview) hence this section only focuses on functionalities and features that Waypoint Proxy provides. {{< image width="100%" link="waypoint-architecture.png" @@ -152,14 +151,14 @@ The waypoint proxy's data plane operates at Layer 7, enabling it to fully parse - Request retries - gRPC-specific capabilities -Waypoint proxies are deployed either per-namespace or per-service account, providing granular control over L7 traffic management. This deployment model allows for independent scaling of waypoint proxies based on the request load for individual workloads. Unlike the traditional sidecar deployment approach, waypoint proxies can be scaled independently to better fit the incoming traffic for a service and match the actual workload usage, optimizing resource utilization and improving performance. You can think of these waypoint proxies as individual gateways per workload type as shown here - +Waypoint proxies are deployed either per-namespace or per-service account, providing granular control over L7 traffic management. This deployment model allows for independent scaling of waypoint proxies based on the request load for individual workloads. Unlike the traditional sidecar deployment approach, waypoint proxies can be scaled independently to better fit the incoming traffic for a service and match the actual workload usage, optimizing resource utilization and improving performance. You can think of these waypoint proxies as individual gateways per workload type as shown here - {{< image width="100%" link="waypoint-gateway-architecture.svg" -caption="The waypoint proxy is deployed per service account/ workload identity and can be thought of as a “gateway per workload”" +caption="The waypoint proxy is deployed per service account/ workload identity and can be thought of as a 'gateway per workload'" >}} -The deployment of waypoint proxies can be handled by namespace owners, platform operators, or automated systems. Once a waypoint proxy is deployed, and a corresponding L7 policy is configured for a destination represented by the waypoint proxy, the secure overlay layer ensures that connection is routed to the correct L7 waypoint proxy for processing and policy enforcement as shown here - +The deployment of waypoint proxies can be handled by namespace owners, platform operators, or automated systems. Once a waypoint proxy is deployed, and a corresponding L7 policy is configured for a destination represented by the waypoint proxy, the secure overlay layer ensures that connection is routed to the correct L7 waypoint proxy for processing and policy enforcement as shown here - {{< image width="100%" link="waypoint-traffic-flow.svg" @@ -172,7 +171,7 @@ Functionally, the Waypoint proxy resembles the sidecar proxy but operates indepe Subsequently, the Waypoint proxy initiates communication with istioD, requesting XDS configuration to govern its operation. This configuration defines the L7 routing rules, policy enforcement mechanisms, and other parameters essential for managing L7 traffic. -In essence, the Waypoint proxy serves as an L7 traffic management hub, decoupled from application pods and centrally managed by istioD. This architecture simplifies L7 configuration and policy enforcement, enabling efficient and scalable L7 services within Istio Ambient deployments as shown in the figure - +In essence, the Waypoint proxy serves as an L7 traffic management hub, decoupled from application pods and centrally managed by istioD. This architecture simplifies L7 configuration and policy enforcement, enabling efficient and scalable L7 services within Istio Ambient deployments as shown in the figure - {{< image width="100%" link="waypoint-architecture-deep-dive.svg" @@ -181,7 +180,7 @@ caption="Waypoint Architecture Deep Dive" ### Destination Only Waypoint -In contrast to traditional sidecar proxies, which reside alongside application pods, Waypoint proxies operate solely on the server-side, acting as reverse proxies for L7 traffic. This approach streamlines L7 traffic management by centralising policy enforcement to the destination workload's namespace or service account. +In contrast to traditional sidecar proxies, which reside alongside application pods, Waypoint proxies operate solely on the server-side, acting as reverse proxies for L7 traffic. This approach streamlines L7 traffic management by centralizing policy enforcement to the destination workload's namespace or service account. When a request originates from an application pod, it bypasses the client-side Waypoint proxy and directly reaches the server-side Waypoint proxy associated with the destination workload's namespace or service account. Istio enforces that all traffic coming into the namespace goes through the waypoint, which then enforces all policies for that namespace. Because of this, each waypoint only needs to know about configuration for its own namespace. Thus Waypoint proxy assumes responsibility for enforcing all L7 policies and routing rules applicable to the destination workload. @@ -190,21 +189,21 @@ link="destinationonly.svg" caption="Waypoint Proxies" >}} -Destination-only Waypoint simplifies the configuration process by eliminating the need for sidecar proxies and "exportTo" configurations. Waypoint proxies only need to be aware of the endpoints, pods, and workloads within their respective namespaces or service accounts. This streamlined approach reduces the complexity of L7 management and enables a more efficient use of resources. +Destination-only Waypoint simplifies the configuration process by eliminating the need for sidecar proxies and `exportTo` configurations. Waypoint proxies only need to be aware of the endpoints, pods, and workloads within their respective namespaces or service accounts. This streamlined approach reduces the complexity of L7 management and enables a more efficient use of resources. {{< image width="100%" link="destination-only-waypoint.svg" caption="Waypoint Proxies" >}} -- **Policy Enforcement**: In traditional Istio deployments, both source-side and destination-side policies were employed, which often led to confusion for users regarding policy enforcement and troubleshooting. Destination-only Waypoint simplifies this process by enforcing all policies exclusively at the destination workload's namespace or service account. This centralized approach eliminates the need to track policies across multiple locations, making it easier to understand, manage, and troubleshoot L7 security configurations. +* **Policy Enforcement**: In traditional Istio deployments, both source-side and destination-side policies were employed, which often led to confusion for users regarding policy enforcement and troubleshooting. Destination-only Waypoint simplifies this process by enforcing all policies exclusively at the destination workload's namespace or service account. This centralized approach eliminates the need to track policies across multiple locations, making it easier to understand, manage, and troubleshoot L7 security configurations. {{< image width="100%" link="policies-enforced (1).svg" caption="Policy Enforced on Destination Waypoint" >}} -- **Mixed Environment**: In a mixed environment where clients may reside inside or outside the Istio mesh, destination-only Waypoint ensures consistent policy enforcement regardless of the client's location. Since all policies are applied at the destination workload, users can be confident that security measures are consistently applied to all incoming traffic. +* **Mixed Environment**: In a mixed environment where clients may reside inside or outside the Istio mesh, destination-only Waypoint ensures consistent policy enforcement regardless of the client's location. Since all policies are applied at the destination workload, users can be confident that security measures are consistently applied to all incoming traffic. {{< image width="100%" link="mixed-environment.svg" @@ -225,4 +224,4 @@ When someone with Istio admin privileges sets up Istio mesh, it becomes availabl ### Basic application deployment without Ambient -This section is Under Construction... \ No newline at end of file +This section is Under Construction. From 76e88406c000e8c66ec300055cc2271998d295cf Mon Sep 17 00:00:00 2001 From: fykaa Date: Sun, 24 Dec 2023 14:06:24 +0530 Subject: [PATCH 11/19] resolved reviews --- .../docs/ops/ambient/usage/waypoint/index.md | 112 +++++++++--------- 1 file changed, 56 insertions(+), 56 deletions(-) diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index eb3bdd998fcf..2e8a6d56fac4 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -14,9 +14,9 @@ Please **do not run ambient in production** and be sure to thoroughly review the ## Introduction -This guide provides instructions on how to set up and use the Waypoint proxy layer in Istio Ambient Mesh. +This guide provides instructions on how to set up and use the waypoint proxy layer in Istio ambient mesh. -Istio Ambient Mesh is a new way to deploy and manage microservices. In Ambient Mesh, workloads are no longer required to run sidecar proxies to participate in the service mesh. Ambient splits Istio’s functionality into two distinct layers, a secure overlay layer and a Layer 7 processing layer. +Istio ambient mesh is a new way to deploy and manage microservices. In ambient mesh, workloads are no longer required to run sidecar proxies to participate in the service mesh. Ambient splits Istio’s functionality into two distinct layers, a secure overlay layer and a Layer 7 processing layer. Ztunnel is used to handle L3 and L4 networking functions, such as mTLS authentication and L4 authorization. The waypoint proxy is an optional component that is Envoy-based and is responsible for L7 service mesh functionalities. For workloads that require L7 networking features, such as HTTP load balancing and fault injection, a waypoint proxy must be deployed. It can also enforce L7 policies and collect L7 metrics. @@ -25,30 +25,30 @@ Ztunnel is used to handle L3 and L4 networking functions, such as mTLS authentic Before you begin, make sure that you have already read the [Ztunnel Networking sub-guide](../ztunnel/). This guide assumes that you have the following prerequisites in place: -1. Istio Ambient Mesh installed and configured +1. Istio ambient mesh installed and configured 2. Ztunnel proxy is installed and running {{}} -This guide describes the functionality and usage of the waypoint proxy and L7 networking functions using Istio Ambient Mesh. We use a sample user journey to describe these functions hence it would be useful to go through this guide in sequence. However we provide links to the sections below in case the reader would like to jump to the appropriate section. +This guide describes the functionality and usage of the waypoint proxy and L7 networking functions using Istio ambient mesh. We use a sample user journey to describe these functions hence it would be useful to go through this guide in sequence. However we provide links to the sections below in case the reader would like to jump to the appropriate section. * [Introduction](#introduction) -* [Deciding if you need A Waypoint Proxy](#deciding-if-you-need-a-waypoint-proxy) -* [Current Challenges](#current-challenges) - -* [Deciding the scope of your Waypoint Proxy](#Deciding-the-scope-of-your-Waypoint-Proxy) -* [Functional Overview](#functional-overview) -* [Deploying an Application](#deploying-an-application) -* [Configuring Waypoint proxy](#configuring-waypoint-proxy) -* [Monitoring the Waypoint Proxy & L7 Networking](#monitoring-the-waypoint-proxy--l7-networking) -* [L7 Fault Injection](#l7-fault-injection) -* [L7 Observability](#l7-observability) -* [L7 Authorization Policy](#l7-authorization-policy) -* [Co-existence of Ambient/ L7 with Side car proxies](#Co-existence-of-Ambient/-L7-with-Side-car-proxies) -* [Control Traffic towards Waypoint Proxy](##control-traffic-towards-waypoint-proxy) -* [Remove Waypoint proxy layer](#remove-waypoint-proxy-layer) - -## Deciding if you need A Waypoint proxy +* [Deciding if you need a waypoint proxy](#deciding-if-you-need-a-waypoint-proxy) +* [Current challenges](#current-challenges) + +* [Deciding the scope of your waypoint proxy](#Deciding-the-scope-of-your-waypoint-proxy) +* [Functional overview](#functional-overview) +* [Deploying an application](#deploying-an-application) +* [Configuring waypoint proxy](#configuring-waypoint-proxy) +* [Monitoring the waypoint proxy & L7 networking](#monitoring-the-waypoint-proxy--l7-networking) +* [L7 fault injection](#l7-fault-injection) +* [L7 observability](#l7-observability) +* [L7 authorization policy](#l7-authorization-policy) +* [Co-existence of ambient/ L7 with Side car proxies](#Co-existence-of-ambient/-L7-with-side-car-proxies) +* [Control traffic towards waypoint proxy](##control-traffic-towards-waypoint-proxy) +* [Remove waypoint proxy layer](#remove-waypoint-proxy-layer) + +## Deciding if you need a waypoint proxy It's possible that the features offered by the secure overlay doesn’t meet your requirements. For instance, you need a rich Layer 7 authorization policy that sets up access based on a certain method and path. Alternatively you may like to conduct a canary test on the updated version of your service or introduce a new version without affecting current traffic. Or, you would like to receive metrics, HTTP access logs, and distributed tracing for some of your services. In order to accomplish these common cases, we'll go over how you can choose to enforce L7 processing with ambient mesh in this section. @@ -56,7 +56,7 @@ It's possible that the features offered by the secure overlay doesn’t meet you In summary, the waypoint proxy approach for the L7 processing layer offers the following four main advantages: -* Traffic Resiliency - Timeout and retry, circuit breaking +* Traffic resiliency - Timeout and retry, circuit breaking * Security - Rich L7 authorization policy * Observability - HTTP metrics, access logs, and tracing * Traffic management - Dark launch, canary test @@ -78,60 +78,60 @@ To get started with the waypoint proxy and L7 networking features, you will need This guide will provide more detailed instructions on how to deploy and configure the waypoint proxy and L7 networking features. -## Current Challenges +## Current challenges -Unlike Ztunnel proxies, Waypoint proxies are not automatically installed with Istio ambient mesh. Waypoint proxies are deployed declaratively using Kubernetes Gateway resources or the helpful `istioctl` command. The minimum Istio version required for Istio ambient mode is `1.18.0`. In general Istio in ambient mode supports the existing Istio APIs that are supported in sidecar proxy mode. Since the ambient functionality is currently at an alpha release level, the following is a list of feature restrictions or caveats in the current release of Istio's ambient functionality (as of the `1.20.0` release). These restrictions are expected to be addressed/removed in future software releases as ambient graduates to beta and eventually General Availability. +Unlike Ztunnel proxies, waypoint proxies are not automatically installed with Istio ambient mesh. Waypoint proxies are deployed declaratively using Kubernetes Gateway resources or the helpful `istioctl` command. The minimum Istio version required for Istio ambient mode is `1.18.0`. In general Istio in ambient mode supports the existing Istio APIs that are supported in sidecar proxy mode. Since the ambient functionality is currently at an alpha release level, the following is a list of feature restrictions or caveats in the current release of Istio's ambient functionality (as of the `1.20.0` release). These restrictions are expected to be addressed/removed in future software releases as ambient graduates to beta and eventually General Availability. -1. **`PeerAuthentication` Limitations:** As of now, not all components (i.e. Waypoint proxies), support the `PeerAuthentication` resource in Istio Ambient mode. Hence it is recommended to use the `STRICT` mTLS mode currently, this caveat shall be addressed as the feature moves toward beta status. +1. **`PeerAuthentication` Limitations:** As of now, not all components (i.e. waypoint proxies), support the `PeerAuthentication` resource in Istio ambient mode. Hence it is recommended to use the `STRICT` mTLS mode currently, this caveat shall be addressed as the feature moves toward beta status. -1. **No HTTP/3 support:** Waypoint supports HTTP/2, but there are some limitations with HTTP/3 support when using HBONE (HTTP-Based Overlay Network Encapsulation). HBONE is currently limited to HTTP/2 transport, so while Waypoint can handle HTTP/2 traffic, it cannot yet fully support HTTP/3. +1. **No HTTP/3 support:** Waypoint supports HTTP/2, but there are some limitations with HTTP/3 support when using HBONE (HTTP-Based Overlay Network Encapsulation). HBONE is currently limited to HTTP/2 transport, so while waypoint can handle HTTP/2 traffic, it cannot yet fully support HTTP/3. -Despite these caveats, Waypoint is a powerful tool for enabling L7 networking and services for Istio Ambient workloads. It is a good choice for users who are looking for a way to run microservices-based applications in Ambient mode. +Despite these caveats, waypoint is a powerful tool for enabling L7 networking and services for Istio ambient workloads. It is a good choice for users who are looking for a way to run microservices-based applications in ambient mode. ### Environment used for this guide For the environment used in this guide, refer to the [Installation user](../install/) guide or [L4 Networking & mTLS with Ztunnel](../ztunnel/) guide on installing Istio in ambient mode on a Kubernetes cluster. -## Deciding the scope of your Waypoint proxy +## Deciding the scope of your waypoint proxy Waypoint proxies can be deployed at the namespace(default) or service account level. The scope you choose depends on your specific needs and requirements. ### Namespace-level scope -Deploying Waypoint proxies at the namespace level provides a number of benefits, including: +Deploying waypoint proxies at the namespace level provides a number of benefits, including: - Simplified policy management: Policies are enforced at the namespace level, so you only need to define them once for all workloads in the namespace. - Improved performance: Waypoint proxies can cache routing and policy information, which can improve performance for workloads in the namespace. - Increased security: Waypoint proxies can enforce authorization policies at the namespace level, which can help to protect your workloads from unauthorized access. -However, deploying Waypoint proxies at the namespace level also has some drawbacks, including: +However, deploying waypoint proxies at the namespace level also has some drawbacks, including: - Limited granularity: You cannot apply different policies to different workloads in the same namespace. -- Increased resource consumption: Each namespace will require its own Waypoint proxy, which can consume more resources. +- Increased resource consumption: Each namespace will require its own waypoint proxy, which can consume more resources. ### Service account-level scope -Deploying Waypoint proxies at the service account level provides a number of benefits, including: +Deploying waypoint proxies at the service account level provides a number of benefits, including: - Increased granularity: You can apply different policies to different workloads based on their service account. -- Reduced resource consumption: You only need to deploy a Waypoint proxy for each service account that has workloads that require L7 routing or policy enforcement. +- Reduced resource consumption: You only need to deploy a waypoint proxy for each service account that has workloads that require L7 routing or policy enforcement. -However, deploying Waypoint proxies at the service account level also has some drawbacks, including: +However, deploying waypoint proxies at the service account level also has some drawbacks, including: * Increased complexity: Managing policies at the service account level can be more complex, especially if you have a large number of service accounts. * Reduced caching: Waypoint proxies cannot cache routing and policy information at the service account level, which can reduce performance. -### How to choose the right scope for your Waypoint proxies +### How to choose the right scope for your waypoint proxies -The best scope for your Waypoint proxies will depend on your specific needs and requirements. If you have a simple application with a small number of workloads, then namespace-level scope may be a good choice. However, if you have a more complex application with a large number of workloads or if you need to apply different policies to different workloads, then service account-level scope may be a better choice. +The best scope for your waypoint proxies will depend on your specific needs and requirements. If you have a simple application with a small number of workloads, then namespace-level scope may be a good choice. However, if you have a more complex application with a large number of workloads or if you need to apply different policies to different workloads, then service account-level scope may be a better choice. -Here are some factors to consider when choosing the scope for your Waypoint proxies: +Here are some factors to consider when choosing the scope for your waypoint proxies: * The number of workloads in your application * The complexity of your application * The need to apply different policies to different workloads * The performance requirements of your application * The resource requirements of your application -## Functional Overview +## Functional overview -The functional behavior of the waypoint proxy is dynamically configured by Istio to serve your applications configurations. This section takes a brief look at these functional aspects - detailed description of the internal design of the waypoint proxy is out of scope for this guide. The detailed functional overview from the Secure Overlay Networking was already discussed in the [Ztunnel L4 Networking Guide](https://deploy-preview-13635--preliminary-istio.netlify.app/latest/docs/ops/ambient/usage/ztunnel/#functionaloverview) hence this section only focuses on functionalities and features that Waypoint Proxy provides. +The functional behavior of the waypoint proxy is dynamically configured by Istio to serve your applications configurations. This section takes a brief look at these functional aspects - detailed description of the internal design of the waypoint proxy is out of scope for this guide. The detailed functional overview from the Secure Overlay Networking was already discussed in the [Ztunnel L4 Networking Guide](https://deploy-preview-13635--preliminary-istio.netlify.app/latest/docs/ops/ambient/usage/ztunnel/#functionaloverview) hence this section only focuses on functionalities and features that waypoint proxy provides. {{< image width="100%" link="waypoint-architecture.png" @@ -140,7 +140,7 @@ caption="Waypoint architecture" What is unique about the waypoint proxy is that it runs either per-namespace (default) or per-service account. By running outside of the application pod, a waypoint proxy can install, upgrade, and scale independently from the application pod, providing a centralized approach to managing L7 traffic and enforcing policies as well as reduce operational costs. -Upon deployment of a gateway resource using the `kubectl apply` command, Istio's control plane, IstioD, assumes the role of the Waypoint controller. Recognizing the gateway resource with the "istio.io/waypoint" gateway class name, istiod automatically deploys the Waypoint proxy based on the specified configuration in the gateway resource. +Upon deployment of a gateway resource using the `kubectl apply` command, Istio's control plane, IstioD, assumes the role of the waypoint controller. Recognizing the gateway resource with the "istio.io/waypoint" gateway class name, istiod automatically deploys the waypoint proxy based on the specified configuration in the gateway resource. The waypoint proxy's data plane operates at Layer 7, enabling it to fully parse connections into individual requests and apply policies based on request properties such as headers and credentials. This granular control over L7 traffic extends to a comprehensive suite of capabilities, including: - HTTP 1.x, 2, or 3 @@ -167,61 +167,61 @@ caption="Traffic will flow through L7 waypoint proxies when there are L7 policie Tenancy for Layer 7 capabilities in the Istio ambient mesh is similar to the sidecar deployment model. L7 capabilities are not shared across multiple identities within a single L7 proxy. Each application has its own dedicated waypoint proxy, ensuring isolation of configuration and extensions (plug-ins, extensions, etc.) specific to individual workloads. This isolation prevents interference between workloads and facilitates independent management of L7 configurations. -Functionally, the Waypoint proxy resembles the sidecar proxy but operates independently of application pods. It has its own CA client and XDS client, enabling secure communication with istioD. To obtain its identity certificate, the Waypoint proxy establishes a secure connection with istioD, requesting certification. Upon validating the presented token, istioD signs the Waypoint proxy's certificate, granting it access to the Istio control plane. +Functionally, the waypoint proxy resembles the sidecar proxy but operates independently of application pods. It has its own CA client and XDS client, enabling secure communication with istioD. To obtain its identity certificate, the Waypoint proxy establishes a secure connection with istioD, requesting certification. Upon validating the presented token, istioD signs the Waypoint proxy's certificate, granting it access to the Istio control plane. -Subsequently, the Waypoint proxy initiates communication with istioD, requesting XDS configuration to govern its operation. This configuration defines the L7 routing rules, policy enforcement mechanisms, and other parameters essential for managing L7 traffic. +Subsequently, the waypoint proxy initiates communication with istioD, requesting XDS configuration to govern its operation. This configuration defines the L7 routing rules, policy enforcement mechanisms, and other parameters essential for managing L7 traffic. -In essence, the Waypoint proxy serves as an L7 traffic management hub, decoupled from application pods and centrally managed by istioD. This architecture simplifies L7 configuration and policy enforcement, enabling efficient and scalable L7 services within Istio Ambient deployments as shown in the figure - +In essence, the waypoint proxy serves as an L7 traffic management hub, decoupled from application pods and centrally managed by istioD. This architecture simplifies L7 configuration and policy enforcement, enabling efficient and scalable L7 services within Istio ambient deployments as shown in the figure - {{< image width="100%" link="waypoint-architecture-deep-dive.svg" caption="Waypoint Architecture Deep Dive" >}} -### Destination Only Waypoint +### Destination only waypoint -In contrast to traditional sidecar proxies, which reside alongside application pods, Waypoint proxies operate solely on the server-side, acting as reverse proxies for L7 traffic. This approach streamlines L7 traffic management by centralizing policy enforcement to the destination workload's namespace or service account. +In contrast to traditional sidecar proxies, which reside alongside application pods, waypoint proxies operate solely on the server-side, acting as reverse proxies for L7 traffic. This approach streamlines L7 traffic management by centralizing policy enforcement to the destination workload's namespace or service account. -When a request originates from an application pod, it bypasses the client-side Waypoint proxy and directly reaches the server-side Waypoint proxy associated with the destination workload's namespace or service account. Istio enforces that all traffic coming into the namespace goes through the waypoint, which then enforces all policies for that namespace. Because of this, each waypoint only needs to know about configuration for its own namespace. Thus Waypoint proxy assumes responsibility for enforcing all L7 policies and routing rules applicable to the destination workload. +When a request originates from an application pod, it bypasses the client-side waypoint proxy and directly reaches the server-side waypoint proxy associated with the destination workload's namespace or service account. Istio enforces that all traffic coming into the namespace goes through the waypoint, which then enforces all policies for that namespace. Because of this, each waypoint only needs to know about configuration for its own namespace. Thus waypoint proxy assumes responsibility for enforcing all L7 policies and routing rules applicable to the destination workload. {{< image width="100%" link="destinationonly.svg" -caption="Waypoint Proxies" +caption="Waypoint proxies" >}} -Destination-only Waypoint simplifies the configuration process by eliminating the need for sidecar proxies and `exportTo` configurations. Waypoint proxies only need to be aware of the endpoints, pods, and workloads within their respective namespaces or service accounts. This streamlined approach reduces the complexity of L7 management and enables a more efficient use of resources. +Destination-only waypoint simplifies the configuration process by eliminating the need for sidecar proxies and `exportTo` configurations. Waypoint proxies only need to be aware of the endpoints, pods, and workloads within their respective namespaces or service accounts. This streamlined approach reduces the complexity of L7 management and enables a more efficient use of resources. {{< image width="100%" link="destination-only-waypoint.svg" -caption="Waypoint Proxies" +caption="Waypoint proxies" >}} -* **Policy Enforcement**: In traditional Istio deployments, both source-side and destination-side policies were employed, which often led to confusion for users regarding policy enforcement and troubleshooting. Destination-only Waypoint simplifies this process by enforcing all policies exclusively at the destination workload's namespace or service account. This centralized approach eliminates the need to track policies across multiple locations, making it easier to understand, manage, and troubleshoot L7 security configurations. +* **Policy Enforcement**: In traditional Istio deployments, both source-side and destination-side policies were employed, which often led to confusion for users regarding policy enforcement and troubleshooting. Destination-only waypoint simplifies this process by enforcing all policies exclusively at the destination workload's namespace or service account. This centralized approach eliminates the need to track policies across multiple locations, making it easier to understand, manage, and troubleshoot L7 security configurations. {{< image width="100%" link="policies-enforced (1).svg" -caption="Policy Enforced on Destination Waypoint" +caption="Policy Enforced on Destination waypoint" >}} -* **Mixed Environment**: In a mixed environment where clients may reside inside or outside the Istio mesh, destination-only Waypoint ensures consistent policy enforcement regardless of the client's location. Since all policies are applied at the destination workload, users can be confident that security measures are consistently applied to all incoming traffic. +* **Mixed Environment**: In a mixed environment where clients may reside inside or outside the Istio mesh, destination-only waypoint ensures consistent policy enforcement regardless of the client's location. Since all policies are applied at the destination workload, users can be confident that security measures are consistently applied to all incoming traffic. {{< image width="100%" link="mixed-environment.svg" -caption="Waypoint Proxies" +caption="Waypoint proxies" >}} -### Handling Destinations without Waypoint Proxies +### Handling destinations without waypoint proxies -While destination-only Waypoint offers centralized policy enforcement and simplified configuration, there may be instances where the destination workload doesn't have a waypoint proxy deployed. This could arise when connecting to external services beyond the control of the Istio mesh. +While destination-only waypoint offers centralized policy enforcement and simplified configuration, there may be instances where the destination workload doesn't have a waypoint proxy deployed. This could arise when connecting to external services beyond the control of the Istio mesh. To address this scenario, the Istio community is actively developing mechanisms to route traffic to the egress gateway and enable policy enforcement for destinations without waypoint proxies. This functionality will allow users to configure resilience-enhancing policies, such as timeouts, for external services. Please stay tuned for future blog posts and documentation updates that will provide detailed information on this evolving feature. -## Deploying an Application +## Deploying an application When someone with Istio admin privileges sets up Istio mesh, it becomes available for all users in specific namespaces. The examples below shows how Istio can be used transparently once it's successfully deployed in ambient mode and the namespaces are annotated accordingly. -### Basic application deployment without Ambient +### Basic application deployment without ambient This section is Under Construction. From f2be4f4987c50a4b0a804fed341152afff1dfd75 Mon Sep 17 00:00:00 2001 From: Lin Sun Date: Wed, 31 Jan 2024 15:04:14 -0500 Subject: [PATCH 12/19] Update content/en/docs/ops/ambient/usage/waypoint/index.md Co-authored-by: Daniel Hawton --- content/en/docs/ops/ambient/usage/waypoint/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index 2e8a6d56fac4..2869719801da 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -90,7 +90,7 @@ Despite these caveats, waypoint is a powerful tool for enabling L7 networking an ### Environment used for this guide -For the environment used in this guide, refer to the [Installation user](../install/) guide or [L4 Networking & mTLS with Ztunnel](../ztunnel/) guide on installing Istio in ambient mode on a Kubernetes cluster. +For the environment used in this guide, refer to the [Installation user](../../install/) guide or [L4 Networking & mTLS with Ztunnel](../ztunnel/) guide on installing Istio in ambient mode on a Kubernetes cluster. ## Deciding the scope of your waypoint proxy From 5b1c5ad58ed93106e5f98ae6a24948150d1cdcb5 Mon Sep 17 00:00:00 2001 From: Lin Sun Date: Wed, 31 Jan 2024 15:04:29 -0500 Subject: [PATCH 13/19] Update content/en/docs/ops/ambient/usage/waypoint/index.md Co-authored-by: Daniel Hawton --- content/en/docs/ops/ambient/usage/waypoint/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index 2869719801da..ff40a8633407 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -9,7 +9,7 @@ test: no {{< warning >}} Ambient is currently in [alpha status](/docs/releases/feature-stages/#feature-phase-definitions). -Please **do not run ambient in production** and be sure to thoroughly review the [feature phase definitions](/docs/releases/feature-stages/#feature-phase-definitions) before use. In particular, there are known performance, stability, and security issues in the `alpha` release. There are also functional caveats some of which are listed in the [Caveats section](#caveats) of this guide. There are also planned breaking changes, including some that will prevent upgrades. These are all limitations that will be addressed before graduation to `beta`. The current version of this guide is meant to assist early deployments and testing of the alpha version of `ambient`. The guide will continue to get updated as `ambient` itself evolves from alpha to beta status and beyond. +Please **do not run ambient in production** and be sure to thoroughly review the [feature phase definitions](/docs/releases/feature-stages/#feature-phase-definitions) before use. In particular, there are known performance, stability, and security issues in the `alpha` release. There are also functional caveats some of which are listed in the [Caveats section](#caveats) of this guide. There are also planned breaking changes, including some that will prevent upgrades. These are all limitations that will be addressed before graduation to `beta`. The current version of this guide is meant to assist early deployments and testing of the alpha version of ambient. The guide will continue to get updated as ambient itself evolves from alpha to beta status and beyond. {{< /warning >}} ## Introduction From a951d7769d788f8355f3d6f2af188ca98fc72d28 Mon Sep 17 00:00:00 2001 From: Lin Sun Date: Wed, 31 Jan 2024 15:04:40 -0500 Subject: [PATCH 14/19] Update content/en/docs/ops/ambient/usage/waypoint/index.md Co-authored-by: Nina Polshakova --- content/en/docs/ops/ambient/usage/waypoint/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index ff40a8633407..e319af64b3b3 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -140,7 +140,7 @@ caption="Waypoint architecture" What is unique about the waypoint proxy is that it runs either per-namespace (default) or per-service account. By running outside of the application pod, a waypoint proxy can install, upgrade, and scale independently from the application pod, providing a centralized approach to managing L7 traffic and enforcing policies as well as reduce operational costs. -Upon deployment of a gateway resource using the `kubectl apply` command, Istio's control plane, IstioD, assumes the role of the waypoint controller. Recognizing the gateway resource with the "istio.io/waypoint" gateway class name, istiod automatically deploys the waypoint proxy based on the specified configuration in the gateway resource. +Upon deployment of a gateway resource using the `kubectl apply` command, Istio's control plane, istiod, assumes the role of the waypoint controller. Recognizing the gateway resource with the "istio.io/waypoint" gateway class name, istiod automatically deploys the waypoint proxy based on the specified configuration in the gateway resource. The waypoint proxy's data plane operates at Layer 7, enabling it to fully parse connections into individual requests and apply policies based on request properties such as headers and credentials. This granular control over L7 traffic extends to a comprehensive suite of capabilities, including: - HTTP 1.x, 2, or 3 From d5277c29e38c6e2a0e84a47307ee19f303d2f8ba Mon Sep 17 00:00:00 2001 From: Lin Sun Date: Wed, 31 Jan 2024 15:05:09 -0500 Subject: [PATCH 15/19] Update content/en/docs/ops/ambient/usage/waypoint/index.md Co-authored-by: Nina Polshakova --- content/en/docs/ops/ambient/usage/waypoint/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index e319af64b3b3..8ede8b037249 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -131,7 +131,7 @@ Here are some factors to consider when choosing the scope for your waypoint prox ## Functional overview -The functional behavior of the waypoint proxy is dynamically configured by Istio to serve your applications configurations. This section takes a brief look at these functional aspects - detailed description of the internal design of the waypoint proxy is out of scope for this guide. The detailed functional overview from the Secure Overlay Networking was already discussed in the [Ztunnel L4 Networking Guide](https://deploy-preview-13635--preliminary-istio.netlify.app/latest/docs/ops/ambient/usage/ztunnel/#functionaloverview) hence this section only focuses on functionalities and features that waypoint proxy provides. +The functional behavior of the waypoint proxy is dynamically configured by Istio to serve your application's configurations. This section takes a brief look at these functional aspects - detailed description of the internal design of the waypoint proxy is out of scope for this guide. The detailed functional overview from the Secure Overlay Networking was already discussed in the [Ztunnel L4 Networking Guide](https://deploy-preview-13635--preliminary-istio.netlify.app/latest/docs/ops/ambient/usage/ztunnel/#functionaloverview) hence this section only focuses on functionalities and features that waypoint proxy provides. {{< image width="100%" link="waypoint-architecture.png" From f3ca472a66bcb37abac6a45adefc4a5457554024 Mon Sep 17 00:00:00 2001 From: Lin Sun Date: Wed, 31 Jan 2024 15:05:19 -0500 Subject: [PATCH 16/19] Update content/en/docs/ops/ambient/usage/waypoint/index.md Co-authored-by: Nina Polshakova --- content/en/docs/ops/ambient/usage/waypoint/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index 8ede8b037249..dc36984218f6 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -167,7 +167,7 @@ caption="Traffic will flow through L7 waypoint proxies when there are L7 policie Tenancy for Layer 7 capabilities in the Istio ambient mesh is similar to the sidecar deployment model. L7 capabilities are not shared across multiple identities within a single L7 proxy. Each application has its own dedicated waypoint proxy, ensuring isolation of configuration and extensions (plug-ins, extensions, etc.) specific to individual workloads. This isolation prevents interference between workloads and facilitates independent management of L7 configurations. -Functionally, the waypoint proxy resembles the sidecar proxy but operates independently of application pods. It has its own CA client and XDS client, enabling secure communication with istioD. To obtain its identity certificate, the Waypoint proxy establishes a secure connection with istioD, requesting certification. Upon validating the presented token, istioD signs the Waypoint proxy's certificate, granting it access to the Istio control plane. +Functionally, the waypoint proxy resembles the sidecar proxy but operates independently of application pods. It has its own CA client and XDS client, enabling secure communication with istiod. To obtain its identity certificate, the Waypoint proxy establishes a secure connection with istiod, requesting certification. Upon validating the presented token, istiod signs the Waypoint proxy's certificate, granting it access to the Istio control plane. Subsequently, the waypoint proxy initiates communication with istioD, requesting XDS configuration to govern its operation. This configuration defines the L7 routing rules, policy enforcement mechanisms, and other parameters essential for managing L7 traffic. From 8fef477784c982fcc7b45f54c44e04e12cd1dfba Mon Sep 17 00:00:00 2001 From: Lin Sun Date: Wed, 31 Jan 2024 15:06:30 -0500 Subject: [PATCH 17/19] Update content/en/docs/ops/ambient/usage/waypoint/index.md Co-authored-by: Nina Polshakova --- content/en/docs/ops/ambient/usage/waypoint/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index dc36984218f6..227e65a7e732 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -44,7 +44,7 @@ This guide describes the functionality and usage of the waypoint proxy and L7 ne * [L7 fault injection](#l7-fault-injection) * [L7 observability](#l7-observability) * [L7 authorization policy](#l7-authorization-policy) -* [Co-existence of ambient/ L7 with Side car proxies](#Co-existence-of-ambient/-L7-with-side-car-proxies) +* [Co-existence of ambient/ L7 with Sidecar proxies](#Co-existence-of-ambient/-L7-with-side-car-proxies) * [Control traffic towards waypoint proxy](##control-traffic-towards-waypoint-proxy) * [Remove waypoint proxy layer](#remove-waypoint-proxy-layer) From 8b55edb21ef033b701e6979727ee32608a3a49da Mon Sep 17 00:00:00 2001 From: Lin Sun Date: Wed, 31 Jan 2024 15:12:22 -0500 Subject: [PATCH 18/19] Update content/en/docs/ops/ambient/usage/waypoint/index.md Co-authored-by: Daniel Hawton --- content/en/docs/ops/ambient/usage/waypoint/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/ops/ambient/usage/waypoint/index.md b/content/en/docs/ops/ambient/usage/waypoint/index.md index 227e65a7e732..fc956d481ebd 100644 --- a/content/en/docs/ops/ambient/usage/waypoint/index.md +++ b/content/en/docs/ops/ambient/usage/waypoint/index.md @@ -90,7 +90,7 @@ Despite these caveats, waypoint is a powerful tool for enabling L7 networking an ### Environment used for this guide -For the environment used in this guide, refer to the [Installation user](../../install/) guide or [L4 Networking & mTLS with Ztunnel](../ztunnel/) guide on installing Istio in ambient mode on a Kubernetes cluster. +For the environment used in this guide, refer to the [Installation user](../../install/) guide or [L4 Networking & mTLS with ztunnel](../ztunnel/) guide on installing Istio in ambient mode on a Kubernetes cluster. ## Deciding the scope of your waypoint proxy From dcf7feee2a4b6accbc749dd335c6f69d620a62eb Mon Sep 17 00:00:00 2001 From: Craig Box Date: Tue, 12 Mar 2024 19:35:04 +1300 Subject: [PATCH 19/19] oh I see --- content/en/docs/ops/ambient/usage/_index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/en/docs/ops/ambient/usage/_index.md b/content/en/docs/ops/ambient/usage/_index.md index 3afe5ccf45c4..6695d1d278fb 100644 --- a/content/en/docs/ops/ambient/usage/_index.md +++ b/content/en/docs/ops/ambient/usage/_index.md @@ -1,3 +1,4 @@ +--- title: Ambient Mode User Guides description: How to configure a mesh in ambient mode. weight: 15