{"id":15696824,"url":"https://github.com/albertogeniola/terraform-gce-vyos","last_synced_at":"2025-04-30T07:07:53.399Z","repository":{"id":59541055,"uuid":"428383018","full_name":"albertogeniola/terraform-gce-vyos","owner":"albertogeniola","description":null,"archived":false,"fork":false,"pushed_at":"2023-04-02T21:30:04.000Z","size":1384,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-30T07:07:48.028Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/albertogeniola.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2021-11-15T18:46:22.000Z","updated_at":"2024-08-12T03:21:42.000Z","dependencies_parsed_at":"2024-10-24T02:12:04.873Z","dependency_job_id":"ecc9df53-54e2-4203-a1b9-8961e4809e3d","html_url":"https://github.com/albertogeniola/terraform-gce-vyos","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/albertogeniola%2Fterraform-gce-vyos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertogeniola%2Fterraform-gce-vyos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertogeniola%2Fterraform-gce-vyos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertogeniola%2Fterraform-gce-vyos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/albertogeniola","download_url":"https://codeload.github.com/albertogeniola/terraform-gce-vyos/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251658208,"owners_count":21622820,"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-03T19:10:02.979Z","updated_at":"2025-04-30T07:07:53.372Z","avatar_url":"https://github.com/albertogeniola.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GCE VyOS module\n[VyOS][1] is a router open source operating system, based on the previous [vyatta][2] virtual router implementation.\nVyOS runs both on bare-metal devices as well as on all major cloud providers, including Google Cloud Platform.\n\n## Motivation\nAt the time of writing, there is no easy-to-go way to get VyOS running on GCP, except the Google Marketplace deploy. \nWhile the [current version of VyOS][4] available on GCP marketplace is paid (even if it is an open-source project)\nit is not updated and does not come with Google Compute agent nor Google Ops Agent installed.\nThis module aims at enabling IaC projects to take advantage of VyOS instances with ease, following a more IaC-oriented approach.\n\n## Features\nThis module achieves the following major objectives:\n- Provides a way for deploying a VyOS Equuleus 1.3 GCE Image on GCP\n- Enables the VyOS instance to update its configuration using Cloud Storage and Pub/Sub notifications\n- Enables users connecting via IAP/GCLOUD ssh to administer the VyOS instance with the built-in command line\n\n### Why not simply using cloud-init?\nCloud-init is a great feature that allows initial configuration and bootstrapping of cloud images. VyOS has developed\na couple of modules that allow fetching and changing the configuration of the router at boot time, via metadata gathering,\nspecifically using the `user-data` key.\n\nHowever, that approach has some major limitations:\n- It works by issuing configuration commands (i.e. imperative) while the rest of the module works with declarative approach.\n- It is limited to the maximum size of the metadata\n- It requires a reboot to be reapplied (most likely a startup script)\n\nThis module uses a GCS file to hold the configuration state, fetched via pubsub event by a python daemon running on the VyOS instance.\nHowever, the module still allows the developer to pass the user-data content, in case that is preferred.\n\n## Image Prerequisites\nThis Terraform module requires a custom GCE Image to be built or imported into the GCP\nproject where the VyOS router will reside. You can either build and customize that image yourself (but chances are you landed on this page because you don't want to do so), \nor you can simply import the GCE image (vyos-equuleus-gce-image.tar.gz) built on this repository, [available here](https://github.com/albertogeniola/terraform-gce-vyos/releases).\n\nTo get the image ready by using the one built on this repository, simply download the __.ta.gz__ tarball and update it into a GCS bucket. Then, create a new GCE image starting \nfrom the uploaded file. More info about this process can be found on the [official GCP documentation](https://cloud.google.com/compute/docs/images/create-custom#create_image).\n\n### Building VyOS GCE Image by your own\nThe GCE image is built via the build scripts provided by the VyOS team and enriched with the necessary configurations and scripts\nneeded to run on the GCP environment. At the time of writing, the GCE image on this repository is built as follows:\n1. Build the VyOS Equuleus 1.3 ISO, using the official build-script;\n1. Build the base VyOS Equuleus 1.3 GCE Image, using the official build-script;\n1. Configure and patch the image to run correctly on GCE:\n   - Install the GCE Linux Guest Agent\n   - Install the GCE Linux Ops Agent (which includes metrics and logging features) against Stackdriver\n   - Configure the file VyOS boot config to use a single instance with DHCP\n   - Map the metadata.google.internal host to 169.256.169.256\n1. Install the Configuration Reloader service to automatically fetch the configuration from GCS\n1. Install the Login Helper service to handle SSH users login via VyOS\n\n\n_Note_: this module won't take care of enabling the necessary APIs. It is developer's responsibility to enable them in the root module.\n\n\u003e __Please note that covering the build phase of the image is out of the scope of this document.__\n\u003e \n\u003e That being said, if you plan to build the VyOS image by yourself, please inject the repository contents of `vyos-gce-image/chroot-patches/opt/gce_helper` \n\u003e and `vyos-gce-image/chroot-patches/etc/systemd/system` respectively to `/opt/gce_helper` and `/etc/systemd/system` (on the target image).\n\u003e Also, make sure to override the default vyos `config.boot.default` file with the one provided in this repository.\n\u003e Eventually, make sure to install the GCE agent and the ops agent. You can see how this is done in this repository by lookig at the `99-gce-agent.chroot`\n\u003e shell script.\n\n\n## Limitations\nSo far, the VyOS image has been tested only on n2 or n1 instance families. __Other instance families might not be supported__.\n\nThe VyOS image is equipped with the host-agent which might require access to Google APIs. Make sure the Subnet you attach the VyOS instance to \nhas the Private Google Access (PGA) activated. \n\n## Organizational policies prerequisites\nSome organizational policies might require an exception for this module to work.\nFor instance, the `constraints/storage.uniformBucketLevelAccess` constraint should not apply to the bucket where the configuration is held, as the current version of the module works with ACLs on single objects.\nIf you plan to use VyOS instance with a public IP assigned, you should make sure that the policy `constraints/compute.vmExternalIpAccess` does allow that.\n\nMoreover, at the time of writing, the provided GCE VyOS image does not comply with shielded image requirements nor supports OS-LOGIN. \nTherefore `constraints/compute.requireShieldedVm` and `constraints/compute.requireOsLogin` org policies should allow an exception for the VyOS intance.\n\nLastly, the current version of the module assigns the \"ip_forwardign\" capability to the vyos instance, as it would be generally useful \nwhen using natting and firewalling capabilities of VyOS. Therefore, you should make sure the `constraints/compute.vmCanIpForward` \norganizational policy allows the VyOS instance to use the ip_forward functionality.\n\n\n## Usage\nRefer to the `example` folder for some quick examples on how to use this module.\n\n\n## Module reference\n### Providers\n\n| Name | Version |\n|------|---------|\n| \u003ca name=\"provider_google\"\u003e\u003c/a\u003e [google](#provider\\_google) | n/a |\n\n## Resources\n\n| Name | Type |\n|------|------|\n| [google_compute_firewall.allow_ssh_iap](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_firewall) | resource |\n| [google_compute_instance.vyos](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_instance) | resource |\n| [google_project_iam_member.sa_log_writer](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/project_iam_member) | resource |\n| [google_project_iam_member.sa_metric_writer](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/project_iam_member) | resource |\n| [google_project_service.project_services](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/project_service) | resource |\n| [google_pubsub_subscription.vyos_instance_subscription](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/pubsub_subscription) | resource |\n| [google_pubsub_subscription_iam_policy.instance_subscriber](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/pubsub_subscription_iam_policy) | resource |\n| [google_pubsub_topic.configuration_update_topic](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/pubsub_topic) | resource |\n| [google_pubsub_topic_iam_member.pubsub_notification_event](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/pubsub_topic_iam_member) | resource |\n| [google_service_account.vyos_compute_sa](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/service_account) | resource |\n| [google_storage_bucket.conf_file_bucket](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/storage_bucket) | resource |\n| [google_storage_bucket_iam_member.instance_sa_bucket_permissions](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/storage_bucket_iam_member) | resource |\n| [google_storage_bucket_object.conf_file_object](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/storage_bucket_object) | resource |\n| [google_storage_notification.configuration_update](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/storage_notification) | resource |\n| [google_compute_image.vyos](https://registry.terraform.io/providers/hashicorp/google/latest/docs/data-sources/compute_image) | data source |\n| [google_iam_policy.subscription_subscriber](https://registry.terraform.io/providers/hashicorp/google/latest/docs/data-sources/iam_policy) | data source |\n| [google_storage_project_service_account.gcs_account](https://registry.terraform.io/providers/hashicorp/google/latest/docs/data-sources/storage_project_service_account) | data source |\n\n## Inputs\n\n| Name | Description | Type | Default | Required |\n|------|-------------|------|---------|:--------:|\n| \u003ca name=\"input_configuration_bucket_name\"\u003e\u003c/a\u003e [configuration\\_bucket\\_name](#input\\_configuration\\_bucket\\_name) | Bucket name where to store VyOs instance configuration file | `any` | `null` | no |\n| \u003ca name=\"input_configuration_bucket_path\"\u003e\u003c/a\u003e [configuration\\_bucket\\_path](#input\\_configuration\\_bucket\\_path) | GCS object path where to store VyOs instance configuration file | `any` | `null` | no |\n| \u003ca name=\"input_enable_serial_port_connection\"\u003e\u003c/a\u003e [enable\\_serial\\_port\\_connection](#input\\_enable\\_serial\\_port\\_connection) | When true, allows the connection via the serial port | `bool` | `false` | no |\n| \u003ca name=\"input_gcp_region\"\u003e\u003c/a\u003e [gcp\\_region](#input\\_gcp\\_region) | Default GCP region where to spawn resources | `any` | n/a | yes |\n| \u003ca name=\"input_instance_name\"\u003e\u003c/a\u003e [instance\\_name](#input\\_instance\\_name) | Name to assign to the VyOs instance | `string` | `\"vyos\"` | no |\n| \u003ca name=\"input_instance_tags\"\u003e\u003c/a\u003e [instance\\_tags](#input\\_instance\\_tags) | Tags to assign to the vyos instance | `list` | \u003cpre\u003e[\u003cbr\u003e  \"vyos\"\u003cbr\u003e]\u003c/pre\u003e | no |\n| \u003ca name=\"input_instance_tier\"\u003e\u003c/a\u003e [instance\\_tier](#input\\_instance\\_tier) | Machine tier for the VyOs instance | `string` | `\"e2-small\"` | no |\n| \u003ca name=\"input_instance_vyos_image_name\"\u003e\u003c/a\u003e [instance\\_vyos\\_image\\_name](#input\\_instance\\_vyos\\_image\\_name) | Instance image name | `any` | n/a | yes |\n| \u003ca name=\"input_instance_vyos_image_project_id\"\u003e\u003c/a\u003e [instance\\_vyos\\_image\\_project\\_id](#input\\_instance\\_vyos\\_image\\_project\\_id) | The project id where the vyos image is stored. Override this parameter if the image \u003cbr\u003e    specified as instance\\_vyos\\_image\\_name is located into another GCP project.\u003cbr\u003e    When null, the project\\_id value is used instead. | `any` | `null` | no |\n| \u003ca name=\"input_instance_zone\"\u003e\u003c/a\u003e [instance\\_zone](#input\\_instance\\_zone) | GCP Zone where to spawn the VyOs instance | `any` | n/a | yes |\n| \u003ca name=\"input_networks_configuration\"\u003e\u003c/a\u003e [networks\\_configuration](#input\\_networks\\_configuration) | Instance networking configuration. | \u003cpre\u003emap(object({\u003cbr\u003e    assign_external_ip=bool,\u003cbr\u003e    static_external_ip=string,\u003cbr\u003e    create_iap_ssh_firewall_rule=bool,\u003cbr\u003e    network_project_id=string,\u003cbr\u003e    network=string,\u003cbr\u003e    subnetwork=string,\u003cbr\u003e    network_ip=string,\u003cbr\u003e  }))\u003c/pre\u003e | n/a | yes |\n| \u003ca name=\"input_project_id\"\u003e\u003c/a\u003e [project\\_id](#input\\_project\\_id) | Google project id where to spawn the VyOs instance | `any` | n/a | yes |\n| \u003ca name=\"input_user_data_content\"\u003e\u003c/a\u003e [user\\_data\\_content](#input\\_user\\_data\\_content) | Holds the content of the user-data metadata to be used as configuration script at instance boot. | `string` | `\"\"` | no |\n| \u003ca name=\"input_vyos_configuration_content\"\u003e\u003c/a\u003e [vyos\\_configuration\\_content](#input\\_vyos\\_configuration\\_content) | Contents of the VyOs configuration to apply to the target instance | `any` | n/a | yes |\n\n## Licensing notes\nThis module is provided as is, with absolutely no warranty.\n\nQuoting the [original documentation][3], we read:\n```\nVyOS is now free as in speech, but not as in beer. \nThis means that while VyOS is still an open source project, \nthe release ISOs are no longer free and can only be obtained \nvia subscription, or by contributing to the community.\n``` \n\n\n[1]: https://vyos.io/\n[2]: https://en.wikipedia.org/wiki/Vyatta\n[3]: https://docs.vyos.io/en/equuleus/contributing/build-vyos.html#prerequisites\n[4]: https://console.cloud.google.com/marketplace/details/sentrium-sl/vyos?pli=1\u0026__hstc=29142691.81c103d48b29bf69a308c8fc19c4c385.1589665573318.1599490605499.1599492713182.137\u0026__hssc=29142691.11.1599492713182\u0026__hsfp=2286654099\u0026hsCtaTracking=9eef7ede-be44-49bd-aec6-f348ff4ab420%7C881f8bd5-facc-4f16-9640-50339c90751d\n[5]: https://github.com/GoogleCloudPlatform/guest-agent\n[6]: https://cloud.google.com/monitoring/agent/ops-agent\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbertogeniola%2Fterraform-gce-vyos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falbertogeniola%2Fterraform-gce-vyos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbertogeniola%2Fterraform-gce-vyos/lists"}