OSDOCS-15031 Creating AWS specialized regions assembly

_topic_maps/_topic_map.yml

@@ -216,6 +216,8 @@ Topics:
       File: installing-aws-vpc
     - Name: Installing a private cluster
       File: installing-aws-private
+    - Name: Installing a cluster in a specialized region
+      File: installing-aws-specialized-region
     - Name: Installing a cluster into a government region
       File: installing-aws-government-region
     - Name: Installing a cluster into a Secret or Top Secret Region

installing/installing_aws/ipi/installing-aws-specialized-region.adoc

@@ -0,0 +1,161 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="installing-aws-specialized-region"]
+= Installing a cluster on AWS into a specialized region
+include::_attributes/common-attributes.adoc[]
+:context: installing-aws-specialized-region
+
+toc::[]
+
+In {product-title} version {product-version}, you can install a cluster on
+{aws-first} into specialized regions, including secret and top secret regions,
+government regions, and China regions. To configure the region, modify parameters in the `install-config.yaml` file before you install the cluster.
+
+The following specialized regions are supported:
+
+.Specialized regions
+|====
+|Region type|Supported regions
+
+|China
+a|
+* `cn-north-1` (Beijing)
+* `cn-northwest-1` (Ningxia)
+
+|Secret and Top Secret
+a|
+* `us-isob-east-1` (SC2S)
+* `us-iso-east-1` (C2S)
+
+|Government
+a|
+* `us-gov-east-1`
+* `us-gov-west-1`
+
+|====
+
+[WARNING]
+====
+In {product-title} {product-version}, the installation program uses Cluster API instead of Terraform to provision cluster infrastructure during installations on AWS. Installing a cluster on AWS into a secret or top-secret region by using the Cluster API implementation has not been tested as of the release of {product-title} {product-version}. This document will be updated when installation into a secret region has been tested.
+
+There is a known issue with Network Load Balancers' support for security groups in secret or top secret regions that causes installations in these regions to fail. For more information, see link:https://issues.redhat.com/browse/OCPBUGS-33311[OCPBUGS-33311].
+
+The maximum supported MTU in the AWS SC2S and C2S regions is not the same as
+the public regions. For more information about configuring MTU during installation,
+see the _Cluster Network Operator configuration object_ section in _Installing
+a cluster on AWS with network customizations_
+====
+
+== Prerequisites
+
+* If you install a cluster into a China region, 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/overview/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.
+
+[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-term 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-about-government-region.adoc[leveloffset=+1]
+include::modules/installation-aws-marketplace-government.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../../installing/installing_aws/installation-config-parameters-aws.adoc#installation-config-parameters-aws[Installation configuration parameters for AWS]
+
+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]
+
+include::modules/installation-custom-aws-vpc.adoc[leveloffset=+1]
+include::modules/installation-aws-security-groups.adoc[leveloffset=+2]
+
+include::modules/installation-aws-upload-custom-rhcos-ami.adoc[leveloffset=+1]
+
+include::modules/installation-initializing-manual.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../../installing/installing_aws/installation-config-parameters-aws.adoc#installation-config-parameters-aws[Installation configuration parameters for AWS]
+
+include::modules/installation-aws-config-yaml-customizations.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../../installing/installing_aws/installation-config-parameters-aws.adoc#installation-config-parameters-aws[Installation configuration parameters for AWS]
+
+include::modules/installation-minimum-resource-requirements.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../../scalability_and_performance/optimization/optimizing-storage.adoc#optimizing-storage[Optimizing storage]
+
+include::modules/installation-aws-tested-machine-types.adoc[leveloffset=+2]
+include::modules/installation-aws-arm-tested-machine-types.adoc[leveloffset=+2]
+
+include::modules/installation-configure-proxy.adoc[leveloffset=+2]
+
+include::modules/installation-applying-aws-security-groups.adoc[leveloffset=+2]
+
+[id="installing-aws-manual-modes_{context}"]
+== Alternatives to storing administrator-level secrets in the kube-system project
+
+By default, administrator secrets are stored in the `kube-system` project. If you configured the `credentialsMode` parameter in the `install-config.yaml` file to `Manual`, you must use one of the following alternatives:
+
+* To manage long-term cloud credentials manually, follow the procedure in xref:../../../installing/installing_aws/ipi/installing-aws-china.adoc#manually-create-iam_installing-aws-china-region[Manually creating long-term credentials].
+
+* To implement short-term credentials that are managed outside the cluster for individual components, follow the procedures in xref:../../../installing/installing_aws/ipi/installing-aws-china.adoc#installing-aws-with-short-term-creds_installing-aws-china-region[Configuring an AWS cluster to use short-term credentials].
+
+//Manually creating long-term credentials
+include::modules/manually-create-identity-access-management.adoc[leveloffset=+2]
+
+//Supertask: Configuring an AWS cluster to use short-term credentials
+[id="installing-aws-with-short-term-creds_{context}"]
+=== Configuring an AWS cluster to use short-term credentials
+
+To install a cluster that is configured to use the AWS Security Token Service (STS), you must configure the CCO utility and create the required AWS resources for your cluster.
+
+//Task part 1: Configuring the Cloud Credential Operator utility
+include::modules/cco-ccoctl-configuring.adoc[leveloffset=+3]
+
+//Task part 2: Creating the required AWS resources
+[id="sts-mode-create-aws-resources-ccoctl_{context}"]
+==== Creating AWS resources with the Cloud Credential Operator utility
+
+You have the following options when creating AWS resources:
+
+* You can use the `ccoctl aws create-all` command to create the AWS resources automatically. This is the quickest way to create the resources. See xref:../../../installing/installing_aws/ipi/installing-aws-china.adoc#cco-ccoctl-creating-at-once_installing-aws-china-region[Creating AWS resources with a single command].
+
+* If you need to review the JSON files that the `ccoctl` tool creates before modifying AWS resources, or if the process the `ccoctl` tool uses to create AWS resources automatically does not meet the requirements of your organization, you can create the AWS resources individually. See xref:../../../installing/installing_aws/ipi/installing-aws-china.adoc#cco-ccoctl-creating-individually_installing-aws-china-region[Creating AWS resources individually].
+
+//Task part 2a: Creating the required AWS resources all at once
+include::modules/cco-ccoctl-creating-at-once.adoc[leveloffset=+4]
+
+//Task part 2b: Creating the required AWS resources individually
+include::modules/cco-ccoctl-creating-individually.adoc[leveloffset=+4]
+
+//Task part 3: Incorporating the Cloud Credential Operator utility manifests
+include::modules/cco-ccoctl-install-creating-manifests.adoc[leveloffset=+3]
+
+include::modules/installation-launching-installer.adoc[leveloffset=+1]
+
+include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
+
+include::modules/logging-in-by-using-the-web-console.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.
+
+== Next steps
+
+* xref:../../../installing/validation_and_troubleshooting/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:../../../post_installation_configuration/changing-cloud-credentials-configuration.adoc#manually-removing-cloud-creds_changing-cloud-credentials-configuration[remove cloud provider credentials].

modules/installation-aws-marketplace-government.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/installing-aws-specialized-regions.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="installation-aws-marketplace-government_{context}"]
+= Installation requirements for government regions
+If you are deploying an {product-title} cluster using an AWS Marketplace image in a government region, you must first subscribe through {aws-short}. Subscribing to the offer provides you with the AMI ID that the installation program uses to deploy compute nodes.
+
+:platform-abbreviation: an AWS
+:platform-abbreviation-short: AWS
+[NOTE]
+====
+include::snippets/installation-marketplace-note.adoc[]
+====
+
+.Prerequisites
+
+* You have an {aws-short} account to purchase the offer. This account does not have to be the same account that is used to install the cluster.
+
+.Procedure
+
+. Complete the {product-title} subscription from the link:https://aws.amazon.com/marketplace/fulfillment?productId=59ead7de-2540-4653-a8b0-fa7926d5c845[AWS Marketplace].
+
+. Record the AMI ID for your specific AWS Region. As part of the installation process, you must update the `install-config.yaml` file with this value before deploying the cluster.

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

@@ -1,26 +1,22 @@
 // Module included in the following assemblies:
 //
-// * installing/installing_aws/installing-aws-china.adoc
 // * installing/installing_aws/installing-aws-user-infra.adoc
-// * installing/installing_aws/installing-aws-secret-region.adoc
+// * installing/installing_aws/installing-aws-specialized-region.adoc
 
-ifeval::["{context}" == "installing-aws-china-region"]
-:aws-china:
-endif::[]
-ifeval::["{context}" == "installing-aws-secret-region"]
-:aws-secret:
+ifeval::["{context}" == "installing-aws-specialized-region"]
+:specialized:
 endif::[]
 
 [id="installation-aws-regions-with-no-ami_{context}"]
-ifndef::aws-china,aws-secret[]
+ifndef::specialized[]
 = AWS regions without a published {op-system} AMI
-endif::aws-china,aws-secret[]
+endif::specialized[]
 
-ifdef::aws-china,aws-secret[]
-= Installation requirements
-endif::aws-china,aws-secret[]
+ifdef::specialized[]
+= Installation requirements for China, Secret, and Top Secret regions
+endif::specialized[]
 
-ifndef::aws-china,aws-secret[]
+ifndef::specialized[]
 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
@@ -39,32 +35,26 @@ 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-secret[]
+endif::specialized[]
 
-ifdef::aws-china,aws-secret[]
-ifdef::aws-china[Red Hat does not publish a {op-system-first} Amazon Machine Image (AMI) for the AWS China regions.]
-ifdef::aws-secret[Red Hat does not publish a {op-system-first} Amzaon Machine Image for the AWS Secret and Top Secret Regions.]
+ifdef::specialized[]
+Red Hat does not publish a {op-system-first} Amazon Machine Image (AMI) for the AWS China, Secret, or Top Secret regions.
 
-Before you can install the cluster, you must:
+Before you can install a cluster into one of these regions, 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-secret[]
 [IMPORTANT]
 ====
-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.
+If you install a cluster into a Secret or Top 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-secret[]
 
-endif::aws-china,aws-secret[]
+endif::specialized[]
 
-ifeval::["{context}" == "installing-aws-china-region"]
-:!aws-china:
-endif::[]
-ifeval::["{context}" == "installing-aws-secret-region"]
-:!aws-secret:
-endif::[]
+ifeval::["{context}" == "installing-aws-specialized-region"]
+:!specialized:
+endif::[]

modules/installation-launching-installer.adoc

@@ -6,6 +6,7 @@
 // * installing/installing_aws/installing-aws-network-customizations.adoc
 // * installing/installing_aws/installing-aws-private.adoc
 // * installing/installing_aws/installing-aws-vpc.adoc
+// * installing/installing_aws/installing-aws-specialized-region.adoc
 // * installing/installing-aws-localzone.adoc
 // * installing/installing-aws-wavelength-zone.adoc
 // * installing/installing_aws/installing-restricted-networks-aws-installer-provisioned.adoc
@@ -62,6 +63,10 @@ ifeval::["{context}" == "installing-aws-government-region"]
 :custom-config:
 :aws:
 endif::[]
+ifeval::["{context}" == "installing-aws-specialized-region"]
+:custom-config:
+:aws:
+endif::[]
 ifeval::["{context}" == "installing-aws-secret-region"]
 :custom-config:
 :aws:
@@ -555,6 +560,10 @@ ifeval::["{context}" == "installing-aws-secret-region"]
 :!custom-config:
 :!aws:
 endif::[]
