updating install drafts

Author: kalexand-rh

_topic_map.yml

@@ -64,6 +64,19 @@ Topics:
 - Name: Architecture
   File: architecture
 ---
+Name: Installing clusters
+Dir: installation
+Distros: openshift-origin, openshift-enterprise
+Topics:
+- Name: Configuring an AWS account
+  File: installing-aws-account
+- Name: Installing a cluster quickly on AWS
+  File: installing-quickly-cloud
+- Name: Installing a cluster on AWS with customizations
+  File: installing-customizations-cloud
+- Name: Uninstalling a cluster on AWS
+  File: uninstalling-cluster-aws  
+---
 Name: Authentication
 Dir: authentication
 Distros: openshift-*
@@ -127,15 +140,6 @@ Topics:
   File: creating-project-other-user
   Distros: openshift-enterprise,openshift-origin
 ---
-Name: Installing clusters
-Dir: installation
-Distros: openshift-origin, openshift-enterprise
-Topics:
-- Name: Installing a cluster quickly on AWS
-  File: installing-quickly-cloud
-- Name: Installing a cluster on AWS with customizations
-  File: installing-customizations-cloud
----
 Name: Networking
 Dir: networking
 Distros: openshift-*

installation/installing-aws-account.adoc

@@ -0,0 +1,22 @@
+[id='installing-aws-account']
+= Configuring an AWS account
+include::modules/common-attributes.adoc[]
+:context: installing-aws-account
+
+toc::[]
+
+Before you can install {product-title}, you must configure an
+Amazon Web Services (AWS) account.
+
+include::modules/installation-aws-route53.adoc[leveloffset=+1]
+
+include::modules/installation-aws-limits.adoc[leveloffset=+1]
+
+include::modules/installation-aws-iam-user.adoc[leveloffset=+1]
+
+.Next steps
+
+* Install a {product-title} cluster. You can
+xref:../installation/installing-customizations-cloud.adoc#installing-customizations-cloud[install a customized cluster]
+or xref:../installation/installing-quickly-cloud.adoc#installing-quickly-cloud[quickly install a cluster]
+with default options.

installation/installing-customizations-cloud.adoc

@@ -6,31 +6,38 @@ include::modules/common-attributes.adoc[]
 toc::[]
 
 
-In {product-title} version {product-version}, you can install a cluster on
-Amazon Web Services (AWS).
+In {product-title} version {product-version}, you can install a customized
+cluster on Amazon Web Services (AWS).
 
-This cluster is ...
+.Prerequisites
+
+* xref:../installation/installing-aws-account.adoc#installing-aws-account[Configure an AWS account]
+to host the cluster.
 
 include::modules/installation-overview.adoc[leveloffset=+1]
 
-include::modules/cloud_installations.adoc[leveloffset=+1]
+include::modules/installation-clouds.adoc[leveloffset=+1]
 
-include::modules/about-custom-installation.adoc[leveloffset=+1]
+include::modules/installation-about-custom.adoc[leveloffset=+1]
 
-include::modules/preparing-custom-installation.adoc[leveloffset=+1]
+include::modules/installation-preparing-custom.adoc[leveloffset=+1]
 
 include::modules/installation-configuration-parameters.adoc[leveloffset=+2]
 
 include::modules/installation-render-options.adoc[leveloffset=+2]
 
-include::modules/obtaining_cloud_installer.adoc[leveloffset=+1]
+include::modules/installation-provide-credentials.adoc[leveloffset=+1]
+
+include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
+
+include::modules/installation-initializing.adoc[leveloffset=+1]
 
-include::modules/initializing-installation.adoc[leveloffset=+1]
+include::modules/installation-rendering.adoc[leveloffset=+1]
 
-include::modules/rendering-installation.adoc[leveloffset=+1]
+include::modules/installation-customizing.adoc[leveloffset=+1]
 
-include::modules/customizing-installation.adoc[leveloffset=+1]
+include::modules/installation-preparing-assets.adoc[leveloffset=+1]
 
-include::modules/preparing-assets-installation.adoc[leveloffset=+1]
+include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
-include::modules/launching-installer.adoc[leveloffset=+1]
+include::modules/installing-customizations-cloud.adoc[leveloffset=+1]

installation/installing-quickly-cloud.adoc

@@ -7,14 +7,19 @@ toc::[]
 
 
 In {product-title} version {product-version}, you can install a cluster on
-Amazon Web Services (AWS).
+Amazon Web Services (AWS) that uses the default configuration options.
 
-This cluster is ...
+.Prerequisites
+
+* xref:../installation/installing-aws-account.adoc#installing-aws-account[Configure an AWS account]
+to host the cluster.
 
 include::modules/installation-overview.adoc[leveloffset=+1]
 
-include::modules/cloud_installations.adoc[leveloffset=+1]
+include::modules/installation-clouds.adoc[leveloffset=+1]
+
+include::modules/installation-provide-credentials.adoc[leveloffset=+1]
 
-include::modules/obtaining_cloud_installer.adoc[leveloffset=+1]
+include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
 
-include::modules/launching-installer.adoc[leveloffset=+1]
+include::modules/installation-launching-installer.adoc[leveloffset=+1]

installation/uninstalling-cluster-aws.adoc

@@ -0,0 +1,10 @@
+[id='uninstalling-cluster-aws']
+= Uninstalling a cluster on AWS
+include::modules/common-attributes.adoc[]
+:context: uninstall-cluster-aws
+
+toc::[]
+
+You can remove a cluster that you deployed to Amazon Web Services (AWS).
+
+include::modules/installation-uninstall-aws.adoc[leveloffset=+1]

