Skip to content

Commit

Permalink
API for wasm extensions
Browse files Browse the repository at this point in the history
Signed-off-by: huabing zhao <zhaohuabing@gmail.com>
  • Loading branch information
zhaohuabing committed Mar 11, 2024
1 parent 48c19cc commit 1e38c46
Show file tree
Hide file tree
Showing 4 changed files with 336 additions and 2 deletions.
112 changes: 112 additions & 0 deletions api/v1alpha1/wasmextensionpolicy_types.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
// Copyright Envoy Gateway Authors
// SPDX-License-Identifier: Apache-2.0
// The full text of the Apache license is available in the LICENSE file at
// the root of the repo.

package v1alpha1

import (
"google.golang.org/protobuf/types/known/anypb"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
gwapiv1a2 "sigs.k8s.io/gateway-api/apis/v1alpha2"
)

const (
// WasmExtensionPolicy is the name of the WasmExtensionPolicy kind.
KindWasmExtensionPolicy = "WasmExtensionPolicy"
)

// +kubebuilder:object:root=true
// +kubebuilder:resource:categories=envoy-gateway,shortName=sp
// +kubebuilder:subresource:status
// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[?(@.type=="Accepted")].reason`
// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`

// WasmExtensionPolicy allows the user to configure wasm extensions for a Gateway.
type WasmExtensionPolicy struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty"`

// Spec defines the desired state of WasmExtensionPolicy.
Spec WasmExtensionPolicySpec `json:"spec"`

// Status defines the current status of WasmExtensionPolicySpec.
Status gwapiv1a2.PolicyStatus `json:"status,omitempty"`
}

// WasmExtensionPolicySpec defines the desired state of WasmExtensionPolicy.
type WasmExtensionPolicySpec struct {
// +kubebuilder:validation:XValidation:rule="self.group == 'gateway.networking.k8s.io'", message="this policy can only have a targetRef.group of gateway.networking.k8s.io"
// +kubebuilder:validation:XValidation:rule="self.kind in ['Gateway', 'HTTPRoute', 'GRPCRoute']", message="this policy can only have a targetRef.kind of Gateway/HTTPRoute/GRPCRoute"
// +kubebuilder:validation:XValidation:rule="!has(self.sectionName)",message="this policy does not yet support the sectionName field"
//
// TargetRef is the name of the Gateway resource this policy
// is being attached to.
// This Policy and the TargetRef MUST be in the same namespace
// for this Policy to have effect and be applied to the Gateway.
TargetRef gwapiv1a2.PolicyTargetReferenceWithSectionName `json:"targetRef"`

// Extensions is a list of Wasm extensions to be loaded by the Gateway.
// Order matters, as the extensions will be loaded in the order they are
// defined in this list.
//
// +kubebuilder:validation:MinItems=1
Extensions []WasmExtension `json:"extensions"`
}

// WasmExtension defines an wasm extension.
type WasmExtension struct {
// Name is a unique name for this Wasm extension. It is used to identify the
// Wasm extension if multiple extensions are handled by the same vm_id and root_id.
// It's also used for logging/debugging.
Name string `json:"name"`

// VmID is an ID that will be used along with a hash of the wasm code to
// determine which VM will be used to load the Wasm extension. All extensions
// that have the same vm_id and code will use the same VM.
//
// Note that sharing a VM between plugins can reduce memory utilization and
// make sharing of data easier, but it may have security implications.
VmID *string `json:"vmID,omitempty"`

// RootID is a unique ID for a set of extensions in a VM which will share a
// RootContext and Contexts if applicable (e.g., an Wasm HttpFilter and an Wasm AccessLog).
// If left blank, all extensions with a blank root_id with the same vm_id will share Context(s).
RootID *string `json:"rootID,omitempty"`

// Code is the wasm code for the extension.
Code WasmCodeSource `json:"code"`

// Configuration for the wasm code.
Config *anypb.Any `json:"config"`
}

// WasmCodeSource defines the source of the wasm code.
type WasmCodeSource struct {
// ConfigMap is the name of the ConfigMap containing the wasm code.
// The key in the ConfigMap should be the name of the WasmExtension. For example,
// if the WasmExtension is named "my-wasm-extension", the ConfigMap should have a key
// named "my-wasm-extension" and the value should be the wasm code.
ConfigMap *string `json:"ConfigMap,omitempty"`

// HTTP is the HTTP URL containing the wasm code.
//
// Note that the HTTP server must be accessible from the Envoy proxy.
HTTP *string `json:"http,omitempty"`

// Image is the OCI image containing the wasm code.
// Image *string `json:"image,omitempty"` //TODO: Add support for OCI image in the future.
}

//+kubebuilder:object:root=true

// WasmExtensionPolicyList contains a list of WasmExtensionPolicy resources.
type WasmExtensionPolicyList struct {
metav1.TypeMeta `json:",inline"`
metav1.ListMeta `json:"metadata,omitempty"`
Items []WasmExtensionPolicy `json:"items"`
}

