Merge pull request #51171 from bscott-rh/OSDOCS-3940

OSDOCS-3940 Enabling GCP Shared VPC IPI installation

Author: jeana-redhat

_topic_maps/_topic_map.yml

@@ -236,6 +236,8 @@ Topics:
     File: installing-restricted-networks-gcp-installer-provisioned
   - Name: Installing a cluster on GCP into an existing VPC
     File: installing-gcp-vpc
+  - Name: Installing a cluster on GCP into a shared VPC
+    File: installing-gcp-shared-vpc
   - Name: Installing a private cluster on GCP
     File: installing-gcp-private
   - Name: Installing a cluster on GCP using Deployment Manager templates

installing/installing_gcp/installing-gcp-shared-vpc.adoc

@@ -0,0 +1,68 @@
+:_content-type: ASSEMBLY
+[id="installing-gcp-shared-vpc"]
+= Installing a cluster on GCP into a shared VPC
+include::_attributes/common-attributes.adoc[]
+:context: installing-gcp-shared-vpc
+:FeatureName: Installing a cluster on GCP into a shared VPC
+
+toc::[]
+
+In {product-title} version {product-version}, you can install a cluster into a shared Virtual Private Cloud (VPC) on Google Cloud Platform (GCP). In this installation method, the cluster is configured to use a VPC from a different GCP project. A shared VPC enables an organization to connect resources from multiple projects to a common VPC network. You can communicate within the organization securely and efficiently by using internal IP addresses from that network. For more information about shared VPC, see link:https://cloud.google.com/vpc/docs/shared-vpc[Shared VPC overview in the GCP documentation]. 
+
+The installation program provisions the rest of the required infrastructure, which you can further customize. To customize the installation, you modify parameters in the `install-config.yaml` file before you install the cluster.
+
+include::snippets/technology-preview.adoc[leveloffset=+1]
+
+[id="installation-gcp-shared-vpc-prerequisites_{context}"]
+== Prerequisites
+
+* You reviewed details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes.
+* You read the documentation on xref:../../installing/installing-preparing.adoc#installing-preparing[selecting a cluster installation method and preparing it for users].
+* If you use a firewall, you xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configured it to allow the sites] that your cluster requires access to.
+* If the cloud identity and access management (IAM) APIs are not accessible in your environment, or if you do not want to store an administrator-level credential secret in the `kube-system` namespace, you can xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually create and maintain IAM credentials].
+* You have a GCP host project which contains a shared VPC network.
+* You xref:../../installing/installing_gcp/installing-gcp-account.adoc#installing-gcp-account[configured a GCP project] to host the cluster. This project, known as the service project, must be attached to the host project. For more information, see link:https://cloud.google.com/vpc/docs/provisioning-shared-vpc#create-shared[Attaching service projects in the GCP documentation].
+* You have a GCP service account that has the xref:../../installing/installing_gcp/installing-gcp-account.adoc#installation-gcp-permissions_installing-gcp-account[required GCP permissions] in the host project.
+
+include::modules/cluster-entitlements.adoc[leveloffset=+1]
+
+include::modules/ssh-agent-using.adoc[leveloffset=+1]
+
+include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
+
+include::modules/installation-user-infra-generate.adoc[leveloffset=+1]
+
+include::modules/installation-initializing-manual.adoc[leveloffset=+2]
+
+include::modules/installation-gcp-shared-vpc-config.adoc[leveloffset=+2]
+
+include::modules/installation-configuration-parameters.adoc[leveloffset=+2]
+
+include::modules/installation-configure-proxy.adoc[leveloffset=+2]
+
+include::modules/installation-launching-installer.adoc[leveloffset=+1]
+
+include::modules/cli-installing-cli.adoc[leveloffset=+1]
+
+include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
+
+include::modules/installation-gcp-shared-vpc-ingress.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* See xref:../../web_console/web-console.adoc#web-console[Accessing the web console] for more details about accessing and understanding the {product-title} web console.
+
+include::modules/cluster-telemetry.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* See xref:../../support/remote_health_monitoring/about-remote-health-monitoring.adoc#about-remote-health-monitoring[About remote health monitoring] for more information about the Telemetry service
+
+[id="installation-gcp-shared-vpc-next-steps_{context}"]
+== Next steps
+
+* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster].
+* If necessary, you can
+xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting].

modules/installation-configuration-parameters.adoc

@@ -23,6 +23,7 @@
 // * installing/installing_gcp/installing-gcp-network-customizations.adoc
 // * installing/installing_gcp/installing-gcp-private.adoc
 // * installing/installing_gcp/installing-gcp-vpc.adoc