mod_docs_guide/getting-started-modular-docs-ocp.adoc

@@ -23,7 +23,7 @@ initiative.
 * You have read through and familiarized yourself with the
 link:https://redhat-documentation.github.io/modular-docs[Red Hat CCS modular docs guide].
 * You have reviewed
-xref:../mod_docs_guide/mod-docs-coventions-ocp.adoc#mod-docs-ocp-references[the Modular Docs OpenShift Conventions].
+xref:../mod_docs_guide/mod-docs-conventions-ocp.adoc#mod-docs-ocp-references[the Modular Docs OpenShift Conventions].
 * [Optional] You have received the modular docs training.
 * You know how to use Git.
 

modules/about-custom-installation.adoc

@@ -0,0 +1,95 @@
+// Module included in the following assemblies:
+//
+// * installation/installing-customizations-cloud.adoc
+
+[id='installation-about-custom-{context}']
+= About the custom installation
+
+The custom installation is divided into four phases:
+
+* Initialization, where you create and customize the installation configuration
+file 
+* Rendering, where you provide YAML files that describe further customizations
+* Preparing, where the system creates assets based on the rendered data
+* Launching, where you create the cluster in your cloud.
+
+During initialization, you generate and customize a cluster configuration file that
+defines high level configuration and topology and specifies your cloud provider
+credentials. This configuration file contains a limited set of parameters that
+most clusters require.
+
+During rendering, you do a thing with a bunch of yaml files that allows you to
+provide more customization to your cluster. You can specify ...
+
+During the preparing phase, the assets that you render...
+
+Finally, you launch the installation. The installation program first creates the
+infrastructure for the cluster, such as the load balancers, security groups, and
+VPCs, and then creates an initial configuration on a bootstrap master node.
+The bootstrap master then completes the configuration of the cluster by 
+self-configuring and loading other components. By default, all the cluster nodes
+run Red Hat CoreOS as the operating system.
+
+After the installation and configuration process is complete, instructions for 
+connecting to the cluster displays.
+
+[discrete]
+== Key concepts
+
+Before you complete a customized installation, review the following key concepts.
+
+[discrete]
+=== Targets
+
+The {product-title} installer operates on the notion of creating and destroying
+targets. Similar to other tools that operate on a graph of dependencies, like
+`make` and `systemd`, each target represents a subset of the dependencies in the
+graph. The main target in the installation program creates a cluster, but the other targets
+allow the user to interrupt this process and use or modify the intermediate
+artifacts, such as the the Kubernetes manifests that are installed into the
+cluster. Only the immediate dependencies of a target are written to disk by the
+installer, but you can run the installation program multiple times to update more
+dependencies.
+
+The installation program can create the following targets:
+
+`install-config`::
+The installation configuration contains the main parameters
+for the installation process. This configuration provides you with more options
+than the interactive prompts and comes pre-populated with default values.
+`manifest-templates`:: These are the unrendered Kubernetes manifest templates
+that `manifests` target uses. This target is unstable.
+`manifests`::
+You can generate the Kubernetes manifests that will be installed on the cluster.
+This target is unstable.
+`ignition-configs`::
+These files contain the Ignition configurations for the bootstrap, master, and
+worker machines.
+`cluster`::
+This target provisions the cluster and its associated infrastructure.
+
+The following targets can be destroyed by the installation program:
+
+`cluster`::
+This destroys the created cluster and its associated infrastructure.
+`bootstrap`::
+This destroys the bootstrap infrastructure.
+
+[discrete]
+=== Multiple invocations
+
+Because you must run the installation program to generate the assets that you need to
+customize your installation, you can run the installation program multiple times. The
+installation state is stored in a hidden file in the asset directory which 
+contains all of the intermediate artifacts. Storing the artifacts in this way
+lets you pause installation and modify the intermediate artifacts.
+
+For example, if you wanted to create a different number of worker machines, you
+must first run the installation program with the `install-config` target with the
+`openshift-install create install-config` command. After you provide the required
+parameters to the interactive installer, it writes the installation
+configuration into the target directory. You can then modify the installation
+configuration and run the installation program with the `cluster` target with the
+`openshift-install create cluster` command. The installation program reads the install
+configuration from disk, removes it from the target directory, and creates a
+cluster from the provided configuration.

modules/installation-about-custom.adoc

@@ -0,0 +1,33 @@
+// Module included in the following assemblies:
+//
+// * installation/installing-aws-account.adoc
+
+[id='installation-aws-iam-user-{context}']
+= Creating an IAM user
+
+Each Amazon Web Services (AWS) account contains a root user account that is
+based on the email address you used to create the account. This is a
+highly-privileged account, and it is recommended to use it for only initial
+account and billing configuration, creating an initial set of users, and
+securing the account.
+
+Before you install {product-title}, create a secondary IAM
+administrative user. As you complete the 
+link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[Creating an IAM User in Your AWS Account]
+procedure in the the AWS documentation, set the following options:
+
+.Procedure
+
+. Specify the IAM user name and select `Programmatic access`.
+
+. Attach the `AdministratorAccess` policy to ensure that the account has
+sufficient permission to create the cluster.
+
+. Optionally, add metadata to the user by attaching tags.
+
+. Confirm that the user name that you specified is granted the
+`AdministratorAccess` policy.
+
+. Record the access key ID and secret access key values. You must use these
+values when you configure your local machine to run the installation program, and this is
+the only time that you can obtain them.