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]
|
keywords: [extensibility,Wasm,WebAssembly]
|
||||||
owner: istio/wg-policies-and-telemetry-maintainers
|
owner: istio/wg-policies-and-telemetry-maintainers
|
||||||
test: no
|
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/).
|
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.
|
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.
|
These extensions must first be distributed to the Envoy proxy.
|
||||||
Starting in version 1.9, Istio makes this possible by allowing the Istio agent to dynamically download Wasm modules.
|
Istio makes this possible by allowing the proxy agent to dynamically download Wasm modules.
|
||||||
|
|
||||||
## Configure an HTTP Filter with a Remote Wasm Module
|
## 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.
|
To configure a WebAssembly filter with a remote Wasm module, create a `WasmPlugin` resource:
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
{{< text yaml >}}
|
{{< text yaml >}}
|
||||||
apiVersion: networking.istio.io/v1alpha3
|
apiVersion: extensions.istio.io/v1alpha1
|
||||||
kind: EnvoyFilter
|
kind: WasmPlugin
|
||||||
metadata:
|
metadata:
|
||||||
name: basic-auth
|
name: basic-auth
|
||||||
namespace: istio-system
|
namespace: istio-system
|
||||||
spec:
|
spec:
|
||||||
configPatches:
|
selector:
|
||||||
- applyTo: HTTP_FILTER
|
matchLabels:
|
||||||
match:
|
istio: ingressgateway
|
||||||
context: GATEWAY
|
url: oci://ghcr.io/istio-ecosystem/wasm-extensions/basic_auth:{{< istio_version >}}.0
|
||||||
listener:
|
phase: AUTHN
|
||||||
filterChain:
|
pluginConfig:
|
||||||
filter:
|
basic_auth_rules:
|
||||||
name: envoy.http_connection_manager
|
- prefix: "/productpage"
|
||||||
patch:
|
request_methods:
|
||||||
operation: INSERT_BEFORE
|
- "GET"
|
||||||
value:
|
- "POST"
|
||||||
name: istio.basic_auth
|
credentials:
|
||||||
config_discovery:
|
- "ok:test"
|
||||||
config_source:
|
- "YWRtaW4zOmFkbWluMw=="
|
||||||
ads: {}
|
|
||||||
initial_fetch_timeout: 0s # wait indefinitely to prevent bad Wasm fetch
|
|
||||||
type_urls: [ "type.googleapis.com/envoy.extensions.filters.http.wasm.v3.Wasm"]
|
|
||||||
{{< /text >}}
|
{{< /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.
|
An HTTP filter will be injected into ingress gateway proxies as an authentication filter.
|
||||||
Once this update reaches the Istio agent, the agent will download the Wasm module and store it in the local file system.
|
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.
|
||||||
If the download fails, the agent will reject the ECDS update to prevent invalid Wasm filter configuration from reaching the Envoy proxy.
|
The `pluginConfig` field will be converted to the following JSON string, which will be loaded by the Basic auth plugin at initialization:
|
||||||
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:
|
|
||||||
|
|
||||||
- Wasm `vm` configuration which points to a remote Wasm module.
|
{{< text json >}}
|
||||||
- Wasm extension configuration, which is a JSON string that is consumed by the Wasm extension.
|
{
|
||||||
|
"basic_auth_rules": [
|
||||||
{{< text yaml >}}
|
{
|
||||||
apiVersion: networking.istio.io/v1alpha3
|
"prefix": "/productpage",
|
||||||
kind: EnvoyFilter
|
"request_methods":[ "GET", "POST" ],
|
||||||
metadata:
|
"credentials":[ "ok:test", "YWRtaW4zOmFkbWluMw==" ]
|
||||||
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 >}}
|
{{< /text >}}
|
||||||
|
|
||||||
The Istio agent will only intercept and download remote Wasm modules configured via ECDS resources.
|
For more example usage of the `WasmPlugin` API, please take a look at the [API reference](/docs/reference/config/proxy_extensions/wasm-plugin/).
|
||||||
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 >}}
|
|
||||||
|
|
||||||
There are several known limitations with this module distribution mechanism, which will be addressed in future releases:
|
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.
|
- Only HTTP filters are supported.
|
||||||
- Modules can only be downloaded through HTTP/HTTPS.
|
- Modules can only be fetched from a public OCI image registry.
|
||||||
|
|
||||||
## Monitor Wasm Module Distribution
|
## 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:
|
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)
|
- [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 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)
|
- [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