+// * installing/installing_gcp/installing-gcp-shared-vpc.adoc
 // * installing/installing_gcp/installing-restricted-networks-gcp-installer-provisioned.adoc
 // * installing/installing_ibm_cloud_public/installing-ibm-cloud-customizations.adoc
 // * installing/installing_ibm_cloud_public/installing-ibm-cloud-network-customizations.adoc
@@ -114,6 +115,9 @@ endif::[]
 ifeval::["{context}" == "installing-gcp-vpc"]
 :gcp:
 endif::[]
+ifeval::["{context}" == "installing-gcp-shared-vpc"]
+:gcp:
+endif::[]
 ifeval::["{context}" == "installing-restricted-networks-gcp-installer-provisioned"]
 :gcp:
 endif::[]
@@ -1811,6 +1815,9 @@ endif::[]
 ifeval::["{context}" == "installing-gcp-vpc"]
 :!gcp:
 endif::[]
+ifeval::["{context}" == "installing-gcp-shared-vpc"]
+:!gcp:
+endif::[]
 ifeval::["{context}" == "installing-restricted-networks-gcp-installer-provisioned"]
 :!gcp:
 endif::[]

modules/installation-gcp-permissions.adoc

@@ -24,14 +24,18 @@ account requires the following permissions. If you deploy your cluster into an e
 
 .Required roles for the installation program
 * Compute Admin
-* Security Admin
+* IAM Security Admin
 * Service Account Admin
 * Service Account User
 * Storage Admin
 
 .Required roles for creating network resources during installation
 * DNS Administrator
 
+.Required roles for using passthrough credentials mode
+* Compute Load Balancer Admin
+* IAM Role Viewer
+
 ifdef::template[]
 .Required roles for user-provisioned GCP infrastructure
 * Deployment Manager Editor

modules/installation-gcp-shared-vpc-config.adoc

@@ -0,0 +1,77 @@
+// This file is referenced in the following assembly:
+// installing/installing_gcp/installing-gcp-shared-vpc.adoc
+
+:_content-type: PROCEDURE
+[id="installation-gcp-shared-vpc-config_{context}"]
+= Sample customized install-config.yaml file for shared VPC installation
+There are several configuration parameters which are required to install {product-title} on GCP using a shared VPC. The following is a sample `install-config.yaml` file which demonstrates these fields.
+
+[IMPORTANT]
+====
+This sample YAML file is provided for reference only. You must modify this file with the correct values for your environment and cluster.
+====
+
+[source,yaml]
+----
+apiVersion: v1
+baseDomain: example.com
+credentialsMode: Passthrough <1>
+metadata:
+  name: cluster_name
+platform:
+  gcp:
+    computeSubnet: shared-vpc-subnet-1 <2>
+    controlPlaneSubnet: shared-vpc-subnet-2 <3>
+    createFirewallRules: Disabled <4>
+    network: shared-vpc <5>
+    networkProjectID: host-project-name <6>
+    publicDNSZone:
+      id: public-dns-zone <7>
+      project: host-project-name <8> 
+    projectID: service-project-name <9>
+    region: us-east1
+    defaultMachinePlatform:
+      tags: <10>
+      - global-tag1
+controlPlane:
+  name: master
+  platform:
+    gcp:
+      tags: <10>
+      - control-plane-tag1
+      type: n2-standard-4
+      zones:
+      - us-central1-a
+      - us-central1-c
+  replicas: 3
+compute:
+- name: worker
+  platform:
+    gcp:
+      tags: <10>
+      - compute-tag1 
+      type: n2-standard-4
+      zones:
+      - us-central1-a
+      - us-central1-c
+  replicas: 3
+networking:
+  clusterNetwork:
+  - cidr: 10.128.0.0/14
+    hostPrefix: 23
+  machineNetwork:
+  - cidr: 10.0.0.0/16
+pullSecret: '{"auths": ...}'
+sshKey: ssh-ed25519 AAAA... <11>
+----
+<1> `credentialsMode` must be set to `Passthrough` to allow the cluster to use the provided GCP service account after cluster creation. See the "Prerequisites" section for the required GCP permissions that your service account must have.
+<2> The name of the subnet in the shared VPC for compute machines to use.
+<3> The name of the subnet in the shared VPC for control plane machines to use.
+<4> Optional. If you set `createFirewallRules` to `Disabled`, you can create and manage firewall rules manually through the use of network tags. By default, the cluster will automatically create and manage the firewall rules that are required for cluster communication. Your service account must have `roles/compute.networkAdmin` and `roles/compute.securityAdmin` privileges in the host project to perform these tasks automatically. If your service account does not have the `roles/dns.admin` privilege in the host project, it must have the `dns.networks.bindPrivateDNSZone` permission.
+<5> The name of the shared VPC.
+<6> The name of the host project where the shared VPC exists.
+<7> Optional. The name of a public DNS zone in the host project. If you set this value, your service account must have the `roles/dns.admin` privilege in the host project. The public DNS zone domain must match the `baseDomain` parameter. If you do not set this value, the installation program will use the public DNS zone in the service project.
+<8> Optional. The name of the host project which contains the public DNS zone. This value is required if you specify a public DNS zone that exists in another project.
+<9> The name of the GCP project where you want to install the cluster.
+<10> Optional. If you want to manually create and manage your GCP firewall rules, you can set `platform.gcp.createFirewallRules` to `Disabled` and then specify one or more network tags. You can set tags on the compute machines, the control plane machines, or all machines.
+<11> You can optionally provide the `sshKey` value that you use to access the machines in your cluster.

modules/installation-gcp-shared-vpc-ingress.adoc

@@ -0,0 +1,49 @@
+// File included in the following assemblies:
+// * installation/installing_gcp/installing-gcp-shared-vpc.adoc
+
+:_content-type: PROCEDURE
+[id="installation-gcp-shared-vpc-ingress_{context}"]
+= Optional: Adding Ingress DNS records for shared VPC installations
+If the public DNS zone exists in a host project outside the project where you installed your cluster, you must manually create DNS records that point at the Ingress load balancer. You can create either a wildcard `*.apps.{baseDomain}.` or specific records. You can use A, CNAME, and other records per your requirements.
+
+.Prerequisites
+* You completed the installation of {product-title} on GCP into a shared VPC.
+* Your public DNS zone exists in a host project separate from the service project that contains your cluster.
+
+.Procedure
+. Verify that the Ingress router has created a load balancer and populated the `EXTERNAL-IP` field by running the following command:
++
+[source,terminal]
+----
+$ oc -n openshift-ingress get service router-default
+----
++
+.Example output
+[source,terminal]
+----
+NAME             TYPE           CLUSTER-IP      EXTERNAL-IP      PORT(S)                      AGE
+router-default   LoadBalancer   172.30.18.154   35.233.157.184   80:32288/TCP,443:31215/TCP   98
+----
+. Record the external IP address of the router by running the following command:
++
+[source,terminal]
+----
+$ oc -n openshift-ingress get service router-default --no-headers | awk '{print $4}'
+----
+. Add a record to your GCP public zone with the router's external IP address and the name `*.apps.<cluster_name>.<cluster_domain>`. You can use the `gcloud` command line utility or the GCP web console.
+. To add manual records instead of a wildcard record, create entries for each of the cluster's current routes. You can gather these routes by running the following command:
++
+[source,terminal]
+----
+$ oc get --all-namespaces -o jsonpath='{range .items[*]}{range .status.ingress[*]}{.host}{"\n"}{end}{end}' routes
+----
++
+.Example output
+[source,terminal]
+----
+oauth-openshift.apps.your.cluster.domain.example.com
+console-openshift-console.apps.your.cluster.domain.example.com
+downloads-openshift-console.apps.your.cluster.domain.example.com
+alertmanager-main-openshift-monitoring.apps.your.cluster.domain.example.com
+prometheus-k8s-openshift-monitoring.apps.your.cluster.domain.example.com
+----

modules/installation-initializing-manual.adoc

@@ -9,6 +9,7 @@
 // * installing/installing_azure_stack_hub/installing-azure-stack-hub-default.adoc
 // * installing/installing_bare_metal/installing-bare-metal.adoc
 // * installing/installing_gcp/installing-gcp-private.adoc
+// * installing/installing_gcp/installing-gcp-shared-vpc.adoc
 // * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc
 // * installing/installing_platform_agnostic/installing-platform-agnostic.adoc
 // * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc
@@ -53,6 +54,9 @@ endif::[]
 ifeval::["{context}" == "installing-gcp-private"]
 :gcp-private:
 endif::[]
+ifeval::["{context}" == "installing-gcp-shared-vpc"]
+:gcp-shared:
+endif::[]
 ifeval::["{context}" == "installing-azure-stack-hub-default"]
 :ash-default:
 endif::[]
@@ -64,9 +68,9 @@ endif::[]
 [id="installation-initializing-manual_{context}"]
 = Manually creating the installation configuration file
 
-ifndef::aws-china,aws-gov,aws-secret,azure-gov,ash,aws-private,azure-private,gcp-private,ash-default,ash-network[]
+ifndef::aws-china,aws-gov,aws-secret,azure-gov,ash,aws-private,azure-private,gcp-private,gcp-shared,ash-default,ash-network[]
 For user-provisioned installations of {product-title}, you manually generate your installation configuration file.
-endif::aws-china,aws-gov,aws-secret,azure-gov,ash,aws-private,azure-private,gcp-private,ash-default,ash-network[]
+endif::aws-china,aws-gov,aws-secret,azure-gov,ash,aws-private,azure-private,gcp-private,gcp-shared,ash-default,ash-network[]
 ifdef::aws-china,aws-gov,aws-secret[]
 Installing the cluster requires that you manually generate the installation configuration file.
 //Made this update as part of feedback in PR3961. tl;dr Simply state you have to create the config file, instead of creating a number of conditions to explain why.
