GCP: Add install-config.yaml customization doc

Create a doc specifying GCP-specific platform install config fields. Documents GCP cluster isolation in customization doc. Adds examples for GCP install config platform customization.
2026-02-05 15:47:14 +01:00 · 2019-10-24 11:33:45 -04:00
parent 1c32be0d6b
commit f1b05d4e3a
2 changed files with 107 additions and 0 deletions
--- a/docs/user/customization.md
+++ b/docs/user/customization.md
@@ -73,6 +73,7 @@ The following machine-pool properties are available:
 * `platform` (optional object): Platform-specific machine-pool configuration.
    * `aws` (optional object): [AWS-specific properties](aws/customization.md#machine-pools).
    * `azure` (optional object): [Azure-specific properties](azure/customization.md#machine-pools).
+    * `gcp` (optional object): [GCP-specific properties](gcp/customization.md#machine-pools).
    * `openstack` (optional object): [OpenStack-specific properties](openstack/customization.md#machine-pools).
    * `vsphere` (optional object): [vSphere-specific properties](vsphere/customization.md#machine-pools).
 * `replicas` (optional integer): The machine count for the machine pool.
--- a/docs/user/gcp/customization.md
+++ b/docs/user/gcp/customization.md
@@ -0,0 +1,106 @@
+# GCP Platform Customization
+
+Beyond the [platform-agnostic `install-config.yaml` properties](../customization.md#platform-customization), the installer supports additional, GCP-specific properties.
+
+* `projectID` (required string): The project where the cluster should be created.
+* `region` (required string): The GCP region where the cluster should be created.
+* `network` (optional string): The name of an existing GCP VPC where the cluster infrastructure should be provisioned.
+* `controlPlaneSubnet` (optional string): The name of an existing GCP subnet which should be used by the cluster control plane.
+* `computeSubnet` (optional string): The name of an existing GCP subnet which should be used by the cluster nodes.
+* `defaultMachinePlatform` (optional object): Default [GCP-specific machine pool properties](#machine-pools) which apply to [machine pools](../customization.md#machine-pools) that do not define their own GCP-specific properties.
+
+## Machine pools
+
+* `type` (optional string): The [GCP machine type][machine-type].
+* `zones` (optional array of strings): The availability zones used for machines in the pool.
+
+## Installing to Existing Networks & Subnetworks
+
+The installer can use an existing VPC and subnets when provisioning an OpenShift cluster. If one of `network`, `controlPlaneSubnet`, or `computeSubnet` is specified, all must be specified ([see example below](#pre-existing-networks-&-subnets)). Furthermore, each of the networks must belong to the project specified by `projectID`, and the subnets must belong to the specified cluster `region`. The installer will use these existing networks when creating infrastructure such as VM instances, load balancers, firewall rules, and DNS zones.
+
+### Cluster Isolation
+
+In a scenario where multiple clusters are installed to the same VPC network, the installer maintains cluster isolation by using firewall rules which specify allowed sources and destinations through network tags. By tagging each Compute Engine VM instance with a unique cluster id and creating corresponding firewall rules, the installer ensures that a cluster's control plane is only accessible by its own member nodes.
+
+By design, possible inter-cluster access is limited to:
+* The API, which is globally available with an external publishing strategy or available throughout the network in an internal publishing strategy
+* Debugging tools; i.e. ports on VM instances are open to the `machineCidr` for SSH & ICMP
+
+## Examples
+
+Some example `install-config.yaml` are shown below.
+For examples of platform-agnostic configuration fragments, see [here](../customization.md#examples).
+
+### Minimal
+
+An example minimal GCP install config is:
+
+```yaml
+apiVersion: v1
+baseDomain: example.com
+metadata:
+  name: example-cluster
+platform:
+  gcp:
+    project: example-project
+    region: us-east1
+pullSecret: '{"auths": ...}'
+sshKey: ssh-ed25519 AAAA...
+```
+
+### Custom machine pools
+
+An example GCP install config with custom machine pools:
+
+```yaml
+apiVersion: v1
+baseDomain: example.com
+compute:
+- name: worker
+  platform: 
+    gcp:
+      type: n2-standard-2
+      zones:
+      - us-central1-a
+      - us-central1-c
+  replicas: 3
+controlPlane:
+  name: master
+  platform:
+    gcp:
+      type: n2-standard-4
+      zones:
+      - us-central1-a
+      - us-central1-c
+  replicas: 3
+metadata:
+  name: example-cluster
+platform:
+  gcp:
+    projectID: openshift-dev-installer
+    region: us-central1
+pullSecret: '{"auths": ...}'
+sshKey: ssh-ed25519 AAAA...
+```
+
+### Pre-existing Networks & Subnets
+
+An example GCP install config utilizing an existing network and subnets:
+
+```yaml
+apiVersion: v1
+baseDomain: example.com
+metadata:
+  name: example-cluster
+platform:
+  gcp:
+    project: example-project
+    region: us-east1
+    computeSubnet: example-worker-subnet
+    controlPlaneSubnet: example-controlplane-subnet
+    network: example-network
+pullSecret: '{"auths": ...}'
+sshKey: ssh-ed25519 AAAA...
+```
+
+[machine-type]: https://cloud.google.com/compute/docs/machine-types