{"id":22454682,"url":"https://github.com/MissionCriticalCloud/vagrant-cloudstack","last_synced_at":"2025-08-02T02:31:40.879Z","repository":{"id":8296252,"uuid":"9837466","full_name":"MissionCriticalCloud/vagrant-cloudstack","owner":"MissionCriticalCloud","description":"Use Vagrant to manage your Cosmic or Cloudstack instances.","archived":false,"fork":false,"pushed_at":"2022-10-06T04:54:40.000Z","size":669,"stargazers_count":66,"open_issues_count":17,"forks_count":43,"subscribers_count":23,"default_branch":"master","last_synced_at":"2024-11-21T03:36:13.301Z","etag":null,"topics":["cloudstack","cosmic","rubygem","vagrant"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MissionCriticalCloud.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":null,"security":null,"support":null}},"created_at":"2013-05-03T14:22:43.000Z","updated_at":"2024-08-01T14:29:20.000Z","dependencies_parsed_at":"2023-01-11T17:21:07.738Z","dependency_job_id":null,"html_url":"https://github.com/MissionCriticalCloud/vagrant-cloudstack","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MissionCriticalCloud%2Fvagrant-cloudstack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MissionCriticalCloud%2Fvagrant-cloudstack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MissionCriticalCloud%2Fvagrant-cloudstack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MissionCriticalCloud%2Fvagrant-cloudstack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MissionCriticalCloud","download_url":"https://codeload.github.com/MissionCriticalCloud/vagrant-cloudstack/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228426107,"owners_count":17917790,"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":["cloudstack","cosmic","rubygem","vagrant"],"created_at":"2024-12-06T07:08:51.102Z","updated_at":"2024-12-06T07:08:53.492Z","avatar_url":"https://github.com/MissionCriticalCloud.png","language":"Ruby","readme":"# Vagrant Cloudstack Provider\n\n[![Build Status](https://travis-ci.org/MissionCriticalCloud/vagrant-cloudstack.png?branch=master)](https://travis-ci.org/MissionCriticalCloud/vagrant-cloudstack)\n[![Gem Version](https://badge.fury.io/rb/vagrant-cloudstack.png)](http://badge.fury.io/rb/vagrant-cloudstack)\n[![Code climate](https://codeclimate.com/github/MissionCriticalCloud/vagrant-cloudstack.png)](https://codeclimate.com/github/MissionCriticalCloud/vagrant-cloudstack)\n[![Coverage Status](https://coveralls.io/repos/github/MissionCriticalCloud/vagrant-cloudstack/badge.svg?branch=master)](https://coveralls.io/github/MissionCriticalCloud/vagrant-cloudstack?branch=master)\n[![BCH compliance](https://bettercodehub.com/edge/badge/MissionCriticalCloud/vagrant-cloudstack?branch=master)](https://bettercodehub.com/)\n\nThis is a fork of [mitchellh AWS Provider](https://github.com/mitchellh/vagrant-aws/).\n\nThis is a [Vagrant](http://www.vagrantup.com) 1.5+ plugin that adds a [Cloudstack](http://cloudstack.apache.org)\nprovider to Vagrant for use with either [Cosmic](https://github.com/MissionCriticalCloud/cosmic) or [Cloudstack](http://cloudstack.apache.org).\n\n## Features\n\n* SSH into the instances.\n* Provision the instances with any built-in Vagrant provisioner.\n* Minimal synced folder support via `rsync`/`winrm`.\n\n## Usage\n\nInstall using standard Vagrant 1.1+ plugin installation methods. After\ninstalling, `vagrant up` and specify the `cloudstack` provider. An example is\nshown below.\n\n```\n$ vagrant plugin install vagrant-cloudstack\n...\n$ vagrant up --provider=cloudstack\n...\n```\n\n## Quick Start\n\nAfter installing the plugin (instructions above), the quickest way to get\nstarted is to actually make a Vagrantfile that looks like the following, filling in\nyour information where necessary.\n\n```\nVagrant.configure(\"2\") do |config|\n  config.vm.box = \"${cloudstack.template_name}\"\n\n  config.vm.provider :cloudstack do |cloudstack, override|\n    cloudstack.host = \"cloudstack.local\"\n    cloudstack.path = \"/client/api\"\n    cloudstack.port = \"8080\"\n    cloudstack.scheme = \"http\"\n    cloudstack.api_key = \"AAAAAAAAAAAAAAAAAAA\"\n    cloudstack.secret_key = \"AAAAAAAAAAAAAAAAAAA\"\n\n    cloudstack.service_offering_id = \"AAAAAAAAAAAAAAAAAAA\"\n    cloudstack.disk_offering_id = \"AAAAAAAAAAAAAAAAAAA\"\n    cloudstack.network_id = \"AAAAAAAAAAAAAAAAAAA\"\n    cloudstack.zone_id = \"AAAAAAAAAAAAAAAAAAA\"\n    cloudstack.project_id = \"AAAAAAAAAAAAAAAAAAA\"\n  end\nend\n```\n\nOr with names instead of ids:\n\n```\nVagrant.configure(\"2\") do |config|\n  config.vm.box = \"${cloudstack.template_name}\"\n\n  config.vm.provider :cloudstack do |cloudstack, override|\n    cloudstack.host = \"cloudstack.local\"\n    cloudstack.path = \"/client/api\"\n    cloudstack.port = \"8080\"\n    cloudstack.scheme = \"http\"\n    cloudstack.api_key = \"AAAAAAAAAAAAAAAAAAA\"\n    cloudstack.secret_key = \"AAAAAAAAAAAAAAAAAAA\"\n\n    cloudstack.service_offering_name = \"THE-BESTEST\"\n    cloudstack.disk_offering_name = \"THE-LARGEST-OFFER-AVAILABLE\"\n    cloudstack.network_name = \"WOW-SUCH-FAST-OFFERING\"\n    cloudstack.zone_name = \"District-9\"\n    cloudstack.name = \"doge-is-a-hostname-now\"\n    # Sadly there is currently no support for the project api in fog.\n    cloudstack.project_id = \"AAAAAAAAAAAAAAAAAAA\"\n  end\nend\n```\n\nAnd then run `vagrant up --provider=cloudstack`.\n\nThis will start an instance in Cloudstack. And assuming your template\non Cloudstack is Vagrant compatible _(vagrant user with official\nvagrant pub key in authorized_keys)_ SSH and provisioning will work as\nwell.\n\n## Configuration\n\nThis provider exposes quite a few provider-specific configuration options. Most of the settings\nhave both an id and a name setting and you can chose to use either (i.e network_id or network_name).\nThis gives the possibility to use the easier to remember name instead of the UUID,\nthis will also enable you to upgrade the different settings in your cloud without having\nto update UUIDs in your Vagrantfile. If both are specified, the id parameter takes precedence.\n\n* `name` - Hostname of the created machine\n* `host` - Cloudstack api host\n* `path` - Cloudstack api path\n* `port` - Cloudstack api port\n* `scheme` - Cloudstack api scheme _(defaults: https (thanks to the resolution order in fog))_\n* `api_key` - The api key for accessing Cloudstack\n* `secret_key` - The secret key for accessing Cloudstack\n* `instance_ready_timeout` - The number of seconds to wait for the instance\n  to become \"ready\" in Cloudstack. Defaults to 120 seconds.\n* `domain_id` - Domain id to launch the instance into\n* `network_id` - Network uuid(s) that the instance should use\n  - `network_id` is single value (e.g. `\"AAAA\"`) or multiple values (e.g. `[\"AAAA\", \"BBBB\"]`)\n* `network_name` - Network name(s) that the instance should use\n  - `network_name` is single value (e.g. `\"AAAA\"`) or multiple values (e.g. `[\"AAAA\", \"BBBB\"]`)\n* `project_id` - Project uuid that the instance should belong to\n* `service_offering_id`- Service offering uuid to use for the instance\n* `service_offering_name`- Service offering name to use for the instance\n* `template_id` - Template uuid to use for the instance\n* `template_name` - Template name to use for the instance, defaults to Vagrants config.vm.box\n* `zone_id` - Zone uuid to launch the instance into\n* `zone_name` - Zone uuid to launch the instance into\n* `keypair` - SSH keypair name, if neither'keypair' nor 'ssh_key' have been specified, a temporary keypair will be created\n* `static_nat` - static nat for the virtual machine\n* `pf_ip_address_id` - IP address ID for port forwarding rule\n* `pf_ip_address` - IP address for port forwarding rule\n* `pf_public_port` - Public Communicator port for port forwarding rule\n* `pf_public_rdp_port` - Public RDP port for port forwarding rule\n* `pf_public_port_randomrange` - If public port is omited, a port from this range wll be used (default `{:start=\u003e49152, :end=\u003e65535}`)\n* `pf_private_port` - Private port for port forwarding rule (defaults to respective Communicator protocol)\n* `pf_open_firewall` - Flag to enable/disable automatic open firewall rule (by CloudStack)\n* `pf_trusted_networks` - Array of CIDRs or (array of) comma-separated string of CIDRs to network(s) to \n  - automatically (by plugin) generate firewall rules for, ignored if `pf_open_firewall` set `true`\n  - use as default for firewall rules where source CIDR is missing\n* `port_forwarding_rules` - Port forwarding rules for the virtual machine\n* `firewall_rules` - Firewall rules\n* `display_name` - Display name for the instance\n* `group` - Group for the instance\n* `ssh_key` - Path to a private key to be used with ssh _(defaults to Vagrant's `config.ssh.private_key_path`)_\n* `ssh_user` - User name to be used with ssh _(defaults to Vagrant's `config.ssh.username`)_\n* `ssh_network_id` - The network_id to be used when loging in to the vm via ssh _(defaults to first nic)_\n* `ssh_network_name` - The network_name to be used when loging in to the vm via ssh _(defaults to first nic)_\n  - Use either `ssh_network_id` or `ssh_network_name`. If specified both , use `ssh_network_id`\n* `vm_user` - User name to be used with winrm _(defaults to Vagrant's `config.winrm.username`)_\n* `vm_password` - Password to be used with winrm. _(If the CloudStack template is \"Password Enabled\", leaving this unset will trigger the plugin to retrieve and use it.)_\n* `private_ip_address` - private (static)ip address to be used by the virtual machine\n* `expunge_on_destroy` - Flag to enable/disable expunge vm on destroy\n\nThese can be set like typical provider-specific configuration:\n\n```ruby\nVagrant.configure(\"2\") do |config|\n  # ... other stuff\n\n  config.vm.provider :cloudstack do |cloudstack|\n    cloudstack.api_key = \"foo\"\n    cloudstack.secret_key = \"bar\"\n  end\nend\n```\n\nIn addition to the above top-level configs, you can use the `region_config`\nmethod to specify region-specific overrides within your Vagrantfile. Note\nthat the top-level `region` config must always be specified to choose which\nregion you want to actually use, however. This looks like this:\n\n```ruby\nVagrant.configure(\"2\") do |config|\n  # ... other stuff\n\n  config.vm.provider :cloudstack do |cloudstack|\n    cloudstack.api_key = \"foo\"\n    cloudstack.secret_key = \"bar\"\n    cloudstack.domain = \"internal\"\n\n    # Simple domain config\n    cloudstack.domain_config \"internal\", :network_id =\u003e \"AAAAAAAAAAAAAAAAAAA\"\n\n    # More comprehensive region config\n    cloudstack.domain_config \"internal\" do |domain|\n      domain.network_id = \"AAAAAAAAAAAAAAAAAAA\"\n      domain.service_offering_id = \"AAAAAAAAAAAAAAAAAAA\"\n    end\n  end\nend\n```\n\nThe domain-specific configurations will override the top-level\nconfigurations when that domain is used. They otherwise inherit\nthe top-level configurations, as you would probably expect.\n\n## Networks\n\nNetworking features in the form of `config.vm.network` are not\nsupported with `vagrant-cloudstack`, currently. If any of these are\nspecified, Vagrant will emit a warning, but will otherwise boot\nthe Cloudstack machine.\n\n### Basic networking versus Advanced networking\n\nThe plugin will determine this network type dynamically from the zone.\nThe setting `network_type` in the Vagrant file has been deprecated,\nand is silently ignored.\n\n### Basic Networking\n\nIf the network type of your zone is `basic`, you can use Security\nGroups and associate rules in your Vagrantfile.\n\nIf you already have Security Groups, you can associate them to your\ninstance, with their IDs:\n\n```ruby\nVagrant.configure(\"2\") do |config|\n  # ... other stuff\n\n  config.vm.provider :cloudstack do |cloudstack|\n    cloudstack.api_key = \"foo\"\n    cloudstack.secret_key = \"bar\"\n    cloudstack.security_group_ids = ['aaaa-bbbb-cccc-dddd', '1111-2222-3333-4444']\n  end\nend\n```\n\nor their names:\n\n```ruby\nVagrant.configure(\"2\") do |config|\n  # ... other stuff\n\n  config.vm.provider :cloudstack do |cloudstack|\n    cloudstack.api_key = \"foo\"\n    cloudstack.secret_key = \"bar\"\n    cloudstack.security_group_names = ['\nmin_fantastiska_security_group', 'another_security_grupp']\n  end\nend\n```\n\nBut you can also create your Security Groups in the Vagrantfile:\n\n```ruby\nVagrant.configure(\"2\") do |config|\n  # ... other stuff\n\n  config.vm.provider :cloudstack do |cloudstack|\n    cloudstack.api_key = \"foo\"\n    cloudstack.secret_key = \"bar\"\n    cloudstack.security_groups = [\n      {\n        :name         =\u003e \"Awesome_security_group\",\n        :description  =\u003e \"Created from the Vagrantfile\",\n          :rules =\u003e [\n        {:type =\u003e \"ingress\", :protocol =\u003e \"TCP\", :startport =\u003e 22, :endport =\u003e 22, :cidrlist =\u003e \"0.0.0.0/0\"},\n        {:type =\u003e \"ingress\", :protocol =\u003e \"TCP\", :startport =\u003e 80, :endport =\u003e 80, :cidrlist =\u003e \"0.0.0.0/0\"},\n        {:type =\u003e \"egress\",  :protocol =\u003e \"TCP\", :startport =\u003e 81, :endport =\u003e 82, :cidrlist =\u003e \"1.2.3.4/24\"},\n    ]\n      }\n    ]\n  end\nend\n```\n\n### Static NAT, Firewall, Port forwarding\n\nYou can create your static nat, firewall and port forwarding rules in the Vagrantfile.\nYou can use this rule to access virtual machine from an external machine.\n\nThe rules created in Vagrantfile are removed when the virtual machine is destroyed.\n\n```ruby\nVagrant.configure(\"2\") do |config|\n  # ... other stuff\n\n  config.vm.provider :cloudstack do |cloudstack|\n\n    override.ssh.host = \"X.X.X.X\"\n\n    cloudstack.static_nat = [\n      { :ipaddress =\u003e \"A.A.A.A\"}\n    ]\n\n    cloudstack.port_forwarding_rules = [\n      { :ipaddress =\u003e \"X.X.X.X\", :protocol =\u003e \"tcp\", :publicport =\u003e 22, :privateport  =\u003e 22, :openfirewall =\u003e false },\n      { :ipaddress =\u003e \"X.X.X.X\", :protocol =\u003e \"tcp\", :publicport =\u003e 80, :privateport  =\u003e 80, :openfirewall =\u003e false }\n    ]\n\n    cloudstack.firewall_rules = [\n      { :ipaddress =\u003e \"A.A.A.A\", :cidrlist  =\u003e \"1.2.3.4/24\", :protocol =\u003e \"icmp\", :icmptype =\u003e 8, :icmpcode =\u003e 0 },\n      { :ipaddress =\u003e \"X.X.X.X\", :cidrlist  =\u003e \"1.2.3.4/24\", :protocol =\u003e \"tcp\", :startport =\u003e 22, :endport =\u003e 22 },\n      { :ipaddress =\u003e \"X.X.X.X\", :cidrlist  =\u003e \"1.2.3.4/24\", :protocol =\u003e \"tcp\", :startport =\u003e 80, :endport =\u003e 80 }\n    ]\n\n  end\nend\n```\nMost values in the firewall and portforwarding rules are not mandatory, except either startport/endport or privateport/publicport\n* `:ipaddress` - defaults to `pf_ip_address`\n* `:protocol` - defaults to `'tcp'`\n* `:publicport` - defaults to `:privateport`\n* `:privateport` - defaults to `:publicport`\n* `:openfirewall` - defaults to `pf_open_firewall`\n* `:cidrlist` - defaults to `pf_trusted_networks`\n* `:startport` - defaults to `:endport`\n* `:endport` - not required by CloudStack\n\n\nFor only allowing Vagrant to access the box for further provisioning (SSH/WinRM), and opening the Firewall for some subnets, the following config is sufficient:\n```ruby\nVagrant.configure(\"2\") do |config|\n  # ... other stuff\n\n  config.vm.provider :cloudstack do |cloudstack|\n    cloudstack.pf_open_firewall      = \"false\"\n    cloudstack.pf_ip_address         = X.X.X.X\n    cloudstack.pf_trusted_networks   = [ \"1.2.3.4/24\" , \"11.22.33.44/32\" ]\n  end\nend\n```\nWhere X.X.X.X is the ip of the respective CloudStack network, this will automatically map the port of the used Communicator (SSH/Winrm) via a random public port, open the Firewall and set Vagrant to use it.\n\nThe plugin can also automatically generate firewall rules off of the portforwarding rules:\n```ruby\nVagrant.configure(\"2\") do |config|\n  # ... other stuff\n\n  config.vm.provider :cloudstack do |cloudstack|\n\n    cloudstack.pf_trusted_networks   = \"1.2.3.4/24,11.22.33.44/32\"\n    cloudstack.port_forwarding_rules = [\n      { :privateport  =\u003e 22, :generate_firewall =\u003e true },\n      { :privateport  =\u003e 80, :generate_firewall =\u003e true }\n    ]\n\n  end\nend\n```\n\n### Virtual Router versus VPC\nBoth Virtual Routers and VPCs are supported when using port-forwarding and firewall. This is automatically determined by the specific `pf_ip_address`.\n\nNote that there are architectural differences in CloudStack which the configuration must adhere to.\n\nFor VPC:\n* `pf_open_firewall` will be ignored as global setting and (specifically) in `port_forwarding_rules`\n* for `firewall_rules` to open access for `port_forwarding_rules`, the firewall rule should allow traffic for the `:privateport` port.\n\nFor Virtual Router:\n* for `firewall_rules` to open access for `port_forwarding_rules`, the firewall rule should allow traffic for the `:publicport` port.\n\nUsage of other attributes and features work with both network types. Such as `:generate_firewall` for portforwarding rules, or `pf_trusted_networks` to automatically generate rules for the Communicator.\n\n## Synced Folders\n\nThere is minimal support for synced folders. Upon `vagrant up`, `vagrant reload`, and `vagrant provision`, the Cloudstack provider will use `rsync` (if available) to uni-directionally sync the folder to the remote machine over SSH, and use Vagrant plugin `vagrant-winrm-syncedfolders` (if available) to uni-directionally sync the folder to the remote machine over WinRM.\n\nThis is good enough for all built-in Vagrant provisioners (shell,\nchef, and puppet) to work!\n\n### User data\n\nYou can specify user data for the instance being booted.\n\n```ruby\nVagrant.configure(\"2\") do |config|\n  # ... other stuff\n\n  config.vm.provider :cloudstack do |cloudstack|\n    # Option 1: a single string\n    cloudstack.user_data = \"#!/bin/bash\\necho 'got user data' \u003e /tmp/user_data.log\\necho\"\n\n    # Option 2: use a file\n    cloudstack.user_data = File.read(\"user_data.txt\")\n  end\nend\n```\n\nThe maximum length of user_data is around 1500 bytes with Cloudstack API \u003c 4.2 (base64 encoded user_data must be \u003c 2048 bytes)\n\n## Development\n\nTo work on the `vagrant-cloudstack` plugin, clone this repository out, and use\n[Bundler](http://gembundler.com) to get the dependencies:\n\n```\n$ bundle\n```\n\nOnce you have the dependencies, verify the unit tests pass with `rake`:\n\n```\n$ bundle exec rake\n```\n\nIf the unit-tests pass, verify the plugin is functionaly good by running the functional tests with bats.\nBefore running the tests you need to export a set of variables that are used in the tests. Look at the\nRake file for the required variables, or run the following Rake command to check:\n```\nbundle exec rake functional_tests:check_environment\n```\n\nRun all functional tests by executing:\n```\nbundle exec rake functional_tests:all\n```\n\nIf those pass, you're ready to start developing the plugin. You can test\nthe plugin without installing it into your Vagrant environment by just\ncreating a `Vagrantfile` in the top level of this directory (it is gitignored)\nand add the following line to your `Vagrantfile`\n```ruby\nVagrant.require_plugin \"vagrant-cloudstack\"\n```\nUse bundler to execute Vagrant:\n\n```\n$ bundle exec vagrant up --provider=cloudstack\n```\n","funding_links":[],"categories":["Configuration Management Integrations"],"sub_categories":["Vagrant"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMissionCriticalCloud%2Fvagrant-cloudstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMissionCriticalCloud%2Fvagrant-cloudstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMissionCriticalCloud%2Fvagrant-cloudstack/lists"}