@@ -81,6 +85,9 @@ endif::aws-private,azure-private,gcp-private[]
 ifdef::ash-default,ash-network[]
 When installing {product-title} on Microsoft Azure Stack Hub, you must manually create your installation configuration file.
 endif::ash-default,ash-network[]
+ifdef::gcp-shared[]
+You must manually create your installation configuration file when installing {product-title} on GCP into a shared VPC using installer-provisioned infrastructure.
+endif::gcp-shared[]
 
 .Prerequisites
 
@@ -132,12 +139,12 @@ mirror the repository.
 endif::restricted[]
 +
 
-ifndef::aws-china,aws-gov,aws-secret,azure-gov,ash,ash-default,ash-network[]
+ifndef::aws-china,aws-gov,aws-secret,azure-gov,ash,ash-default,ash-network,gcp-shared[]
 [NOTE]
 ====
 For some platform types, you can alternatively run `./openshift-install create install-config --dir <installation_directory>` to generate an `install-config.yaml` file. You can provide details about your cluster configuration at the prompts.
 ====
-endif::aws-china,aws-gov,aws-secret,azure-gov,ash,ash-default,ash-network[]
+endif::aws-china,aws-gov,aws-secret,azure-gov,ash,ash-default,ash-network,gcp-shared[]
 ifdef::ash[]
 +
 Make the following modifications for Azure Stack Hub:
@@ -228,6 +235,9 @@ endif::[]
 ifeval::["{context}" == "installing-gcp-private"]
 :!gcp-private:
 endif::[]
+ifeval::["{context}" == "installing-gcp-shared-vpc"]
+:!gcp-shared:
+endif::[]
 ifeval::["{context}" == "installing-azure-stack-hub-default"]
 :!ash-default:
 endif::[]

modules/installation-initializing.adoc

@@ -14,6 +14,7 @@
 // * installing/installing_gcp/installing-gcp-customizations.adoc
 // * installing/installing_gcp/installing-gcp-network-customizations.adoc
 // * installing/installing_gcp/installing-gcp-vpc.adoc
+// * installing/installing_gcp/installing-gcp-shared-vpc.adoc
 // * installing/installing_gcp/installing-gcp-user-infra.adoc
 // * installing/installing_gcp/installing-restricted-networks-gcp.adoc
 // * installing/installing_gcp/installing-restricted-networks-gcp-installer-provisioned.adoc
@@ -76,6 +77,9 @@ endif::[]
 ifeval::["{context}" == "installing-gcp-vpc"]
 :gcp:
 endif::[]
+ifeval::["{context}" == "installing-gcp-shared-vpc"]
+:gcp:
+endif::[]
 ifeval::["{context}" == "installing-gcp-network-customizations"]
 :gcp:
 endif::[]
@@ -641,6 +645,9 @@ endif::[]
 ifeval::["{context}" == "installing-gcp-vpc"]
 :!gcp:
 endif::[]
+ifeval::["{context}" == "installing-gcp-shared-vpc"]
+:!gcp:
+endif::[]
 ifeval::["{context}" == "installing-gcp-user-infra"]
 :!gcp:
 :!gcp-user-infra:

modules/installation-launching-installer.adoc

@@ -20,6 +20,7 @@
 // * installing/installing_gcp/installing-gcp-private.adoc
 // * installing/installing_gcp/installing-gcp-default.adoc
 // * installing/installing_gcp/installing-gcp-vpc.adoc
+// * installing/installing_gcp/installing-gcp-shared-vpc.adoc
 // * installing/installing_gcp/installing-restricted-networks-gcp-installer-provisioned.adoc
 // * installing/installing_gcp/installing-ibm-cloud-customizations.adoc
 // * installing/installing_gcp/installing-ibm-cloud-vpc.adoc
@@ -101,6 +102,10 @@ ifeval::["{context}" == "installing-gcp-vpc"]
 :custom-config:
 :gcp:
 endif::[]
+ifeval::["{context}" == "installing-gcp-shared-vpc"]
+:custom-config:
+:gcp:
+endif::[]
 ifeval::["{context}" == "installing-gcp-default"]
 :no-config:
 :gcp:
@@ -590,6 +595,10 @@ ifeval::["{context}" == "installing-gcp-vpc"]
 :!custom-config:
 :!gcp:
 endif::[]
+ifeval::["{context}" == "installing-gcp-shared-vpc"]
+:!custom-config:
+:!gcp:
+endif::[]
 ifeval::["{context}" == "installing-gcp-default"]
 :!no-config:
 :!gcp: