This is an automated email from the ASF dual-hosted git repository.
xiaoyu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/shenyu-website.git
The following commit(s) were added to refs/heads/main by this push:
new 563216d1d1 add doc for shenyu kubernetes controller (#944)
563216d1d1 is described below
commit 563216d1d1563e448223130e2c1929374e89480b
Author: Kunshuai Zhu <[email protected]>
AuthorDate: Mon Aug 7 11:09:30 2023 +0800
add doc for shenyu kubernetes controller (#944)
* add doc for shenyu kubernetes controller
* fix
* fix
---
.../kubernetes-controller/_category_.json | 4 +
.../kubernetes-controller/build-deploy.md | 120 +++++++++++++++++++++
docs/user-guide/kubernetes-controller/config.md | 45 ++++++++
.../kubernetes-controller/_category_.json | 4 +
.../kubernetes-controller/build-deploy.md | 120 +++++++++++++++++++++
.../user-guide/kubernetes-controller/config.md | 45 ++++++++
6 files changed, 338 insertions(+)
diff --git a/docs/user-guide/kubernetes-controller/_category_.json
b/docs/user-guide/kubernetes-controller/_category_.json
new file mode 100644
index 0000000000..47a0b85e93
--- /dev/null
+++ b/docs/user-guide/kubernetes-controller/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "Kubernetes Controller",
+ "position": 5
+}
diff --git a/docs/user-guide/kubernetes-controller/build-deploy.md
b/docs/user-guide/kubernetes-controller/build-deploy.md
new file mode 100644
index 0000000000..c8ecdbd9df
--- /dev/null
+++ b/docs/user-guide/kubernetes-controller/build-deploy.md
@@ -0,0 +1,120 @@
+---
+title: Build And Deploy Kubernetes Controller
+description: Build And Deploy Kubernetes Controller
+---
+
+This article introduces how to use ShenYu Ingress Controller.
+
+## Construct
+
+It is recommended to refer to [Custom
Deployment](../../deployment/deployment-custom.md) to build a custom gateway,
add the shenyu-kubernetes-controller dependency to the Maven dependency of the
gateway, and the gateway can integrate the kubernetes controller.
+
+```xml
+ <dependency>
+ <groupId>org.apache.shenyu</groupId>
+ <artifactId>shenyu-spring-boot-starter-k8s</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+```
+
+You can also directly use the officially built docker image (TODO, unfinished)
+
+## deployment
+
+K8s deployment files can refer to:
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+ name: shenyu-ingress
+---
+apiVersion: v1
+automountServiceAccountToken: true
+kind: ServiceAccount
+metadata:
+ name: shenyu-ingress-controller
+ namespace: shenyu-ingress
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: shenyu-ingress-controller
+ namespace: shenyu-ingress
+ labels:
+ app: shenyu-ingress-controller
+ all: shenyu-ingress-controller
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ app: shenyu-ingress-controller
+ template:
+ metadata:
+ labels:
+ app: shenyu-ingress-controller
+ spec:
+ containers:
+ - name: shenyu-ingress-controller
+ image: apache/shenyu-integrated-test-k8s-ingress:latest
+ ports:
+ - containerPort: 9195
+ imagePullPolicy: IfNotPresent
+ serviceAccountName: shenyu-ingress-controller
+---
+apiVersion: v1
+kind: Service
+metadata:
+ name: shenyu-ingress-controller
+ namespace: shenyu-ingress
+spec:
+ selector:
+ app: shenyu-ingress-controller
+ type: NodePort
+ ports:
+ - port: 9195
+ targetPort: 9195
+ nodePort: 30095
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+ name: shenyu-ingress-controller
+rules:
+- apiGroups:
+ - ""
+ resources:
+ - namespaces
+ - services
+ - endpoints
+ - secrets
+ - pods
+ verbs:
+ - get
+ - list
+ - watch
+- apiGroups:
+ - networking.k8s.io
+ resources:
+ - ingresses
+ verbs:
+ - get
+ - list
+ - watch
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+ name: shenyu-ingress-controller
+ namespace: shenyu-ingress
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: ClusterRole
+ name: shenyu-ingress-controller
+subjects:
+- kind: ServiceAccount
+ name: shenyu-ingress-controller
+ namespace: shenyu-ingress
+```
+
+Among them, Service can be changed to `LoadBalancer` type according to the
actual situation.
diff --git a/docs/user-guide/kubernetes-controller/config.md
b/docs/user-guide/kubernetes-controller/config.md
new file mode 100644
index 0000000000..8e05c85eac
--- /dev/null
+++ b/docs/user-guide/kubernetes-controller/config.md
@@ -0,0 +1,45 @@
+---
+title: Kubernetes Controller Config
+description: Kubernetes Controller Config
+---
+
+This article introduces Kubernetes Controller configuration.
+
+## Enable HTTPS
+
+To enable HTTPS, you need to configure the `sni protocol` in the
`application.yml` file of the gateway:
+
+```yaml
+shenyu:
+ netty:
+ http:
+ sni:
+ enabled: true
+ mod: k8s #k8s mode applies
+ defaultK8sSecretNamespace: shenyu-ingress #The namespace of the
default secret resource
+ defaultK8sSecretName: default-cert #default secret resource name
+```
+
+Among them, the default secret resource must be available, but it will not be
actually used at present.
+
+## Ingress configuration
+
+ShenYu Kubernetes Controller implements the K8s native Ingress standard, see
[K8s official
documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/)
for the use of the native standard
+
+In addition, Apache ShenYu has expanded based on the Annotation field of
Ingress, and the configuration is shown in the following tables:
+
+### General
+
+| Name | Default | Required | Description |
+| --------------------------- | ------ | -------- | ----- --- |
+| kubernetes.io/ingress.class | | Yes | Fill in shenyu |
+
+### Divide plugin (HTTP proxy)
+
+| Name | Default | Required | Description |
+| ------------------------------------- | ------ | ------- - |
------------------------------------------------ ------------ |
+| shenyu.apache.org/loadbalancer | random | No | Load balancing algorithm,
optional hash, random, roundRobin, leastActive, p2c, shortestResponse |
+| shenyu.apache.org/retry | 3 | No | Number of failed retries |
+| shenyu.apache.org/timeout | 3000 | No | Backend request timeout, in
milliseconds |
+| shenyu.apache.org/header-max-size | 10240 | No | The maximum size of the
request header, unit byte |
+| shenyu.apache.org/request-max-size | 102400 | No | Maximum request body
size, unit byte |
diff --git
a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/kubernetes-controller/_category_.json
b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/kubernetes-controller/_category_.json
new file mode 100644
index 0000000000..47a0b85e93
--- /dev/null
+++
b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/kubernetes-controller/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "Kubernetes Controller",
+ "position": 5
+}
diff --git
a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/kubernetes-controller/build-deploy.md
b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/kubernetes-controller/build-deploy.md
new file mode 100644
index 0000000000..868fd5bbaa
--- /dev/null
+++
b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/kubernetes-controller/build-deploy.md
@@ -0,0 +1,120 @@
+---
+title: 构建和部署 Kubernetes 控制器
+description: 构建和部署 Kubernetes 控制器
+---
+
+本篇介绍如何使用 ShenYu Kubernetes Controller。
+
+## 构建
+
+建议参考[自定义部署](../../deployment/deployment-custom.md)构建自定义网关，在网关的 Maven 依赖中加入
shenyu-kubernetes-controller 的依赖，网关即可集成 kubernetes 控制器。
+
+```xml
+ <dependency>
+ <groupId>org.apache.shenyu</groupId>
+ <artifactId>shenyu-spring-boot-starter-k8s</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+```
+
+也可以直接使用官方构建的 docker 镜像（TODO，未完成）
+
+## 部署
+
+K8s 部署文件可参考：
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+ name: shenyu-ingress
+---
+apiVersion: v1
+automountServiceAccountToken: true
+kind: ServiceAccount
+metadata:
+ name: shenyu-ingress-controller
+ namespace: shenyu-ingress
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: shenyu-ingress-controller
+ namespace: shenyu-ingress
+ labels:
+ app: shenyu-ingress-controller
+ all: shenyu-ingress-controller
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ app: shenyu-ingress-controller
+ template:
+ metadata:
+ labels:
+ app: shenyu-ingress-controller
+ spec:
+ containers:
+ - name: shenyu-ingress-controller
+ image: apache/shenyu-integrated-test-k8s-ingress:latest
+ ports:
+ - containerPort: 9195
+ imagePullPolicy: IfNotPresent
+ serviceAccountName: shenyu-ingress-controller
+---
+apiVersion: v1
+kind: Service
+metadata:
+ name: shenyu-ingress-controller
+ namespace: shenyu-ingress
+spec:
+ selector:
+ app: shenyu-ingress-controller
+ type: NodePort
+ ports:
+ - port: 9195
+ targetPort: 9195
+ nodePort: 30095
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+ name: shenyu-ingress-controller
+rules:
+- apiGroups:
+ - ""
+ resources:
+ - namespaces
+ - services
+ - endpoints
+ - secrets
+ - pods
+ verbs:
+ - get
+ - list
+ - watch
+- apiGroups:
+ - networking.k8s.io
+ resources:
+ - ingresses
+ verbs:
+ - get
+ - list
+ - watch
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+ name: shenyu-ingress-controller
+ namespace: shenyu-ingress
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: ClusterRole
+ name: shenyu-ingress-controller
+subjects:
+- kind: ServiceAccount
+ name: shenyu-ingress-controller
+ namespace: shenyu-ingress
+```
+
+其中，Service 可以根据实际情况改成 `LoadBalancer` 类型。
diff --git
a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/kubernetes-controller/config.md
b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/kubernetes-controller/config.md
new file mode 100644
index 0000000000..ae23851e68
--- /dev/null
+++
b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/kubernetes-controller/config.md
@@ -0,0 +1,45 @@
+---
+title: Kubernetes 控制器配置
+description: Kubernetes 控制器配置
+---
+
+本篇介绍 Kubernetes 控制器配置。
+
+## 开启 HTTPS
+
+开启 HTTPS 需要在网关的 `application.yml` 文件中进行 `sni协议` 的相关配置：
+
+```yaml
+shenyu:
+ netty:
+ http:
+ sni:
+ enabled: true
+ mod: k8s #k8s模式适用
+ defaultK8sSecretNamespace: shenyu-ingress #默认secret资源的namespace
+ defaultK8sSecretName: default-cert #默认secret资源名字
+```
+
+其中，默认secret资源必须要有，但是目前不会实际使用。
+
+## Ingress 配置
+
+ShenYu Kubernetes Controller 实现了 K8s 原生的 Ingress 标准，原生标准的使用见 [K8s
官方文档](https://kubernetes.io/docs/concepts/services-networking/ingress/)
+
+另外，Apache ShenYu 基于 Ingress 的 Annotation 字段进行了拓展，配置见下文表格：
+
+### 通用
+
+| 名称 | 默认值 | 是否必填 | 说明 |
+| --------------------------- | ------ | -------- | -------- |
+| kubernetes.io/ingress.class | | 是 | 填shenyu |
+
+### Divide 插件（HTTP代理）
+
+| 名称 | 默认值 | 是否必填 | 说明
|
+| ---------------------------------- | ------ | -------- |
------------------------------------------------------------ |
+| shenyu.apache.org/loadbalancer | random | 否 |
负载均衡算法，可选hash、random、roundRobin、leastActive、p2c、shortestResponse |
+| shenyu.apache.org/retry | 3 | 否 | 失败重试次数
|
+| shenyu.apache.org/timeout | 3000 | 否 | 后端请求超时时间，单位毫秒
|
+| shenyu.apache.org/header-max-size | 10240 | 否 | 请求头最大大小，单位byte
|
+| shenyu.apache.org/request-max-size | 102400 | 否 | 请求体最大大小，单位byte
|
