This is an automated email from the ASF dual-hosted git repository.
wwei pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/yunikorn-site.git
The following commit(s) were added to refs/heads/master by this push:
new 703a62fa2 [YUNIKORN-1414] Adding Chinese translations of Sorting
Policies (#275)
703a62fa2 is described below
commit 703a62fa2e3ececf151ea10e2e8cc00d48093c89
Author: KatLantyss <[email protected]>
AuthorDate: Thu Mar 16 14:27:36 2023 +0800
[YUNIKORN-1414] Adding Chinese translations of Sorting Policies (#275)
---
.../current/user_guide/resource_quota_mgmt.md | 334 +++++++++++++++++++++
.../current/user_guide/sorting_policies.md | 190 ++++++++++++
2 files changed, 524 insertions(+)
diff --git
a/i18n/zh-cn/docusaurus-plugin-content-docs/current/user_guide/resource_quota_mgmt.md
b/i18n/zh-cn/docusaurus-plugin-content-docs/current/user_guide/resource_quota_mgmt.md
new file mode 100644
index 000000000..9233142a3
--- /dev/null
+++
b/i18n/zh-cn/docusaurus-plugin-content-docs/current/user_guide/resource_quota_mgmt.md
@@ -0,0 +1,334 @@
+---
+id: resource_quota_management
+title: Resource Quota Management
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+## Quota configuration and rules
+YuniKorn can offer a finer grained resource quota management setup compared to
the simple namespace resource quota provided by Kubernetes.
+
+On Kubernetes a pod must fit into the namespace quota when the pod is
submitted.
+If the pod does not fit in the namespace quota the pod is rejected.
+The client must implement a retry-mechanism and re-submit the pod if it needs
the pod to be scheduled.
+
+Contrary to quotas in Kubernetes YuniKorn does not enforce quotas on
submission but only on actively consumed resources.
+To explain the difference: when using YuniKorn for quota enforcement a new pod
submitted to Kubernetes is always accepted.
+Yunikorn will queue the pod without counting the queued pod's resources
towards the consumed quota.
+When YuniKorn tries to schedule the pod it checks at scheduling time if the
pod fits in the quota configured for the queue the pod is assigned to.
+If at that point the pod does not fit in the quota the pod is skipped and not
counted in the resource consumption.
+This means that until a scheduling attempt of a pod is successful a pod it is
not consuming resources in the YuniKorn quota system.
+
+Resource quotas in YuniKorn are linked to the queue and its place in the queue
hierarchy.
+The base of the queue structure, the `root` queue, does not allow setting a
quota as it reflects the current size of the cluster.
+Node additions and removals update the `root` queue quota automatically.
+
+Beside the `root` queue the quotas can be set, and is enforced, at any point
in the hierarchy.
+Every queue can have a quota set. The quota is enforced recursively throughout
the hierarchy.
+This means that a child queue can never use more resources than the
**configured** quota of the parent queue.
+Setting a quota on a child queue larger than its parent queue's quota would
thus not have any effect and is handled as a configuration error.
+
+In the hierarchy there are some further rules that need to be considered.
+If a parent queue has multiple children the sum of the **usage** of all
children combined can never exceed the quota **configured** on the parent.
+However, from a configuration perspective this does not mean that the sum of
the **configured** quotas for all children must be smaller than the parent
quota.
+
+
+
+As an example the `root.parent` queue has a quota of 900.
+It contains three child queues, two with a quota set.
+The `root.parent.child1` has no quota set and will thus be limited to the
`root.parent` quota.
+The two other queues `root.parent.child2` and `root.parent.child3` each have a
quota of 750 set.
+During normal operation the total usage of the 3 child queues together will be
900.
+The applications running in each child queue have a demand of more than 1000
each.
+
+Distribution in that case could be any of:
+* all 900 used by just the `child1` queue
+* spread out evenly over the 3 queues (300 by each)
+* `child2` maxed out using 750, and the left over 150 used by `child3`
+
+The exact distribution between the queues will fluctuate and is dependent on
the scheduling policies.
+
+## Converting Kubernetes resources and quotas
+Resource support for pods is limited to the resources specified as part of the
_requests_ specification:
+* _cpu_ is mapped to _vcore_ with the value in milli cpu.
+* _memory_ is mapped to _memory_ with the value in MB (1 MB = 10^6 B = 1 000
000 B).
+* all other resources are mapped as provided.
+
+Extended resource as per the [Kubernetes
documentation](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/)
are supported.
+
+Example pod with a single container:
+```yaml
+apiVersion: v1
+kind: Pod
+spec:
+ containers:
+ - name: container-1
+ resources:
+ requests:
+ cpu: "250m"
+ memory: "1Gi"
+ hugepages-1Gi: "1"
+```
+The above specification will set pod resources request for scheduling in
YuniKorn to:
+* _vcore_ -> 250m
+* _memory_ -> 1073741824
+* _hugepages-1Gi_ -> 1
+
+Two remarks:
+Multiple container specifications will be aggregated into one total pod
resource request automatically. All memory is reported in bytes.
+
+In the case that static queue definitions are used for a queue there is no
limit on the type of resource that can be specified in a quota.
+Quota annotations on namespaces, used as part of the automatic queue creation,
are limited to the equivalent _cpu_ and _memory_ resources.
+See the [setup](#Namespace-quota) below for the annotations on the namespace
for quotas.
+
+## Kubernetes and YuniKorn quota interaction
+The recommendation is to turn off, not configure, the Kubernetes Namespace
quotas.
+Using only YuniKorn queue quotas provides a more flexible setup and allows
queueing of workloads.
+
+In a setup that has both YuniKorn and Kubernetes quotas turned on consider the
following points:
+* Two separate configurations need to be maintained.
+ This increases the maintenance burden, and the possibility of configuration
mistakes.
+* Both quotas will be enforced.
+
+Having both quotas turned on can lead to unexpected behaviour.
+The main issue is the fact that the Kubernetes namespace quota is enforced on
submit.
+There are three combinations of quota configuration that are possible.
+The 3 combinations could have two effects when used in combination with the
YuniKorn quota.
+
+1. Both quotas are _equal_: workloads will not be queued, the full configured
quota can be used.
+ - Maximum usage and queueing will be limited to the set quota
+2. Kubernetes quota is _lower_ than YuniKorn: the YuniKorn quota will never be
reached and workloads will not be queued.
+ - Maximum usage will be limited to the Kubernetes quota.
+3. Kubernetes quota is _higher_ than YuniKorn: YuniKorn will limit the usage
to the quota set in YuniKorn.
+ The Kubernetes quota will be enforced on submit and thus set the limit for
the workload that can be queued on top of the YuniKorn quota.
+ - Maximum usage will be limited to the YuniKorn quota.
+ - Workload queueing will be limited to the Kubernetes quota.
+
+:::note
+The following configuration examples are just to demonstrate the format needed
+to create a queue hierarchy with quotas set.
+:::
+
+## Static queue definition
+
+### Goal
+A preconfigured hierarchy of queues with a maximum and guaranteed capacity.
+The users can only submit applications to the leaf queues.
+This approach manages the resource capacity for each of the queues, which is
suitable to the scenarios that queues do not change too often.
+
+### Configuration
+Apply the following configuration to YuniKorn's configmap to:
+* setup 3 queues under `root`
+* each queue has a specific guaranteed and maximum capacity
+* anyone can submit to any queue
+
+```yaml
+partitions:
+ - name: default
+ queues:
+ - name: root
+ submitacl: '*'
+ queues:
+ - name: advertisement
+ resources:
+ guaranteed:
+ memory: 500G
+ vcore: 50
+ max:
+ memory: 800G
+ vcore: 80
+ - name: search
+ resources:
+ guaranteed:
+ memory: 400G
+ vcore: 40
+ max:
+ memory: 600G
+ vcore: 60
+ - name: sandbox
+ resources:
+ guaranteed:
+ memory: 100G
+ vcore: 10
+ max:
+ memory: 100G
+ vcore: 10
+```
+
+### Run a workload
+In order to run applications in specific queues, you will need to set the
following labels in all pod specs.
+All pods with the same `applicationID` label are considered ti be one
application.
+In the below example the application `my-test-app` will run in the queue
`root.sandbox`:
+
+```yaml
+labels:
+ app: my-test-app
+ applicationId: "my-test-app-01"
+ queue: root.sandbox
+```
+
+## Namespace to queue mapping
+
+### Goal
+Automatically map a Kubernetes `namespace` to a queue in YuniKorn.
+The user creates the required namespaces in Kubernetes.
+The YuniKorn k8s shim and core scheduler automatically pass the required
information and map the namespace to a queue, creating the queue if it does not
exist.
+The resource quota will be managed by YuniKorn instead of using the Kubernetes
namespace quota.
+This does require the namespaces to be setup without Kubernetes quota
enforcement and tags as per the [setup](#Namespace-quota) below.
+
+### Configuration
+Apply the following configuration to YuniKorn's configmap:
+
+```yaml
+partitions:
+ - name: default
+ placementrules:
+ - name: tag
+ value: namespace
+ create: true
+ queues:
+ - name: root
+ submitacl: '*'
+ properties:
+ application.sort.policy: stateaware
+```
+
+This configuration places an application based on the `tag` rule.
+The tag selected is the `namespace` tag which is automatically added by the
k8s shim to all applications that get created.
+The `create` flag is set to true which will trigger the creation of the queue
with the same name as the namespace if it does not exist.
+
+Applications within the automatically created child queues will be sorted
based sorting policy set on the parent queue.
+In this case the property `application.sort.policy` is in this configuration
set to `stateaware`.
+This is a simple app sorting policy applicable for batch jobs, you can find
more document [here](sorting_policies.md#StateAwarePolicy).
+
+You can change the configuration using the helm charts during the installation
by overwriting the configuration in the
+[helm chart
template](https://github.com/apache/yunikorn-release/blob/master/helm-charts/yunikorn/values.yaml#L71-L81).
+
+### Namespace quota
+Namespaces in Kubernetes contain the quota information.
+If a quota is set on a namespace Kubernetes will automatically enforce the
quota.
+In the case that YuniKorn is used for quota enforcement no quota must be set
on the namespace.
+
+To allow specifying a quota on the namespace the following annotations should
be set in the namespace object:
+
+```yaml
+yunikorn.apache.org/namespace.quota: "{\"cpu\": \"64\", \"memory\": \"100G\",
\"nvidia.com/gpu\": \"1\"}"
+```
+YuniKorn will parse these annotations and set the maximum capacity of the
queue mapped to this namespace.
+The values specified follow the standard Kubernetes formatting and unit
specification.
+Annotation value must be a single json compliant string. Ensure double quotes
iare escaped properly to not cause any problems.
+
+The example above will limit the queue mapped to the annotated namespace to 64
CPUs, 100GB memory and 1 `nvidia.com/gpu`.
+
+[DEPRECATED]
+The below annotations are deprecated and will be removed from next major
release.
+They only support mapping memory and cpu, not other resource types.
+```yaml
+yunikorn.apache.org/namespace.max.cpu: "64"
+yunikorn.apache.org/namespace.max.memory: "100Gi"
+```
+The example for the deprecated annotation will set the queue quota to 64 CPUs
and 100GB memory.
+
+### Run a workload
+
+Applications, and the pods that are part of the application, can be submitted
without specific labels.
+YuniKorn will automatically add the required tags.
+The configured placement rule will create the queue, if required, and add the
application to the queue.
+
+For example, if an application is submitted to namespace `development`, then
the application will run in the `root.development` queue.
+
+## Parent queue mapping for namespaces
+
+### Goal
+Though the tag placement rule using the `namespace` tag is capable of placing
an application in a queue this might not be enough in all setups.
+In some cases, multi tenancy for example, namespaces need to be grouped
together.
+Administrators could annotate namespaces which allows dynamic placement of
applications based on multiple annotations if placement rules were setup.
+YuniKorn cannot and does not just add all annotations from a namespace to an
application.
+
+To help support this grouping case a parent queue can be tagged on a
namespace.
+
+### Configuration
+The configuration for this functionality consists of two pieces:
+1. the mapping rule
+1. the namespace annotation
+
+First we set the following configuration to YuniKorn's configmap:
+
+```yaml
+partitions:
+ - name: default
+ placementrules:
+ - name: tag
+ value: namespace
+ create: true
+ parent:
+ name: tag
+ value: namespace.parentqueue
+ queues:
+ - name: root
+ queues:
+ - name: production
+ parent: true
+ - name: development
+ parent: true
+```
+
+The configuration used for the namespace to queue mapping is the same as
[above](#Namespace-to-queue-mapping).
+As an extension to the placement rule a `parent` rule is added to support the
grouping.
+The parent rule is used to generate the parent, or the queue above, in the
hierarchy.
+The rule uses the tag `namespace.parentqueue` from the application to generate
the parent queue name.
+The `namespace.parentqueue` tag is automatically added by the Kubernetes shim
but does require a namespace annotation (see below).
+
+In the example rule configuration given the `create` flag is not set on the
parent rule.
+This means that the parent queue must exist in the configuration otherwise the
application submit will fail.
+For the example configuration this means supported values for the parent are
thus limited to `production` and `development`.
+
+Quotas cannot be set on the parent queue using any of these mappings.
+The quota linked to the namespace is set on the namespace queue not the parent
as per the namespace mapping provided earlier.
+
+Parent queue quotas must always be set directly in the configuration.
+This requires the `create` flag to be set to `false` on the parent rule.
+
+### Namespace parent queue
+Contrary to the namespace name itself, and inline with the quota settings, the
namespaces need to be annotated to use the parent queue mapping.
+Namespace names must be unique in Kubernetes which is not affected by this
annotation.
+The same annotation value may be used for multiple namespaces:
+```yaml
+yunikorn.apache.org/parentqueue: root.production
+```
+
+The example annotation above will map the parent queue to the existing
`root.production` queue.
+Note that the rule will fully qualify the name if needed, you can thus omit
the `root.` part in the annotation.
+If the annotation starts with `root.` the system assumes it is a fully
qualified queue name.
+
+To complete the picture here is an image that shows the mapping from
Kubernetes namespaces to queues in YuniKorn.
+It uses the annotations on the namespaces in Kubernetes as described, and the
example configuration for the mapping rules.
+The `finance` and `sales` namespaces become queues grouped under the parent
queue `production`.
+The namespaces `dev` and `test` are placed under the `development` parent
queue.
+
+
+
+### Run a workload
+Applications, and the pods that are part of the application, can be submitted
without specific labels or changes.
+YuniKorn will add the tags, the placement rules will do the rest.
+The configured placement rule will create the queues, if required, and add the
application to the queue.
+
+Since the namespace `finance` is annotated with the example value, and the
rules are in place.
+Applications in the `finance` namespace will run in the
`root.production.finance` queue that is created dynamically.
diff --git
a/i18n/zh-cn/docusaurus-plugin-content-docs/current/user_guide/sorting_policies.md
b/i18n/zh-cn/docusaurus-plugin-content-docs/current/user_guide/sorting_policies.md
new file mode 100644
index 000000000..49d64e900
--- /dev/null
+++
b/i18n/zh-cn/docusaurus-plugin-content-docs/current/user_guide/sorting_policies.md
@@ -0,0 +1,190 @@
+---
+id: sorting_policies
+title: 排序策略
+---
+
+<!--
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ -->
+
+调度器使用策略可以在不更改代码的情况下改变调度行为。
+可以为以下项目设置策略：
+* [应用程序](#应用程序排序)
+* [节点](#节点排序)
+* [请求](#请求排序)
+
+## 应用程序排序
+通过配置为每个队列设置应用程序排序策略。排序策略设置仅对*叶子*队列有效。每个*叶子*队列可以使用不同的策略。
+
+排序策略仅指定应用程序在队列内排序的顺序。
+该顺序对于指定在分配资源时首先考虑哪个应用程序非常重要。
+排序策略*不会*影响在队列中同时调度或激活的应用程序数量。
+所有具有待处理资源请求的应用程序都可以并且将在队列中调度，除非明确地被过滤掉。
+即使使用先进先出策略(FIFO)对应用程序进行排序，多个应用程序也将在队列中并行运行。
+
+*父*队列始终使用公平策略对子队列进行排序。
+
+考虑子队列的相对优先级（在*父*队列排序的情况下）和应用程序的相对优先级（在*叶子*队列排序的情况下）。
+要在调度时忽略应用程序和队列优先级，请将队列属性`application.sort.priority`设置为`disabled`。
+
+以下配置条目将应用程序排序策略设置为FIFO，适用于队列`root.sandbox`：
+
+```yaml
+partitions:
+ - name: default
+ queues:
+ - name: root
+ queues:
+ - name: sandbox
+ properties:
+ application.sort.policy: fifo
+```
+
+仅考虑具有未处理请求的应用程序进行调度。
+在排序应用程序*时*应用筛选器以移除所有没有未处理请求的应用程序。
+
+### FifoSortPolicy
+简短描述：先进先出，基于应用程序创建时间。
+
+配置值：`fifo`（默认）
+
+在排序之前，需要过滤应用程序，并且必须有挂起(pending)的资源请求。
+
+经过筛选后，应用程序将根据创建时间戳进行排序，不会使用其他过滤。
+由于系统仅在锁定状态下添加应用程序，因此不可能有两个具有完全相同时间戳的应用程序。
+
+结果，最早的请求资源的应用程序获得资源。
+较晚请求的应用程序将在满足之前应用程序当前所有请求之后获得资源。
+
+### FairSortPolicy
+简短描述：基于资源利用率公平性排序。
+
+配置值： `fair`
+
+在排序之前，需要过滤应用程序，并且必须有挂起(pending)的资源请求。
+
+经过筛选后，剩下的应用程序将根据使用情况进行排序。
+应用程序的使用情况是指应用程序所有已确认和未确认的分配。
+计算使用情况时，将考虑应用程序中定义的所有资源。
+
+达到的效果是资源相对平均分配给所有请求资源的应用程序
+
+### StateAwarePolicy
+简短描述：限制同一时间只有一个为 Starting 或 Accepted 状态的应用程序。
+
+配置值： `stateaware`
+
+此排序策略需要了解应用程序状态。
+应用程序状态在[应用程序状态](design/scheduler_object_states.md#application-state)文档中进行了描述。
+
+在对所有排队的应用程序进行排序之前，将应用以下过滤器：
+第一个过滤器基于应用程序状态。
+以下应用程序通过过滤器并生成第一个中间列表：
+* 处于 *running* 状态的所有应用程序
+* *一个*（1）处于 *starting* 状态的应用程序
+* 如果*没有*处于 *starting* 状态的应用程序，则添加 *一个*（1）处于 *accepted* 状态的应用程序
+
+第二个过滤器将第一个过滤器的结果作为输入。
+再次过滤初步列表：删除所有*没有*挂起(pending)请求的应用程序。
+
+根据状态和挂起(pending)请求进行过滤后，剩余的应用程序将进行排序。
+因此，最终列表将使用剩余的应用程序两次过滤并按创建时间排序。
+
+回顾下 *Starting* 和 *Accepted* 状态的交互：
+只有在没有处于 *Starting* 状态的应用程序时，才会添加处于 *Accepted* 状态的应用程序。
+处于 *Starting* 状态的应用程序不必有挂起(pending)请求。
+任何处于 *Starting* 状态的应用程序都将防止 *Accepted* 应用程序被添加到已过滤的列表中。
+
+有关详细信息，请参阅设计文档中的 [示例](design/state_aware_scheduling.md#example-run) 运行。
+
+达到的效果是，已经在运行的应用程序讲优先得到资源。
+在所有已运行的应用程序后，逐一调度新的应用程序。
+
+
+## 节点排序
+节点排序策略通过配置文件为每个分区设置，不同的分区可以使用不同的策略。
+以下配置项将分区`default`的节点排序策略设置为`fair`:
+```yaml
+partitions:
+ - name: default
+ nodesortpolicy:
+ type: fair
+```
+
+### FairnessPolicy
+简要描述：按可用资源排序，按降序排列
+
+配置值：`fair` (默认值)
+
+行为：
+按可用资源的数量对节点列表进行排序，使具有最高可用资源量的节点排在列表的第一位。
+计算使用情况时，将考虑节点上定义的所有资源。
+对于节点的相同类型资源进行比较。
+
+这将导致考虑可用性最低的节点首先进行新分配的分配，从而在所有可用节点上分散分配。
+这将导致每个可用节点的整体利用率降低，除非整个环境的利用率非常高。
+将所有节点的负载保持在相似水平有助于。
+在自动缩放添加新节点的环境中，这可能会触发意外的自动缩放请求。
+
+### BinPackingPolicy
+简要描述：按可用资源排序，按升序排列
+
+配置值：`binpacking`
+
+行为：
+按可用资源的数量对节点列表进行排序，使具有最低可用资源量的节点排在列表的第一位。
+计算使用情况时，将考虑节点上定义的所有资源。
+对于节点的相同类型资源进行比较。
+
+这将导致考虑可用性最高的节点首先进行新分配的分配，从而使少量节点的利用率更高，更适合云部署。
+
+## 资源加权
+节点排序策略可能使用节点利用率来确定顺序。
+因为节点可以具有多个唯一的资源类型，所以节点的利用率是由其各个资源类型的加权平均值确定的。
+资源加权可以通过使用`nodesortpolicy`的`resourceweights`部分进行自定义。
+如果`resourceweights`不存在或为空，则默认配置将`vcore`和`memory`的权重设置为相等的`1.0`。
+所有其他资源类型都将被忽略。
+只有明确提到的资源类型才会具有权重。
+
+YuniKorn在内部跟踪CPU资源作为`vcore`资源类型。
+这将映射到Kubernetes资源类型`cpu`。
+除`vcore`和memory之外，所有其他资源类型在YuniKorn和Kubernetes之间具有一致的命名。
+
+例如，在默认配置中，如果节点的CPU和内存分别分配了`90％`和`50％`，则该节点将被视为已使用`70％`。
+
+以下配置条目为分区default设置了`vcore`权重为`4.0`和`memory`权重为`1.0`。
+这将使CPU使用的权重比内存使用高四倍：
+```yaml
+partitions:
+ - name: default
+ nodesortpolicy:
+ type: fair
+ resourceweights:
+ vcore: 4.0
+ memory: 1.0
+```
+
+使用此配置，在此示例中，如果节点的CPU和内存分别分配了`90％`和`50％`，则该节点将被视为已使用`82％`。
+
+请注意，权重是相对于彼此的，因此指定`{4.0，1.0}`的权重等效于`{1.0，0.25}`。不允许负权重。
+
+## 请求排序
+当前仅有一种策略可用于在应用程序内对请求进行排序。
+此策略不可配置。
+仅可以基于请求的优先级对请求进行排序。
+如果应用程序中有多个具有相同优先级的请求，则请求的顺序未确定。
+这意味着具有相同优先级的请求的顺序可能会在运行之间改变。
\ No newline at end of file
