2.21. 확장
WebAssembly 확장을 사용하여 Red Hat OpenShift Service Mesh 프록시에 새 기능을 직접 추가할 수 있습니다. 이를 통해 애플리케이션에서 일반적인 기능을 더 많이 이동하고 WebAssembly 바이트 코드로 컴파일되는 단일 언어로 구현할 수 있습니다.
WebAssembly 확장은 IBM Z® 및 IBM Power®에서 지원되지 않습니다.
2.21.1. WebAssembly 모듈 개요
WebAssembly 모듈은 프록시를 포함한 많은 플랫폼에서 실행할 수 있으며 광범위한 언어 지원, 빠른 실행 및 샌드박스별 보안 모델을 사용할 수 있습니다.
Red Hat OpenShift Service Mesh 확장은 Envoy HTTP 필터 로, 다양한 기능을 제공합니다.
- 요청 및 응답의 본문과 헤더를 조작합니다.
- 인증 또는 정책 검사와 같이 요청 경로에 없는 서비스에 대한 대역 외 HTTP 요청입니다.
- 필터가 서로 통신할 수 있는 사이드 채널 데이터 스토리지 및 큐입니다.
WebAssembly 확장을 새로 생성할 때 WasmPlugin API를 사용합니다. ServiceMeshExtension API는 Red Hat OpenShift Service Mesh 버전 2.2에서 더 이상 사용되지 않으며 Red Hat OpenShift Service Mesh 버전 2.3에서 제거되었습니다.
Red Hat OpenShift Service Mesh 확장을 작성하는 데는 두 가지 부분이 있습니다.
- proxy-wasm API 를 노출하고 WebAssembly 모듈로 컴파일하는 SDK를 사용하여 확장을 작성해야 합니다.
- 그런 다음 모듈을 컨테이너에 패키징해야 합니다.
지원되는 언어
WebAssembly 바이트 코드에 컴파일된 모든 언어를 사용하여 Red Hat OpenShift Service Mesh 확장을 작성할 수 있지만, 다음 언어에는 proxy-wasm API를 공개하는 기존 SDK가 있어 직접 사용할 수 있습니다.
| 언어 | 유지 관리자 | 리포지터리 |
|---|---|---|
| AssemblyScript | solo.io | |
| C++ | proxy-wasm 팀(Istio 커뮤니티) | |
| Go | tetrate.io | |
| Rust | proxy-wasm 팀(Istio 커뮤니티) |
2.21.2. WasmPlugin 컨테이너 형식
Istio는 Wasm 플러그인 메커니즘에서 OCI(Open Container Initiative) 이미지를 지원합니다. Wasm 플러그인을 컨테이너 이미지로 배포할 수 있으며 spec.url 필드를 사용하여 컨테이너 레지스트리 위치를 참조할 수 있습니다. 예를 들어 quay.io/my-username/my-plugin:latest.
WASM 모듈의 각 실행 환경(runtime)에는 런타임별 구성 매개변수가 있을 수 있으므로 WASM 이미지는 다음 두 계층으로 구성할 수 있습니다.
-
plugin.wasm (필수) - 콘텐츠 계층. 이 계층은 런타임에서 로드할 WebAssembly 모듈의 바이트 코드가 포함된
.wasm바이너리로 구성됩니다. 이 파일 이름을plugin.wasm로 지정해야 합니다. - runtime-config.json (선택 사항) - 구성 계층. 이 계층은 대상 런타임의 모듈에 대한 메타데이터를 설명하는 JSON 형식의 문자열로 구성됩니다. 대상 런타임에 따라 구성 계층에 따라 추가 데이터가 포함될 수도 있습니다. 예를 들어 WASM Envoy Filter의 구성에는 필터에서 사용할 수 있는 root_ids가 포함되어 있습니다.
2.21.3. WasmPlugin API 참조
WasmPlugins API는 WebAssembly 필터를 통해 Istio 프록시에서 제공하는 기능을 확장하는 메커니즘을 제공합니다.
여러 WasmPlugins를 배포할 수 있습니다. phase 및 priority 설정은 Envoy의 필터 체인의 일부로 실행 순서를 결정하므로 사용자가 제공하는 WasmPlugins와 Istio의 내부 필터 간의 복잡한 상호 작용을 구성할 수 있습니다.
다음 예에서 인증 필터는 OpenID 흐름을 구현하고 JWT(JSON Web Token)로 인증 헤더를 채웁니다. Istio 인증은 이 토큰을 사용하여 수신 게이트웨이에 배포합니다. WasmPlugin 파일은 프록시 사이드카 파일 시스템에 있습니다. url 필드를 참조하세요.
apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
name: openid-connect
namespace: istio-ingress
spec:
selector:
matchLabels:
istio: ingressgateway
url: file:///opt/filters/openid.wasm
sha256: 1ef0c9a92b0420cf25f7fe5d481b231464bc88f486ca3b9c83ed5cc21d2f6210
phase: AUTHN
pluginConfig:
openid_server: authn
openid_realm: ingress
다음은 동일한 예제이지만 이번에는 파일 시스템의 파일 대신 OCI(Open Container Initiative) 이미지가 사용됩니다. url,imagePullPolicy, imagePullSecret 필드에 유의하십시오.
apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
name: openid-connect
namespace: istio-system
spec:
selector:
matchLabels:
istio: ingressgateway
url: oci://private-registry:5000/openid-connect/openid:latest
imagePullPolicy: IfNotPresent
imagePullSecret: private-registry-pull-secret
phase: AUTHN
pluginConfig:
openid_server: authn
openid_realm: ingress| 필드 | 유형 | 설명 | 필수 항목 |
|---|---|---|---|
| spec.selector | WorkloadSelector |
이 플러그인 구성을 적용해야 하는 특정 Pod/VM 세트를 선택하는 데 사용되는 기준입니다. 생략하면 이 구성은 동일한 네임스페이스의 모든 워크로드 인스턴스에 적용됩니다. | 없음 |
| spec.url | string |
Wasm 모듈 또는 OCI 컨테이너의 URL입니다. 스키마가 없는 경우 기본값은 OCI 이미지를 참조하여 | 없음 |
| spec.sha256 | string |
Wasm 모듈 또는 OCI 컨테이너를 확인하는 데 사용할 SHA256 체크섬입니다. | 없음 |
| spec.imagePullPolicy | PullPolicy |
OCI 이미지를 가져올 때 적용할 가져오기 동작입니다. SHA 대신 태그에서 이미지를 참조하는 경우에만 관련이 있습니다. | 없음 |
| spec.imagePullSecret | string |
OCI 이미지 가져오기에 사용할 자격 증명입니다. 이미지를 가져올 때 레지스트리에 대해 인증하기 위한 풀 시크릿이 포함된 | 없음 |
| spec.phase | PluginPhase |
필터 체인에서 이 | 없음 |
| spec.priority |
|
동일한 | 없음 |
| spec.pluginName | string | Envoy 구성에 사용되는 플러그인 이름입니다. 일부 Wasm 모듈에는 실행할 Wasm 플러그인을 선택하기 위해 이 값이 필요할 수 있습니다. | 없음 |
| spec.pluginConfig | struct | 플러그인에 전달될 구성입니다. | 없음 |
| spec.pluginConfig.verificationKey | string | 서명된 OCI 이미지 또는 Wasm 모듈의 서명을 확인하는 데 사용되는 공개 키입니다. PEM 형식으로 제공해야 합니다. | 없음 |
WorkloadSelector 오브젝트는 필터를 프록시에 적용할 수 있는지 확인하는 데 사용되는 기준을 지정합니다. 일치하는 기준에는 프록시와 관련된 메타데이터, Pod/VM에 연결된 라벨과 같은 워크로드 인스턴스 정보 또는 프록시가 초기 핸드셰이크 중에 Istio에 제공하는 기타 정보가 포함됩니다. 여러 조건이 지정된 경우 워크로드 인스턴스를 선택하기 위해 모든 조건을 일치해야 합니다. 현재는 레이블 기반 선택 메커니즘만 지원됩니다.
| 필드 | 유형 | 설명 | 필수 항목 |
|---|---|---|---|
| matchLabels | map<string, string> | 정책을 적용해야 하는 특정 Pod/VM 세트를 나타내는 하나 이상의 레이블입니다. 레이블 검색 범위는 리소스가 있는 구성 네임스페이스로 제한됩니다. | 제공됨 |
PullPolicy 오브젝트는 OCI 이미지를 가져올 때 적용할 가져오기 동작을 지정합니다.
| 현재의 | 설명 |
|---|---|
| <empty> |
latest 태그가 있는 OCI 이미지를 제외하고 |
| IfNotPresent | 기존 버전의 이미지를 이전에 가져온 경우 해당 이미지가 사용됩니다. 로컬에 이미지 버전이 없는 경우 최신 버전을 가져옵니다. |
| Always | 이 플러그인을 적용할 때 항상 최신 버전의 이미지를 가져옵니다. |
struct 는 동적으로 형식화된 값에 매핑되는 필드로 구성된 구조화된 데이터 값을 나타냅니다. 일부 언어에서는 Struct이 기본 표현으로 지원될 수 있습니다. 예를 들어 JavaScript와 같은 스크립팅 언어에서는 구조를 오브젝트로 나타냅니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| 필드 | map<string, Value> | 동적으로 형식화된 값의 맵입니다. |
PluginPhase 는 플러그인이 삽입될 필터 체인의 단계를 지정합니다.
| 필드 | 설명 |
|---|---|
| <empty> | 컨트롤 플레인은 플러그인을 삽입할 위치를 결정합니다. 일반적으로 라우터 바로 앞에 필터 체인의 끝에 있습니다. 플러그인이 다른 사용자와 독립적이면 PluginPhase를 지정하지 마십시오. |
| AUTHN | Istio 인증 필터 앞에 플러그인을 삽입합니다. |
| AUTHZ | Istio 권한 부여 필터 앞에 플러그인을 삽입하고 Istio 인증 필터 후에 플러그인을 삽입합니다. |
| STATS | Istio 통계 필터 앞에 플러그인을 삽입하고 Istio 권한 부여 필터 후에 플러그인을 삽입합니다. |
2.21.3.1. WasmPlugin 리소스 배포
WasmPlugin 리소스를 사용하여 Red Hat OpenShift Service Mesh 확장을 활성화할 수 있습니다. 이 예에서 istio-system 은 Service Mesh Control Plane 프로젝트의 이름입니다. 다음 예제에서는 사용자를 인증하기 위해 OpenID Connect 흐름을 수행하는 openid-connect 필터를 생성합니다.
프로세스
다음 예제 리소스를 만듭니다.
plugin.yaml의 예
apiVersion: extensions.istio.io/v1alpha1 kind: WasmPlugin metadata: name: openid-connect namespace: istio-system spec: selector: matchLabels: istio: ingressgateway url: oci://private-registry:5000/openid-connect/openid:latest imagePullPolicy: IfNotPresent imagePullSecret: private-registry-pull-secret phase: AUTHN pluginConfig: openid_server: authn openid_realm: ingress다음 명령을 사용하여
plugin.yaml파일을 적용합니다.$ oc apply -f plugin.yaml
2.21.4. ServiceMeshExtension 컨테이너 형식
컨테이너 이미지를 유효한 확장 이미지로 만들려면 컨테이너 파일 시스템의 루트에 WebAssembly 모듈의 바이트 코드가 포함된 .wasm 파일과 manifest.yaml 파일이 있어야 합니다.
WebAssembly 확장을 새로 생성할 때 WasmPlugin API를 사용합니다. ServiceMeshExtension API는 Red Hat OpenShift Service Mesh 버전 2.2에서 더 이상 사용되지 않으며 Red Hat OpenShift Service Mesh 버전 2.3에서 제거되었습니다.
manifest.yaml
schemaVersion: 1 name: <your-extension> description: <description> version: 1.0.0 phase: PreAuthZ priority: 100 module: extension.wasm
| 필드 | 설명 | 필수 항목 |
|---|---|---|
| schemaVersion |
매니페스트 스키마 버전 지정에 사용됩니다. 현재 가능한 값은 | 이 필드는 필수 항목입니다. |
| name | 해당 확장의 이름입니다. | 이 필드는 메타데이터일 뿐이며 현재 사용되지 않습니다. |
| description | 해당 확장의 설명입니다. | 이 필드는 메타데이터일 뿐이며 현재 사용되지 않습니다. |
| version | 해당 확장의 버전입니다. | 이 필드는 메타데이터일 뿐이며 현재 사용되지 않습니다. |
| phase | 해당 확장의 기본 실행 단계입니다. | 이 필드는 필수 항목입니다. |
| priority | 해당 확장의 기본 우선순위입니다. | 이 필드는 필수 항목입니다. |
| module | 컨테이너 파일 시스템의 루트에서 WebAssembly 모듈에 대한 상대적 경로입니다. | 이 필드는 필수 항목입니다. |
2.21.5. ServiceMeshExtension 참조
ServiceMeshExtension API는 WebAssembly 필터를 통해 Istio 프록시에서 제공하는 기능을 확장하는 메커니즘을 제공합니다. WebAssembly 확장을 작성하는 데는 두 가지 부분이 있습니다.
- proxy-wasm API를 노출하고 WebAssembly 모듈로 컴파일하는 SDK를 사용하여 확장을 작성합니다.
- 컨테이너에 패키징합니다.
WebAssembly 확장을 새로 생성할 때 WasmPlugin API를 사용합니다. Red Hat OpenShift Service Mesh 버전 2.2에서 더 이상 사용되지 않는 ServiceMeshExtension API가 Red Hat OpenShift Service Mesh 버전 2.3에서 제거되었습니다.
| 필드 | 설명 |
|---|---|
| metadata.namespace |
|
| spec.workloadSelector |
|
| spec.config | 이는 배포 중인 확장에 따라 의미 체계가 달라지며 확장에 전달되는 구조화된 필드입니다. |
| spec.image | 확장자가 있는 이미지를 가리키는 컨테이너 이미지 URI입니다. |
| spec.phase |
단계는 인증, 권한 부여, 지표 생성과 같은 기존 Istio 기능과 관련하여 필터 체인에서 확장이 삽입되는 위치를 결정합니다. 유효한 값: PreAuthN, PostAuthN, PreAuthZ, PostAuthZ, PreStats, PostStats. 이 필드의 기본값은 확장자의 |
| spec.priority |
|
2.21.5.1. ServiceMeshExtension 리소스 배포
ServiceMeshExtension 리소스를 사용하여 Red Hat OpenShift Service Mesh 확장을 활성화할 수 있습니다. 이 예에서 istio-system 은 Service Mesh Control Plane 프로젝트의 이름입니다.
WebAssembly 확장을 새로 생성할 때 WasmPlugin API를 사용합니다. ServiceMeshExtension API는 Red Hat OpenShift Service Mesh 버전 2.2에서 더 이상 사용되지 않으며 Red Hat OpenShift Service Mesh 버전 2.3에서 제거되었습니다.
Rust SDK를 사용하여 빌드된 전체 예제는 header-append-filter를 참조하십시오. 확장의 config 필드에서 가져온 이름과 값을 사용하여 하나 이상의 헤더를 HTTP 응답에 추가하는 간단한 필터입니다. 아래 코드 조각의 샘플 구성을 참조하십시오.
프로세스
다음 예제 리소스를 만듭니다.
ServiceMeshExtension 리소스 extensions.yaml의 예
apiVersion: maistra.io/v1 kind: ServiceMeshExtension metadata: name: header-append namespace: istio-system spec: workloadSelector: labels: app: httpbin config: first-header: some-value another-header: another-value image: quay.io/maistra-dev/header-append-filter:2.1 phase: PostAuthZ priority: 100다음 명령을 사용하여
extension.yaml파일을 적용합니다.$ oc apply -f <extension>.yaml
2.21.6. ServiceMeshExtension 에서 WasmPlugin 리소스로 마이그레이션
Red Hat OpenShift Service Mesh 버전 2.2에서 더 이상 사용되지 않는 ServiceMeshExtension API가 Red Hat OpenShift Service Mesh 버전 2.3에서 제거되었습니다. ServiceMeshExtension API를 사용하는 경우 WebAssembly 확장을 계속 사용하려면 WasmPlugin API로 마이그레이션해야 합니다.
API는 매우 비슷합니다. 마이그레이션은 다음 두 단계로 구성됩니다.
- 플러그인 파일 이름 변경 및 모듈 패키지 업데이트입니다.
-
업데이트된 컨테이너 이미지를 참조하는
WasmPlugin리소스를 생성합니다.
2.21.6.1. API 변경
새로운 WasmPlugin API는 ServiceMeshExtension 와 유사하지만 특히 필드 이름에서 몇 가지 차이점이 있습니다.
| ServiceMeshExtension | WasmPlugin |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
다음은 ServiceMeshExtension 리소스를 WasmPlugin 리소스로 변환하는 방법의 예입니다.
ServiceMeshExtension 리소스
apiVersion: maistra.io/v1
kind: ServiceMeshExtension
metadata:
name: header-append
namespace: istio-system
spec:
workloadSelector:
labels:
app: httpbin
config:
first-header: some-value
another-header: another-value
image: quay.io/maistra-dev/header-append-filter:2.2
phase: PostAuthZ
priority: 100
위의 ServiceMeshExtension에 해당하는 새로운 WasmPlugin 리소스
apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
name: header-append
namespace: istio-system
spec:
selector:
matchLabels:
app: httpbin
url: oci://quay.io/maistra-dev/header-append-filter:2.2
phase: STATS
pluginConfig:
first-header: some-value
another-header: another-value
2.21.6.2. 컨테이너 이미지 형식 변경
새로운 WasmPlugin 컨테이너 이미지 형식은 ServiceMeshExtensions 와 유사하지만 다음과 같은 차이점이 있습니다.
-
ServiceMeshExtension컨테이너 형식에는 컨테이너 파일 시스템의 루트 디렉터리에manifest.yaml이라는 메타데이터 파일이 필요했습니다.WasmPlugin컨테이너 형식에는manifest.yaml파일이 필요하지 않습니다. -
이전에 파일 이름을 사용할 수 있는
.wasm파일(실제 플러그인)은 이제plugin.wasm로 지정해야 하며 컨테이너 파일 시스템의 루트 디렉터리에 있어야 합니다.
2.21.6.3. WasmPlugin 리소스로 마이그레이션
WebAssembly 확장을 ServiceMeshExtension API에서 WasmPlugin API로 업그레이드하려면 플러그인 파일의 이름을 바꿉니다.
사전 요구 사항
-
ServiceMeshControlPlane이 버전 2.2 이상으로 업그레이드됩니다.
프로세스
컨테이너 이미지를 업데이트합니다. 플러그인이 컨테이너 내
/plugin.wasm에 이미 있는 경우 다음 단계로 건너뜁니다. 그렇지 않은 경우:-
플러그인 파일 이름이
plugin.wasm인지 확인합니다. 플러그인 파일 이름을plugin.wasm으로 지정해야 합니다. - 플러그인 파일이 루트(/) 디렉터리에 있는지 확인합니다. 확장 파일을 컨테이너 파일 시스템의 루트에 저장해야 합니다.
- 컨테이너 이미지를 다시 빌드하고 컨테이너 레지스트리로 내보냅니다.
-
플러그인 파일 이름이
-
ServiceMeshExtension리소스를 제거하고 빌드한 새 컨테이너 이미지를 참조하는WasmPlugin리소스를 생성합니다.
