From fee96a15098dfcb03d4aa84258c19996a1d4ff56 Mon Sep 17 00:00:00 2001 From: Manikandan R Date: Thu, 22 Aug 2024 16:22:01 +0530 Subject: [PATCH 1/3] [YUNIKORN-2783] Doc changes to describe the new behaviour and caveats --- .../labels_and_annotations_in_yunikorn.md | 14 +++++++----- docs/user_guide/placement_rules.md | 11 ++-------- docs/user_guide/queue_config.md | 22 +++++++++++++++++-- 3 files changed, 30 insertions(+), 17 deletions(-) diff --git a/docs/user_guide/labels_and_annotations_in_yunikorn.md b/docs/user_guide/labels_and_annotations_in_yunikorn.md index 3e617090b84..b09556671e8 100644 --- a/docs/user_guide/labels_and_annotations_in_yunikorn.md +++ b/docs/user_guide/labels_and_annotations_in_yunikorn.md @@ -25,11 +25,13 @@ under the License. YuniKorn utilizes several Kubernetes labels and annotations to support various features: ### Labels in YuniKorn -| Name | Description | -|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| -| `applicationId` | Associates this pod with an application. | -| `queue` | Selects the YuniKorn queue this application should be scheduled in. This may be ignored if a placement policy is in effect. | -| `spark-app-selector` | Alternative method of specifying `applicationId` used by Spark Operator if the label `applicationId` and annotation `yunikorn.apache.org/app-id` unset. | +Label values should comply with [Kubernetes Syntax and character set](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). + +| Name | Description | +|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `applicationId` | Associates this pod with an application. | +| `queue` | Selects the YuniKorn queue this application should be scheduled in. Queue name should comply with [Kubernetes Syntax and character set](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set) and also with [Partition and Queue Configuration](queue_config#queues). If Queue name doesn't comply, Annotations could be used as described below. This may be ignored if a placement policy is in effect. | +| `spark-app-selector` | Alternative method of specifying `applicationId` used by Spark Operator if the label `applicationId` and annotation `yunikorn.apache.org/app-id` unset. | ### Annotations in YuniKorn All annotations are under the namespace `yunikorn.apache.org`. For example `yunikorn.apache.org/app-id`. @@ -37,7 +39,7 @@ All annotations are under the namespace `yunikorn.apache.org`. For example `yuni | Name | Description | |-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `app-id` | Assoiates this pod with an application.
The priority of applicationID is determined by: annotation `yunikorn.apache.org/app-id` > label `applicationId` > label `spark-app-selector`. | -| `queue` | Selects the YuniKorn queue this application should be scheduled in.
The priority of queue is determined by: label `queue` > annotation `yunikorn.apache.org/queue` > default. | +| `queue` | Selects the YuniKorn queue this application should be scheduled in.
Queue name should comply with rules described in [Partition and Queue Configuration](queue_config#queues).
The priority of queue is determined by: label `queue` > annotation `yunikorn.apache.org/queue` > default. | | `task-group-name` | Sets the task group name this pod belongs to for the purposes of gang scheduling. It must be listed within `task-groups`. | | `task-groups` | Defines the set of task groups for this application for gang scheduling. Each pod within an application must define all task groups. | | `schedulingPolicyParameters` | Arbitrary key-value pairs used to customize scheduling policies such as gang scheduling. | diff --git a/docs/user_guide/placement_rules.md b/docs/user_guide/placement_rules.md index 3b8b14358d8..7cc5f4c86e2 100644 --- a/docs/user_guide/placement_rules.md +++ b/docs/user_guide/placement_rules.md @@ -72,6 +72,7 @@ This means that we allow user name and or tag values to contain dots without the For queues in the configuration that as an example must map to username with a dot you must specify them as follows: A user rule with the user `user.name` will generate the queue name `root.user_dot_name` as output. If that "user queue" must be added to the configuration the `user_dot_name` name should be used. +Queue name should comply with rules described in [Partition and Queue Configuration](queue_config#queues). ### Create parameter The create parameter is a boolean flag that defines if a queue that is generated by the rule may be created if it does not exist. @@ -123,15 +124,7 @@ If the entry for users or groups contains more than 1 entry in the yaml it is al Duplicate entries in the lists are ignored and do not cause an error. Specifying a regular expression beside other list elements is not allowed. -User and group names follow the standard linux user and group conventions. -For user names: -* start with a letter: a-z or A-Z -* followed by 0 or more characters a-z, A-Z, 0-9 or _ . @ - -* the last character may also be a $ - -For group names: -* start with a letter: a-z or A-Z -* followed by 0 or more characters a-z, A-Z, 0-9 or _ - +User and group names follow the standard linux user and group conventions, also need to comply with rules described in [Partition and Queue Configuration](queue_config#limits) If the list is exactly one entry it can be either a single user or group or a regular expression. When an entry contains a character that is not allowed in a user or group name the entry is considered a regular expression. diff --git a/docs/user_guide/queue_config.md b/docs/user_guide/queue_config.md index c665fc07a3b..9df0c05878d 100644 --- a/docs/user_guide/queue_config.md +++ b/docs/user_guide/queue_config.md @@ -143,7 +143,13 @@ The name of a queue must be unique at the level that the queue is defined. Since the queue structure is fully hierarchical queues at different points in the hierarchy may have the same name. As an example: the queue structure `root.testqueue` and `root.parent.testqueue` is a valid structure. A queue cannot contain a dot "." character as that character is used to separate the queues in the hierarchy. -If the name is not unique for the queue in the configuration or contains a dot a parsing error is generated and the configuration is rejected. + +Valid Queue name: + +* must be 64 characters or less, +* could contain alphanumeric character ([a-z0-9A-Z]), underscores (_), colons (:), hashes (#), slashes (/), ampersands (&), and dashes (-). + +If the name is not unique for the queue in the configuration or contains a dot or do not follow the above rules a parsing error is generated and the configuration is rejected. Queues in the structure will automatically get a type assigned. The type of the queue is based on the fact that the queue has children or sub queues. @@ -265,7 +271,19 @@ The star "*" is the wildcard character and matches all users or groups. Duplicate entries in the lists are ignored and do not cause a parsing error. Specifying a star beside other list elements is not allowed. When a wildcard group is configured, a limit must be configured with at least one named group. -Parsing will reject the configuration with limits that do not follow this rule. + +Valid User name: + +* must start with lower case or upper case alphabet, +* followed by alphanumeric character ([a-z0-9A-Z]), underscores (_), colons (:), hashes (#), slashes (/), ampersands (&), dots (.), and dashes (-). +* could end with dollar ($). + +Valid Group name: + +* must start with lower case or upper case alphabet +* followed by alphanumeric character ([a-z0-9A-Z]), underscores (_), colons (:), dots (.), and dashes (-). + +Parsing will reject the configuration with limits that do not follow the above rules. _maxapplications_ is an unsigned integer value, which allows you to limit the number of running applications for the configured user or group. Specifying 0 for _maxapplications_ is not allowed. From 71a515bd31d5b909516ed3cd5a7ab89a13554e74 Mon Sep 17 00:00:00 2001 From: Manikandan R Date: Wed, 28 Aug 2024 14:01:01 +0530 Subject: [PATCH 2/3] Addressed review comments --- docs/user_guide/queue_config.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user_guide/queue_config.md b/docs/user_guide/queue_config.md index 9df0c05878d..d459163e518 100644 --- a/docs/user_guide/queue_config.md +++ b/docs/user_guide/queue_config.md @@ -147,7 +147,7 @@ A queue cannot contain a dot "." character as that character is used to separate Valid Queue name: * must be 64 characters or less, -* could contain alphanumeric character ([a-z0-9A-Z]), underscores (_), colons (:), hashes (#), slashes (/), ampersands (&), and dashes (-). +* could contain alphanumeric character ([a-z0-9A-Z]), underscores (_), colons (:), hashes (#), slashes (/), at signs (@), and dashes (-). If the name is not unique for the queue in the configuration or contains a dot or do not follow the above rules a parsing error is generated and the configuration is rejected. @@ -275,7 +275,7 @@ When a wildcard group is configured, a limit must be configured with at least on Valid User name: * must start with lower case or upper case alphabet, -* followed by alphanumeric character ([a-z0-9A-Z]), underscores (_), colons (:), hashes (#), slashes (/), ampersands (&), dots (.), and dashes (-). +* followed by alphanumeric character ([a-z0-9A-Z]), underscores (_), colons (:), hashes (#), slashes (/), at signs (@), dots (.), and dashes (-). * could end with dollar ($). Valid Group name: From 17d83a5093f13add7736901493e28c071bc6bedd Mon Sep 17 00:00:00 2001 From: Manikandan R Date: Wed, 4 Sep 2024 11:31:40 +0530 Subject: [PATCH 3/3] Addressed review comments --- docs/user_guide/labels_and_annotations_in_yunikorn.md | 10 +++++----- docs/user_guide/placement_rules.md | 2 +- docs/user_guide/queue_config.md | 10 +++++----- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/user_guide/labels_and_annotations_in_yunikorn.md b/docs/user_guide/labels_and_annotations_in_yunikorn.md index b09556671e8..2069d29c353 100644 --- a/docs/user_guide/labels_and_annotations_in_yunikorn.md +++ b/docs/user_guide/labels_and_annotations_in_yunikorn.md @@ -27,11 +27,11 @@ YuniKorn utilizes several Kubernetes labels and annotations to support various f ### Labels in YuniKorn Label values should comply with [Kubernetes Syntax and character set](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). -| Name | Description | -|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `applicationId` | Associates this pod with an application. | -| `queue` | Selects the YuniKorn queue this application should be scheduled in. Queue name should comply with [Kubernetes Syntax and character set](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set) and also with [Partition and Queue Configuration](queue_config#queues). If Queue name doesn't comply, Annotations could be used as described below. This may be ignored if a placement policy is in effect. | -| `spark-app-selector` | Alternative method of specifying `applicationId` used by Spark Operator if the label `applicationId` and annotation `yunikorn.apache.org/app-id` unset. | +| Name | Description | +|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `applicationId` | Associates this pod with an application. | +| `queue` | Selects the YuniKorn queue this application should be scheduled in.
Queue name should comply with [Kubernetes Syntax and character set](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set) and also with [Partition and Queue Configuration](queue_config#queues).
If the queue doesn't comply, annotations could be used as described below. This may be ignored if a placement policy is in effect. | +| `spark-app-selector` | Alternative method of specifying `applicationId` used by Spark Operator if the label `applicationId` and annotation `yunikorn.apache.org/app-id` are unset. | ### Annotations in YuniKorn All annotations are under the namespace `yunikorn.apache.org`. For example `yunikorn.apache.org/app-id`. diff --git a/docs/user_guide/placement_rules.md b/docs/user_guide/placement_rules.md index 7cc5f4c86e2..8f613ce2296 100644 --- a/docs/user_guide/placement_rules.md +++ b/docs/user_guide/placement_rules.md @@ -72,7 +72,7 @@ This means that we allow user name and or tag values to contain dots without the For queues in the configuration that as an example must map to username with a dot you must specify them as follows: A user rule with the user `user.name` will generate the queue name `root.user_dot_name` as output. If that "user queue" must be added to the configuration the `user_dot_name` name should be used. -Queue name should comply with rules described in [Partition and Queue Configuration](queue_config#queues). +The queue name should comply with rules described in [Partition and Queue Configuration](queue_config#queues). ### Create parameter The create parameter is a boolean flag that defines if a queue that is generated by the rule may be created if it does not exist. diff --git a/docs/user_guide/queue_config.md b/docs/user_guide/queue_config.md index d459163e518..1e6dfe22b8d 100644 --- a/docs/user_guide/queue_config.md +++ b/docs/user_guide/queue_config.md @@ -147,9 +147,9 @@ A queue cannot contain a dot "." character as that character is used to separate Valid Queue name: * must be 64 characters or less, -* could contain alphanumeric character ([a-z0-9A-Z]), underscores (_), colons (:), hashes (#), slashes (/), at signs (@), and dashes (-). +* can contain alphanumeric character ([a-z0-9A-Z]), underscores (_), colons (:), hashes (#), slashes (/), at signs (@), and dashes (-). -If the name is not unique for the queue in the configuration or contains a dot or do not follow the above rules a parsing error is generated and the configuration is rejected. +If the name is not unique for the queue in the configuration or contains a dot or does not follow the above rules, a parsing error is generated and the configuration is rejected. Queues in the structure will automatically get a type assigned. The type of the queue is based on the fact that the queue has children or sub queues. @@ -274,13 +274,13 @@ When a wildcard group is configured, a limit must be configured with at least on Valid User name: -* must start with lower case or upper case alphabet, +* must start with a letter (uppercase or lowercase) or an underscore (_), * followed by alphanumeric character ([a-z0-9A-Z]), underscores (_), colons (:), hashes (#), slashes (/), at signs (@), dots (.), and dashes (-). -* could end with dollar ($). +* can end with dollar ($). Valid Group name: -* must start with lower case or upper case alphabet +* must start with a letter (uppercase or lowercase) or an underscore (_), * followed by alphanumeric character ([a-z0-9A-Z]), underscores (_), colons (:), dots (.), and dashes (-). Parsing will reject the configuration with limits that do not follow the above rules.