{"id":16288178,"url":"https://github.com/amendlik/salt-gen-resource","last_synced_at":"2025-03-20T03:30:35.832Z","repository":{"id":50927301,"uuid":"72455927","full_name":"amendlik/salt-gen-resource","owner":"amendlik","description":"Generate Rundeck node resources from the Salt Mine","archived":false,"fork":false,"pushed_at":"2024-08-02T00:32:31.000Z","size":111,"stargazers_count":8,"open_issues_count":1,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-17T14:03:25.099Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amendlik.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-31T16:32:15.000Z","updated_at":"2024-02-20T12:08:26.000Z","dependencies_parsed_at":"2024-10-27T21:44:00.217Z","dependency_job_id":"6dbf483b-699e-470d-9e62-349d3a3ac2a1","html_url":"https://github.com/amendlik/salt-gen-resource","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amendlik%2Fsalt-gen-resource","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amendlik%2Fsalt-gen-resource/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amendlik%2Fsalt-gen-resource/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amendlik%2Fsalt-gen-resource/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amendlik","download_url":"https://codeload.github.com/amendlik/salt-gen-resource/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244543704,"owners_count":20469546,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-10T19:47:29.034Z","updated_at":"2025-03-20T03:30:35.473Z","avatar_url":"https://github.com/amendlik.png","language":"Python","funding_links":[],"categories":["Integrations"],"sub_categories":["Salt Project Package Repositories"],"readme":"## Synopsis\n\nA script that uses Mine function of SaltStack to populate nodes\nin Rundeck. In addition to providing nodes, any Salt Grain can be\nadded as a node attribute or tag.\n\nThis script requires that a Salt Minion be running on the Rundeck server.\n\n\u003e **Note**\n\u003e Due to breaking changes introduced in the Python API for Salt, this branch no longer supports Salt versions prior to Phosphorus (3005). Anyone using an older version of Salt should follow the `legacy` branch instead.\n\n## Installation\n\n### Resource Model Provider Script\n\nThe only file required from this repository is [SaltGenResource.py](https://github.com/amendlik/salt-gen-resource/blob/master/SaltGenResource.py). Copy it to the Rundeck server, in the location where Rundeck configuration scripts are stored (e.g. `/opt/rundeck/scripts`). As an alternative, this entire repository can be cloned to make future updates easy using `git pull`.\n\n### Sudo policy\n\nBecause the script is essentially running the Salt Minion, it must be run as root. Add the following snippet to the sudoers policy to permit Rundeck to run it. Change the path to match the installed location of the script.\n```\nCmnd_Alias SALT_GEN_RESOURCE = /opt/rundeck/scripts/salt-gen-resource/SaltGenResource.py\nrundeck ALL=(root) NOPASSWD: SALT_GEN_RESOURCE\nDefaults!SALT_GEN_RESOURCE !requiretty\n```\n\n### Project configuration\n\nThe project configuration can be edited through the web UI, or by editing the file on disk. The web UI is recommended for several reasons:\n\n1. It works whether using filesystem-backed projects or database-backed projects. If using database-backed projects, there is no file on disk to edit.\n2. It knows the location of the file. Rundeck can be installed in a variety of configurations, and all of them place configuration files in different places.\n3. It handles string escaping. If editing the file directly, the escaping rules of Java `.properties` files must be followed.\n\nEdit the Rundeck project configuration to include a new node source script. Change the `file` parameter to match the installed location of `SaltGenResource.py`.\n```\nresources.source.2.type=script\nresources.source.2.config.format=resourceyaml\nresources.source.2.config.interpreter=sudo\nresources.source.2.config.file=/opt/rundeck/scripts/SaltGenResource.py\nresources.source.2.config.args=-G virtual:kvm\n```\n**Note:** Be careful about deleting an existing node source from the configuration file. One of those sources usually provides the 'server node', which is necessary for certain Rundeck workflows. The server node is **not** provided by `SaltGenResource.py` by default. \nAdd additional node sources as necessary, by using another number in the properties (resources.source._#_.config), or configure `SaltGenResource.py` to provide the server node with `--include-server-node`.\n\n### Salt Mine\nThis resource model provider depends on the Salt Mine having access to the `grains.items` function on all minions. To enable this, the `mine_functions` options need to be applied to all Minions, either through the Minion configuration files, or using Pillar. The simplest `mine_functions` that would work is this:\n```\nmine_functions:\n  grains.items: []\n```\nIt is also possible to create an alias to the `grains.items` function using this syntax:\n```\nmine_functions:\n  allgrains:\n    mine_function: grains.items\n```\nWhen using a function alias (`allgrains`, in the example above), be sure to supply the name with `--mine-function`.\n\n**Note:** Salt Mine values are refreshed according to the interval defined by the `mine_interval` option (60 minutes, by default). When the mine configuration is created or changed, the values will not be updated until the next interval elapses. To force an immediate update, use the [`mine.update`](https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.mine.html#salt.modules.mine.update) function.\n\nSee the Salt Mine [online documentation](https://docs.saltstack.com/en/latest/topics/mine/#the-salt-mine) for more detail.\n\n## Configuration\n\nFor usage instructions, run `SaltGenResource.py --help`:\n```\nUsage: SaltGenResource.py [options] \u003ctarget\u003e [\u003cattr\u003e=\u003cvalue\u003e ...]\n\nSalt Mine node source for Rundeck.\n\nOptions:\n  --version             show program's version number and exit\n  -V, --versions-report\n                        Show program's dependencies version number and exit.\n  -h, --help            show this help message and exit\n  -c CONFIG_DIR, --config-dir=CONFIG_DIR\n                        Pass in an alternative configuration directory.\n                        Default: '/etc/salt'.\n  -m MINE_FUNCTION, --mine-function=MINE_FUNCTION\n                        Set the function name for Salt Mine to execute to\n                        retrieve grains. Default value is grains.items but\n                        this could be different if mine function aliases are\n                        used.\n  -s, --include-server-node\n                        Include the Rundeck server node in the output. The\n                        server node is required for some workflows and must be\n                        provided by exactly one resource provider.\n  -u SERVER_NODE_USER, --server-node-user=SERVER_NODE_USER\n                        Specify the user name to use when running jobs on the\n                        server node. This would typically be the same user\n                        that the Rundeck service is running as. Default:\n                        'rundeck'.\n  -a ATTRIBUTES, --attributes=ATTRIBUTES\n                        Create Rundeck node attributes from the values of\n                        grains. Multiple grains may be specified when\n                        separated by a space or comma.\n  -t TAGS, --tags=TAGS  Create Rundeck node tags from the values of grains.\n                        Multiple grains may be specified when separated by a\n                        space or comma.\n\n  Logging Options:\n    Logging options which override any settings defined on the\n    configuration files.\n\n    -l LOG_LEVEL, --log-level=LOG_LEVEL\n                        Console logging log level. One of 'all', 'garbage',\n                        'trace', 'debug', 'profile', 'info', 'warning',\n                        'error', 'critical', 'quiet'. Default: 'warning'.\n    --log-file=RESOURCE_GENERATOR_LOGFILE\n                        Log file path. Default: '/var/log/salt/resource-\n                        generator'.\n    --log-file-level=RESOURCE_GENERATOR_LOG_LEVEL_LOGFILE\n                        Logfile logging log level. One of 'all', 'garbage',\n                        'trace', 'debug', 'profile', 'info', 'warning',\n                        'error', 'critical', 'quiet'. Default: 'warning'.\n\n  Target Options:\n    Target selection options.\n\n    -E, --pcre          Instead of using shell globs to evaluate the target\n                        servers, use pcre regular expressions.\n    -L, --list          Instead of using shell globs to evaluate the target\n                        servers, take a comma or space delimited list of\n                        servers.\n    -G, --grain         Instead of using shell globs to evaluate the target\n                        use a grain value to identify targets, the syntax for\n                        the target is the grain key followed by a\n                        globexpression: \"os:Arch*\".\n    -P, --grain-pcre    Instead of using shell globs to evaluate the target\n                        use a grain value to identify targets, the syntax for\n                        the target is the grain key followed by a pcre regular\n                        expression: \"os:Arch.*\".\n    -N, --nodegroup     Instead of using shell globs to evaluate the target\n                        use one of the predefined nodegroups to identify a\n                        list of targets.\n    -R, --range         Instead of using shell globs to evaluate the target\n                        use a range expression to identify targets. Range\n                        expressions look like %cluster.\n    -C, --compound      The compound target option allows for multiple target\n                        types to be evaluated, allowing for greater\n                        granularity in target matching. The compound target is\n                        space delimited, targets other than globs are preceded\n                        with an identifier matching the specific targets\n                        argument type: salt 'G@os:RedHat and webser* or\n                        E@database.*'.\n    -I, --pillar        Instead of using shell globs to evaluate the target\n                        use a pillar value to identify targets, the syntax for\n                        the target is the pillar key followed by a glob\n                        expression: \"role:production*\".\n    -J, --pillar-pcre   Instead of using shell globs to evaluate the target\n                        use a pillar value to identify targets, the syntax for\n                        the target is the pillar key followed by a pcre\n                        regular expression: \"role:prod.*\".\n    -S, --ipcidr        Match based on Subnet (CIDR notation) or IP address.\n\n  Additional Target Options:\n    Additional options for minion targeting.\n\n    --delimiter=DELIMITER\n                        Change the default delimiter for matching in multi-\n                        level data structures. Default: ':'.\n```\nCommand line options will be provided to Rundeck using the `resources.source.#.config.args` line in the project configuration. \n\n### Targeting\nThe only required argument is a targeting expression. This has the effect of limiting which Salt Minions are presented as Rundeck nodes. This script supports the [same targeting methods and syntax](https://docs.saltstack.com/en/latest/topics/targeting/) as the `salt` command.\n\n**Note:** Rundeck will not pass this command through any shell command interpreters, so **do not** add shell escape characters. For example, to target all minions with the `*` glob expression, use this configuration:\n```\nresources.source.2.config.args=*\n```\n\n### Node Attributes\nNode attributes can be added by including the `--attributes` argument. This can be used to add any grain value as a node attribute in Rundeck. Note that the value of the grain must not be a dictionary. If the requested grain is a list, the first element of the list will be used as the attribute value. Nested grains can be specified using `:` as a delimiter, such as `--attributes locale_info:defaultlanguage`. The delimiter can be changed using the `--delimiter` command-line argument.\nRequesting an attribute for a grain that does not exist will emit a warning and continue without adding the attribute.\n\n### Node Tags\nNode tags can be added by including the `--tags` argument. This is particularly useful when the value of a grain is a list, because a tag will be created for each item in the list. A common example of this is a `roles` grain. Tags will also be created for single value grains. For example, `--tags=init` will tag every Linux system with `systemd`, `upstart`, etc.\nRequesting a tag for a grain that does not exist will emit a warning and continue without adding the tag.\n\n### Mine Function\nBy default, this script depends on Salt Mine having access to `grains.items` on every minion. If an alias is configured for that function, specify it using the `--mine-function` option.\n\n### Static Attributes\nAdditional attributes that are not provided by a grain can be specified by including key value pairs on the command line, after the targeting expression. These static attributes will be added to all generated node resources. For example:\n```\nSaltGenResource.py '*' username='rduser'\n```\n\n### Configuration File\nSaltGenResource loads its configuration from the standard Minion configuration files, normally located at `/etc/salt/minion` and `/etc/salt/minion.d/*.conf` on Linux. This path is different on other operating systems, and can be overridden using the `-c` or `--config-dir` command-line options.\nIn addition to the normal, [documented](https://docs.saltstack.com/en/latest/ref/configuration/minion.html) configuration, there are two additional options to control file-based logging:\n\n| Option | Default Value | Description |\n|--------|---------------|-------------|\n| `resource_generator_logfile` | `/var/log/salt/resource-generator` | Log file path. This path will be prepended with `root_dir` at runtime. |\n| `resource_generator_log_level_logfile` | `warning` | Logfile logging log level. One of `all`, `garbage`, `trace`, `debug`, `profile`, `info`, `warning`, `error`, `critical`, `quiet`. |\n\n### Example\nA more complete example might look like this:\n```\nresources.source.2.type=script\nresources.source.2.config.format=resourceyaml\nresources.source.2.config.interpreter=sudo\nresources.source.2.config.file=/opt/rundeck/scripts/SaltGenResource.py\nresources.source.2.config.args=--mine-function allgrains --attributes domain,selinux:enabled --tags roles,init -S 10.0.1.0/24 username=rduser\n```\n1. Use the mine function alias `allgrains` instead of `grains.items`.\n2. Create node attributes in Rundeck for grains `domain` and `selinux:enabled`.\n3. Create tags for every element of the `roles` grain, and a tag for the value of the `init` grain.\n4. Only create Rundeck nodes for those minions on the 10.0.1.0/24 subnet.\n5. Add the `username` attribute to every node with a value of `rduser`.\n\n### Validation\nThis script can be run at any time from a shell. This can be useful when testing command line arguments. The result should be a YAML document sent to stdout, formatted according the Rundeck [resource-yaml specification](http://rundeck.org/docs/man5/resource-yaml.html). For example:\n```\napp01:\n  hostname: app01.example.org\n  manufacturer: OpenStack Foundation\n  os: CentOS\n  osArch: amd64\n  osFamily: unix\n  osName: Linux\n  osVersion: 3.10.0-327.36.2.el7.x86_64\n  os_family: RedHat\n  osmajorrelease: '7'\n  osrelease: 7.2.1511\n  saltversion: 2016.3.3\n  tags:\n    - kvm\napp02:\n  hostname: app02.example.org\n  manufacturer: OpenStack Foundation\n  os: CentOS\n  osArch: amd64\n  osFamily: unix\n  osName: Linux\n  osVersion: 3.10.0-327.36.2.el7.x86_64\n  os_family: RedHat\n  osmajorrelease: '7'\n  osrelease: 7.2.1511\n  saltversion: 2016.3.3\n  tags:\n    - kvm\ndb01:\n  hostname: db01.example.org\n  manufacturer: OpenStack Foundation\n  os: CentOS\n  osArch: amd64\n  osFamily: unix\n  osName: Linux\n  osVersion: 3.10.0-327.36.2.el7.x86_64\n  os_family: RedHat\n  osmajorrelease: '7'\n  osrelease: 7.2.1511\n  saltversion: 2016.3.3\n  tags:\n    - kvm\ndb02:\n  hostname: db02.example.org\n  manufacturer: OpenStack Foundation\n  os: CentOS\n  osArch: amd64\n  osFamily: unix\n  osName: Linux\n  osVersion: 3.10.0-327.36.2.el7.x86_64\n  os_family: RedHat\n  osmajorrelease: '7'\n  osrelease: 7.2.1511\n  saltversion: 2016.3.3\n  tags:\n    - kvm\n```\n\n## License\n\n   Licensed under the Apache License, Version 2.0 (the \"License\");\n   you may not use this file except in compliance with the License.\n   You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n   Unless required by applicable law or agreed to in writing, software\n   distributed under the License is distributed on an \"AS IS\" BASIS,\n   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famendlik%2Fsalt-gen-resource","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famendlik%2Fsalt-gen-resource","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famendlik%2Fsalt-gen-resource/lists"}