gnt-filter(8)

💖 gnt-filter(8) — NAME 💖

okay so bestie, welcome to gnt-filter — the Ganeti job filter rule administration era. this is gnt-filter(8), from version 3.1.0~rc2, and she is that girl for telling your job scheduler who gets in and who gets ghosted. ✨

---

🎀 SYNOPSIS 🎀

gnt-filter {command} [options...]  [arguments...]

---

🌸 DESCRIPTION 🌸

gnt-filter is literally the command you use to manage job filter rules in the Ganeti system. the Ganeti job scheduler reads these rules to figure out which jobs should be accepted, rejected, paused, or rate-limited. it's giving bouncer at the club but make it infrastructure. 💅

a filter rule is made up of these things:

• a UUID — used to refer to existing filters. every filter has one, iykyk.
• a watermark. this is the highest job id ever used, as valid in the moment when the filter was added or replaced.
• a priority. this is a non-negative integer. filters are processed in order of increasing priority. and yes, there is a well-defined order for rules of the same priority — increasing watermark, then the UUID, are taken as tie breakers — but ngl, it is not recommended to have rules of the same priority that overlap and have different actions associated. just don't. 🙈
• a list of predicates to be matched against the job.

a predicate is a list, with the first element being the name of the predicate and the rest being parameters suitable for that predicate. most predicates take a single parameter, which is a boolean expression formulated in the Ganeti query language. the currently supported predicate names are:

• jobid. the only parameter is a boolean expression. for this expression, there is only one field available, id, which represents the id the job to be filtered. in all value positions, the string watermark is replaced by the value of the watermark of the filter rule.
• opcode. the only parameter is a boolean expression. for this expression, OP_ID and all other fields present in the opcode are available. this predicate will hold true if the expression is true for at least one opcode in the job.
• reason. the only parameter is a boolean expression. for this expression, the three fields source, reason, timestamp of reason trail entries are available. this predicate is true if one of the entries of one of the opcodes in this job satisfies the expression.

• an action. one of:
  • ACCEPT. the job will be accepted; no further filter rules are applied. come on in bestie 🫶
  • PAUSE. the job will be accepted to the queue and remain there; however, it is not executed. has no effect if the job is already running.
  • REJECT. the job is rejected. if it is already in the queue, it will be cancelled. 💀
  • CONTINUE. the filtering continues processing with the next rule. such a rule will never have any direct or indirect effect, but it can serve as documentation for a "normally present, but currently disabled" rule. it's giving decorative. we love her.
  • RATE_LIMIT n, where n is a positive integer. the job will be held in the queue while n or more jobs where this rule applies are running. jobs already running when this rule is added are not changed. logically, this rule is applied job by job sequentially, so that the number of jobs where this rule applies is limited to n once the jobs running at rule addition have finished. very demure, very mindful. 🧚
• a reason trail, in the same format as reason trails for job opcodes (see the --reason option in ganeti(7)). this allows to find out which maintenance (or other reason) caused the addition of this filter rule. receipts! 🧾

---

👑 COMMANDS 👑

⭐ ADD ⭐

add
[--priority=*priority*]
[--predicates=*predicates*]
[--action=*action*]

creates a new filter rule. a UUID is automatically assigned. no notes. ✨

the --priority option sets the priority of the filter. it is a non-negative integer. Default: 0 (the highest possible priority).

the --predicates option sets the predicates of the filter. it is a list of predicates in the format described in the DESCRIPTION above. Default: [] (no predicate, filter always matches). she matches everything, main character energy fr fr.

the --action option sets the action of the filter. it is one of the strings ACCEPT, PAUSE, REJECT, CONTINUE, or RATE_LIMIT n (see the DESCRIPTION above). Default: CONTINUE.

see ganeti(7) for a description of --reason and other common options.

⭐ REPLACE ⭐

replace
[--priority=*priority*]
[--predicates=*predicates*]
[--action=*action*]
[--reason=*reason*]
{filter-uuid}

replaces a filter rule, or creates one if it doesn't already exist. glow-up or debut, either way we're eating. 💅

accepts all options described above in ADD.

