You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sp...@apache.org on 2022/09/21 06:02:28 UTC
[apisix] branch master updated: docs: update discovery Kubernetes doc formatting (#7957)
This is an automated email from the ASF dual-hosted git repository.
spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new d89dfce1c docs: update discovery Kubernetes doc formatting (#7957)
d89dfce1c is described below
commit d89dfce1cd900c2cbad288ac03283d18768d4929
Author: Sylvia <39...@users.noreply.github.com>
AuthorDate: Wed Sep 21 14:02:21 2022 +0800
docs: update discovery Kubernetes doc formatting (#7957)
---
docs/en/latest/discovery/kubernetes.md | 151 +++++++++++++++++----------------
docs/zh/latest/discovery/kubernetes.md | 129 ++++++++++++++--------------
2 files changed, 141 insertions(+), 139 deletions(-)
diff --git a/docs/en/latest/discovery/kubernetes.md b/docs/en/latest/discovery/kubernetes.md
index d95cdcceb..04e01f6ca 100644
--- a/docs/en/latest/discovery/kubernetes.md
+++ b/docs/en/latest/discovery/kubernetes.md
@@ -1,5 +1,12 @@
---
title: Kubernetes
+keywords:
+ - Kubernetes
+ - Apache APISIX
+ - Service discovery
+ - Cluster
+ - API Gateway
+description: This article introduce how to perform service discovery based on Kubernetes in Apache APISIX and summarize related issues.
---
<!--
@@ -23,14 +30,13 @@ title: Kubernetes
## Summary
-The [_Kubernetes_](https://kubernetes.io/) service discovery [_List-Watch_](https://kubernetes.io/docs/reference/using-api/api-concepts/) real-time changes of [_Endpoints_](https://kubernetes.io/docs/concepts/services-networking/service/) resources,
-then store theirs value into ngx.shared.DICT \
-Discovery also provides a node query interface in accordance with the [_APISIX Discovery Specification_](https://github.com/apache/apisix/blob/master/docs/en/latest/discovery.md)
+The [_Kubernetes_](https://kubernetes.io/) service discovery [_List-Watch_](https://kubernetes.io/docs/reference/using-api/api-concepts/) real-time changes of [_Endpoints_](https://kubernetes.io/docs/concepts/services-networking/service/) resources, then store theirs value into `ngx.shared.DICT`.
+
+Discovery also provides a node query interface in accordance with the [_APISIX Discovery Specification_](https://github.com/apache/apisix/blob/master/docs/en/latest/discovery.md).
## How To Use
-Kubernetes service discovery both support single-cluster and multi-cluster mode, \
-applicable to the case where the service is distributed in a single or multiple Kubernetes clusters.
+Kubernetes service discovery both support single-cluster and multi-cluster mode, applicable to the case where the service is distributed in a single or multiple Kubernetes clusters.
### Single-Cluster Mode Configuration
@@ -112,10 +118,10 @@ discovery:
The Kubernetes service discovery provides a query interface in accordance with the [_APISIX Discovery Specification_](https://github.com/apache/apisix/blob/master/docs/en/latest/discovery.md).
-**function:** \
+**function:**
nodes(service_name)
-**description:** \
+**description:**
nodes() function attempts to look up the ngx.shared.DICT for nodes corresponding to service_name, \
service_name should match pattern: _[namespace]/[name]:[portName]_
@@ -125,7 +131,7 @@ The Kubernetes service discovery provides a query interface in accordance with t
+ portName: The ports.name value in the Kubernetes endpoints, if there is no ports.name, use targetPort, port instead
-**return value:** \
+**return value:**
if the Kubernetes endpoints value is as follows:
```yaml
@@ -222,10 +228,10 @@ Multi-Kubernetes service discovery does not fill default values for service and
The Kubernetes service discovery provides a query interface in accordance with the [_APISIX Discovery Specification_](https://github.com/apache/apisix/blob/master/docs/en/latest/discovery.md).
-**function:** \
+**function:**
nodes(service_name)
-**description:** \
+**description:**
nodes() function attempts to look up the ngx.shared.DICT for nodes corresponding to service_name, \
service_name should match pattern: _[id]/[namespace]/[name]:[portName]_
@@ -237,7 +243,7 @@ service_name should match pattern: _[id]/[namespace]/[name]:[portName]_
+ portName: The ports.name value in the Kubernetes endpoints, if there is no ports.name, use targetPort, port instead
-**return value:** \
+**return value:**
if the Kubernetes endpoints value is as follows:
```yaml
@@ -274,73 +280,68 @@ a nodes("release/default/plat-dev:port") call will get follow result:
## Q&A
-> Q: Why only support configuration token to access _Kubernetes APIServer_ \
-> A: Usually, we will use three ways to complete the authentication of _Kubernetes APIServer_:
->
->+ mTLS
->+ token
->+ basic authentication
->
-> Because lua-resty-http does not currently support mTLS, and basic authentication is not recommended,\
-> So currently only the token authentication method is implemented
+**Q: Why only support configuration token to access _Kubernetes APIServer_?**
----
+A: Usually, we will use three ways to complete the authentication of _Kubernetes APIServer_:
-> Q: APISIX inherits Nginx's multiple process model, does it mean that each nginx worker process will [_List-Watch_](https://kubernetes.io/docs/reference/using-api/api-concepts/) kubernetes endpoints resources \
-> A: The Kubernetes service discovery only uses privileged processes to [_List-Watch_](https://kubernetes.io/docs/reference/using-api/api-concepts/) Kubernetes endpoints resources, then store theirs value \
-> into ngx.shared.DICT, worker processes get results by querying ngx.shared.DICT
++ mTLS
++ Token
++ Basic authentication
----
+Because lua-resty-http does not currently support mTLS, and basic authentication is not recommended, so currently only the token authentication method is implemented.
+
+**Q: APISIX inherits Nginx's multiple process model, does it mean that each nginx worker process will [_List-Watch_](https://kubernetes.io/docs/reference/using-api/api-concepts/) kubernetes endpoints resources?**
+
+A: The Kubernetes service discovery only uses privileged processes to [_List-Watch_](https://kubernetes.io/docs/reference/using-api/api-concepts/) Kubernetes endpoints resources, then store theirs value into `ngx.shared.DICT`, worker processes get results by querying `ngx.shared.DICT`.
-> Q: What permissions do [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) require \
-> A: ServiceAccount requires the permissions of cluster-level [ get, list, watch ] endpoints resources, the declarative definition is as follows:
->
->```yaml
->kind: ServiceAccount
->apiVersion: v1
->metadata:
-> name: apisix-test
-> namespace: default
->---
->
->kind: ClusterRole
->apiVersion: rbac.authorization.k8s.io/v1
->metadata:
-> name: apisix-test
->rules:
->- apiGroups: [ "" ]
-> resources: [ endpoints ]
-> verbs: [ get,list,watch ]
->---
->
->apiVersion: rbac.authorization.k8s.io/v1
->kind: ClusterRoleBinding
->metadata:
-> name: apisix-test
->roleRef:
-> apiGroup: rbac.authorization.k8s.io
-> kind: ClusterRole
-> name: apisix-test
->subjects:
-> - kind: ServiceAccount
-> name: apisix-test
-> namespace: default
->```
+**Q: What permissions do [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) require?**
+
+A: ServiceAccount requires the permissions of cluster-level [ get, list, watch ] endpoints resources, the declarative definition is as follows:
+
+```yaml
+kind: ServiceAccount
+apiVersion: v1
+metadata:
+ name: apisix-test
+ namespace: default
+---
+kind: ClusterRole
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+ name: apisix-test
+rules:
+- apiGroups: [ "" ]
+ resources: [ endpoints ]
+ verbs: [ get,list,watch ]
---
-> Q: How to get [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) token value \
-> A: Assume your [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) located in namespace apisix and name is Kubernetes-discovery, you can use the following steps to get token value
->
-> 1. Get secret name: \
-> you can execute the following command, the output of the first column is the secret name we want
->
-> ```shell
-> kubectl -n apisix get secrets | grep kubernetes-discovery
-> ```
->
-> 2. Get token value: \
-> assume secret resources name is kubernetes-discovery-token-c64cv, you can execute the following command, the output is the service account token value we want
->
-> ```shell
-> kubectl -n apisix get secret kubernetes-discovery-token-c64cv -o jsonpath={.data.token} | base64 -d
-> ```
+
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+ name: apisix-test
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: ClusterRole
+ name: apisix-test
+subjects:
+ - kind: ServiceAccount
+ name: apisix-test
+ namespace: default
+```
+
+**Q: How to get [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) token value?**
+
+A: Assume your [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) located in namespace apisix and name is Kubernetes-discovery, you can use the following steps to get token value.
+
+ 1. Get secret name. You can execute the following command, the output of the first column is the secret name we want:
+
+ ```shell
+ kubectl -n apisix get secrets | grep kubernetes-discovery
+ ```
+
+ 2. Get token value. Assume secret resources name is kubernetes-discovery-token-c64cv, you can execute the following command, the output is the service account token value we want:
+
+ ```shell
+ kubectl -n apisix get secret kubernetes-discovery-token-c64cv -o jsonpath={.data.token} | base64 -d
+ ```
diff --git a/docs/zh/latest/discovery/kubernetes.md b/docs/zh/latest/discovery/kubernetes.md
index e1bc22122..173428820 100644
--- a/docs/zh/latest/discovery/kubernetes.md
+++ b/docs/zh/latest/discovery/kubernetes.md
@@ -1,5 +1,12 @@
---
title: Kubernetes
+keywords:
+ - Kubernetes
+ - Apache APISIX
+ - 服务发现
+ - 集群
+ - API 网关
+description: 本文将介绍如何在 Apache APISIX 中基于 Kubernetes 进行服务发现以及相关问题汇总。
---
<!--
@@ -271,74 +278,68 @@ nodes("release/default/plat-dev:port") 调用会得到如下的返回值：
## Q&A
-> Q: 为什么只支持配置 token 来访问 Kubernetes APIServer \
-> A: 一般情况下，我们有三种方式可以完成与 Kubernetes APIServer 的认证：
->
->+ mTLS
->+ token
->+ basic authentication
->
-> 因为 lua-resty-http 目前不支持 mTLS, basic authentication 不被推荐使用，\
-> 所以当前只实现了 token 认证方式
+**Q: 为什么只支持配置 token 来访问 Kubernetes APIServer?**
----
+A: 一般情况下，我们有三种方式可以完成与 Kubernetes APIServer 的认证：
-> Q: APISIX 继承了 Nginx 的多进程模型，是否意味着每个 APISIX 工作进程都会监听 Kubernetes Endpoints \
-> A: Kubernetes 服务发现只使用特权进程监听 Kubernetes Endpoints，然后将其值存储\
-> 到 ngx.shared.DICT，工作进程通过查询 ngx.shared.DICT 来获取结果
+- mTLS
+- Token
+- Basic authentication
----
+因为 lua-resty-http 目前不支持 mTLS, Basic authentication 不被推荐使用，所以当前只实现了 Token 认证方式。
+
+**Q: APISIX 继承了 NGINX 的多进程模型，是否意味着每个 APISIX 工作进程都会监听 Kubernetes Endpoints？**
+
+A: Kubernetes 服务发现只使用特权进程监听 Kubernetes Endpoints，然后将其值存储到 `ngx.shared.DICT` 中，工作进程通过查询 `ngx.shared.DICT` 来获取结果。
-> Q: [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) 需要的权限有哪些 \
-> A: [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) 需要集群级 [ get,list,watch ] endpoints 资源的的权限，其声明式定义如下：
->
->```yaml
->kind: ServiceAccount
->apiVersion: v1
->metadata:
-> name: apisix-test
-> namespace: default
->---
->
->kind: ClusterRole
->apiVersion: rbac.authorization.k8s.io/v1
->metadata:
-> name: apisix-test
->rules:
->- apiGroups: [ "" ]
-> resources: [ endpoints ]
-> verbs: [ get,list,watch ]
->---
->
->apiVersion: rbac.authorization.k8s.io/v1
->kind: ClusterRoleBinding
->metadata:
-> name: apisix-test
->roleRef:
-> apiGroup: rbac.authorization.k8s.io
-> kind: ClusterRole
-> name: apisix-test
->subjects:
-> - kind: ServiceAccount
-> name: apisix-test
-> namespace: default
->```
+**Q: [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) 需要的权限有哪些？**
+
+A: [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) 需要集群级 [ get,list,watch ] endpoints 资源的的权限，其声明式定义如下：
+
+```yaml
+kind: ServiceAccount
+apiVersion: v1
+metadata:
+ name: apisix-test
+ namespace: default
+---
+kind: ClusterRole
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+ name: apisix-test
+rules:
+- apiGroups: [ "" ]
+ resources: [ endpoints ]
+ verbs: [ get,list,watch ]
---
-> Q: 怎样获取指定 [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) 的 Token 值 \
-> A: 假定你指定的 [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) 资源名为 “kubernetes-discovery“, 命名空间为 “apisix”, 请按如下步骤获取其 Token 值
->
-> 1. 获取 _Secret_ 资源名: \
- > 执行以下命令，输出的第一列内容就是目标 _Secret_ 资源名
->
-> ```shell
-> kubectl -n apisix get secrets | grep kubernetes-discovery
-> ```
->
-> 2. 获取 Token 值: \
- > 假定你获取到的 _Secret_ 资源名为 "kubernetes-discovery-token-c64cv", 执行以下命令，输出内容就是目标 Token 值
->
-> ```shell
-> kubectl -n apisix get secret kubernetes-discovery-token-c64cv -o jsonpath={.data.token} | base64 -d
-> ```
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+ name: apisix-test
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: ClusterRole
+ name: apisix-test
+subjects:
+ - kind: ServiceAccount
+ name: apisix-test
+ namespace: default
+```
+
+**Q: 怎样获取指定 [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) 的 Token 值？**
+
+A: 假定你指定的 [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) 资源名为 “kubernetes-discovery“, 命名空间为 “apisix”, 请按如下步骤获取其 Token 值。
+
+ 1. 获取 _Secret_ 资源名。执行以下命令，输出的第一列内容就是目标 _Secret_ 资源名：
+
+ ```shell
+ kubectl -n apisix get secrets | grep kubernetes-discovery
+ ```
+
+ 2. 获取 Token 值。假定你获取到的 _Secret_ 资源名为 "kubernetes-discovery-token-c64cv", 执行以下命令，输出内容就是目标 Token 值：
+
+ ```shell
+ kubectl -n apisix get secret kubernetes-discovery-token-c64cv -o jsonpath={.data.token} | base64 -d
+ ```