Merge pull request #120 from matyasselmeci/pr/pilot-section-docs-SOFTWARE-4430

matyasselmeci · web-flow · commit 844492e93753 · 2021-02-01T15:03:24.000-06:00
Pilot sections docs
diff --git a/README.md b/README.md
@@ -17,7 +17,7 @@ once the repos are enabled, install by running
 OSG-Configure can also be installed from a checkout.
 Run
 
-    git clone https://github.com/opensciencegrid/org-configure
+    git clone https://github.com/opensciencegrid/osg-configure
     cd osg-configure
     make install
 
@@ -93,12 +93,12 @@ In the tables below:
 Syntax and layout
 -----------------
 
-The configuration files used by `osg-configure` are the one supported by Python's [SafeConfigParser](http://docs.python.org/library/configparser.html), similar in format to the [INI configuration file](http://en.wikipedia.org/wiki/INI_file) used by MS Windows:
+The configuration files used by `osg-configure` are the one supported by Python's [SafeConfigParser](https://docs.python.org/library/configparser.html), similar in format to the [INI configuration file](https://en.wikipedia.org/wiki/INI_file) used by MS Windows:
 
 -   Config files are separated into sections, specified by a section name in square brackets (e.g. `[Section 1]`)
 -   Options should be set using `name = value` pairs
 -   Lines that begin with `;` or `#` are comments