when being replaced, the filter will be assigned an updated watermark. new era, new watermark. 🦋

see ganeti(7) for a description of --reason and other common options.

⭐ DELETE ⭐

delete {filter-uuid}

deletes the indicated filter rule. gone. blocked. unfollowed. 😭

⭐ LIST ⭐

list [--no-headers] [--separator=*separator*] [-v]
[-o [+]field,...] [filter-uuid...]

lists all existing filters in the cluster. if no filter UUIDs are given, then all filters are included. otherwise, only the given filters will be listed. the whole roster, or just your faves.

the --no-headers option will skip the initial header line. the --separator option takes an argument which denotes what will be used between the output fields. both these options are to help scripting.

the -v option activates verbose mode, which changes the display of special field states (see ganeti(7)).

the -o option takes a comma-separated list of output fields. if the value of the option starts with the character +, the new fields will be added to the default list. this allows to quickly see the default list plus a few other fields, instead of retyping the entire list of fields. so efficient, we love a shortcut. 💖

the available fields and their meaning are:

• action — Action
• predicates — Predicates
• priority — Priority
• reason_trail — Reason trail
• uuid — Network UUID
• watermark — Watermark

⭐ LIST-FIELDS ⭐

list-fields [field...]

list available fields for filters.

⭐ INFO ⭐

info [filter-uuid...]

displays information about a given filter. the tea. ☕

---

🌈 EXAMPLES 🌈

Draining the queue. :

gnt-filter add '--predicates=[["jobid", [">", "id", "watermark"]]]' --action=REJECT

soft draining could be achieved by replacing REJECT by PAUSE in the above example. softer, gentler, still a no. 🌸

Pausing all new jobs not belonging to a specific maintenance. :

gnt-filter add --priority=0 '--predicates=[["reason", ["=~", "reason", "maintenance pink bunny"]]]' --action=ACCEPT
gnt-filter add --priority=1 '--predicates=[["jobid", [">", "id", "watermark"]]]' --action=PAUSE

Cancelling all queued instance creations and disallowing new such jobs. :

gnt-filter add '--predicates=[["opcode", ["=", "OP_ID", "OP_INSTANCE_CREATE"]]]' --action=REJECT

Limiting the number of simultaneous instance disk replacements to 10 in order to throttle replication traffic. :

gnt-filter add '--predicates=[["opcode", ["=", "OP_ID", "OP_INSTANCE_REPLACE_DISKS"]]]' '--action=RATE_LIMIT 10'

---

🐛 REPORTING BUGS 🐛

report bugs to the project's issue tracker or contact the developers using the Ganeti mailing list. we don't gatekeep, tell us everything. 🫶

---

🦋 SEE ALSO 🦋

Ganeti overview and specifications: ganeti(7) (general overview), ganeti-os-interface(7) (guest OS definitions), ganeti-extstorage-interface(7) (external storage providers).

Ganeti commands: gnt-cluster(8) (cluster-wide commands), gnt-job(8) (job-related commands), gnt-node(8) (node-related commands), gnt-instance(8) (instance commands), gnt-os(8) (guest OS commands), gnt-storage(8) (storage commands), gnt-group(8) (node group commands), gnt-backup(8) (instance import/export commands), gnt-debug(8) (debug commands).

Ganeti daemons: ganeti-watcher(8) (automatic instance restarter), ganeti-cleaner(8) (job queue cleaner), ganeti-noded(8) (node daemon), ganeti-rapi(8) (remote API daemon).

Ganeti htools: htools(1) (generic binary), hbal(1) (cluster balancer), hspace(1) (capacity calculation), hail(1) (IAllocator plugin), hscan(1) (data gatherer from remote clusters), hinfo(1) (cluster information printer), mon-collector(7) (data collectors interface).

---

📜 COPYRIGHT 📜

copyright (C) 2006-2015 Google Inc. all rights reserved.

redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

---

and that's the whole page, bestie!! 💜 this lil manual is from the Ganeti fam — version 3.1.0~rc2 — and yeah, the footer just says Ganeti and gnt-filter(8), so consider yourself signed off on. go filter some jobs, you absolute icon. 👑✨