{"id":15393878,"url":"https://github.com/mitchellh/vagrant-google","last_synced_at":"2025-04-04T19:13:07.064Z","repository":{"id":12170711,"uuid":"14768990","full_name":"mitchellh/vagrant-google","owner":"mitchellh","description":"Vagrant provider for GCE.","archived":false,"fork":false,"pushed_at":"2024-06-27T06:55:27.000Z","size":500,"stargazers_count":338,"open_issues_count":33,"forks_count":101,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-03-28T18:14:46.595Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/mitchellh.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-11-28T05:51:37.000Z","updated_at":"2025-03-18T23:38:53.000Z","dependencies_parsed_at":"2024-06-27T07:57:03.653Z","dependency_job_id":"a98fdf84-b5c0-41a0-8b2d-edde08adf7d1","html_url":"https://github.com/mitchellh/vagrant-google","commit_stats":{"total_commits":272,"total_committers":45,"mean_commits":6.044444444444444,"dds":0.5661764705882353,"last_synced_commit":"9fa82b186b8b6981e6210ad1e2599ab7b73423f9"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitchellh%2Fvagrant-google","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitchellh%2Fvagrant-google/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitchellh%2Fvagrant-google/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitchellh%2Fvagrant-google/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mitchellh","download_url":"https://codeload.github.com/mitchellh/vagrant-google/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247234923,"owners_count":20905854,"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-01T15:20:38.913Z","updated_at":"2025-04-04T19:13:07.040Z","avatar_url":"https://github.com/mitchellh.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Vagrant Google Compute Engine (GCE) Provider\n\n[![Gem Version](https://badge.fury.io/rb/vagrant-google.svg)](https://badge.fury.io/rb/vagrant-google)\n\n[gem]: https://rubygems.org/gems/vagrant-google\n[gemnasium]: https://gemnasium.com/mitchellh/vagrant-google\n\nThis is a [Vagrant](https://www.vagrantup.com) plugin that adds an\n[Google Compute Engine](https://cloud.google.com/compute/) (GCE) provider to\nVagrant, allowing Vagrant to control and provision instances in GCE.\n\n**NOTE:** The plugin is currently looking for maintainers, please contact @temikus.\n\n# Features\n\n* Boot Google Compute Engine instances.\n* SSH into the instances.\n* Provision the instances with any built-in Vagrant provisioner.\n* Synced folder support via Vagrant's\n[rsync action](https://www.vagrantup.com/docs/synced-folders/rsync.html).\n* Define zone-specific configurations so Vagrant can manage machines in\n  multiple zones.\n\n# Requirements\n\n* Google Cloud Platform (GCP) account,\n* a GCP project with:\n  * Google Compute Engine API enabled\n  * Your public SSH key added as GCE metadata.\n* Vagrant 2.0.3+\n\n## Google Cloud Platform Setup\n\nDo the following:\n\n1. Log in with your Google Account and go to\n   [Google Cloud Platform](https://cloud.google.com) and click on the\n   `Try it free` button.\n2. Create a new project and remember to record the `Project ID`\n3. Enable the\n   [Google Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com)\n   for your project in the API console. If prompted, review and agree to the\n   terms of service.\n4. Install the [Cloud SDK](https://cloud.google.com/sdk/docs/install)\n5. Run `[gcloud auth application-default login](https://cloud.google.com/sdk/gcloud/reference/auth/application-default/login)\n   to create your credentials. (Alternatively, you may use a service account, see **Using a Service Account** section).\n6. Add the public SSH key you're going to use to GCE Metadata in `Compute` -\u003e\n   `Compute Engine` -\u003e `Metadata` section of the console, `SSH Keys` tab. (Read\n   the [SSH Support](https://github.com/mitchellh/vagrant-google#ssh-support)\n   readme section for more information.)\n\n### Using a Service Account\n\nThe `[appplication-default login](https://cloud.google.com/sdk/gcloud/reference/auth/application-default/login)\nmethod is intended to be used for developing code on a local environment - this is typically Vagrant's use-case\nas well. However, if this is not your use-case, you will want to use a credential not tied to your local environment:\na service account.\n\nTo use a service account:\n\n1. While still in the API \u0026 Services, go to\n   [Credentials subsection](https://console.cloud.google.com/apis/api/compute.googleapis.com/credentials),\n   and click `Create credentials` -\u003e `Service account`.\n2. Create a Service Account with any name (f.e. `vagrant`) and grant it\n   a `Compute Admin` role.\n3. Open the new service account page and click on the `Keys` tab. \n   Click `Add key` -\u003e `Create new key`, choose JSON. Download the JSON private key\n   and save this file in a secure and reliable location.\n\nThen include the private key in your Vagrantfile's `provider` block as a `google_json_key_location`\nattribute:\n\n```ruby\nVagrant.configure(\"2\") do |config|\n  # ... other stuff\n\n  config.vm.provider :google do |google|\n    google.google_project_id = \"YOUR_GOOGLE_CLOUD_PROJECT_ID\"\n    google.google_json_key_location = \"/path/to/your/private-key.json\"\n  end\nend\n```\n\n## Vagrant Setup\n\nInstall as a Vagrant plugin:\n\n```sh\nvagrant plugin install vagrant-google\n```\n\n# Usage\n\nMake a `Vagrantfile` that looks like the following, filling in\nyour information where necessary:\n\n```ruby\nVagrant.configure(\"2\") do |config|\n  config.vm.box = \"google/gce\"\n\n  config.vm.provider :google do |google, override|\n    google.google_project_id = \"YOUR_GOOGLE_CLOUD_PROJECT_ID\"\n    google.image_family = 'ubuntu-2004-lts'\n\n    override.ssh.username = \"USERNAME\"\n    override.ssh.private_key_path = \"~/.ssh/id_rsa\"\n  end\n\nend\n```\n\nRun:\n```sh\nvagrant up --provider=google\n```\n\nThis will start the latest version of Ubuntu 20.04 LTS instance in the\n`us-central1-f` zone, with an `n1-standard-1` machine, and the `\"default\"`\nnetwork within your project. And assuming your SSH information (see below) was\nfilled in properly within your Vagrantfile, SSH and provisioning will work as\nwell.\n\nNote that normally a lot of this boilerplate is encoded within the box file,\nbut the box file used for the quick start, the \"google\" box, has no\npreconfigured defaults.\n\n## SSH Support\n\nIn order for SSH to work properly to the GCE VM, you will first need to add\nyour public key to the GCE metadata service for the desired VM user account.\nWhen a VM first boots, a Google-provided daemon is responsible for talking to\nthe internal GCE metadata service and creates local user accounts and their\nrespective `~/.ssh/authorized_keys` entries.  Most new GCE users will use the\n[Cloud SDK](https://cloud.google.com/sdk/) `gcloud compute` utility when first\ngetting started with GCE. This utility has built in support for creating SSH\nkey pairs, and uploading the public key to the GCE metadata service.  By\ndefault, `gcloud compute` creates a key pair named\n`~/.ssh/google_compute_engine[.pub]`.\n\nNote that you can use the more standard `~/.ssh/id_rsa[.pub]` files, but you\nwill need to manually add your public key to the GCE metadata service so your\nVMs will pick up the key. Note that the public key is typically\nprefixed with the username, so that the daemon on the VM adds the public key\nto the correct user account.\n\nAdditionally, you will probably need to add the key and username to override\nsettings in your Vagrantfile like so:\n\n```ruby\nconfig.vm.provider :google do |google, override|\n\n    #...google provider settings are skipped...\n\n    override.ssh.username = \"testuser\"\n    override.ssh.private_key_path = \"~/.ssh/id_rsa\"\n\n    #...google provider settings are skipped...\n\nend\n```\n\nSee the links below for more help with SSH and GCE VMs.\n\n  * https://cloud.google.com/compute/docs/instances#sshing\n  * https://cloud.google.com/compute/docs/console#sshkeys\n\n## Box Format\n\nEvery provider in Vagrant must introduce a custom box format. This provider\nintroduces `google` boxes. You can view an example box in\n[example_boxes/](https://github.com/mitchellh/vagrant-google/tree/master/example_boxes).\nThat directory also contains instructions on how to build a box.\n\nThe box format is basically just the required `metadata.json` file along with\na `Vagrantfile` that does default settings for the provider-specific\nconfiguration for this provider.\n\n## Configuration\n\nThis provider exposes quite a few provider-specific configuration options:\n\n* `google_json_key_location` - The location of the JSON private key file matching your\n  Service Account.\n  (Can also be configured with `GOOGLE_JSON_KEY_LOCATION` environment variable.)\n* `google_project_id` - The Project ID for your Google Cloud Platform account.\n  (Can also be configured with `GOOGLE_PROJECT_ID` environment variable.)\n* `image` - The image name to use when booting your instance.\n* `image_family` - Specify an \"image family\" to pull the latest image from. For example: `centos-7`\nwill pull the most recent CentOS 7 image. For more info, refer to\n[Google Image documentation](https://cloud.google.com/compute/docs/images#image_families).\n* `image_project_id` - The ID of the GCP project to search for the `image` or `image_family`.\n  For example: `centos-cloud` for Centos 7/8/Stream image families.\n* `instance_group` - Unmanaged instance group to add the machine to. If one\n  doesn't exist it will be created.\n* `instance_ready_timeout` - The number of seconds to wait for the instance\n  to become \"ready\" in GCE. Defaults to 20 seconds.\n* `machine_type` - The machine type to use.  The default is \"n1-standard-1\".\n* `disk_size` - The disk size in GB.  The default is 10.\n* `disk_name` - The disk name to use.  If the disk exists, it will be reused, otherwise created.\n* `disk_type` - Whether to use Standard disk or SSD disk. Use either `pd-ssd` or `pd-standard`.\n* `autodelete_disk` - Boolean whether to delete the disk when the instance is deleted or not. Default is true.\n* `metadata` - Custom key/value pairs of metadata to add to the instance.\n* `name` - The name of your instance.  The default is \"i-yyyymmddhh-randomsd\",\n  e.g. 10/08/2015 13:15:15 is \"i-2015081013-15637fda\".\n* `network` - The name of the network to use for the instance.  Default is\n \"default\".\n* `network_project_id` - The ID of the GCP project for the network and subnetwork to use for the instance. Default is `google_project_id`.\n* `subnetwork` - The name of the subnetwork to use for the instance.\n* `tags` - An array of tags to apply to this instance.\n* `labels` - Custom key/value pairs of labels to add to the instance.\n* `zone` - The zone name where the instance will be created.\n* `can_ip_forward` - Boolean whether to enable IP Forwarding.\n* `external_ip` - The external IP address to use (supports names). Set to `false` to not assign an external address.\n* `network_ip` - The internal IP address to use. Default is to use next available address.\n* `use_private_ip` - Boolean whether to use private IP for SSH/provisioning. Default is false.\n* `preemptible` - Boolean whether to enable preemptibility. Default is false.\n* `auto_restart` - Boolean whether to enable auto_restart. Default is true.\n* `on_host_maintenance` - What to do on host maintenance. Can be set to `MIGRATE` or `TERMINATE` Default is `MIGRATE`.\n* `scopes` or `service_accounts` - An array of OAuth2 account scopes for\n  services that the instance will have access to. Those can be both full API\n  scopes, just endpoint aliases (the part after `...auth/`), and `gcloud`\n  utility aliases, for example:\n  `['storage-full', 'bigquery', 'https://www.googleapis.com/auth/compute']`.\n* `service_account` - The IAM service account email to use for the instance.\n* `additional_disks` - An array of additional disk configurations. `disk_size` is default to `10`GB;\n  `disk_name` is default to `name` + \"-additional-disk-#{index}\"; `disk_type` is default to `pd-standard`;\n  `autodelete_disk` is default to `true`. Here is an example of configuration.\n  ```ruby\n    [{\n     :image_family =\u003e \"google-image-family\",\n     :image =\u003e nil,\n     :image_project_id =\u003e \"google-project-id\",\n     :disk_size =\u003e 20,\n     :disk_name =\u003e \"google-additional-disk-0\",\n     :disk_type =\u003e \"pd-standard\",\n     :autodelete_disk =\u003e true\n    }]\n  ```\n* `accelerators` - An array of accelerator configurations. `type` is the\n  accelerator type (e.g. `nvidia-tesla-k80`); `count` is the number of\n  accelerators and defaults to 1. Note that only `TERMINATE` is supported for\n  `on_host_maintenance`; this should be set explicitly, since the default is\n  `MIGRATE`.\n  ```ruby\n  google.accelerators = [{\n    :type =\u003e \"nvidia-tesla-k80\",\n    :count =\u003e 2\n  }]\n\n  google.on_host_maintenance = \"TERMINATE\"\n  ```\n* `enable_secure_boot` - For [Shielded VM](https://cloud.google.com/security/shielded-cloud/shielded-vm), whether to enable Secure Boot.\n* `enable_vtpm` - For [Shielded VM](https://cloud.google.com/security/shielded-cloud/shielded-vm), whether to enable vTPM.\n* `enable_integrity_monitoring` - For [Shielded VM](https://cloud.google.com/security/shielded-cloud/shielded-vm), whether to enable Integrity monitoring.\n* `resource_policies` - Adds [Resource Policies](https://cloud.google.com/compute/docs/reference/rest/v1/resourcePolicies) to given instance.\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 :google do |google|\n    google.google_project_id = \"YOUR_GOOGLE_CLOUD_PROJECT_ID\"\n    google.google_json_key_location = \"/path/to/your/private-key.json\"\n  end\nend\n```\n\nIn addition to the above top-level configs, you can use the `zone_config`\nmethod to specify zone-specific overrides within your Vagrantfile. Note\nthat the top-level `zone` config must always be specified to choose which\nzone you want to actually use, however. This looks like this:\n\n```ruby\nVagrant.configure(\"2\") do |config|\n\n  config.vm.box = \"google/gce\"\n\n  config.vm.provider :google do |google|\n    google.google_project_id = \"YOUR_GOOGLE_CLOUD_PROJECT_ID\"\n    google.google_json_key_location = \"/path/to/your/private-key.json\"\n\n    # Make sure to set this to trigger the zone_config\n    google.zone = \"us-central1-f\"\n\n    google.zone_config \"us-central1-f\" do |zone1f|\n        zone1f.name = \"testing-vagrant\"\n        zone1f.image = \"debian-9-stretch-v20211105\"\n        zone1f.machine_type = \"n1-standard-4\"\n        zone1f.zone = \"us-central1-f\"\n        zone1f.metadata = {'custom' =\u003e 'metadata', 'testing' =\u003e 'foobarbaz'}\n        zone1f.scopes = ['bigquery', 'monitoring', 'https://www.googleapis.com/auth/compute']\n        zone1f.tags = ['web', 'app1']\n    end\n  end\nend\n```\n\nThe zone-specific configurations will override the top-level configurations\nwhen that zone is used. They otherwise inherit the top-level configurations,\nas you would expect.\n\nThere are a few example Vagrantfiles located in the\n[vagrantfile_examples/ directory](https://github.com/mitchellh/vagrant-google/tree/master/vagrantfile_examples/).\n\n## Networks\n\nNetworking features in the form of `config.vm.network` are not supported\nwith `vagrant-google`, currently. If any of these are specified, Vagrant will\nemit a warning, but will otherwise boot the GCE machine.\n\n## Synced Folders\n\nSince plugin version 2.0, this is implemented via built-in `SyncedFolders` action.\nSee Vagrant's [rsync action](https://www.vagrantup.com/docs/synced-folders/rsync.html)\ndocumentation for more info.\n\n## Automatic shutdown\n\nTo save money you may want to ensure you don't forget to shut down your instances\nwhen you stop using them.\n\nA very basic solution for this is to use Vagrant's provisioning feature to plan\nautomatic shutdown of the vm after given time after each `vagrant up`:\n\n```ruby\n# Plan automatic shutdown of machine to prevent unwanted costs\nconfig.vm.provision \"auto-shutdown\", type: \"shell\", run: \"always\",\n  inline: \"shutdown -P +480\" # = 60 minutes * 8 hours\n```\n\n## Print external IP\n\nYou may want to know your machine's external IP f.e. to put it in your Ansible inventory\nor open the app you deploy in it in your browser.\n\nTo automate printing it IP you can also use the Vagrant's provisioning feature:\n\n```ruby\n# Print the external IP\nconfig.vm.provision \"print-ip\", type: \"shell\", run: \"always\",\n  inline: \"echo External IP: $(curl -s icanhazip.com)\"\n```\n\n# Development\n\nTo work on the `vagrant-google` plugin, clone this repository, and use\n[Bundler](https://gembundler.com) to get the dependencies:\n\n```sh\n$ bundle\n```\n\nOnce you have the dependencies, verify the unit tests pass with `rake`:\n\n```sh\n$ bundle exec rake\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 ignored by\n git), and use bundler to execute Vagrant:\n\n```sh\n$ bundle exec vagrant up --provider=google\n```\n\n## Acceptance testing\n\n**Work-in-progress:** Acceptance tests are based on vagrant-spec library which\nis currently under active development so they may occasionally break.\n\nBefore you start acceptance tests, you'll need to set the authentication\nshell variables accordingly:\n\n```sh\nexport GOOGLE_PROJECT_ID=\"your-google-cloud-project-id\"\nexport GOOGLE_JSON_KEY_LOCATION=\"/full/path/to/your/private-key.json\"\n\nexport GOOGLE_SSH_USER=\"testuser\"\nexport GOOGLE_SSH_KEY_LOCATION=\"/home/testuser/.ssh/id_rsa\"\n```\n\nAfter, you can run acceptance tests by running the `full` task in `acceptance`\nnamespace:\n```sh\n$ bundle exec rake acceptance:full\n```\n\n**IMPORTANT NOTES**:\n\n- Since acceptance tests spin up instances on GCE, the whole suite may take\n 20+ minutes to run.\n- Since those are live instances, **you will be billed** for running them.\n\n# Changelog\nSee [CHANGELOG.md](CHANGELOG.md)\n\n# License\nApache 2.0; see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitchellh%2Fvagrant-google","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmitchellh%2Fvagrant-google","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitchellh%2Fvagrant-google/lists"}