+ifeval::["{context}" == "installing-aws-specialized-region"]
+:!custom-config:
+:!aws:
+endif::[]
 ifeval::["{context}" == "installing-aws-network-customizations"]
 :!custom-config:
 :!aws:

modules/private-clusters-default.adoc

@@ -1,9 +1,6 @@
 // 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-private.adoc
-// * installing/installing_aws/installing-aws-secret-region.adoc
 // * installing/installing_gcp/installing-gcp-private.adoc
 // * installing/installing_azure/installing-azure-government-region.adoc
 // * installing/installing_azure/installing-azure-private.adoc
@@ -12,16 +9,8 @@
 [id="private-clusters-default_{context}"]
 = Private clusters
 
-ifeval::["{context}" == "installing-aws-government-region"]
-:aws-gov:
-endif::[]
-
-ifeval::["{context}" == "installing-aws-china-region"]
-:aws-china:
-endif::[]
-
-ifeval::["{context}" == "installing-aws-secret-region"]
-:aws-secret:
+ifeval::["{context}" == "installing-aws-specialized-region"]
+:aws-specialized:
 endif::[]
 
 ifeval::["{context}" == "installing-ibm-cloud-private"]
@@ -34,21 +23,13 @@ endif::[]
 
 You can deploy a private {product-title} cluster that does not expose external endpoints. Private clusters are accessible from only an internal network and are not visible to the internet.
 
-ifdef::aws-gov[]
+ifdef::aws-specialized[]
 [NOTE]
 ====
-Public zones are not supported in Route 53 in an AWS GovCloud Region. Therefore, clusters
-must be private if they are deployed to an AWS GovCloud Region.
+Public zones are not supported in Route 53 in {aws-short} Government, Secret, and Top Secret regions. Therefore, clusters must be private if they are deployed to one of these regions.
 ====
-endif::aws-gov[]
+endif::aws-specialized[]
 
-ifdef::aws-secret[]
-[NOTE]
-====
-Public zones are not supported in Route 53 in an AWS Top Secret Region. Therefore, clusters
-must be private if they are deployed to an AWS Top Secret Region.
-====
-endif::aws-secret[]
 By default, {product-title} is provisioned to use publicly-accessible DNS and endpoints. A private cluster sets the DNS, Ingress Controller, and API server to private when you deploy your cluster. This means that the cluster resources are only accessible from your internal network and are not visible to the internet.
 
 include::snippets/snip-private-clusters-public-ingress.adoc[]
@@ -69,32 +50,17 @@ endif::ibm-cloud-private,ibm-power-vs-private[]
 ** The hosts on the network that you provision.
 ** The internet to obtain installation media.
 
-ifndef::aws-china[]
-You can use any machine that meets these access requirements and follows your company's guidelines. For example, this machine can be a bastion host on your cloud network or a machine that has access to the network through a VPN.
-endif::aws-china[]
-
-ifdef::aws-china[]
+ifndef::aws-specialized[]
 You can use any machine that meets these access requirements and follows your company's guidelines. For example, this machine can be a bastion host on your cloud network.
-endif::aws-china[]
 
-ifdef::aws-china[]
 [NOTE]
 ====
 AWS China does not support a VPN connection between the VPC and your network. For more information about the Amazon VPC service in the Beijing and Ningxia regions, see link:https://docs.amazonaws.cn/en_us/aws/latest/userguide/vpc.html[Amazon Virtual Private Cloud] in the AWS China documentation.
-
 ====
-endif::aws-china[]
-
-ifeval::["{context}" == "installing-aws-government-region"]
-:!aws-gov:
-endif::[]
-
-ifeval::["{context}" == "installing-aws-china-region"]
-:!aws-china:
-endif::[]
+endif::aws-specialized[]
 
-ifeval::["{context}" == "installing-aws-secret-region"]
-:!aws-secret:
+ifeval::["{context}" == "installing-aws-specialized-region"]
+:!aws-specialized:
 endif::[]
 
 ifeval::["{context}" == "installing-ibm-cloud-private"]