func init() {
SchemeBuilder.Register(&WasmExtensionPolicy{}, &WasmExtensionPolicyList{})
}
139 changes: 139 additions & 0 deletions api/v1alpha1/zz_generated.deepcopy.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ spec:
- name: v1alpha1
schema:
openAPIV3Schema:
description: EnvoyProxy is the schema for the envoyproxies API.
description: EnvoyProxy is the schema for the envoyproxies API.©∫
properties:
apiVersion:
description: 'APIVersion defines the versioned schema of this representation
Expand Down Expand Up @@ -6541,7 +6541,7 @@ spec:
type: object
x-kubernetes-validations:
- message: maxReplicas cannot be less than minReplicas
rule: '!has(self.minReplicas) || self.maxReplicas >= self.minReplicas'
rule: '!has(self.minReplicas) || self.maxReplicas >= self.minReplicas'©
envoyService:
description: EnvoyService defines the desired state of the
Envoy service resource. If unspecified, default settings
Expand Down
83 changes: 83 additions & 0 deletions site/content/en/latest/api/extension_types.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ API group.
- [EnvoyProxy](#envoyproxy)
- [SecurityPolicy](#securitypolicy)
- [SecurityPolicyList](#securitypolicylist)
- [WasmExtensionPolicy](#wasmextensionpolicy)
- [WasmExtensionPolicyList](#wasmextensionpolicylist)



Expand Down Expand Up @@ -2535,6 +2537,87 @@ _Appears in:_



#### WasmCodeSource



WasmCodeSource defines the source of the wasm code.

_Appears in:_
- [WasmExtension](#wasmextension)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `configMapRef` | _[LocalObjectReference](#localobjectreference)_ | true | ConfigMapRef is a reference to a ConfigMap containing the wasm code. The key in the ConfigMap should be the name of the WasmExtension. For example, if the WasmExtension is named "my-wasm-extension", the ConfigMap should have a key named "my-wasm-extension" and the value should be the wasm code. |
| `http` | _string_ | true | HTTP is the HTTP URL containing the wasm code. |


#### WasmExtension



WasmExtension defines an wasm extension.

_Appears in:_
- [WasmExtensionPolicySpec](#wasmextensionpolicyspec)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | _string_ | true | Name is a unique name for this Wasm extension. It is used to identify the Wasm extension if multiple extensions are handled by the same vm_id and root_id. It's also used for logging/debugging. |
| `vmID` | _string_ | true | VmID is an ID that will be used along with a hash of the wasm code to determine which VM will be used to load the Wasm extension. All extensions that have the same vm_id and code will use the same VM. <br /><br /> Note that sharing a VM between plugins can reduce memory utilization and make sharing of data easier, but it may have security implications. |
| `rootID` | _string_ | true | RootID is a unique ID for a set of extensions in a VM which will share a RootContext and Contexts if applicable (e.g., an Wasm HttpFilter and an Wasm AccessLog). If left blank, all extensions with a blank root_id with the same vm_id will share Context(s). |
| `code` | _[WasmCodeSource](#wasmcodesource)_ | true | Code is the wasm code for the extension. |
| `config` | _string_ | true | Configuration for the wasm code. |


#### WasmExtensionPolicy



WasmExtensionPolicy allows the user to configure wasm extensions for a Gateway.

_Appears in:_
- [WasmExtensionPolicyList](#wasmextensionpolicylist)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1`
| `kind` | _string_ | |`WasmExtensionPolicy`
| `metadata` | _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#objectmeta-v1-meta)_ | true | Refer to Kubernetes API documentation for fields of `metadata`. |
| `spec` | _[WasmExtensionPolicySpec](#wasmextensionpolicyspec)_ | true | Spec defines the desired state of WasmExtensionPolicy. |


#### WasmExtensionPolicyList



WasmExtensionPolicyList contains a list of WasmExtensionPolicy resources.



| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1`
| `kind` | _string_ | |`WasmExtensionPolicyList`
| `metadata` | _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#listmeta-v1-meta)_ | true | Refer to Kubernetes API documentation for fields of `metadata`. |
| `items` | _[WasmExtensionPolicy](#wasmextensionpolicy) array_ | true | |


#### WasmExtensionPolicySpec



WasmExtensionPolicySpec defines the desired state of WasmExtensionPolicy.

_Appears in:_
- [WasmExtensionPolicy](#wasmextensionpolicy)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `targetRef` | _[PolicyTargetReferenceWithSectionName](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.PolicyTargetReferenceWithSectionName)_ | true | TargetRef is the name of the Gateway resource this policy is being attached to. This Policy and the TargetRef MUST be in the same namespace for this Policy to have effect and be applied to the Gateway. |
| `extensions` | _[WasmExtension](#wasmextension) array_ | true | Extensions is a list of Wasm extensions to be loaded by the Gateway. Order matters, as the extensions will be loaded in the order they are defined in this list. |


#### XDSTranslatorHook

_Underlying type:_ _string_
Expand Down

0 comments on commit 1e38c46

Please sign in to comment.