From 9034be6e64b458edf82585f44746dc0d8feffebe Mon Sep 17 00:00:00 2001 From: suyiiyii Date: Mon, 20 Oct 2025 16:28:41 +0800 Subject: [PATCH] Add admission policy documentation ([#416](https://github.com/suyiiyii/website/issues/416)) add VAP/MAP doc Signed-off-by: suyiiyii --- content/en/docs/admission_policy.md | 129 ++++++++++++++++++++++++++++ content/zh/docs/admission_policy.md | 129 ++++++++++++++++++++++++++++ 2 files changed, 258 insertions(+) create mode 100644 content/en/docs/admission_policy.md create mode 100644 content/zh/docs/admission_policy.md diff --git a/content/en/docs/admission_policy.md b/content/en/docs/admission_policy.md new file mode 100644 index 00000000..b2773091 --- /dev/null +++ b/content/en/docs/admission_policy.md @@ -0,0 +1,129 @@ ++++ +title = "Admission Policy" + +date = 2025-09-18 +lastmod = 2025-09-18 + +draft = false # Is this a draft? true/false +toc = true # Show table of contents? true/false +type = "docs" # Do not modify. + +# Add menu entry to sidebar. +linktitle = "Admission Policy" +[menu.docs] + parent = "concepts" + weight = 7 ++++ + +## Introduction +Volcano supports Validating Admission Policy (VAP) and Mutating Admission Policy (MAP) to validate and automatically modify Volcano resources like Jobs, Pods, Queues, and PodGroups when they are created or updated. These policies work alongside existing Volcano admission webhooks, providing additional validation and mutation capabilities using Kubernetes native admission policies. + +> **Note**: VAP and MAP are **not enabled by default**. You must explicitly enable them during installation. + +## Installation and Configuration +### Prerequisites +- Kubernetes 1.30+ for ValidatingAdmissionPolicy (stable) +- Kubernetes 1.32+ for MutatingAdmissionPolicy (beta) + +### Enable VAP and MAP + +#### Option 1: Helm Installation +Configure the following values when installing Volcano: + +```bash +# Install Volcano with VAP and MAP enabled +helm install volcano volcano/volcano --namespace volcano-system --create-namespace \ + --set custom.vap_enable=true \ + --set custom.map_enable=true + +# Or upgrade existing installation +helm upgrade volcano volcano/volcano --namespace volcano-system \ + --set custom.vap_enable=true \ + --set custom.map_enable=true +``` + +Alternatively, you can set these values in your `values.yaml`: + +```yaml +custom: + vap_enable: true # Enable Validating Admission Policy + map_enable: true # Enable Mutating Admission Policy +``` + +#### Option 2: YAML Installation +You can also install Volcano directly using YAML manifests. Choose the appropriate file based on your requirements: + +```bash +# Install Volcano without VAP/MAP (default) +kubectl apply -f https://raw.githubusercontent.com/volcano-sh/volcano/master/installer/volcano-development.yaml + +# Install Volcano with VAP only +kubectl apply -f https://raw.githubusercontent.com/volcano-sh/volcano/master/installer/volcano-development-vap.yaml + +# Install Volcano with both VAP and MAP +kubectl apply -f https://raw.githubusercontent.com/volcano-sh/volcano/master/installer/volcano-development-vap-map.yaml +``` + + +## Key Configuration Fields + +### vap_enable +`vap_enable` enables Validating Admission Policy. When enabled, Volcano will validate all Volcano resources before they are created or updated. + +### map_enable +`map_enable` enables Mutating Admission Policy. When enabled, Volcano will automatically set default values for Jobs, Pods, and other resources. + +> **Important**: MAP provides partial functionality compared to existing webhooks. It handles job-level defaults but has limitations with task-level modifications. The existing webhook system continues to work alongside MAP. + +## Usage + +### Verify Policies are Active +After installation, check that the policies are running: + +```bash +# Check ValidatingAdmissionPolicies +kubectl get validatingadmissionpolicy | grep volcano + +# Check MutatingAdmissionPolicies +kubectl get mutatingadmissionpolicy | grep volcano + +# Verify policy bindings +kubectl get validatingadmissionpolicybinding | grep volcano +kubectl get mutatingadmissionpolicybinding | grep volcano +``` + +### Test Validation +Try creating an invalid job to see validation in action: + +```bash +# This will be rejected due to duplicate task names +kubectl apply -f - < **注意**：VAP 和 MAP **默认未启用**。您必须在安装时明确启用它们。 + +## 安装和配置 +### 前置条件 +- ValidatingAdmissionPolicy 需要 Kubernetes 1.30+（1.30 版本稳定） +- MutatingAdmissionPolicy 需要 Kubernetes 1.32+（1.32 版本测试） + +### 启用 VAP 和 MAP + +#### 方式一：Helm 安装 +安装 Volcano 时配置以下值： + +```bash +# 启用 VAP 和 MAP 安装 Volcano +helm install volcano volcano/volcano --namespace volcano-system --create-namespace \ + --set custom.vap_enable=true \ + --set custom.map_enable=true + +# 或升级现有安装 +helm upgrade volcano volcano/volcano --namespace volcano-system \ + --set custom.vap_enable=true \ + --set custom.map_enable=true +``` + +或者在 `values.yaml` 中设置这些值： + +```yaml +custom: + vap_enable: true # 启用验证准入策略 + map_enable: true # 启用变更准入策略 +``` + +#### 方式二：YAML 安装 +您也可以直接使用 YAML 清单安装 Volcano。根据需求选择相应的文件： + +```bash +# 安装不启用 VAP/MAP 的 Volcano（默认） +kubectl apply -f https://raw.githubusercontent.com/volcano-sh/volcano/master/installer/volcano-development.yaml + +# 安装仅启用 VAP 的 Volcano +kubectl apply -f https://raw.githubusercontent.com/volcano-sh/volcano/master/installer/volcano-development-vap.yaml + +# 安装同时启用 VAP 和 MAP 的 Volcano +kubectl apply -f https://raw.githubusercontent.com/volcano-sh/volcano/master/installer/volcano-development-vap-map.yaml +``` + + +## 关键字段 + +### vap_enable +`vap_enable` 启用验证准入策略。启用后，Volcano 将在创建或更新所有 Volcano 资源前进行验证。 + +### map_enable +`map_enable` 启用变更准入策略。启用后，Volcano 将自动为 Jobs、Pods 和其他资源设置默认值。 + +> **重要**：相比现有 webhook，MAP 提供部分功能。它处理作业级默认值，但在任务级修改方面有限制。现有的 webhook 系统将继续与 MAP 协同工作。 + +## 使用 + +### 验证策略是否生效 +安装后，检查策略是否运行： + +```bash +# 检查验证准入策略 +kubectl get validatingadmissionpolicy | grep volcano + +# 检查变更准入策略 +kubectl get mutatingadmissionpolicy | grep volcano + +# 验证策略绑定 +kubectl get validatingadmissionpolicybinding | grep volcano +kubectl get mutatingadmissionpolicybinding | grep volcano +``` + +### 测试验证 +尝试创建无效作业以查看验证效果： + +```bash +# 这将因重复任务名称被拒绝 +kubectl apply -f - <