Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[YUNIKORN-2783] Doc changes to describe the new behaviour and caveats #464

Closed
wants to merge 3 commits into from
Closed

[YUNIKORN-2783] Doc changes to describe the new behaviour and caveats #464

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fee96a1
[YUNIKORN-2783] Doc changes to describe the new behaviour and caveats
manirajv06 Aug 22, 2024
71a515b
Addressed review comments
manirajv06 Aug 28, 2024
17d83a5
Addressed review comments
manirajv06 Sep 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions docs/user_guide/labels_and_annotations_in_yunikorn.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,19 +25,21 @@ 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. |
manirajv06 marked this conversation as resolved.
Show resolved Hide resolved
manirajv06 marked this conversation as resolved.
Show resolved Hide resolved
manirajv06 marked this conversation as resolved.
Show resolved Hide resolved
| `spark-app-selector` | Alternative method of specifying `applicationId` used by Spark Operator if the label `applicationId` and annotation `yunikorn.apache.org/app-id` unset. |
manirajv06 marked this conversation as resolved.
Show resolved Hide resolved

### Annotations in YuniKorn
All annotations are under the namespace `yunikorn.apache.org`. For example `yunikorn.apache.org/app-id`.

| Name | Description |
|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `app-id` | Assoiates this pod with an application.<br/>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.<br/>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.<br/>Queue name should comply with rules described in [Partition and Queue Configuration](queue_config#queues).<br/>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. |
Expand Down
11 changes: 2 additions & 9 deletions docs/user_guide/placement_rules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
manirajv06 marked this conversation as resolved.
Show resolved Hide resolved

### 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.
Expand Down Expand Up @@ -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.
Expand Down
22 changes: 20 additions & 2 deletions docs/user_guide/queue_config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 (/), at signs (@), and dashes (-).
manirajv06 marked this conversation as resolved.
Show resolved Hide resolved

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.
manirajv06 marked this conversation as resolved.
Show resolved Hide resolved

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.
Expand Down Expand Up @@ -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,
manirajv06 marked this conversation as resolved.
Show resolved Hide resolved
* followed by alphanumeric character ([a-z0-9A-Z]), underscores (_), colons (:), hashes (#), slashes (/), at signs (@), dots (.), and dashes (-).
* could end with dollar ($).
manirajv06 marked this conversation as resolved.
Show resolved Hide resolved

Valid Group name:

* must start with lower case or upper case alphabet
manirajv06 marked this conversation as resolved.
Show resolved Hide resolved
* 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.
Expand Down