# Placement Rule 配置
placement 的基礎概念請參考[其他官方文檔](/@ntcu-k8s/S1S1vtGM0#placement-rules-定義)

placement rule 可以被多個 rule 連鎖構建起來，並且內部的 ACLs 跟 filter 依然由 rule 定義，並依 rule 強制執行

## 配置
每個 partition 只會有一個 rule 作為 scheduler queue 的配置，有關 rule 的處理順序、回傳的 queue 名稱請參考[其他文檔筆記](/@ntcu-k8s/S1S1vtGM0#placement-rules-定義)

在 rule 處理時，先前產生的結果並不會干涉到現在處理的 rule，也就是說，其他 rule 不會影響到其他 rule ， parent rule 除外，這在[之後](#parent)會提及

如果沒產生一個 queue name 且沒有更多 rule 可以使用，則會拒絕 application

配置基礎架構如下：

placementrules:
  - name: <name of the 1st rule>
  - name: <name of the 2nd rule>

每個 rule 使用預先定義的配置屬性如：
- name
- create
- parent
- filter
- value

對於 rule name，命名規則如下：
- 使用 a-z 或 A-Z 開頭
- 接著零個或多個字元 a-z A-Z 0-9 或 _

沒有使用上述規則的 rule 會產生 error ，一個有 error 的 rule 會被視為不被啟用的
只有在設定一個可被啟用的 rule 時， placement manager 才會被視為是初始化的，如果載入一個新的不被啟用的 rule 配置，則 placement manager 將維持原本的配置

### create
create 屬性是一個布林值，它的意義是「如果目標 queue 不存在，是否允許 rule 產生 queue」，如果目標 queue 不存在且 `create` 不為 `true` 則會 `fail`
但不一定設為 `true` 就會創建 queue ，因為其他 queue 可能防止 queue 的創建

可修改值：`true` 、 `false`
預設值：`false`

簡單配置範例如下：

placementrules:
  - name: <name of the rule>
    create: true

### parent
parent 屬性就是「是否使用其他 rule 來當作目前 rule 的父 rule」，parent 可以是巢狀的，且沒有深度限制
最頂層的 parent rule 具有與其他 rule 相同的參數及要求

使用已經產生完全合格的 queue 的 rule 當成 parent rule 會產生錯誤，這個例外情況在類型為 fixed 時產生，類型在[之後](#fixed)會提及

> rule 會向下遍歷過所有 rule，而在最後一個 parent rule 開始判斷，同時，最後一個 parent rule 代表在 `root` 下面生成 queue ，也就是說，巢狀使用了幾個 parent rule，對於 `root` 的深度就是多深

預設值：空

基本配置架構如下：

placementrules:
  - name: <name of the rule>
    parent:
      name: <name of the parent rule>

### Filter
filter 是選擇可被 rule 應用的 user / group ，可以用以下兩種方法配置：
- 正規表達式
- user / group 的 list

多於一個的 user / group 會被視為 list ，重複的部分會被忽略，且不能在旁邊增加正規表達式

對於 user name ，可用字元規則為：
- 使用 a-z A-Z 開頭
- 接著零個或多個字元像是 a-z A-Z 0-9 或 _ . @ -
- 最後一個字元可以是 \$

對於 group name 則是：
- 使用 a-z A-Z 開頭
- 接著零個或多個字元像是 a-z A-Z 0-9 或 _

一個元素的 list ，內部可以是單一 user / group 或一個正規表達式，使用命名規則以外的字元將被視為正規表達式，無法編譯的正規表達式將被忽略

對於 group 的正規表達式是「一次符合一組，而不是一個 list of groups」

預設值：空

配置文件架構為：

filter:
  type: deny
  users:
    - <user name or regexp>
    - <user name>
  groups:
    - <group name or regexp>
    - <group name>

### value
value 是拿來實作或控制 rule 的行為，它會被 fixed 或者 tag 使用，這兩個都會在之後提及，它的 type 是 string

預設值：空

配置文件架構為：

placementrules:
  - name: <name of the rule>
    value: "any string"

## ACLs (Access Control List)
ACLs 不是在 rule 的配置中定義，但是會影響它的輸出，它在 queue 的配置文件下有兩種類型會被定義：

1. Submit ACL: submitacl
2. Administration ACL: adminacl

placement rule 只會在「其中一個 ACL 具有提交權限時」相符，如果 queue 沒有 ACLs ，則會往上遞迴檢查

查看[其他官方文檔](https://yunikorn.apache.org/docs/user_guide/acls)以獲得更多資訊

## rule name 配置
### provided
使用這個 name 將會回傳一個完全合法的 queue 給 application，如果 rule 配置的 queue 不合法，則會使得 queue 合法
如果 parent rule 回傳一個完全合法的 queue ，則停止判斷

可用屬性：
- create
- parent
- filter

如果 user 下面不存在 queue 則建立一個的範例：

placementrules:
  - name: provided
    create: true
    parent:
      name: user
      create: true

`developer` 提交一個 appliction，並指定 `my_special_queue` 這個 queue
結果：`root.develper.my_special_queue` (parent rule 設定了 user name 的 queue)

`developer` 提交一個 application，並指定 `root.dev_queue` 這個 queue
結果：`root.dev_queue` (parent rule 被忽略了)

### user
基於 application 提交的 user name 回傳一個 queue

可用屬性：
- create
- parent
- filter

基於 user name 回傳一個 queue ，如果不存在則**不**創建一個新的 queue 的範例：

placementrules:
  - name: user
    create: false

user `finance.test` 提交了 application，而且 queue 存在
結果：`root.finance_dot_test` (注意 "." 被解析成 "\_dot\_")

user `developer` 提交了 application，並且 queue 不存在
結果： 失敗，繼續判斷下一個 rule

### fixed
使用 `value` 屬性的配置指定 queue 的 name ，它的配置應該是一個合法的 queue name 或 queue 階層，它不一定是完全合法的 queue name

如果 `value` 屬性是完全合格的 queue name ，那麼 parent rule 將會被視為 error

可用屬性：
- value (必需)
- create
- parent
- filter

沒有 `create` 屬性（因此 queue 必須是 *leaf queue*）的範例：

placementrules:
  - name: fixed
    value: last_resort

user `developer` 提交了 application ，並且指定 `my_special_queue` 作為配置的 queue
結果：`root.last_resort`

### tag
從 application tag 搜索出 queue name ，tag 的選擇基於 `value` 的配置
如果沒有配置 `value` 屬性則會出錯，但 application 不一定需要配置 tag

如果 application 上沒有配置 tag ，則會失敗，如果成功回傳一個完全合法的 queue name，則 parent rule 不會執行

可用屬性：
- value (必需)
- create
- parent
- filter

基於 k8s 的 `namespace` 屬性放置 application 的範例：

placementrules:
  - name: tag
    value: namespace
    create: true

user `developer` 提交 `default` namespace 的 application，並且指定 queue `my_special_queu`
結果：`root.default`

user `developer` 提交 `default` namespace 的 application
結果：`root.default`

user `developer` 提交不是 k8s-based 的 application
結果：失敗，繼續判斷下一個 rule

## 較複雜的範例
在此範例中，我們連鎖了三個 rule
1. 一個 `user` rule，且 user 限定為 `dev` group 的 user
其 parent rule 是「使用 k8s namespace 判斷的 `tag` rule」
2. 一個 `tag` rule，且使用 k8s 的 namesapce 作為判斷
其 parent rule 是「使用 `root.namespaces` 這個已存在的 queue 作為固定 queue 的 `fixed` rule」
3. 一個 `fixed` rule，將所有到達此判斷的 application 放置在 `root.default`

範例配置檔案：

placementrules:
  - name: user
    create: true
    filter:
      type: allow
      groups:
        - dev*
    parent:
      name: tag
      value: namespace
  - name: tag
    value: namespace
    create: true
    parent:
      name: fixed
      value: root.namespaces
      filter:
        type: allow
        users:
          - john
  - name: fixed
    value: root.default

user `john` 提交了 namespace 為 `testing` 的 application
結果：`root.namespaces.testing` (第二個 rule)

屬於 `sarah, test_app, dev_app` 這些 group 的 user `sarah` 提交了一個 namespace 為 `newapp` 的 application
結果：`root.newapp.sarah` (第一個 rule)

屬於 `bob` group 的 user `bob` 提交了 namespace 為 `testapp` 的 application
結果：`root.default` (第三個 rule)

在第二個範例中，我們連鎖使用了兩個 rule:
1. `fixed` rule 將所有 application 放置在 `root.production` 這個 queue 裡面
2. 包含 `create` 屬性的 `user` rule

在使用以下配置後，只有 user `john` 及 `bob` 可以將 application 放置在 `root.production` ，其他的 user 則會放置在自己名稱的 queue 底下(如果沒有，則建立)

partitions:
  - name: default
    queues:
      - name: production
        submitacl: john,bob
    placementrules:
      - name: fixed
        value: root.production
      - name: user
        create: true

---
[官方文檔連結](https://yunikorn.apache.org/docs/user_guide/placement_rules)