Merge pull request #55612 from mjpytlak/osdocs-4896

OSDOCS#4896: Adding new parameter for IBM Cloud VPC BYON install use cases

Author: mjpytlak

modules/installation-configuration-parameters.adoc

@@ -1339,36 +1339,27 @@ Additional IBM Cloud VPC configuration parameters are described in the following
 |Parameter|Description|Values
 
 |`platform.ibmcloud.resourceGroupName`
-ifndef::ibm-cloud-vpc[]
-|The name of an existing resource group to install your cluster to. This resource group must only be used for this specific cluster because the cluster components assume ownership of all of the resources in the resource group. If undefined, a new resource group is created for the cluster. [^1^]
-endif::ibm-cloud-vpc[]
-ifdef::ibm-cloud-vpc[]
-|The name of an existing resource group. The existing VPC and subnets should be in this resource group. Cluster installation resources are created in this resource group.
-endif::ibm-cloud-vpc[]
-
+|The name of an existing resource group.
+By default, an installer-provisioned VPC and cluster resources are placed in this resource group. When not specified, the installation program creates the resource group for the cluster.
+If you are deploying the cluster into an existing VPC, the installer-provisioned cluster resources are placed in this resource group. When not specified, the installation program creates the resource group for the cluster. The VPC resources that you have provisioned must exist in a resource group that you specify using the `networkResourceGroupName` parameter.
+In either case, this resource group must only be used for a single cluster installation, as the cluster components assume ownership of all of the resources in the resource group. [^1^]
 |String, for example `existing_resource_group`.
 
+|`platform.ibmcloud.networkResourceGroupName`
+|The name of an existing resource group. This resource contains the existing VPC and subnets to which the cluster will be deployed. This parameter is required when deploying the cluster to a VPC that you have provisioned.
+|String, for example `existing_network_resource_group`.
+
 |`platform.ibmcloud.dedicatedHosts.profile`
 |The new dedicated host to create. If you specify a value for `platform.ibmcloud.dedicatedHosts.name`, this parameter is not required.
-ifndef::ibm-cloud-vpc[]
 |Valid IBM Cloud VPC dedicated host profile, such as `cx2-host-152x304`. [^2^]
-endif::ibm-cloud-vpc[]
-ifdef::ibm-cloud-vpc[]
-|Valid IBM Cloud VPC dedicated host profile, such as `cx2-host-152x304`. [^1^]
-endif::ibm-cloud-vpc[]
 
 |`platform.ibmcloud.dedicatedHosts.name`
 |An existing dedicated host. If you specify a value for `platform.ibmcloud.dedicatedHosts.profile`, this parameter is not required.
 |String, for example `my-dedicated-host-name`.
 
 |`platform.ibmcloud.type`
 |The instance type for all IBM Cloud VPC machines.
-ifndef::ibm-cloud-vpc[]
 |Valid IBM Cloud VPC instance type, such as `bx2-8x32`. [^2^]
-endif::ibm-cloud-vpc[]
-ifdef::ibm-cloud-vpc[]
-|Valid IBM Cloud VPC instance type, such as `bx2-8x32`. [^1^]
-endif::ibm-cloud-vpc[]
 
 |`platform.ibmcloud.vpcName`
 | The name of the existing VPC that you want to deploy your cluster to.
@@ -1385,13 +1376,8 @@ endif::ibm-cloud-vpc[]
 |====
 [.small]
 --
-ifndef::ibm-cloud-vpc[]
-1. Whether you define an existing resource group, or if the installer creates one, determines how the resource group is treated when the cluster is uninstalled. If you define a resource group, the installer removes all of the installer-provisioned resources, but leaves the resource group alone; if a resource group is created as part of the installation, the installer removes all of the installer provisioned resources and the resource group.
+1. Whether you define an existing resource group, or if the installer creates one, determines how the resource group is treated when the cluster is uninstalled. If you define a resource group, the installer removes all of the installer-provisioned resources, but leaves the resource group alone; if a resource group is created as part of the installation, the installer removes all of the installer-provisioned resources and the resource group.
 2. To determine which profile best meets your needs, see https://cloud.ibm.com/docs/vpc?topic=vpc-profiles&interface=ui[Instance Profiles] in the IBM documentation.
-endif::ibm-cloud-vpc[]
-ifdef::ibm-cloud-vpc[]
-1. To determine which profile best meets your needs, see https://cloud.ibm.com/docs/vpc?topic=vpc-profiles&interface=ui[Instance Profiles] in the IBM documentation.
-endif::ibm-cloud-vpc[]
 --
 endif::ibm-cloud[]
 

modules/installation-ibm-cloud-config-yaml.adoc

@@ -137,24 +137,25 @@ platform:
   ibmcloud:
     region: eu-gb <1>
     resourceGroupName: eu-gb-example-network-rg <7>
-    vpcName: eu-gb-example-network-1 <8>
-    controlPlaneSubnets: <9>
+    networkResourceGroupName: eu-gb-example-existing-network-rg <8>
+    vpcName: eu-gb-example-network-1 <9>
+    controlPlaneSubnets: <10>
       - eu-gb-example-network-1-cp-eu-gb-1
       - eu-gb-example-network-1-cp-eu-gb-2
       - eu-gb-example-network-1-cp-eu-gb-3
-    computeSubnets: <10>
+    computeSubnets: <11>
       - eu-gb-example-network-1-compute-eu-gb-1
       - eu-gb-example-network-1-compute-eu-gb-2
       - eu-gb-example-network-1-compute-eu-gb-3
 credentialsMode: Manual
 publish: External
 pullSecret: '{"auths": ...}' <1>
 ifndef::openshift-origin[]
-fips: false <11>
-sshKey: ssh-ed25519 AAAA... <12>
+fips: false <12>
+sshKey: ssh-ed25519 AAAA... <13>
 endif::openshift-origin[]
 ifdef::openshift-origin[]
-sshKey: ssh-ed25519 AAAA... <11>
+sshKey: ssh-ed25519 AAAA... <12>
 endif::openshift-origin[]
 ----
 <1> Required. The installation program prompts you for this value.
@@ -168,21 +169,22 @@ If you disable simultaneous multithreading, ensure that your capacity planning a
 ====
 <5> The machine CIDR must contain the subnets for the compute machines and control plane machines.
 <6> The cluster network plugin to install. The supported values are `OVNKubernetes` and `OpenShiftSDN`. The default value is `OVNKubernetes`.
-<7> The name of an existing resource group. The existing VPC and subnets should be in this resource group. The cluster is deployed to this resource group.
-<8> Specify the name of an existing VPC.
-<9> Specify the name of the existing subnets to which to deploy the control plane machines. The subnets must belong to the VPC that you specified. Specify a subnet for each availability zone in the region.
-<10> Specify the name of the existing subnets to which to deploy the compute machines. The subnets must belong to the VPC that you specified. Specify a subnet for each availability zone in the region.
+<7> The name of an existing resource group. All installer-provisioned cluster resources are deployed to this resource group. If undefined, a new resource group is created for the cluster.
+<8> Specify the name of the resource group that contains the existing virtual private cloud (VPC). The existing VPC and subnets should be in this resource group. The cluster will be installed to this VPC.
+<9> Specify the name of an existing VPC.
+<10> Specify the name of the existing subnets to which to deploy the control plane machines. The subnets must belong to the VPC that you specified. Specify a subnet for each availability zone in the region.
+<11> Specify the name of the existing subnets to which to deploy the compute machines. The subnets must belong to the VPC that you specified. Specify a subnet for each availability zone in the region.
 ifndef::openshift-origin[]
-<11> Enables or disables FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead.
+<12> Enables or disables FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead.
 +
 [IMPORTANT]
 ====
 The use of FIPS Validated or Modules in Process cryptographic libraries is only supported on {product-title} deployments on the `x86_64` architecture.
 ====
-<12> Optional: provide the `sshKey` value that you use to access the machines in your cluster.
+<13> Optional: provide the `sshKey` value that you use to access the machines in your cluster.
 endif::openshift-origin[]
 ifdef::openshift-origin[]
-<11> Optional: provide the `sshKey` value that you use to access the machines in your cluster.
+<12> Optional: provide the `sshKey` value that you use to access the machines in your cluster.
 endif::openshift-origin[]
 +
 [NOTE]
@@ -223,24 +225,25 @@ platform:
   ibmcloud:
     region: eu-gb <1>
     resourceGroupName: eu-gb-example-network-rg <8>
-    vpcName: eu-gb-example-network-1 <9>
-    controlPlaneSubnets: <10>
+    networkResourceGroupName: eu-gb-example-existing-network-rg <9>
+    vpcName: eu-gb-example-network-1 <10>
+    controlPlaneSubnets: <11>
       - eu-gb-example-network-1-cp-eu-gb-1
       - eu-gb-example-network-1-cp-eu-gb-2
       - eu-gb-example-network-1-cp-eu-gb-3
-    computeSubnets: <11>
+    computeSubnets: <12>
       - eu-gb-example-network-1-compute-eu-gb-1
       - eu-gb-example-network-1-compute-eu-gb-2
       - eu-gb-example-network-1-compute-eu-gb-3
 credentialsMode: Manual
-publish: Internal <12>
+publish: Internal <13>
 pullSecret: '{"auths": ...}' <1>
 ifndef::openshift-origin[]
-fips: false <13>
-sshKey: ssh-ed25519 AAAA... <14>
+fips: false <14>
+sshKey: ssh-ed25519 AAAA... <15>
 endif::openshift-origin[]
 ifdef::openshift-origin[]
-sshKey: ssh-ed25519 AAAA... <13>
+sshKey: ssh-ed25519 AAAA... <14>
 endif::openshift-origin[]
 ----
 <1> Required.
@@ -255,22 +258,23 @@ If you disable simultaneous multithreading, ensure that your capacity planning a
 <5> The machine CIDR must contain the subnets for the compute machines and control plane machines.
 <6> The CIDR must contain the subnets defined in `platform.ibmcloud.controlPlaneSubnets` and `platform.ibmcloud.computeSubnets`.
 <7> The cluster network plugin to install. The supported values are `OVNKubernetes` and `OpenShiftSDN`. The default value is `OVNKubernetes`.
-<8> The name of an existing resource group. The existing VPC and subnets should be in this resource group. The cluster is deployed to this resource group.
-<9> Specify the name of an existing VPC.
-<10> Specify the name of the existing subnets to which to deploy the control plane machines. The subnets must belong to the VPC that you specified. Specify a subnet for each availability zone in the region.
-<11> Specify the name of the existing subnets to which to deploy the compute machines. The subnets must belong to the VPC that you specified. Specify a subnet for each availability zone in the region.
-<12> How to publish the user-facing endpoints of your cluster. Set `publish` to `Internal` to deploy a private cluster. The default value is `External`.
+<8> The name of an existing resource group. All installer-provisioned cluster resources are deployed to this resource group. If undefined, a new resource group is created for the cluster.
+<9> Specify the name of the resource group that contains the existing virtual private cloud (VPC). The existing VPC and subnets should be in this resource group. The cluster will be installed to this VPC.
+<10> Specify the name of an existing VPC.
+<11> Specify the name of the existing subnets to which to deploy the control plane machines. The subnets must belong to the VPC that you specified. Specify a subnet for each availability zone in the region.
+<12> Specify the name of the existing subnets to which to deploy the compute machines. The subnets must belong to the VPC that you specified. Specify a subnet for each availability zone in the region.
+<13> How to publish the user-facing endpoints of your cluster. Set `publish` to `Internal` to deploy a private cluster. The default value is `External`.
 ifndef::openshift-origin[]
-<13> Enables or disables FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead.
+<14> Enables or disables FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead.
 +
 [IMPORTANT]
 ====
 The use of FIPS Validated or Modules in Process cryptographic libraries is only supported on {product-title} deployments on the `x86_64` architecture.
 ====
-<14> Optional: provide the `sshKey` value that you use to access the machines in your cluster.
+<15> Optional: provide the `sshKey` value that you use to access the machines in your cluster.
 endif::openshift-origin[]
 ifdef::openshift-origin[]
-<13> You can optionally provide the `sshKey` value that you use to access the machines in your cluster.
+<14> You can optionally provide the `sshKey` value that you use to access the machines in your cluster.
 endif::openshift-origin[]
 +
 [NOTE]