{"id":15022753,"url":"https://github.com/puppetlabs/vmfloaty","last_synced_at":"2025-04-04T06:07:28.743Z","repository":{"id":22562875,"uuid":"25904162","full_name":"puppetlabs/vmfloaty","owner":"puppetlabs","description":"A CLI helper tool for Puppet vmpooler to help you stay afloat","archived":false,"fork":false,"pushed_at":"2025-02-04T02:15:22.000Z","size":644,"stargazers_count":24,"open_issues_count":14,"forks_count":26,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T05:11:15.714Z","etag":null,"topics":["automation","cli","hacktoberfest","ruby","vmpooler"],"latest_commit_sha":null,"homepage":"https://github.com/puppetlabs/vmpooler","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-10-29T04:18:22.000Z","updated_at":"2024-09-09T09:57:51.000Z","dependencies_parsed_at":"2024-02-12T10:49:28.138Z","dependency_job_id":"0d79d2d3-be58-4211-a943-a3b2e42b465c","html_url":"https://github.com/puppetlabs/vmfloaty","commit_stats":{"total_commits":425,"total_committers":35,"mean_commits":"12.142857142857142","dds":0.7811764705882354,"last_synced_commit":"6b6d6f73cdc55d4300d8c4e61c508cb0399963da"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fvmfloaty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fvmfloaty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fvmfloaty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fvmfloaty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/vmfloaty/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247128747,"owners_count":20888235,"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":["automation","cli","hacktoberfest","ruby","vmpooler"],"created_at":"2024-09-24T19:58:20.903Z","updated_at":"2025-04-04T06:07:28.725Z","avatar_url":"https://github.com/puppetlabs.png","language":"Ruby","readme":"# vmfloaty\n\n[![Gem Version](https://badge.fury.io/rb/vmfloaty.svg)](https://badge.fury.io/rb/vmfloaty)\n[![Test](https://github.com/puppetlabs/vmfloaty/actions/workflows/test.yml/badge.svg)](https://github.com/puppetlabs/vmfloaty/actions/workflows/test.yml)\n\nA CLI helper tool for [Puppet's VMPooler](https://github.com/puppetlabs/vmpooler) to help you stay afloat.\n\n![float image](float.jpg)\n\n- [vmfloaty](#vmfloaty)\n  - [Install](#install)\n    - [Ruby](#ruby)\n    - [Docker](#docker)\n  - [Usage](#usage)\n    - [Example workflow](#example-workflow)\n    - [vmfloaty dotfile](#vmfloaty-dotfile)\n      - [Basic configuration](#basic-configuration)\n      - [Using multiple services](#using-multiple-services)\n      - [Using backends besides VMPooler](#using-backends-besides-vmpooler)\n      - [Valid config keys](#valid-config-keys)\n    - [Tab Completion](#tab-completion)\n  - [VMPooler API](#vmpooler-api)\n  - [Using the Pooler class](#using-the-pooler-class)\n    - [Example Projects](#example-projects)\n  - [Contributing](#contributing)\n    - [Code Reviews](#code-reviews)\n  - [Releasing](#releasing)\n  - [Special thanks](#special-thanks)\n\n## Install\n\n### Ruby\n\nGrab the latest from ruby gems...\n\n```bash\ngem install vmfloaty\n```\n\n### Docker\n\nRun the docker image:\n\n`docker run -it --rm -v ~/.vmfloaty.yml:/home/floatyuser/.vmfloaty.yml ghcr.io/puppetlabs/vmfloaty --help`\n\n## Usage\n\n```plain\n$ floaty --help\n  NAME:\n\n    floaty\n\n  DESCRIPTION:\n\n    A CLI helper tool for Puppet's VMPooler to help you stay afloat\n\n  COMMANDS:\n\n    completion Outputs path to completion script\n    delete     Schedules the deletion of a host or hosts\n    get        Gets a vm or vms based on the os argument\n    help       Display global or [command] help documentation\n    list       Shows a list of available vms from the pooler or vms obtained with a token\n    modify     Modify a VM's tags, time to live, disk space, or reservation reason\n    query      Get information about a given vm\n    revert     Reverts a vm to a specified snapshot\n    service    Display information about floaty services and their configuration\n    snapshot   Takes a snapshot of a given vm\n    ssh        Grabs a single vm and sshs into it\n    status     Prints the status of pools in the pooler service\n    summary    Prints a summary of a pooler service\n    token      Retrieves or deletes a token or checks token status\n\n  GLOBAL OPTIONS:\n\n    -h, --help\n        Display help documentation\n\n    -v, --version\n        Display version information\n\n    -t, --trace\n        Display backtrace when an error occurs\n```\n\n### Example workflow\n\nGrabbing a token for authenticated pooler requests:\n\n```bash\nfloaty token get --user username --url https://vmpooler.example.net/api/v1\n```\n\nThis command will then ask you to log in. If successful, it will return a token that you can save either in a dotfile or use with other cli commands.\n\nGrabbing vms:\n\n```bash\nfloaty get centos-7-x86_64=2 debian-7-x86_64 windows-10=3 --token mytokenstring --url https://vmpooler.example.net/api/v1\n```\n\n### vmfloaty dotfile\n\nIf you do not wish to continually specify various config options with the cli, you can `~/.vmfloaty.yml` for some defaults. You can get a list of valid service types and example configuration files via `floaty service types` and `floaty service examples`, respectively.\n\n#### Basic configuration\n\nThis is the simplest type of configuration where you only need a single service:\n\n```yaml\n# file at ~/.vmfloaty.yml\nurl: 'https://vmpooler.example.net/api/v1'\nuser: 'brian'\ntoken: 'tokenstring'\n```\n\nRun `floaty service examples` to see additional configuration options\n\n#### Using multiple services\n\nMost commands allow you to specify a `--service \u003cservicename\u003e` option to allow the use of multiple pooler instances. This can be useful when you'd rather not specify a `--url` or `--token` by hand for alternate services.\n\n- If you run `floaty` without a `--service \u003cname\u003e` option, vmfloaty will use the first configured service by default.\n- If keys are missing for a configured service, vmfloaty will attempt to fall back to the top-level values.\n  This makes it so you can specify things like `user` once at the top of your `~/.vmfloaty.yml`.\n\n#### Using backends besides VMPooler\n\nvmfloaty supports additional backends besides VMPooler. To see a complete list, run `floaty service types`. The output of `floaty service examples` will show you how to configure each of the supported backends.\n\n#### Valid config keys\n\nHere are the keys that vmfloaty currently supports:\n\n- verbose (Boolean)\n- token (String)\n- user (String)\n- url (String)\n- services (String)\n- type (String)\n- vmpooler_fallback (String)\n\n### Tab Completion\n\nThere is a basic completion script for Bash (and possibly other shells) included with the gem in the [extras/completions](https://github.com/puppetlabs/vmfloaty/blob/master/extras/completions) folder. To activate, that file simply needs to be sourced somehow in your shell profile.\n\nFor convenience, the path to the completion script for the currently active version of the gem can be found with the `floaty completion` subcommand. This makes it easy to add the completion script to your profile like so:\n\n```bash\nsource $(floaty completion --shell bash)\n```\n\nIf you are running on macOS and use Homebrew's `bash-completion` formula, you can symlink the script to `/usr/local/etc/bash_completion.d/floaty` and it will be sourced automatically:\n\n```bash\nln -s $(floaty completion --shell bash) /usr/local/etc/bash_completion.d/floaty\n```\n\nThere is also tab completion for zsh:\n\n```zsh\nsource $(floaty completion --shell zsh)\n```\n\n## VMPooler API\n\nThis cli tool uses the [VMPooler API](https://github.com/puppetlabs/vmpooler/blob/master/API.md).\n\n## Using the Pooler class\n\nvmfloaty providers a `Pooler` class that gives users the ability to make requests to VMPooler without having to write their own requests. It also provides an `Auth` class for managing VMPooler tokens within your application.\n\n### Example Projects\n\n- [John McCabe: vmpooler-bitbar](https://github.com/johnmccabe/vmpooler-bitbar/)\n  - vmpooler status and management in your menubar with bitbar\n- [Brian Cain: vagrant-vmpooler](https://github.com/briancain/vagrant-vmpooler)\n  - Use Vagrant to manage your vmpooler instances\n\n## Contributing\n\nPR's are welcome! We always love to see how others think this tool can be made better.\n\n### Code Reviews\n\nPlease wait for multiple code owners to sign off on any notable change.\n\n## Releasing\n\nFollow these steps to publish a new GitHub release, build and push the gem to \u003chttps://rubygems.org\u003e, and build and push a Docker Image to GitHub Container Registry:\n\n1. Bump the \"VERSION\" in `lib/vmfloaty/version.rb` appropriately based on changes in `CHANGELOG.md` since the last release.\n2. Run `./release-prep` to update `Gemfile.lock` and `CHANGELOG.md`.\n3. Commit and push changes to a new branch, then open a pull request against `main` and be sure to add the \"maintenance\" label.\n4. After the pull request is approved and merged, then navigate to \u003chttps://github.com/puppetlabs/vmfloaty/actions/workflows/release.yml\u003e --\u003e Run workflow --\u003e select \"main\" branch --\u003e Run workflow. This will publish a GitHub release, build and push the gem to RubyGems, and build and push a Docker Image to GitHub Container Registry.\n\n## Special thanks\n\nSpecial thanks to [Brian Cain](https://github.com/briancain) as he is the original author of vmfloaty! Vast amounts of this code exist thanks to his efforts.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fvmfloaty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fvmfloaty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fvmfloaty/lists"}