mirror of https://github.com/istio/istio.io.git
Moving/Updating the WasmPlugin tutorial and Adding ImagePullPolicy description (#11379)
* Update for Wasm contents * Fix the wrong cleanup code * Fix the description of `extensibility` folder's description * Apply suggestions from code review Co-authored-by: craigbox <craigbox@google.com> * Update _index.md * Regenerate snips * Add old URL path as an alias * Update content/en/docs/tasks/extensibility/_index.md * Add description for the wasm pull policy Signed-off-by: Ingwon Song <igsong@google.com> * Apply suggestions from code review Co-authored-by: Douglas Reid <douglas-reid@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: craigbox <craigbox@google.com> * Applying the comment from @dgn Co-authored-by: craigbox <craigbox@google.com> Co-authored-by: Douglas Reid <douglas-reid@users.noreply.github.com>
This commit is contained in:
Ingwon Song
GitHub
parent
0b8bc9f3d4
commit
3ecc5aeb4a
|
|
@ -13,4 +13,4 @@ For built-in adapters, several alternatives are provided:
|
|||
* Global and Local Rate-Limiting (`memquota` and `redisquota` adapters) functionality is provided through the [Envoy-based rate-limiting solution](/docs/tasks/policy-enforcement/rate-limit/).
|
||||
* `OPA` adapter is replaced by the [Envoy ext-authz based solution](/docs/tasks/security/authorization/authz-custom/), which supports [integration with OPA policy agent](https://www.openpolicyagent.org/docs/latest/envoy-introduction/).
|
||||
|
||||
For custom out-of-process adapters, migration to Wasm-based extensions is strongly encouraged. Please refer to the guides on [Wasm module development](https://github.com/istio-ecosystem/wasm-extensions/blob/master/doc/write-a-wasm-extension-with-cpp.md) and [extension distribution](/docs/ops/configuration/extensibility/wasm-module-distribution/). As a temporary solution, you can [enable Envoy ext-authz and gRPC access log API support in Mixer](https://github.com/istio/istio/wiki/Enabling-Envoy-Authorization-Service-and-gRPC-Access-Log-Service-With-Mixer), which allows you to upgrade Istio to post 1.7 versions while still using 1.7 Mixer with out-of-process adapters. This will give you more time to migrate to Wasm-based extensions. Note this temporary solution is not battle-tested and will unlikely get patch fixes, since it is only available on the Istio 1.7 branch which is out of support window after Feb 2021.
|
||||
For custom out-of-process adapters, migration to Wasm-based extensions is strongly encouraged. Please refer to the guides on [Wasm module development](https://github.com/istio-ecosystem/wasm-extensions/blob/master/doc/write-a-wasm-extension-with-cpp.md) and [extension distribution](/docs/tasks/extensibility/wasm-module-distribution/). As a temporary solution, you can [enable Envoy ext-authz and gRPC access log API support in Mixer](https://github.com/istio/istio/wiki/Enabling-Envoy-Authorization-Service-and-gRPC-Access-Log-Service-With-Mixer), which allows you to upgrade Istio to post 1.7 versions while still using 1.7 Mixer with out-of-process adapters. This will give you more time to migrate to Wasm-based extensions. Note this temporary solution is not battle-tested and will unlikely get patch fixes, since it is only available on the Istio 1.7 branch which is out of support window after Feb 2021.
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ To fix this issue, [a fundamental change](https://github.com/envoyproxy/envoy/is
|
|||
Istio 1.9 provides a reliable distribution mechanism out of the box by leveraging the xDS proxy inside istio-agent and Envoy's [Extension Configuration Discovery Service](https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/extension) (ECDS).
|
||||
|
||||
istio-agent intercepts the extension config resource update from istiod, reads the remote fetch hint from it, downloads the Wasm module, and rewrites the ECDS configuration with the path of the downloaded Wasm module.
|
||||
If the download fails, istio-agent will reject the ECDS update and prevent a bad configuration reaching Envoy. For more detail, please see [our docs on Wasm module distribution](/docs/ops/configuration/extensibility/wasm-module-distribution/).
|
||||
If the download fails, istio-agent will reject the ECDS update and prevent a bad configuration reaching Envoy. For more detail, please see [our docs on Wasm module distribution](/docs/tasks/extensibility/wasm-module-distribution/).
|
||||
|
||||
{{< image width="75%"
|
||||
link="./architecture-istio-agent-downloading-wasm-module.svg"
|
||||
|
|
|
|||
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
title: Pull Policy for WebAssembly Modules
|
||||
description: Describes how Istio determines whether to pull Wasm modules or use cached versions.
|
||||
weight: 10
|
||||
keywords: [extensibility,Wasm,WebAssembly]
|
||||
owner: istio/wg-policies-and-telemetry-maintainers
|
||||
test: n/a
|
||||
status: Alpha
|
||||
---
|
||||
|
||||
The [WasmPlugin API](/docs/reference/config/proxy_extensions/wasm-plugin) provides a method for [distributing Wasm modules](/docs/tasks/extensibility/wasm-module-distribution) to proxies.
|
||||
Since each proxy will pull Wasm modules from a remote registry or an HTTP server, understanding how Istio chooses to pull modules is important in terms of usability as well as performance.
|
||||
|
||||
## Image pull policy and exceptions
|
||||
|
||||
Analogous to `ImagePullPolicy` of Kubernetes, [WasmPlugin](/docs/reference/config/proxy_extensions/wasm-plugin/#WasmPlugin) also has the notion of `IfNotPresent` and `Always`, which means "use the cached module" and "always pull the module regardless of the cache", respectively.
|
||||
|
||||
Users explicitly configure the behavior for Wasm module retrieval with the `ImagePullPolicy` field. However, user-provided behavior can be overridden by Istio in the following scenarios:
|
||||
|
||||
1. If the user sets `sha256` in [WasmPlugin](/docs/reference/config/proxy_extensions/wasm-plugin/#WasmPlugin), regardless of `ImagePullPolicy`, `IfNotPresent` policy is used.
|
||||
1. If the `url` field points to an OCI image and it has a digest suffix (e.g., `gcr.io/foo/bar@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`), `IfNotPresent` policy is used.
|
||||
|
||||
When `ImagePullPolicy` is not specified for a resource, Istio defaults to `IfNotPresent` behavior. However, if the provided `url` field specifies an OCI image that has a tag value of `latest`, Istio will use `Always` behavior.
|
||||
|
||||
## Lifecycle of cached modules
|
||||
|
||||
Each proxy, whether a sidecar proxy or a gateway, caches Wasm modules. The lifetime of the cached Wasm module is therefore bounded by the lifetime of the corresponding pod.
|
||||
In addition, there is an expiration mechanism for keeping the proxy memory footprint to a minimum: if a cached Wasm module is not used for a certain amount of the time, the module is purged.
|
||||
|
||||
This expiration can be configured via the environment variables `WASM_MODULE_EXPIRY` and `WASM_PURGE_INTERVAL` of [pilot-proxy](/docs/reference/commands/pilot-agent/#envvars), which are the duration of expiration and the interval for checking the expiration respectively.
|
||||
|
||||
## The meaning of "Always"
|
||||
|
||||
In Kubernetes, `ImagePullPolicy: Always` means that an image is pulled directly from its source each time a pod is created.
|
||||
Every time a new pod is started, Kubernetes pulls the image anew.
|
||||
|
||||
For a `WasmPlugin`, `ImagePullPolicy: Always` means that Istio will pull an image directly from its source each time the corresponding `WasmPlugin` Kubernetes resource is created or changed.
|
||||
Please note that a change not only in `spec` but also `metadata` triggers the pulling of a Wasm module when the `Always` policy is used. This can mean that an image is pulled from source several times over the lifetime of a pod, and over the lifetime of an individual proxy.
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
title: Extensibility
|
||||
description: Demonstrates how to extend mesh behavior.
|
||||
weight: 45
|
||||
keywords: [extensibility,WebAssembly,Wasm]
|
||||
test: n/a
|
||||
---
|
||||
|
|
@ -5,9 +5,10 @@ weight: 10
|
|||
aliases:
|
||||
- /help/ops/extensibility/distribute-remote-wasm-module
|
||||
- /docs/ops/extensibility/distribute-remote-wasm-module
|
||||
- /ops/configuration/extensibility/wasm-module-distribution
|
||||
keywords: [extensibility,Wasm,WebAssembly]
|
||||
owner: istio/wg-policies-and-telemetry-maintainers
|
||||
test: no
|
||||
test: yes
|
||||
status: Alpha
|
||||
---
|
||||
|
||||
|
|
@ -16,13 +17,18 @@ One of the key advantages of Wasm extensibility is that extensions can be loaded
|
|||
These extensions must first be distributed to the Envoy proxy.
|
||||
Istio makes this possible by allowing the proxy agent to dynamically download Wasm modules.
|
||||
|
||||
## Configure an HTTP Filter with a Remote Wasm Module
|
||||
## Setup the Test Application
|
||||
|
||||
Before you begin this task, please deploy the [Bookinfo](/docs/examples/bookinfo/#deploying-the-application) sample application.
|
||||
|
||||
## Configure Wasm Modules
|
||||
|
||||
In this example, you will add a HTTP Basic auth extension to your mesh. You will configure Istio to pull the [Basic auth module](https://github.com/istio-ecosystem/wasm-extensions/tree/master/extensions/basic_auth) from a remote image registry and load it. It will be configured to run on calls to `/productpage`.
|
||||
|
||||
To configure a WebAssembly filter with a remote Wasm module, create a `WasmPlugin` resource:
|
||||
|
||||
{{< text yaml >}}
|
||||
{{< text bash >}}
|
||||
$ kubectl apply -f - <<EOF
|
||||
apiVersion: extensions.istio.io/v1alpha1
|
||||
kind: WasmPlugin
|
||||
metadata:
|
||||
|
|
@ -43,30 +49,39 @@ spec:
|
|||
credentials:
|
||||
- "ok:test"
|
||||
- "YWRtaW4zOmFkbWluMw=="
|
||||
EOF
|
||||
{{< /text >}}
|
||||
|
||||
An HTTP filter will be injected into ingress gateway proxies as an authentication filter.
|
||||
The Istio agent will interpret the `WasmPlugin` configuration, download remote Wasm modules from the OCI image registry to a local file, and inject the HTTP filter into Envoy by referencing that file.
|
||||
The `pluginConfig` field will be converted to the following JSON string, which will be loaded by the Basic auth plugin at initialization:
|
||||
|
||||
{{< text json >}}
|
||||
{
|
||||
"basic_auth_rules": [
|
||||
{
|
||||
"prefix": "/productpage",
|
||||
"request_methods":[ "GET", "POST" ],
|
||||
"credentials":[ "ok:test", "YWRtaW4zOmFkbWluMw==" ]
|
||||
}
|
||||
]
|
||||
}
|
||||
{{< idea >}}
|
||||
If a `WasmPlugin` is created in a specific namespace besides `istio-system`, the pods in that namespace will be configured. If the resource is created in the `istio-system` namespace, all namespaces will be affected.
|
||||
{{< /idea >}}
|
||||
|
||||
## Check the configured Wasm module
|
||||
|
||||
1. Test `/productpage` without credentials
|
||||
|
||||
{{< text bash >}}
|
||||
$ curl -s -o /dev/null -w "%{http_code}" "http://$INGRESS_HOST:$INGRESS_PORT/productpage"
|
||||
401
|
||||
{{< /text >}}
|
||||
|
||||
1. Test `/productpage` with credentials
|
||||
|
||||
{{< text bash >}}
|
||||
$ curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Basic YWRtaW4zOmFkbWluMw==" "http://$INGRESS_HOST:$INGRESS_PORT/productpage"
|
||||
200
|
||||
{{< /text >}}
|
||||
|
||||
For more example usage of the `WasmPlugin` API, please take a look at the [API reference](/docs/reference/config/proxy_extensions/wasm-plugin/).
|
||||
|
||||
There are several known limitations with this module distribution mechanism, which will be addressed in future releases:
|
||||
## Clean up Wasm modules
|
||||
|
||||
- Only HTTP filters are supported.
|
||||
- Modules can only be fetched from a public OCI image registry.
|
||||
{{< text bash >}}
|
||||
$ kubectl delete wasmplugins.extensions.istio.io -n istio-system basic-auth
|
||||
{{< /text >}}
|
||||
|
||||
## Monitor Wasm Module Distribution
|
||||
|
||||
|
|
@ -90,3 +105,9 @@ which is maintained by the Istio community and used to develop Istio's Telemetry
|
|||
- [Build Istio Wasm plugin-compatible OCI images](https://github.com/istio-ecosystem/wasm-extensions/blob/master/doc/how-to-build-oci-images.md)
|
||||
- [Write unit tests for C++ Wasm extensions](https://github.com/istio-ecosystem/wasm-extensions/blob/master/doc/write-cpp-unit-test.md)
|
||||
- [Write integration tests for Wasm extensions](https://github.com/istio-ecosystem/wasm-extensions/blob/master/doc/write-integration-test.md)
|
||||
|
||||
## Limitations
|
||||
|
||||
There are known limitations with this module distribution mechanism, which will be addressed in future releases:
|
||||
|
||||
- Only HTTP filters are supported.
|
||||
|
|
@ -0,0 +1,66 @@
|
|||
#!/bin/bash
|
||||
# shellcheck disable=SC2034,SC2153,SC2155,SC2164
|
||||
|
||||
# Copyright Istio Authors. All Rights Reserved.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
####################################################################################################
|
||||
# WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL MARKDOWN FILE:
|
||||
# docs/tasks/extensibility/wasm-module-distribution/index.md
|
||||
####################################################################################################
|
||||
|
||||
snip_configure_wasm_modules_1() {
|
||||
kubectl apply -f - <<EOF
|
||||
apiVersion: extensions.istio.io/v1alpha1
|
||||
kind: WasmPlugin
|
||||
metadata:
|
||||
name: basic-auth
|
||||
namespace: istio-system
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
istio: ingressgateway
|
||||
url: oci://ghcr.io/istio-ecosystem/wasm-extensions/basic_auth:1.12.0
|
||||
phase: AUTHN
|
||||
pluginConfig:
|
||||
basic_auth_rules:
|
||||
- prefix: "/productpage"
|
||||
request_methods:
|
||||
- "GET"
|
||||
- "POST"
|
||||
credentials:
|
||||
- "ok:test"
|
||||
- "YWRtaW4zOmFkbWluMw=="
|
||||
EOF
|
||||
}
|
||||
|
||||
snip_check_the_configured_wasm_module_1() {
|
||||
curl -s -o /dev/null -w "%{http_code}" "http://$INGRESS_HOST:$INGRESS_PORT/productpage"
|
||||
}
|
||||
|
||||
! read -r -d '' snip_check_the_configured_wasm_module_1_out <<\ENDSNIP
|
||||
401
|
||||
ENDSNIP
|
||||
|
||||
snip_check_the_configured_wasm_module_2() {
|
||||
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Basic YWRtaW4zOmFkbWluMw==" "http://$INGRESS_HOST:$INGRESS_PORT/productpage"
|
||||
}
|
||||
|
||||
! read -r -d '' snip_check_the_configured_wasm_module_2_out <<\ENDSNIP
|
||||
200
|
||||
ENDSNIP
|
||||
|
||||
snip_clean_up_wasm_modules_1() {
|
||||
kubectl delete wasmplugins.extensions.istio.io -n istio-system basic-auth
|
||||
}
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
#!/usr/bin/env bash
|
||||
# shellcheck disable=SC1090,SC2154
|
||||
|
||||
# Copyright Istio Authors
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
set -e
|
||||
set -u
|
||||
set -o pipefail
|
||||
|
||||
source "tests/util/samples.sh"
|
||||
|
||||
# @setup profile=default
|
||||
|
||||
_set_ingress_environment_variables
|
||||
|
||||
startup_bookinfo_sample
|
||||
|
||||
snip_configure_wasm_modules_1
|
||||
|
||||
_verify_same snip_check_the_configured_wasm_module_1 "$snip_check_the_configured_wasm_module_1_out"
|
||||
|
||||
_verify_same snip_check_the_configured_wasm_module_2 "$snip_check_the_configured_wasm_module_2_out"
|
||||
|
||||
# @cleanup
|
||||
snip_clean_up_wasm_modules_1
|
||||
cleanup_bookinfo_sample
|
||||
|
|
@ -78,7 +78,7 @@ to integrate with an external authorization system, we recommend you try this fe
|
|||
|
||||
## Remote fetch and load of WebAssembly (Wasm) HTTP filters (Experimental)
|
||||
|
||||
Now Istio supports an experimental feature to [fetch WebAssembly modules](/docs/ops/configuration/extensibility/wasm-module-distribution) from remote repositories and dynamically (re)load them without restarting the proxies in your mesh. With this you can inject [custom C++ code](https://github.com/istio-ecosystem/wasm-extensions/blob/master/doc/write-a-wasm-extension-with-cpp.md) into your mesh to handle uses cases that go well beyond the Istio APIs.
|
||||
Now Istio supports an experimental feature to [fetch WebAssembly modules](/docs/tasks/extensibility/wasm-module-distribution) from remote repositories and dynamically (re)load them without restarting the proxies in your mesh. With this you can inject [custom C++ code](https://github.com/istio-ecosystem/wasm-extensions/blob/master/doc/write-a-wasm-extension-with-cpp.md) into your mesh to handle uses cases that go well beyond the Istio APIs.
|
||||
|
||||
Please try it and tell us how it worked for you. Also, stay tuned for more blogs, support for more languages, and integration with more repositories.
|
||||
|
||||
|
|
|
|||
|
|
@ -62,7 +62,7 @@ this option was tied to `DNS_CAPTURE`. Now, `DNS_CAPTURE` can be enabled without
|
|||
|
||||
## Extensibility
|
||||
|
||||
- **Added** [Reliable Wasm module remote load](/docs/ops/configuration/extensibility/wasm-module-distribution) with Istio agent. ([Issue #29989](https://github.com/istio/istio/issues/29989))
|
||||
- **Added** [Reliable Wasm module remote load](/docs/tasks/extensibility/wasm-module-distribution) with Istio agent. ([Issue #29989](https://github.com/istio/istio/issues/29989))
|
||||
|
||||
## Networking
|
||||
|
||||
|
|
|
|||
|
|
@ -13,4 +13,4 @@ Mixer在 [Istio 1.8 版本中被移除](/zh/news/releases/1.8.x/announcing-1.8/#
|
|||
* Global 和 Local Rate-Limiting (`memquota` 和 `redisquota` 适配器)功能是通过[基于 Envoy 的速率限制解决方案提供的](/zh/docs/tasks/policy-enforcement/rate-limit/)。
|
||||
* `OPA` 适配器被[基于 Envoy ext-authz 的解决方案](/zh/docs/tasks/security/authorization/authz-custom/)所取代，该解决方案支持与 [OPA 策略代理的集成](https://www.openpolicyagent.org/docs/latest/envoy-introduction/)。
|
||||
|
||||
对于自定义进程外适配器，强烈建议迁移到基于 Wasm 的扩展。请参阅有关 [Wasm 模块开发](https://github.com/istio-ecosystem/wasm-extensions/blob/master/doc/write-a-wasm-extension-with-cpp.md)和[扩展分发](/zh/docs/ops/configuration/extensibility/wasm-module-distribution/)的指南。作为临时解决方案，您可以在 [Mixer 中启用 Envoy ext-authz 和 gRPC 访问日志 API 支持](https://github.com/istio/istio/wiki/Enabling-Envoy-Authorization-Service-and-gRPC-Access-Log-Service-With-Mixer)，这允许您将 Istio 升级到发布 1.7 版本，同时仍然使用 1.7 Mixer 的进程外适配器。这将使您有更多时间迁移到基于 Wasm 的扩展。请注意，此临时解决方案未经实战测试，不太可能得到补丁修复，因为它只在 Istio 1.7 分支上可用，这是在 2021 年 2月 之后的支持窗口之外的。
|
||||
对于自定义进程外适配器，强烈建议迁移到基于 Wasm 的扩展。请参阅有关 [Wasm 模块开发](https://github.com/istio-ecosystem/wasm-extensions/blob/master/doc/write-a-wasm-extension-with-cpp.md)和[扩展分发](/zh/docs/tasks/extensibility/wasm-module-distribution/)的指南。作为临时解决方案，您可以在 [Mixer 中启用 Envoy ext-authz 和 gRPC 访问日志 API 支持](https://github.com/istio/istio/wiki/Enabling-Envoy-Authorization-Service-and-gRPC-Access-Log-Service-With-Mixer)，这允许您将 Istio 升级到发布 1.7 版本，同时仍然使用 1.7 Mixer 的进程外适配器。这将使您有更多时间迁移到基于 Wasm 的扩展。请注意，此临时解决方案未经实战测试，不太可能得到补丁修复，因为它只在 Istio 1.7 分支上可用，这是在 2021 年 2月 之后的支持窗口之外的。
|
||||
|
|
|
|||
|
|
@ -317,6 +317,8 @@ error as the Istio control plane is being started. Adding a config when creating
|
|||
TEST_ENV=kind ADDITIONAL_CONTAINER_OPTIONS="--network host" make doc.test
|
||||
```
|
||||
|
||||
If you encounter `couldn't get current server API group list: Get "...": dial tcp ... connect: connection refused`, the option above also works.
|
||||
|
||||
1. Set the HUB and TAG environment variables to use a particular Istio build when running tests.
|
||||
If unset, their default values will match those used by the prow tests.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue