Create GCP Infrastructure

This guide explains how to create network infrastructure for GCP hosted clusters using the hypershift create infra gcp command.

Prerequisites

• The hypershift CLI built from the repository
• gcloud CLI authenticated with permissions in the hosted cluster GCP project
• A GCP project for the hosted cluster with required APIs enabled:

gcloud services enable \
  compute.googleapis.com \
  dns.googleapis.com \
  iam.googleapis.com \
  iamcredentials.googleapis.com \
  cloudresourcemanager.googleapis.com \
  --project=<hosted-cluster-project-id>

Create Infrastructure

The hypershift create infra gcp command creates network resources in the hosted cluster project:

• VPC — Virtual Private Cloud network for worker nodes
• Subnet — Subnet within the VPC
• Cloud Router + NAT — Egress for worker nodes

hypershift create infra gcp \
  --infra-id=<infra-id> \
  --project-id=<hosted-cluster-project-id> \
  --region=<region>

Flags

Example

hypershift create infra gcp \
  --infra-id=my-cluster \
  --project-id=my-hc-project \
  --region=us-central1 \
  > infra-output.json

Output

The command outputs JSON with the created resource names:

{
  "region": "us-central1",
  "projectId": "my-hc-project",
  "infraId": "my-cluster",
  "networkName": "my-cluster-network",
  "subnetName": "my-cluster-subnet",
  "subnetCidr": "10.0.0.0/24",
  "routerName": "my-cluster-router",
  "natName": "my-cluster-nat"
}

Save this output — you will need the networkName and subnetName values when creating the hosted cluster.

Worker firewall rules

The control-plane-operator (CPO) owns the worker firewall rule <infra-id>-internal-cluster. It is created in the hosted cluster's GCP project and VPC, continuously reconciled while the cluster exists, and deleted during hosted cluster teardown. This CLI never creates or deletes the firewall rule.

Teardown happens only when cloud resource cleanup is enabled, i.e. when the HostedCluster carries the hypershift.openshift.io/cleanup-cloud-resources=true annotation. hypershift destroy cluster sets it by default (--destroy-cloud-resources); a plain kubectl delete hostedcluster does not, leaving the rule in place — remove it manually (gcloud compute firewall-rules delete <infra-id>-internal-cluster) before deleting the VPC. Teardown can also be skipped explicitly with the hypershift.openshift.io/skip-gcp-firewall-rule-cleanup annotation on the HostedCluster.

The managed rule is an enabled INGRESS / ALLOW rule at priority 1000, scoped by the <infra-id>-worker network tag as both source and target (no machine, pod, or PSC CIDR allowances):

The NodePort range is spec.configuration.network.serviceNodePortRange on the HostedCluster, defaulting to 30000-32767 (the same default kube-apiserver uses) when unset.

CPO uses its mounted Workload Identity Federation credentials to reconcile the rule and requires the roles/compute.securityAdmin role on the ctrlplane-op service account (provisioned by hypershift create iam gcp). The reconcile is best-effort: if credentials are not yet available or the IAM role is missing, the GCPFirewallRulesReady condition on the HostedCluster/HostedControlPlane reports False with an actionable message and converges automatically once the prerequisite is satisfied — cluster bootstrap is never blocked.

Enabling on an existing cluster

Because the reconciler is name-based and idempotent, an existing cluster whose CPO is on a release payload containing this feature converges the same as a fresh one. The only prerequisite is granting roles/compute.securityAdmin to ctrlplane-op — re-run hypershift create iam gcp (it grants the role to the already-created service account; no cluster recreation is needed). Until the role is granted, GCPFirewallRulesReady reports False with a permission-denied message.

Destroy Infrastructure

To clean up infrastructure resources:

hypershift destroy infra gcp \
  --infra-id=<infra-id> \
  --project-id=<hosted-cluster-project-id> \
  --region=<region>

Next Steps

• Create GCP IAM Resources — Create WIF pool and service accounts
• Create a GCP Hosted Cluster — Deploy your hosted cluster