feat: opt-in non-authoritative project metadata

Add use_authoritative_project_metadata variable (default: true) to let
users switch from google_compute_project_metadata (authoritative) to
per-key google_compute_project_metadata_item resources.

Existing deployments see no change on upgrade. Users who share the GCP
project with other metadata sources can opt in by setting the variable
to false and running the documented state migration.

Co-authored-by: Ona <no-reply@ona.com>

Author: nandajavarma

README.md

@@ -26,6 +26,47 @@ for setup instructions, configuration options, and troubleshooting.
 The [`runner-with-networking`](./examples/runner-with-networking/) example
 provides a full infrastructure setup including VPC, DNS, and certificates.
 
+## Project Metadata Mode
+
+By default this module uses `google_compute_project_metadata` (authoritative),
+which manages **all** project-level metadata. Any metadata keys not declared in
+this module will be removed on `terraform apply`.
+
+If other systems or Terraform modules manage project metadata in the same GCP
+project, set `use_authoritative_project_metadata = false` to switch to per-key
+`google_compute_project_metadata_item` resources. This only manages the keys
+the module needs (`enable-oslogin`, `gitpod-runner-id`) and leaves everything
+else untouched.
+
+```hcl
+module "runner" {
+  source = "gitpod-io/ona-runner/google"
+  # ...
+  use_authoritative_project_metadata = false
+}
+```
+
+### Migrating an existing deployment to per-key metadata
+
+Switching an existing deployment from authoritative to per-key requires a state
+migration. Without it, Terraform will try to destroy the old resource and create
+the new ones, which can fail or cause a brief metadata gap.
+
+```bash
+# 1. Remove the old authoritative resource from state
+terraform state rm 'module.runner.google_compute_project_metadata.runner_metadata'
+
+# 2. Import the individual keys into the new resources
+terraform import 'module.runner.google_compute_project_metadata_item.enable_oslogin[0]' 'projects/<PROJECT_ID>/enable-oslogin'
+terraform import 'module.runner.google_compute_project_metadata_item.runner_id[0]' 'projects/<PROJECT_ID>/gitpod-runner-id'
+
+# 3. Apply — should show no changes
+terraform apply
+```
+
+Replace `<PROJECT_ID>` with your GCP project ID and adjust the module path if
+your module block uses a different name.
+
 ## Releases
 
 New stable releases are published roughly once a week. To get notified when a

runner-vm.tf

@@ -358,12 +358,29 @@ resource "google_compute_health_check" "runner" {
 }
 
 
-# Resource tagging for lifecycle management
+# Project metadata: authoritative (default) or per-key items.
+# Authoritative manages ALL project metadata — keys not in this block are removed.
+# Per-key items only touch the keys this module needs, leaving other metadata intact.
 resource "google_compute_project_metadata" "runner_metadata" {
+  count   = var.use_authoritative_project_metadata ? 1 : 0
   project = var.project_id
 
   metadata = {
     "enable-oslogin"   = "TRUE"
     "gitpod-runner-id" = var.runner_id
   }
 }
+
+resource "google_compute_project_metadata_item" "enable_oslogin" {
+  count   = var.use_authoritative_project_metadata ? 0 : 1
+  project = var.project_id
+  key     = "enable-oslogin"
+  value   = "TRUE"
+}
+
+resource "google_compute_project_metadata_item" "runner_id" {
+  count   = var.use_authoritative_project_metadata ? 0 : 1
+  project = var.project_id
+  key     = "gitpod-runner-id"
+  value   = var.runner_id
+}

variables.tf

@@ -337,4 +337,10 @@ variable "enable_agents" {
   default     = true
 }
 
+variable "use_authoritative_project_metadata" {
+  description = "Use authoritative google_compute_project_metadata (true) or per-key google_compute_project_metadata_item (false). The authoritative resource manages ALL project metadata — keys not listed in this module will be removed. Set to false if other systems or Terraform modules manage project metadata in the same project. Switching from true to false on an existing deployment requires state migration (see README)."
+  type        = bool
+  default     = true
+}
+