--   Long lines can be split up using continutations: each white space character can be preceded by a newline to fold/continue the field on a new line (same syntax as specified in [email RFC 822](http://tools.ietf.org/html/rfc822.html))
+-   Long lines can be split up using continutations: each white space character can be preceded by a newline to fold/continue the field on a new line (same syntax as specified in [email RFC 822](https://tools.ietf.org/html/rfc822.html))
 -   Variable substitutions are supported -- [see below](#variable-substitution)
 
 `osg-configure` reads and uses all of the files in `/etc/osg/config.d` that have a ".ini" suffix. The files in this directory are ordered with a numeric prefix with higher numbers being applied later and thus having higher precedence (e.g. `00-foo.ini` has a lower precedence than `99-local-site-settings.ini`). Configuration sections and options can be specified multiple times in different files. E.g. a section called `[PBS]` can be given in `20-pbs.ini` as well as `99-local-site-settings.ini`.
@@ -417,11 +417,14 @@ If you would like to properly advertise multiple CEs per cluster, make sure that
 
 #### Subcluster Configuration ####
 
-Each homogeneous set of worker node hardware is called a **subcluster**. For each subcluster in your cluster, fill in the information about the worker node hardware by creating a new Subcluster section with a unique name in the following format: `[Subcluster CHANGEME]`, where CHANGEME is the globally unique subcluster name (yes, it must be a **globally** unique name for the whole grid, not just unique to your site. Get creative.)
+Each homogeneous set of worker node hardware is called a **subcluster**.
+For each subcluster in your cluster, fill in the information about the worker node hardware by creating a new Subcluster section in the following format:
+`[Subcluster CHANGEME]`, where CHANGEME is the subcluster name.
+If you have multiple subclusters, they must have different names.
 
 | Option               | Values Accepted             | Explanation                                                                   |
 |----------------------|-----------------------------|-------------------------------------------------------------------------------|
-| **name**             | String                      | The same name that is in the Section label; it should be **globally unique**  |
+| **name**             | String                      | The same name that is in the Section label                                    |
 | **ram\_mb**          | Positive Integer            | Megabytes of RAM per node                                                     |
 | **cores\_per\_node** | Positive Integer            | Number of cores per node                                                      |
 | **allowed\_vos**     | Comma-separated List or `*` | The VOs that are allowed to run jobs on this subcluster (autodetected if `*`) |
@@ -458,6 +461,42 @@ The following attributes are optional:
 
 
 
+### 35-pilot.ini / [Pilot] ###
+
+These sections describe the size and scale of GlideinWMS pilots that your site is willing to accept.
+This file contains multiple sections of the form `[Pilot <PILOT_TYPE>]`,
+where `<PILOT_TYPE>` is a free-form name of a type of pilot.
+The name should only have lower-case letters, numbers, and `-` or `_` characters.
+In addition, it must be unique within your cluster.
+We recommend a name that describes the capabilities of the pilots you accept.
+Good names are `singularity_8core`, `gpu`, `bigmem`, `main`.
+
+The following attributes are required:
+| Option                   | Values Accepted             | Explanation                                                                                                                        |
+|--------------------------|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------|
+| **allowed\_vos**         | Comma-separated List or `*` | The VOs that are allowed to run jobs on this resource (autodetected if `*`)                                                        |
+| **max\_pilots**          | Positive Integer            | The maximum number of pilots of this type that the factory can send to this CE                                                     |
+| **os**                   | Choice (see below)          | The operating system on the workers the pilot should request.  Not set by default.  Only required if **require\_singularity** is `False`               |
+| **require\_singularity** | `True`, `False`             | `True` if the pilot should require Singularity support on any worker it lands on.  Default `False`; **os** is optional if this is `True` |
+
+Valid values for the **os** option are: `rhel6`, `rhel7`, `rhel8`, or `ubuntu18`.
+
+The following attributes are optional:
+| Option              | Values Accepted      | Explanation                                                                                                                              |
+|---------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------|
+| **cpucount**        | Positive Integer     | Number of cores that a job using this type of pilot can get.  Default `1`; ignored if **whole\_node** is `True`                          |
+| **ram\_mb**         | Positive Integer     | Maximum amount of memory (in MB) that a job using this type of pilot can get.  Default `2500`; ignored if **whole\_node** is `True`      |
+| **whole\_node**     | `True`, `False`      | Whether this type of pilot can use all the resources on a node.  Default `False`; **cpucount** and **ram\_mb** are ignored if this is `True` |
+| **gpucount**        | Non-negative Integer | The number of GPUs to request.  Default `0`                                                                                              |
+| **max\_wall\_time** | Positive Integer     | Maximum wall-clock time, in minutes, that a job is allowed to run on this resource.  Default `1440`, i.e. 24 hours                       |
+| **queue**           | String               | The queue or partition which jobs should be submitted to in order to run on this resource (see note).  Not set by default                |
+| **send\_tests**     | `True`, `False`      | Send test pilots.  Default `False`; set it to `True` for testing job routes or pilot types                                               |
+
+**Note:** **queue** is equivalent to the HTCondor grid universe classad attribute **remote\_queue**.
+
+
+
+
 ### 40-localsettings.ini / [Local Settings] ###
 
 This section differs from other sections in that there are no set options in this section. Rather, the options set in this section will be placed in the `osg-local-job-environment.conf` verbatim. The options in this section are case sensitive and the case will be preserved when they are converted to environment variables. The `osg-local-job-environment.conf` file gets sourced by jobs run on your cluster so any variables set in this section will appear in the environment of jobs run on your system.
@@ -499,5 +538,3 @@ If your resource has multiple sponsors, you can separate them using commas or sp
 `osg, atlas, cms` or `osg:10, atlas:45, cms:45`.
 The percentages must add up to 100 if multiple sponsors are used.
 If you have a sponsor that is not an OSG VO, you can indicate this by using 'local' as the VO.
-
-
diff --git a/config/30-gip.ini b/config/30-gip.ini
@@ -3,9 +3,8 @@
 ;===================================================================
 
 ; For each subcluster, add a new subcluster section.
-; Each subcluster name must be unique for the entire grid, so make sure to not
-; pick anything generic like "MAIN".  Each subcluster section must start with
-; the words "Subcluster", and cannot be named "CHANGEME".
+; Each subcluster section must start with the words "Subcluster", and cannot be
+; named "CHANGEME".
 
 ; There should be one subcluster section per set of homogeneous nodes in the
 ; cluster.
diff --git a/config/35-pilot.ini b/config/35-pilot.ini
@@ -3,15 +3,20 @@
 ;===================================================================
 
 ; For each pilot type, add a new pilot section.
-; Each pilot name must be unique for the entire grid, so make sure to not
-; pick anything generic like "MAIN". The name will be used as-is as the
-; "Name" attribute in the OSG_ResourceCatalog entry.
+; If you accept multiple pilot types, each section must have a different name.
+; Names should only contain lowercase letters, numbers, "-" or "_", and should
+; describe the capabilities of that type of pilot.
+
+; Good names are "singularity_8core", "gpu", "bigmem", "main".
+
+; The name will be used as-is as the "Name" attribute in the
+; OSG_ResourceCatalog entry.
 
 ; This data is used to determine the resources requested by pilot jobs submitted by the OSG, so it's
 ; important to keep it up to date.
 
 
-;[Pilot PILOT_NAME]
+;[Pilot PILOT_TYPE]
 ;; The number of cores for this pilot type.
 ;cpucount = 1
 ;; The amount of memory (in megabytes) for this pilot type.
