mirror of https://github.com/istio/istio.io.git
Update Wasm module distribution doc to use WasmPlugin. (#10654)
* Update Wasm module distribution doc to use WasmPlugin. * fix. * Update content/en/docs/ops/configuration/extensibility/wasm-module-distribution/index.md Co-authored-by: craigbox <craigbox@google.com> * Update content/en/docs/ops/configuration/extensibility/wasm-module-distribution/index.md Co-authored-by: craigbox <craigbox@google.com> * Update content/en/docs/ops/configuration/extensibility/wasm-module-distribution/index.md Co-authored-by: craigbox <craigbox@google.com> * Update content/en/docs/ops/configuration/extensibility/wasm-module-distribution/index.md Co-authored-by: craigbox <craigbox@google.com> * Update content/en/docs/ops/configuration/extensibility/wasm-module-distribution/index.md Co-authored-by: craigbox <craigbox@google.com> * Update content/en/docs/ops/configuration/extensibility/wasm-module-distribution/index.md Co-authored-by: craigbox <craigbox@google.com> * Update content/en/docs/ops/configuration/extensibility/wasm-module-distribution/index.md Co-authored-by: craigbox <craigbox@google.com> * Update content/en/docs/ops/configuration/extensibility/wasm-module-distribution/index.md Co-authored-by: craigbox <craigbox@google.com> * Update content/en/docs/ops/configuration/extensibility/wasm-module-distribution/index.md Co-authored-by: craigbox <craigbox@google.com> Co-authored-by: craigbox <craigbox@google.com>
This commit is contained in:
Pengyuan Bian
GitHub
parent
dcb58d3851
commit
7518f2517f
|
|
@ -8,121 +8,65 @@ aliases:
|
|||
keywords: [extensibility,Wasm,WebAssembly]
|
||||
owner: istio/wg-policies-and-telemetry-maintainers
|
||||
test: no
|
||||
status: Experimental
|
||||
status: Alpha
|
||||
---
|
||||
|
||||
{{< boilerplate experimental-feature-warning >}}
|
||||
|
||||
Istio provides the ability to [extend proxy functionality using WebAssembly (Wasm)](/blog/2020/wasm-announce/).
|
||||
One of the key advantages of Wasm extensibility is that extensions can be loaded dynamically at runtime.
|
||||
But first these extensions must be distributed to the proxy.
|
||||
Starting in version 1.9, Istio makes this possible by allowing the Istio agent to dynamically download Wasm modules.
|
||||
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
|
||||
|
||||
Here we will walk through an example of adding a basic auth extension to our mesh. We will configure Istio to pull a [basic auth module](https://github.com/istio-ecosystem/wasm-extensions/tree/master/extensions/basic_auth) from a remote URI and load it with configuration to run the module on calls to the `/productpage` path.
|
||||
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, two `EnvoyFilter` resources will be installed: one injects the HTTP filter, and the other provides configuration for the filter to use the remote Wasm module.
|
||||
|
||||
With the first `EnvoyFilter`, an HTTP filter will be injected into gateway proxies. It is configured to request the extension configuration named `istio.basic_auth` from `ads` (i.e. Aggregated Discovery Service), which is the same configuration source that Istiod uses to provide all other configuration resources. Within the configuration source, the initial fetch timeout is set to `0s`, which means that when the Envoy proxy processes a listener update with this filter, it will wait indefinitely for the first extension configuration update before accepting requests with this listener.
|
||||
To configure a WebAssembly filter with a remote Wasm module, create a `WasmPlugin` resource:
|
||||
|
||||
{{< text yaml >}}
|
||||
apiVersion: networking.istio.io/v1alpha3
|
||||
kind: EnvoyFilter
|
||||
apiVersion: extensions.istio.io/v1alpha1
|
||||
kind: WasmPlugin
|
||||
metadata:
|
||||
name: basic-auth
|
||||
namespace: istio-system
|
||||
name: basic-auth
|
||||
namespace: istio-system
|
||||
spec:
|
||||
configPatches:
|
||||
- applyTo: HTTP_FILTER
|
||||
match:
|
||||
context: GATEWAY
|
||||
listener:
|
||||
filterChain:
|
||||
filter:
|
||||
name: envoy.http_connection_manager
|
||||
patch:
|
||||
operation: INSERT_BEFORE
|
||||
value:
|
||||
name: istio.basic_auth
|
||||
config_discovery:
|
||||
config_source:
|
||||
ads: {}
|
||||
initial_fetch_timeout: 0s # wait indefinitely to prevent bad Wasm fetch
|
||||
type_urls: [ "type.googleapis.com/envoy.extensions.filters.http.wasm.v3.Wasm"]
|
||||
selector:
|
||||
matchLabels:
|
||||
istio: ingressgateway
|
||||
url: oci://ghcr.io/istio-ecosystem/wasm-extensions/basic_auth:{{< istio_version >}}.0
|
||||
phase: AUTHN
|
||||
pluginConfig:
|
||||
basic_auth_rules:
|
||||
- prefix: "/productpage"
|
||||
request_methods:
|
||||
- "GET"
|
||||
- "POST"
|
||||
credentials:
|
||||
- "ok:test"
|
||||
- "YWRtaW4zOmFkbWluMw=="
|
||||
{{< /text >}}
|
||||
|
||||
The second `EnvoyFilter` provides configuration for the filter, which is an `EXTENSION_CONFIG` patch and will be distributed to the proxy as an Envoy [Extension Configuration Discovery Service](https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/extension) (ECDS) resource.
|
||||
Once this update reaches the Istio agent, the agent will download the Wasm module and store it in the local file system.
|
||||
If the download fails, the agent will reject the ECDS update to prevent invalid Wasm filter configuration from reaching the Envoy proxy.
|
||||
Because of this protection, with the initial fetch timeout being set to 0, the listener update will not become effective and invalid Wasm filter will not disturb the traffic.
|
||||
The important parts of this configuration are:
|
||||
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:
|
||||
|
||||
- Wasm `vm` configuration which points to a remote Wasm module.
|
||||
- Wasm extension configuration, which is a JSON string that is consumed by the Wasm extension.
|
||||
|
||||
{{< text yaml >}}
|
||||
apiVersion: networking.istio.io/v1alpha3
|
||||
kind: EnvoyFilter
|
||||
metadata:
|
||||
name: basic-auth-config
|
||||
namespace: istio-system
|
||||
spec:
|
||||
configPatches:
|
||||
- applyTo: EXTENSION_CONFIG
|
||||
match:
|
||||
context: GATEWAY
|
||||
patch:
|
||||
operation: ADD
|
||||
value:
|
||||
name: istio.basic_auth
|
||||
typed_config:
|
||||
"@type": type.googleapis.com/udpa.type.v1.TypedStruct
|
||||
type_url: type.googleapis.com/envoy.extensions.filters.http.wasm.v3.Wasm
|
||||
value:
|
||||
config:
|
||||
vm_config:
|
||||
vm_id: basic-auth
|
||||
runtime: envoy.wasm.runtime.v8
|
||||
code:
|
||||
remote:
|
||||
http_uri:
|
||||
uri: https://github.com/istio-ecosystem/wasm-extensions/releases/download/{{< istio_version >}}.0/basic-auth.wasm
|
||||
# Optional: specifying sha256 checksum will let istio agent verify the checksum of downloaded artifacts.
|
||||
# It is **highly** recommended to provide the checksum, since missing checksum will cause the Wasm module to be downloaded repeatedly.
|
||||
# To compute the sha256 checksum of a Wasm module, download the module and run `sha256sum` command with it.
|
||||
# sha256: <WASM-MODULE-SHA>
|
||||
# The configuration for the Wasm extension itself
|
||||
configuration:
|
||||
'@type': type.googleapis.com/google.protobuf.StringValue
|
||||
value: |
|
||||
{
|
||||
"basic_auth_rules": [
|
||||
{
|
||||
"prefix": "/productpage",
|
||||
"request_methods":[ "GET", "POST" ],
|
||||
"credentials":[ "ok:test", "YWRtaW4zOmFkbWluMw==" ]
|
||||
}
|
||||
]
|
||||
}
|
||||
{{< text json >}}
|
||||
{
|
||||
"basic_auth_rules": [
|
||||
{
|
||||
"prefix": "/productpage",
|
||||
"request_methods":[ "GET", "POST" ],
|
||||
"credentials":[ "ok:test", "YWRtaW4zOmFkbWluMw==" ]
|
||||
}
|
||||
]
|
||||
}
|
||||
{{< /text >}}
|
||||
|
||||
The Istio agent will only intercept and download remote Wasm modules configured via ECDS resources.
|
||||
This feature is enabled by default.
|
||||
To disable ECDS interception and Wasm downloading in the Istio agent, set the `ISTIO_AGENT_ENABLE_WASM_REMOTE_LOAD_CONVERSION` environment variable to `false`.
|
||||
For example, to set it globally:
|
||||
|
||||
{{< text yaml >}}
|
||||
meshConfig:
|
||||
defaultConfig:
|
||||
proxyMetadata:
|
||||
ISTIO_AGENT_ENABLE_WASM_REMOTE_LOAD_CONVERSION: "false"
|
||||
{{< /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:
|
||||
|
||||
- Envoy's extension configuration discovery service only supports HTTP filters.
|
||||
- Modules can only be downloaded through HTTP/HTTPS.
|
||||
- Only HTTP filters are supported.
|
||||
- Modules can only be fetched from a public OCI image registry.
|
||||
|
||||
## Monitor Wasm Module Distribution
|
||||
|
||||
|
|
@ -143,5 +87,6 @@ To learn more about Wasm module development, please refer to the guides provided
|
|||
which is maintained by the Istio community and used to develop Istio's Telemetry Wasm extension:
|
||||
|
||||
- [Write, test, deploy, and maintain a Wasm extension with C++](https://github.com/istio-ecosystem/wasm-extensions/blob/master/doc/write-a-wasm-extension-with-cpp.md)
|
||||
- [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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue