Merge pull request #35550 from mjpytlak/osdocs2443

OSDOCS-2443: Adding support for installing a cluster to AWS China regions

Author: kalexand-rh

_topic_map.yml

@@ -156,6 +156,8 @@ Topics:
     File: installing-aws-private
   - Name: Installing a cluster on AWS into a government or secret region
     File: installing-aws-government-region
+  - Name: Installing a cluster on AWS into a China region
+    File: installing-aws-china
   - Name: Installing a cluster on AWS using CloudFormation templates
     File: installing-aws-user-infra
   - Name: Installing a cluster on AWS in a restricted network with user-provisioned infrastructure

installing/installing_aws/installing-aws-china.adoc

@@ -0,0 +1,68 @@
+[id="installing-aws-china-region"]
+= Installing a cluster on AWS China
+include::modules/common-attributes.adoc[]
+:context: installing-aws-china-region
+
+toc::[]
+
+In {product-title} version {product-version}, you can install a cluster to the following Amazon Web Services (AWS) China regions:
+
+* `cn-north-1` (Beijing)
+* `cn-northwest-1` (Ningxia)
+
+== Prerequisites
+
+* You have an Internet Content Provider (ICP) license.
+* 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].
+* You xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[configured an AWS account] to host the cluster.
+* 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_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually create and maintain IAM credentials].
+
+[IMPORTANT]
+====
+If you have an AWS profile stored on your computer, it must not use a temporary session token that you generated while using a multi-factor authentication device. The cluster continues to use your current AWS credentials to create AWS resources for the entire life of the cluster, so you must use long-lived credentials. To generate appropriate keys, see link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html[Managing Access Keys for IAM Users] in the AWS documentation. You can supply the keys when you run the installation program.
+====
+
+include::modules/installation-aws-regions-with-no-ami.adoc[leveloffset=+1]
+
+include::modules/cluster-entitlements.adoc[leveloffset=+1]
+
+include::modules/private-clusters-default.adoc[leveloffset=+1]
+include::modules/private-clusters-about-aws.adoc[leveloffset=+2]
+
+include::modules/installation-custom-aws-vpc.adoc[leveloffset=+1]
+
+include::modules/ssh-agent-using.adoc[leveloffset=+1]
+
+include::modules/installation-aws-upload-custom-rhcos-ami.adoc[leveloffset=+1]
+
+include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
+
+include::modules/installation-initializing-manual.adoc[leveloffset=+1]
+include::modules/installation-configuration-parameters.adoc[leveloffset=+2]
+include::modules/installation-aws-config-yaml.adoc[leveloffset=+2]
+include::modules/installation-supported-aws-machine-types.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/logging-in-by-using-the-web-console.adoc[leveloffset=+1]
+
+include::modules/cluster-telemetry.adoc[leveloffset=+1]
+
+.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.
+* 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.
+
+== Next steps
+
+* xref:../../installing/validating-an-installation.adoc#validating-an-installation[Validating an installation].
+* 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].
+* If necessary, you can xref:../../authentication/managing_cloud_provider_credentials/cco-mode-mint.adoc#manually-removing-cloud-creds_cco-mode-mint[remove cloud provider credentials].

installing/installing_aws/installing-aws-government-region.adoc

@@ -24,6 +24,7 @@ If you have an AWS profile stored on your computer, it must not use a temporary
 * 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_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually create and maintain IAM credentials].
 
 include::modules/installation-aws-about-government-region.adoc[leveloffset=+1]
+include::modules/installation-aws-regions-with-no-ami.adoc[leveloffset=+1]
 
 include::modules/private-clusters-default.adoc[leveloffset=+1]
 include::modules/private-clusters-about-aws.adoc[leveloffset=+2]
@@ -34,14 +35,15 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/ssh-agent-using.adoc[leveloffset=+1]
 
+include::modules/installation-aws-upload-custom-rhcos-ami.adoc[leveloffset=+1]
+
 include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
 
 include::modules/installation-initializing-manual.adoc[leveloffset=+1]
 include::modules/installation-configuration-parameters.adoc[leveloffset=+2]
 include::modules/installation-supported-aws-machine-types.adoc[leveloffset=+2]
 include::modules/installation-aws-config-yaml.adoc[leveloffset=+2]
-include::modules/installation-aws-regions-with-no-ami.adoc[leveloffset=+2]
-include::modules/installation-aws-upload-custom-rhcos-ami.adoc[leveloffset=+2]
+
 include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 
 include::modules/installation-launching-installer.adoc[leveloffset=+1]

modules/cli-installing-cli.adoc

@@ -4,6 +4,7 @@
 // * installing/installing_aws/installing-aws-user-infra.adoc
 // * installing/installing_aws/installing-aws-customizations.adoc
 // * installing/installing_aws/installing-aws-default.adoc
+// * installing/installing_aws/installing-aws-china.adoc
 // * installing/installing_aws/installing-aws-government-region.adoc
 // * installing/installing_aws/installing-aws-network-customizations.adoc
 // * installing/installing_aws/installing-aws-private.adoc

modules/cli-logging-in-kubeadmin.adoc

@@ -3,6 +3,7 @@
 // * installing/installing_aws/installing-aws-user-infra.adoc
 // * installing/installing_aws/installing-aws-customizations.adoc
 // * installing/installing_aws/installing-aws-default.adoc
+// * installing/installing_aws/installing-aws-china.adoc
 // * installing/installing_aws/installing-aws-government-region.adoc
 // * installing/installing_aws/installing-aws-network-customizations.adoc
 // * installing/installing_aws/installing-aws-private.adoc

modules/cluster-entitlements.adoc

@@ -35,6 +35,7 @@
 // * installing/installing_aws/installing-aws-default.adoc
 // * installing/installing_aws/installing-aws-vpc.adoc
 // * installing/installing_aws/installing-aws-government-region.adoc
+// * installing/installing_aws/installing-aws-china-region.adoc
 // * installing/installing_openstack/installing-openstack-installer-kuryr.adoc
 // * installing/installing_openstack/installing-openstack-installer-restricted.adoc
 // * installing/installing_openstack/installing-openstack-user.adoc
@@ -130,7 +131,7 @@ ifdef::openshift-enterprise,openshift-webscale[]
 
 [IMPORTANT]
 ====
-If your cluster cannot have direct internet access, you can perform a restricted network installation on some types of infrastructure that you provision. During that process, you download the content that is required and use it to populate a mirror registry with the packages that you need to install a cluster and generate the installation program. With some installation types, the environment that you install your cluster in will not require internet access. Before you update the cluster, you update the content of the mirror registry.
+If your cluster cannot have direct internet access, you can perform a restricted network installation on some types of infrastructure that you provision. During that process, you download the required content and use it to populate a mirror registry with the installation packages. With some installation types, the environment that you install your cluster in will not require internet access. Before you update the cluster, you update the content of the mirror registry.
 ====
 
 endif::openshift-enterprise,openshift-webscale[]

modules/cluster-telemetry.adoc

@@ -35,6 +35,7 @@
 // * installing/installing_aws/installing-aws-default.adoc
 // * installing/installing_aws/installing-aws-vpc.adoc
 // * installing/installing_aws/installing-aws-government-region.adoc
+// * installing/installing_aws/installing-aws-china.adoc
 // * installing/installing_openstack/installing-openstack-installer-kuryr.adoc
 // * installing/installing_openstack/installing-openstack-installer-restricted.adoc
 // * installing/installing_openstack/installing-openstack-user.adoc

modules/installation-aws-about-government-region.adoc

@@ -21,12 +21,3 @@ The following AWS GovCloud partitions are supported:
 The following AWS Secret Region partition is supported:
 
 * `us-iso-east-1`
-
-The AWS government or secret region, and accompanying custom AMI, must be manually configured in the
-`install-config.yaml` file since {op-system} AMIs are not provided by Red Hat
-for those regions.
-
-[IMPORTANT]
-====
-If you are deploying to the C2S Secret Region, you must also define a custom CA certificate in the `additionalTrustBundle` field of the `install-config.yaml` file because the AWS API requires a custom CA trust bundle. To allow the installation program to access the AWS API, the CA certificates must also be defined on the machine that runs the installation program. You must add the CA bundle to the trust store on the machine, use the `AWS_CA_BUNDLE` environment variable, or define the CA bundle in the link:https://docs.aws.amazon.com/credref/latest/refdocs/setting-global-ca_bundle.html[`ca_bundle`] field of the AWS config file.
-====

modules/installation-aws-config-yaml.adoc

@@ -25,22 +25,36 @@ ifeval::["{context}" == "installing-aws-government-region"]
 :private:
 :gov:
 endif::[]
+ifeval::["{context}" == "installing-aws-china-region"]
+:vpc:
+:private:
+:china:
+endif::[]
 ifeval::["{context}" == "installing-restricted-networks-aws-installer-provisioned"]
 :restricted:
 endif::[]
 
 [id="installation-aws-config-yaml_{context}"]
 = Sample customized `install-config.yaml` file for AWS
 
-You can customize the `install-config.yaml` file to specify more details about
+You can customize the installation configuration file (`install-config.yaml`) to specify more details about
 your {product-title} cluster's platform or modify the values of the required
 parameters.
 
+ifndef::china,gov[]
 [IMPORTANT]
 ====
 This sample YAML file is provided for reference only. You must obtain your
 `install-config.yaml` file by using the installation program and modify it.
 ====
+endif::china,gov[]
+
+ifdef::china,gov[]
+[IMPORTANT]
+====
+This sample YAML file is provided for reference only. Use it as a resource to enter parameter values into the installation configuration file that you created manually.
+====
+endif::china,gov[]
 
 [source,yaml]
 ----
@@ -53,14 +67,18 @@ controlPlane: <3> <4>
   platform:
     aws:
       zones:
+ifdef::china[]
+      - cn-north-1a
+      - cn-north-1b
+endif::china[]
 ifdef::gov[]
       - us-gov-west-1a
       - us-gov-west-1b
 endif::gov[]
-ifndef::gov[]
+ifndef::gov,china[]
       - us-west-2a
       - us-west-2b
-endif::gov[]
+endif::gov,china[]
       rootVolume:
         iops: 4000
         size: 500
@@ -78,12 +96,15 @@ compute: <3>
         type: io1 <6>
       type: c5.4xlarge
       zones:
+ifdef::china[]
+      - cn-north-1a
+endif::china[]
 ifdef::gov[]
       - us-gov-west-1c
 endif::gov[]
-ifndef::gov[]
+ifndef::gov,china[]
       - us-west-2c
-endif::gov[]
+endif::gov,china[]
   replicas: 3
 metadata:
   name: test-cluster <1>
@@ -108,11 +129,14 @@ endif::openshift-origin[]
   - 172.30.0.0/16
 platform:
   aws:
-ifndef::gov[]
+ifndef::gov,china[]
     region: us-west-2 <1>
-endif::gov[]
+endif::gov,china[]
+ifdef::china[]
+    region: cn-north-1 <1>
+endif::china[]
 ifdef::gov[]
-    region: us-gov-west-1
+    region: us-gov-west-1 <1>
 endif::gov[]
     userTags:
       adminContact: jdoe
@@ -122,10 +146,20 @@ ifdef::vpc,restricted[]
     - subnet-1
     - subnet-2
     - subnet-3
+ifndef::gov,china[]
     amiID: ami-96c6f8f7 <8>
+endif::gov,china[]
+ifdef::gov,china[]
+    amiID: ami-96c6f8f7 <1> <8>
+endif::gov,china[]
     serviceEndpoints: <9>
       - name: ec2
+ifndef::china[]
         url: https://vpce-id.ec2.us-west-2.vpce.amazonaws.com
+endif::china[]
+ifdef::china[]
+        url: https://vpce-id.ec2.cn-north-1.vpce.amazonaws.com.cn
+endif::china[]
     hostedZone: Z3URY6TWQ91KVV <10>
 endif::vpc,restricted[]
 ifndef::vpc,restricted[]
@@ -220,12 +254,12 @@ endif::restricted[]
 
 
 ----
-ifndef::gov[]
+ifndef::gov,china[]
 <1> Required. The installation program prompts you for this value.
-endif::gov[]
-ifdef::gov[]
+endif::gov,china[]
+ifdef::gov,china[]
 <1> Required.
