{"id":15156683,"url":"https://github.com/puppetlabs/provision","last_synced_at":"2025-04-07T07:08:01.708Z","repository":{"id":33871137,"uuid":"152235766","full_name":"puppetlabs/provision","owner":"puppetlabs","description":"Simple tasks to provision and tear_down containers / instances and virtual machines. ","archived":false,"fork":false,"pushed_at":"2025-03-27T13:53:43.000Z","size":499,"stargazers_count":19,"open_issues_count":3,"forks_count":53,"subscribers_count":84,"default_branch":"main","last_synced_at":"2025-03-31T05:07:48.317Z","etag":null,"topics":["hacktoberfest","module","supported"],"latest_commit_sha":null,"homepage":"","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":"2018-10-09T10:58:02.000Z","updated_at":"2025-02-12T11:41:53.000Z","dependencies_parsed_at":"2022-07-28T21:08:53.926Z","dependency_job_id":"0df344f9-1677-41b6-bf68-be0ec554fbc2","html_url":"https://github.com/puppetlabs/provision","commit_stats":{"total_commits":334,"total_committers":51,"mean_commits":6.549019607843137,"dds":0.874251497005988,"last_synced_commit":"7562eb57ff76e808eef55fa3218297f8802af741"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fprovision","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fprovision/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fprovision/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fprovision/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/provision/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247608151,"owners_count":20965952,"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":["hacktoberfest","module","supported"],"created_at":"2024-09-26T19:40:53.500Z","updated_at":"2025-04-07T07:08:01.680Z","avatar_url":"https://github.com/puppetlabs.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Provision\n\n[![Code Owners](https://img.shields.io/badge/owners-DevX--team-blue)](https://github.com/puppetlabs/provision/blob/main/CODEOWNERS)\n![ci](https://github.com/puppetlabs/provision/actions/workflows/ci.yml/badge.svg)\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/puppetlabs/provision)\n\nSimple tasks to provision and tear down containers, instances and virtual machines.\n\n## Table of Contents\n\n1. [Description](#description)\n2. [Setup - The basics of getting started with provision](#setup)\n    * [Setup requirements](#setup-requirements)\n3. [Usage - Configuration options and additional functionality](#usage)\n    * [ABS](#abs)\n    * [Docker](#docker)\n    * [Vagrant](#vagrant)\n    * [Provision Service](#provision_service)\n4. [Limitations - OS compatibility, etc.](#limitations)\n5. [Development - Guide for contributing to the module](#development)\n6. [License - Additional information in regards to licensing](#license)\n\n## Description\n\nBolt tasks allowing a user to provision and tear down systems. It also maintains a Bolt inventory file.\nProvisioners so far:\n\n* ABS (AlwaysBeScheduling)\n* Docker\n* Vagrant\n* Provision Service\n\n## Setup\n\n### Setup Requirements\n\nBolt has to be installed to run the tasks. Each provisioner has its own requirements. From having Docker to installed or access to private infrastructure.\n\n#### Running the tasks as part of puppet_litmus\n\nPlease follow the litmus documentation [here](https://puppetlabs.github.io/content-and-tooling-team/docs/litmus/).\n\n#### Running the module stand-alone call the tasks/plans directly\n\nFor provisioning to work you will need to have a number of other modules available. You can use bolt to install the modules for you from your Puppetfile, by following this [guide](https://puppet.com/docs/bolt/latest/installing_tasks_from_the_forge.html).\nThe required modules are:\n\n```shell\ncat $HOME/.puppetlabs/bolt/Puppetfile\nmod 'puppetlabs-puppet_agent'\nmod 'puppetlabs-facts'\nmod 'puppetlabs-puppet_conf'\n```\n\n## Usage\n\nThere is a basic workflow for the provision tasks.\n\n* provision - creates/initiates a platform and edits a bolt inventory file.\n* tear_down - creates/initiates a system/container and edits a bolt inventory file.\n\nFor extended functionality please look at the [provision wiki](https://github.com/puppetlabs/provision/wiki).\n\n### ABS\n\n(internal to puppet) Allows you to provision machines on puppets internal pooler. Reads the '~/.fog' file for your authentication token.\n\n#### Setting up your Token\n\nIn order to run ABS you first require an access token stored within your '.fog' file. If you already have one you may skip this section, otherwise request one by running the following command, changing the username.\n\n```shell\n$ curl -X POST -d '' -u tp --url https://test-example.abs.net/api/v2/token\nEnter host password for user 'tp':\n{\n  \"ok\": true,\n  \"token\": \"0pd263lej948h28493692r07\"\n}%\n```\n\nNow that you have your token, check that it works by running:\n\n```shell\n$ curl --url https://test-example.abs.net/api/v2/token/0pd263lej948h28493692r07\n{\n  \"ok\": true,\n  \"user\": \"tp\",\n  \"created\": \"2019-01-04 14:25:55 +0000\",\n  \"last_accessed\": \"2019-01-04 14:26:27 +0000\"\n}%\n```\n\nFinally all that you have left to do is to place your new token into your '.fog' file as shown below:\n\n```shell\n$ cat ~/.fog\n:default:\n  :abs_token: 0pd263lej948h28493692r07\n```\n\n#### Running the Commands\n\n##### Setting up a new machine\n\n```ruby\n$ bundle exec bolt task run provision::abs --targets localhost action=provision platform=ubuntu-1604-x86_64\n\nStarted on localhost...\nFinished on localhost:\n  {\n    \"status\": \"ok\",\n    \"node_name\": \"yh6f4djvz7o3te6.delivery.puppetlabs.net\"\n  }\nSuccessful on 1 node: localhost\nRan on 1 node in 1.44 seconds\n```\n\n##### Tearing down a finished machine\n\n```ruby\n$ bundle exec bolt task run provision::abs --targets localhost action=tear_down node_name=yh6f4djvz7o3te6.delivery.puppetlabs.net\n\nStarted on localhost...\nFinished on localhost:\n  Removed yh6f4djvz7o3te6.delivery.puppetlabs.net\n  {\"status\":\"ok\"}\n  {\n  }\nSuccessful on 1 node: localhost\nRan on 1 node in 1.54 seconds\n```\n\n### Docker\n\nGiven an docker image name it will spin up that container and setup external ssh on that platform. For helpful docker tips look [here](https://github.com/puppetlabs/litmus_image/blob/main/README.md)\n\nContainers by default will be managed in the current [docker context](https://docs.docker.com/engine/context/working-with-contexts/), on the [DOCKER_HOST](https://docs.docker.com/engine/reference/commandline/cli/#environment-variables), or on localhost if nether are configured.\n\n#### Provision\n\n```ruby\n$ bundle exec bolt task run provision::docker --targets localhost action=provision platform=ubuntu:14.04\n\nStarted on localhost...\nFinished on localhost:\n  Provisioning ubuntu_14.04-2222\n  {\"status\":\"ok\",\"node_name\":\"localhost\"}\n  {\n  }\nSuccessful on 1 node: localhost\nRan on 1 node in 33.96 seconds\n```\n\nProvision allows for passing additional command line arguments to the docker run when specifying `vars['docker_run_opts']` as an array of arguments.\n\nWhen running Debian or Ubuntu containers, the following flags will be added to the $docker_run_opts by default.\n\n```shell\n--volume /sys/fs/cgroup:/sys/fs/cgroup:rw --cgroupns=host\n```\n\nThese defaults can be overriden by passing the flags with different values i.e.\n\n```shell\n--volume /sys/fs/cgroup:/sys/fs/cgroup:ro --cgroupns=private\n```\n\n```ruby\nbundle exec bolt task run provision::docker --targets localhost action=provision platform=ubuntu:14.04 vars='{ \"docker_run_opts\": [\"-p 8086:8086\", \"-p 3000:3000\"]}'\n```\n\n#### Tear down\n\n```ruby\n$ bundle exec bolt task run provision::docker --targets localhost action=tear_down node_name=localhost:2222\n\nStarted on localhost...\nFinished on localhost:\n  Removed localhost:2222\n  {\"status\":\"ok\"}\n  {\n  }\nSuccessful on 1 node: localhost\nRan on 1 node in 2.02 seconds\n```\n\n### Vagrant\n\nTested with vagrant images:\n\n* ubuntu/trusty64\n* ubuntu/xenial64\n* ubuntu/bionic64\n* debian/jessie64\n* centos/7\n\nprovision\n\n```ruby\n$ bundle exec bolt task run provision::vagrant --targets localhost action=provision platform=ubuntu/xenial64\n\nStarted on localhost...\nFinished on localhost:\n  {\n    \"status\": \"ok\",\n    \"node_name\": \"127.0.0.1:2222\"\n  }\nSuccessful on 1 node: localhost\nRan on 1 node in 51.98 seconds\n```\n\nFor multi-node provisioning, you can assign arbitrary tags to the nodes you deploy, by passing an optional YAML-string 'vars' to the bolt task. In the example below we are assigning the role of `k8s-controller` to the provisioned node.\n\n```ruby\n$ bundle exec bolt task run provision::vagrant --targets localhost action=provision platform=ubuntu/xenial64 inventory=/Users/tp/workspace/git/provision vars='role: k8s-controller'\n```\n\nsudo secure_path fix\n\nAs some Vagrant boxes do not allow ssh root logins, the **vagrant** user is used to login and *sudo* is used to execute privileged commands as root user.\nBy default the Puppet agent installation does not change the systems' sudo *secure_path* configuration.\nThis leads to errors when anything tries to execute `puppet` commands on the test system.\nTo add the Puppet agent binary path to the *secure_path* please run the `provision::fix_secure_path` Bolt task:\n\n```ruby\n$ bundle exec bolt task run provision::fix_secure_path path=/opt/puppetlabs/bin -i inventory.yaml -t ssh_nodes\n\nStarted on 127.0.0.1:2222...\nFinished on 127.0.0.1:2222:\n  Task completed successfully with no result\nSuccessful on 1 target: 127.0.0.1:2222\nRan on 1 target in 0.84 sec\n```\n\ntear_down\n\n```ruby\n$ bundle exec bolt task run provision::vagrant --targets localhost action=tear_down node_name=127.0.0.1:2222\n\nStarted on localhost...\nFinished on localhost:\n  Removed 127.0.0.1:2222\n  {\"status\":\"ok\"}\n  {\n  }\nSuccessful on 1 node: localhost\nRan on 1 node in 4.52 seconds\n```\n\n#### Additional Vagrant options\n\n##### Box URL\n\nIf you need to use a local/private Vagrant box requiring you to specify a URL to access, you can pass a URL by setting the `VAGRANT_BOX_URL` environment variable. If you put `%BOX%` in the URL it will be replaced with the name of the box/image. You can also set the variable by setting the `params` hash in `provision.yaml`.\n\nIn `provision.yaml`:\n\n```yaml\nvagrant_boxes:\n  provisioner: vagrant\n  images:\n  - mybox1\n  params:\n    vagrant_box_url: 'https://boxes.example.com/box/%BOX%.json'\n```\n\n##### Password\n\nIf you use a custom Vagrant box which requires the use of a password instead of the standard Vagrant keypair then you can set it in the `VAGRANT_PASSWORD` environment variable, or in the `provision.yaml` params hash with the `vagrant_password` key.\n\n### Provision_service\n\nThe provision service task is meant to be used from a Github Action workflow.\n\nExample usage:\nUsing the following provision.yaml file:\n\n```yaml\ntest_serv:\n  provisioner: provision::provision_service\n  params:\n    cloud: gcp\n    region: europe-west1\n    zone: europe-west1-d\n  images: ['centos-7-v20200618', 'windows-server-2016-dc-v20200813']\n```\n\nIn the provision step you can invoke bundle exec rake 'litmus:provision_list[test_serv]' and this will ensure the creation of two VMs in GCP.\n\nManual invocation of the provision service task from a workflow can be done using:\n\n```ruby\nbundle exec bolt task run provision::provision_service --targets localhost action=provision platform=centos-7-v20200813 inventory=/Users/tp/workspace/git/provision/inventory.yaml vars='role: puppetserver'\n```\n\nOr using Litmus:\n\n```ruby\nbundle exec rake 'litmus:provision[provision_service, centos-7-v20200813, role: puppetserver]'\n```\n\n#### Synced Folders\n\nBy default the task will provision a Vagrant box with the [synced folder](https://developer.hashicorp.com/vagrant/docs/synced-folders) **disabled**.\nTo enable the synced folder you must specify the parameter `enable_synced_folder` as `true`.\nInstead of passing this parameter directly you can instead specify the environment variable `LITMUS_ENABLE_SYNCED_FOLDER` as `true`.\n\n#### Hyper-V Provider\n\nThis task can also be used against a Windows host to utilize Hyper-V Vagrant boxes.\nWhen provisioning, a few additional parameters need to be passed:\n\n* `hyperv_vswitch`, which specifies the Hyper-V Virtual Switch to assign the VM.\n  If you do not specify one the [`Default Switch`](https://searchenterprisedesktop.techtarget.com/blog/Windows-Enterprise-Desktop/Default-Switch-Makes-Hyper-V-Networking-Dead-Simple) will be used.\n* `hyperv_smb_username` and `hyperv_smb_password`, which ensure the synced folder works correctly (only necessary is `enable_synced_folder` is `true`).\n  If these parameters are omitted when provisioning on Windows and using synced folders Vagrant will try to prompt for input and the task will hang indefinitely until it finally times out.\n  The context in which a Bolt task is run does not allow for mid-task input.\n\nInstead of passing them as parameters directly they can also be passed as environment variables:\n\n* `LITMUS_HYPERV_VSWITCH` for `hyperv_vswitch`\n* `HYPERV_SMB_USERNAME` for `hyperv_smb_username`\n* `HYPERV_SMB_PASSWORD` for `hyperv_smb_password`\n\nprovision\n\n```powershell\nPS\u003e $env:LITMUS_HYPERV_VSWITCH = 'internal_nat'\nPS\u003e bundle exec bolt task run provision::vagrant --targets localhost action=provision platform=centos/7 hyperv_smb_username=tp hyperv_smb_password=notMyrealPassword\n\nStarted on localhost...\nFinished on localhost:\n  {\n    \"status\": \"ok\",\n    \"node_name\": \"127.0.0.1:2222\"\n  }\nSuccessful on 1 node: localhost\nRan on 1 node in 51.98 seconds\n```\n\nUsing the `tear_down` task is the same as on Linux or MacOS.\n\n## Limitations\n\n* The docker task only supports Linux\n* The docker task uses port forwarding, not internal IP addresses. This is because of limitations when running on the mac.\n\n## Development\n\nTesting/development/debugging it is better to use ruby directly, you will need to pass the JSON parameters. Depending on how you are running (using a puppet file or as part of a puppet_litmus). The dependencies of provision will need to be available. See the setup section above.\n\n```shell\n# powershell\n echo '{ \"platform\": \"ubuntu-1604-x86_64\", \"action\": \"provision\", \"inventory\": \"c:\\\\workspace\\\\puppetlabs-motd\\\\\" }' | bundle exec ruby .\\spec\\fixtures\\modules\\provision\\tasks\\abs.rb\n# bash / zshell ...\n echo '{ \"platform\": \"ubuntu-1604-x86_64\", \"action\": \"provision\", \"inventory\": \"/home/tp/workspace/puppetlabs-motd/\" }' | bundle exec ruby spec/fixtures/modules/provision/tasks/abs.rb\n```\n\nTesting using bolt, the second step\n\n```ruby\nbundle exec bolt task run provision::docker --targets localhost action=provision platform=ubuntu:14.04\n```\n\n## License\n\nThis codebase is licensed under Apache 2.0. However, the open source dependencies included in this codebase might be subject to other software licenses such as AGPL, GPL2.0, and MIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fprovision","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fprovision","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fprovision/lists"}