diff --git a/_topic_map.yml b/_topic_map.yml index 4bb6c1625c85..6a9019a0fcf6 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -37,3 +37,14 @@ Topics: File: getting-started-modular-docs-ocp - Name: OpenShift CCS Modular Docs Conventions File: mod-docs-conventions-ocp +--- +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: Installing a cluster on existing hosts + File: installing-existing-hosts diff --git a/installation/installing-customizations-cloud.adoc b/installation/installing-customizations-cloud.adoc new file mode 100644 index 000000000000..11e6fa7707c5 --- /dev/null +++ b/installation/installing-customizations-cloud.adoc @@ -0,0 +1,46 @@ +// This assembly is included in the following assemblies: +// +// * n/a + + +[id='installing-customizations-cloud'] += Installing a cluster on AWS with customizations +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: +:context: install-customizations-cloud + +toc::[] + + +In {product-title} version {product-version}, you can install a cluster on +Amazon Web Services (AWS). + +This cluster is ... + +include::modules/cloud_installations.adoc[leveloffset=+1] + +include::modules/about-custom-installation.adoc[leveloffset=+1] + +include::modules/preparing-custom-installation.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/initializing-installation.adoc[leveloffset=+1] + +include::modules/rendering-installation.adoc[leveloffset=+1] + +include::modules/customizing-installation.adoc[leveloffset=+1] + +include::modules/preparing-assets-installation.adoc[leveloffset=+1] + +include::modules/launching-installer.adoc[leveloffset=+1] diff --git a/installation/installing-existing-hosts.adoc b/installation/installing-existing-hosts.adoc new file mode 100644 index 000000000000..04ca3154be08 --- /dev/null +++ b/installation/installing-existing-hosts.adoc @@ -0,0 +1,36 @@ +// This assembly is included in the following assemblies: +// +// * n/a + + +[id='installing-existing-hosts'] += Installing a cluster on existing hosts +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macros +:toc-title: +:prewrap!: +:context: install-existing-hosts + +toc::[] + + +You can install {product-title} version {product-version} on existing Red Hat +Enterprise Linux (RHEL) hosts. + +You run an Ansible-based installer to establish the cluster on your hosts. + +Use this option if you: + +* Already have your own mechanisms for building and provisioning machines that +run RHEL +* Have your own infrastructure provisioning +* Are upgrading your {product-title} cluster +* Are willing to give up upgrade automation and the cluster’s default +self-management of nodes in exchange for more flexibility + + +*TBD* diff --git a/installation/installing-quickly-cloud.adoc b/installation/installing-quickly-cloud.adoc new file mode 100644 index 000000000000..92334f596354 --- /dev/null +++ b/installation/installing-quickly-cloud.adoc @@ -0,0 +1,30 @@ +// This assembly is included in the following assemblies: +// +// * n/a + + +[id='installing-quickly-cloud'] += Installing a cluster quickly on AWS +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: +:context: installing-quickly-cloud + +toc::[] + + +In {product-title} version {product-version}, you can install a cluster on +Amazon Web Services (AWS). + +This cluster is ... + +include::modules/cloud_installations.adoc[leveloffset=+1] + +include::modules/obtaining_cloud_installer.adoc[leveloffset=+1] + +include::modules/launching-installer.adoc[leveloffset=+1] diff --git a/modules/about-custom-installation.adoc b/modules/about-custom-installation.adoc new file mode 100644 index 000000000000..8691f7c977eb --- /dev/null +++ b/modules/about-custom-installation.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * installation/installing-customizations-cloud.adoc + +[id='about-custom-installation-{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 installer 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. diff --git a/modules/cloud_installations.adoc b/modules/cloud_installations.adoc new file mode 100644 index 000000000000..35c92af446ff --- /dev/null +++ b/modules/cloud_installations.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * installation/installing-quickly-cloud.adoc +// * installation/installing-customizations-cloud.adoc + +[id='concept-explanation-{context}'] += {product-title} clusters on clouds + +[IMPORTANT] +==== +In version {product-version}, you can install {product-title} on only Amazon +Web Services (AWS) or your own hosts. +==== + +You can install either a standard cluster or a customized cluster. With a +standard cluster, you specify the minimum number of details to establish the +cluster. These details include ... + +With a customized cluster, you can specify more details of the installation, +such as ... + +[IMPORTANT] +==== +You cannot modify the parameters that you set during installation. You have to +... +==== diff --git a/modules/customizing-installation.adoc b/modules/customizing-installation.adoc new file mode 100644 index 000000000000..54dacffbd3d8 --- /dev/null +++ b/modules/customizing-installation.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * installation/installing-customizations-cloud.adoc + + +[id='customizing-installation_{context}'] += Further customizing the installation + +If you need to make even more customizations, you can. + +.Prerequisites + +* Render the installation assets. + +.Procedure + + +. Create the YAML definition: + +. Modify the controlling file: + +. Add more Kubernetes files: diff --git a/modules/initializing-installation.adoc b/modules/initializing-installation.adoc new file mode 100644 index 000000000000..6cfc97390a04 --- /dev/null +++ b/modules/initializing-installation.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * installation/installing-customizations-cloud.adoc + +[id='initializing-installation_{context}'] += Creating the installation configuration file + +You can customize your installation of {product-title} on a compatible cloud. + +.Prerequisites + +* Obtain the {product-title} installer and the access token for your cluster. +* Obtain configuration details for your cloud. + +.Procedure + + +. Obtain the `*./install-config.yaml*` file. +.. Run the following command: ++ +---- +$ openshift-install init +---- +.. At the prompts, provide the configuration details for your cloud. + +. If required, modify the `*./install-config.yaml*` file. In this file, you can +provide more values. + +. Validate the contents of the `*./install-config.yaml*` file. ++ +---- +$ openshift-install NEED TO VALIDATE +---- diff --git a/modules/installation-configuration-parameters.adoc b/modules/installation-configuration-parameters.adoc new file mode 100644 index 000000000000..b48eac0046ac --- /dev/null +++ b/modules/installation-configuration-parameters.adoc @@ -0,0 +1,54 @@ +// Module included in the following assemblies: +// +// * installation/installing-customizations-cloud.adoc + +[id='installation-configuration-parameters_{context}'] += Installation configuration parameters + +You use a `*./install-config.yaml*` file to provide parameter values during a +{product-title} installation. During the initialization phase of installation, +you provide values for parameters that are unique to your cluster through the +command line. You can also modify the default values of the remaining parameters. + +[NOTE] +==== +You cannot modify these parameters after installation. +==== + +.Parameters that you define during initialization +[cols=".^2,.^3,.^3a",options="header"] +|==== +|Parameter|Description|Values + +|`provider` +|The cloud provider to host the cluster. +a|Enter one of the following values: + +* aws +* azure +* openstack + +|`base-domain` +|The base domain of your cloud provider. This value is used to . +|A FQDN, such as `dev.example.com`. +|==== + +.All installation parameters +[cols=".^3,.^5,.^5a,.^5",options="header"] +|==== +|Parameter|Description|Value format|Default value + +|`provider` +|The cloud provider to host the cluster. +a|Enter one of the following values: + +* aws +* azure +* openstack +| n/a + +|`base-domain` +|The base domain of your cloud provider. This value is used to . +|A FQDN, such as `dev.example.com`. +|n/a +|==== diff --git a/modules/installation-render-options.adoc b/modules/installation-render-options.adoc new file mode 100644 index 000000000000..1059dea6d3fd --- /dev/null +++ b/modules/installation-render-options.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * installation/installing-customizations-cloud.adoc + +[id='installation-render-options_{context}'] += Installation rending options + +You can customize and different assets during installation. + +[NOTE] +==== +You cannot select different assets after installation. +==== + +.Assets that you can render during installation +[cols=".^3,.^5,.^5",options="header"] +|==== +|Asset|Description|Sample YAML + +|*EXAMPLE* +|DESCRIPTION +|YAML + +|*EXAMPLE* +|DESCRIPTION +|YAML +|==== diff --git a/modules/launching-installer.adoc b/modules/launching-installer.adoc new file mode 100644 index 000000000000..fa259c310c0d --- /dev/null +++ b/modules/launching-installer.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * installation/installing-quickly-cloud.adoc +// * installation/installing-customizations-cloud.adoc + +[id='launching-installer-{context}'] += Launching the installer + +You can install {product-title} on a compatible cloud. + +[IMPORTANT] +==== +You can run the launch command only once, during initial installation. If you +need to change your cluster later, you must update the configuration manually. +==== + +.Prerequisites + +* Obtain the {product-title} installer and the access token for your cluster. +* Obtain configuration details for your cloud. + +.Procedure + +. Run the installer: ++ +---- +$ openshift-install launch +---- ++ +After several minutes, things happen and you see a thing to know that your +cluster is online. + + . Optionally, delete the installation media. diff --git a/modules/obtaining_cloud_installer.adoc b/modules/obtaining_cloud_installer.adoc new file mode 100644 index 000000000000..1bada534d866 --- /dev/null +++ b/modules/obtaining_cloud_installer.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * installation/installing-quickly-cloud.adoc +// * installation/installing-customizations-cloud.adoc + + +[id='installing-quickly-cloud-{context}'] += Obtaining the installer + +Before you install {product-title} on a compatible cloud, download the +installation file on a local computer. + +The installation media takes up this much space on your hard drive during +installation. + +.Prerequisites + +* Any requirements about the computer to run the program on. + +.Procedure + +. Access the link:https://try.openshift.com[the OpenShift start page]. If you +have a Red Hat account, log in with your credentials. If you do not, create an +account. + +. Download the installer and your access token. diff --git a/modules/preparing-assets-installation.adoc b/modules/preparing-assets-installation.adoc new file mode 100644 index 000000000000..70ac5269ac80 --- /dev/null +++ b/modules/preparing-assets-installation.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * installation/installing-customizations-cloud.adoc + + +[id='preparing-assets-installation_{context}'] += Preparing assets for installation +Prepare the final Ignition configurations for the master and bootstrap nodes. + +If you update your asset definition files, run this command again. + +.Prerequisites + +* Render and edit your installation assets. + +.Procedure + + +. Generate final assets for use in the bootstrap tool: ++ +---- +$ openshift-install prepare +$ git add . && commit -m ‘my cluster’ +---- ++ +The assets are stored in a .... diff --git a/modules/preparing-custom-installation.adoc b/modules/preparing-custom-installation.adoc new file mode 100644 index 000000000000..4574cfedb381 --- /dev/null +++ b/modules/preparing-custom-installation.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * installation/installing-customizations-cloud.adoc + +[id='preparing-custom-installation_{context}'] += Preparing to install a custom {product-title} cluster + +Before you install {product-title} on a cloud, you need to plan any +customizations that you must need to define at installation. + +.Procedure + +. Gather your cloud credentials. +. Review the parameters in the `*./install-config.yaml*` file and obtain +custom values for them. +. Prepare custom assets to render: +.. Review the list of possible assets. +.. Prepare and validate the YAML files for your selected assets. +. Prepare other customizations. +.. Kubernetes objects? +.. Customizations to the operators? +.. (might need another reference or two to describe these options) diff --git a/modules/rendering-installation.adoc b/modules/rendering-installation.adoc new file mode 100644 index 000000000000..7ef4c55de285 --- /dev/null +++ b/modules/rendering-installation.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * installation/installing-customizations-cloud.adoc + + +[id='rendering-installation_{context}'] += Rendering installation assets + +.Prerequisites + +* Customize the `*./install-config.yaml*` file for your installation. + +.Procedure + + +. Render assets from the parameters that you defined in the +`*./install-config.yaml*` ++ +---- +$ openshift-install render +---- + +. Edit rendered assets (e.g modify kube-dns manifest) ++ +---- +$ vi ./manifests/kube-dns-daemonset.yaml +----