-endif::gov[]
+endif::gov,china[]
 <2> Optional: Add this parameter to force the Cloud Credential Operator (CCO) to use the specified mode, instead of having the CCO dynamically try to determine the capabilities of the credentials. For details about CCO modes, see the _Cloud Credential Operator_ entry in the _Red Hat Operators reference_ content.
 <3> If you do not provide these parameters and values, the installation program
 provides the default value.
@@ -354,6 +388,11 @@ ifeval::["{context}" == "installing-aws-government-region"]
 :!private:
 :!gov:
 endif::[]
+ifeval::["{context}" == "installing-aws-china-region"]
+:!vpc:
+:!private:
+:!china:
+endif::[]
 ifeval::["{context}" == "installing-restricted-networks-aws-installer-provisioned"]
 :!restricted:
 endif::[]

modules/installation-aws-regions-with-no-ami.adoc

@@ -1,17 +1,31 @@
 // Module included in the following assemblies:
 //
+// * installing/installing_aws/installing-aws-china.adoc
 // * installing/installing_aws/installing-aws-government-region.adoc
 // * installing/installing_aws/installing-aws-user-infra.adoc
 
+ifeval::["{context}" == "installing-aws-china-region"]
+:aws-china:
+endif::[]
+ifeval::["{context}" == "installing-aws-government-region"]
+:aws-gov:
+endif::[]
+
 [id="installation-aws-regions-with-no-ami_{context}"]
+ifndef::aws-china,aws-gov[]
 = AWS regions without a published {op-system} AMI
+endif::aws-china,aws-gov[]
+
+ifdef::aws-china,aws-gov[]
+= Installation requirments
+endif::aws-china,aws-gov[]
 
+ifndef::aws-china,aws-gov[]
 You can deploy an {product-title} cluster to Amazon Web Services (AWS) regions
 without native support for a {op-system-first} Amazon Machine Image (AMI) or the
 AWS software development kit (SDK). If a
 published AMI is not available for an AWS region, you can upload a custom AMI
-prior to installing the cluster. This is required if you are deploying your
-cluster to an AWS government or secret region. AWS government and secret regions are supported by the AWS SDK.
+prior to installing the cluster.
 
 If you are deploying to a region not supported by the AWS SDK
 and you do not specify a custom AMI, the installation program
@@ -25,3 +39,32 @@ A region without native support for an {op-system} AMI is not available to
 select from the terminal during cluster creation because it is not published.
 However, you can install to this region by configuring the custom AMI in the
 `install-config.yaml` file.
+endif::aws-china,aws-gov[]
+
+ifdef::aws-china,aws-gov[]
+ifdef::aws-china[Red Hat does not publish a {op-system-first} Amazon Machine Image (AMI) for the AWS China regions.]
+ifdef::aws-gov[Red Hat does not publish a {op-system-first} Amzaon Machine Image for the AWS government or secret regions.]
+
+Before you can install the cluster, you must:
+
+* Upload a custom {op-system} AMI.
+* Manually create the installation configuration file (`install-config.yaml`).
+* Specify the AWS region, and the accompanying custom AMI, in the installation configuration file.
+
+You cannot use the {product-title} installation program to create the installation configuration file. The installer does not list an AWS region without native support for an {op-system} AMI.
+
+ifdef::aws-gov[]
+[IMPORTANT]
+====
+If you are deploying to the C2S Secret Region, you must also define a custom CA certificate in the `additionalTrustBundle` field of the `install-config.yaml` file because the AWS API requires a custom CA trust bundle. To allow the installation program to access the AWS API, the CA certificates must also be defined on the machine that runs the installation program. You must add the CA bundle to the trust store on the machine, use the `AWS_CA_BUNDLE` environment variable, or define the CA bundle in the link:https://docs.aws.amazon.com/credref/latest/refdocs/setting-global-ca_bundle.html[`ca_bundle`] field of the AWS config file.
+====
+endif::aws-gov[]
+
+endif::aws-china,aws-gov[]
+
+ifeval::["{context}" == "installing-aws-china-region"]
+:!aws-china:
+endif::[]
+ifeval::["{context}" == "installing-aws-government-region"]
+:!aws-gov:
+endif::[]