<commit_before>= Advanced Installation
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap!:

toc::[]

== Overview
For production environments, a reference configuration implemented using
http://www.ansible.com[Ansible] playbooks is available as the _advanced
installation_ method for installing OpenShift hosts. Familiarity with Ansible is
assumed, however you can use this configuration as a reference to create your
own implementation using the configuration management tool of your choosing.

While RHEL Atomic Host is supported for running containerized OpenShift
services, the advanced installation method utilizes Ansible, which is not
available in RHEL Atomic Host, and must therefore be run from
ifdef::openshift-enterprise[]
a RHEL 7 system.
endif::[]
ifdef::openshift-origin[]
a supported version of Fedora, CentOS, or RHEL.
endif::[]
The host initiating the installation does not need to be intended for inclusion
in the OpenShift cluster, but it can be.

ifdef::openshift-enterprise[]
Alternatively, you can use the link:quick_install.html[quick installation]
method if you prefer an interactive installation experience.
endif::[]

[[advanced-before-you-begin]]
== Before You Begin

Before installing OpenShift, you must first see the link:../../install_config/install/prerequisites.html[Prerequisites] topic to
prepare your hosts, which includes verifying system and environment requirements
per component type and properly installing and configuring Docker. It also
includes installing Ansible version 1.8.4 or later, as the advanced installation
method is based on Ansible playbooks and as such requires directly invoking
Ansible.

If you are interested in installing OpenShift using the containerized method
(optional for RHEL but required for RHEL Atomic Host), see
link:../../install_config/install/rpm_vs_containerized.html[RPM vs
Containerized] to ensure that you understand the differences between these
methods, then return to this topic to continue.

After following the instructions in the
link:../../install_config/install/prerequisites.html[Prerequisites] topic and
deciding between the RPM and containerized methods, you can continue in this
topic to link:#configuring-ansible[Configuring Ansible].

[[configuring-ansible]]

== Configuring Ansible

The *_/etc/ansible/hosts_* file is Ansible's inventory file for the playbook to
use during the installation. The inventory file describes the configuration for
your OpenShift cluster. You must replace the default contents of the file with
your desired configuration.

The following sections describe commonly-used variables to set in your inventory
file during an advanced installation, followed by example inventory files you
can use as a starting point for your installation. The examples describe various
environment topographies, including link:#multiple-masters[using multiple
masters for high availability]. You can choose an example that matches your
requirements, modify it to match your own environment, and use it as your
inventory file when link:#running-the-advanced-installation[running the advanced
installation].

[[configuring-host-variables]]
=== Configuring Host Variables

To assign environment variables to hosts during the Ansible installation, indicate
the desired variables in the *_/etc/ansible/hosts_* file after the host entry in
the *[masters]* or *[nodes]* sections. For example:

====
----
[masters]
ec2-52-6-179-239.compute-1.amazonaws.com openshift_public_hostname=ose3-master.public.example.com
----
====

The following table describes variables for use with the Ansible installer that
can be assigned to individual host entries:

[[advanced-host-variables]]
.Host Variables
[options="header"]
|===

|Variable |Purpose

|`*openshift_hostname*`
|This variable overrides the internal cluster host name for the system. Use this
when the system's default IP address does not resolve to the system host name.

|`*openshift_public_hostname*`
|This variable overrides the system's public host name. Use this for cloud
installations, or for hosts on networks using a network address translation
(NAT).

|`*openshift_ip*`
|This variable overrides the cluster internal IP address for the system. Use
this when using an interface that is not configured with the default route.

|`*openshift_public_ip*`
|This variable overrides the system's public IP address. Use this for cloud
installations, or for hosts on networks using a network address translation
(NAT).

|`*containerized*`
|If set to *true*, containerized OpenShift services are run on target master and
node hosts instead of installed using RPM packages. If set to *false* or unset,
the default RPM method is used. RHEL Atomic Host requires the containerized
method, and is automatically selected for you based on the detection of the
*_/run/ostree-booted_* file. See
link:../../install_config/install/rpm_vs_containerized.html[RPM vs
Containerized] for more details.
ifdef::openshift-enterprise[]
Containerized installations are supported starting in OSE 3.1.1.
endif::[]

|`*openshift_node_labels*`
|This variable adds labels to nodes during installation. See
link:#configuring-node-host-labels[Configuring Node Host Labels] for more
details.

|`*openshift_node_kubelet_args*`
|This variable is used to configure `kubeletArguments` on nodes, such as
arguments used in link:../../admin_guide/garbage_collection.html[container and
image garbage collection], and to
link:../../admin_guide/manage_nodes.html#configuring-node-resources[specify
resources per node]. `kubeletArguments` are key value pairs that are passed
directly to the Kubelet that match the
http://kubernetes.io/v1.1/docs/admin/kubelet.html[Kubelet's command line
arguments]. `kubeletArguments` are not migrated or validated and may become
invalid if used. These values override other settings in node configuration
which may cause invalid configurations. Example usage:
*{'image-gc-high-threshold': ['90'],'image-gc-low-threshold': ['80']}*.

|`*openshift_router_selector*`
|Default node selector for automatically deploying router pods. See
link:#configuring-node-host-labels[Configuring Node Host Labels] for details.

|`*openshift_registry_selector*`
|Default node selector for automatically deploying registry pods. See
link:#configuring-node-host-labels[Configuring Node Host Labels] for details.

|`*openshift_docker_options*`
|This variable configures additional Docker options within *_/etc/sysconfig/docker_*, such as
options used in link:../../install_config/install/prerequisites.html#managing-docker-container-logs[Managing Docker Container Logs].
Example usage: *"--log-driver json-file --log-opt max-size=1M --log-opt max-file=3"*.

|===

[[configuring-cluster-variables]]
=== Configuring Cluster Variables

To assign environment variables during the Ansible install that apply more
globally to your OpenShift cluster overall, indicate the desired variables in
the *_/etc/ansible/hosts_* file on separate, single lines within the *[OSEv3:vars]*
section. For example:

====
----
[OSEv3:vars]

openshift_master_identity_providers=[{'name': 'htpasswd_auth', 'login': 'true', 'challenge': 'true', 'kind': 'HTPasswdPasswordIdentityProvider', 'filename': '/etc/origin/master/htpasswd'}]
<commit_msg>Bug 1328843, added missing host variables<commit_after>= Advanced Installation
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap!:

toc::[]

== Overview
For production environments, a reference configuration implemented using
http://www.ansible.com[Ansible] playbooks is available as the _advanced
installation_ method for installing OpenShift hosts. Familiarity with Ansible is
assumed, however you can use this configuration as a reference to create your
own implementation using the configuration management tool of your choosing.

While RHEL Atomic Host is supported for running containerized OpenShift
services, the advanced installation method utilizes Ansible, which is not
available in RHEL Atomic Host, and must therefore be run from
ifdef::openshift-enterprise[]
a RHEL 7 system.
endif::[]
ifdef::openshift-origin[]
a supported version of Fedora, CentOS, or RHEL.
endif::[]
The host initiating the installation does not need to be intended for inclusion
in the OpenShift cluster, but it can be.

ifdef::openshift-enterprise[]
Alternatively, you can use the link:quick_install.html[quick installation]
method if you prefer an interactive installation experience.
endif::[]

[[advanced-before-you-begin]]
== Before You Begin

Before installing OpenShift, you must first see the link:../../install_config/install/prerequisites.html[Prerequisites] topic to
prepare your hosts, which includes verifying system and environment requirements
per component type and properly installing and configuring Docker. It also
includes installing Ansible version 1.8.4 or later, as the advanced installation
method is based on Ansible playbooks and as such requires directly invoking
Ansible.

If you are interested in installing OpenShift using the containerized method
(optional for RHEL but required for RHEL Atomic Host), see
link:../../install_config/install/rpm_vs_containerized.html[RPM vs
Containerized] to ensure that you understand the differences between these
methods, then return to this topic to continue.

After following the instructions in the
link:../../install_config/install/prerequisites.html[Prerequisites] topic and
deciding between the RPM and containerized methods, you can continue in this
topic to link:#configuring-ansible[Configuring Ansible].

[[configuring-ansible]]

== Configuring Ansible

The *_/etc/ansible/hosts_* file is Ansible's inventory file for the playbook to
use during the installation. The inventory file describes the configuration for
your OpenShift cluster. You must replace the default contents of the file with
your desired configuration.

The following sections describe commonly-used variables to set in your inventory
file during an advanced installation, followed by example inventory files you
can use as a starting point for your installation. The examples describe various
environment topographies, including link:#multiple-masters[using multiple
masters for high availability]. You can choose an example that matches your
requirements, modify it to match your own environment, and use it as your
inventory file when link:#running-the-advanced-installation[running the advanced
installation].

[[configuring-host-variables]]
=== Configuring Host Variables

To assign environment variables to hosts during the Ansible installation, indicate
the desired variables in the *_/etc/ansible/hosts_* file after the host entry in
the *[masters]* or *[nodes]* sections. For example:

====
----
[masters]
ec2-52-6-179-239.compute-1.amazonaws.com openshift_public_hostname=ose3-master.public.example.com
----
====

The following table describes variables for use with the Ansible installer that
can be assigned to individual host entries:

[[advanced-host-variables]]
.Host Variables
[options="header"]
|===

|Variable |Purpose

|`*openshift_hostname*`
|This variable overrides the internal cluster host name for the system. Use this
when the system's default IP address does not resolve to the system host name.

|`*openshift_public_hostname*`
|This variable overrides the system's public host name. Use this for cloud
installations, or for hosts on networks using a network address translation
(NAT).

|`*openshift_ip*`
|This variable overrides the cluster internal IP address for the system. Use
this when using an interface that is not configured with the default route.

|`*openshift_public_ip*`
|This variable overrides the system's public IP address. Use this for cloud
installations, or for hosts on networks using a network address translation
(NAT).

|`*containerized*`
|If set to *true*, containerized OpenShift services are run on target master and
node hosts instead of installed using RPM packages. If set to *false* or unset,
the default RPM method is used. RHEL Atomic Host requires the containerized
method, and is automatically selected for you based on the detection of the
*_/run/ostree-booted_* file. See
link:../../install_config/install/rpm_vs_containerized.html[RPM vs
Containerized] for more details.
ifdef::openshift-enterprise[]
Containerized installations are supported starting in OSE 3.1.1.
endif::[]

|`*openshift_node_labels*`
|This variable adds labels to nodes during installation. See
link:#configuring-node-host-labels[Configuring Node Host Labels] for more
details.

|`*openshift_node_kubelet_args*`
|This variable is used to configure `kubeletArguments` on nodes, such as
arguments used in link:../../admin_guide/garbage_collection.html[container and
image garbage collection], and to
link:../../admin_guide/manage_nodes.html#configuring-node-resources[specify
resources per node]. `kubeletArguments` are key value pairs that are passed
directly to the Kubelet that match the
http://kubernetes.io/v1.1/docs/admin/kubelet.html[Kubelet's command line
arguments]. `kubeletArguments` are not migrated or validated and may become
invalid if used. These values override other settings in node configuration
which may cause invalid configurations. Example usage:
*{'image-gc-high-threshold': ['90'],'image-gc-low-threshold': ['80']}*.

|`*openshift_hosted_router_selector*`
|Default node selector for automatically deploying router pods. See
link:#configuring-node-host-labels[Configuring Node Host Labels] for details.

|`*openshift_registry_selector*`
|Default node selector for automatically deploying registry pods. See
link:#configuring-node-host-labels[Configuring Node Host Labels] for details.

|`*openshift_docker_options*`
|This variable configures additional Docker options within *_/etc/sysconfig/docker_*, such as
options used in link:../../install_config/install/prerequisites.html#managing-docker-container-logs[Managing Docker Container Logs].
Example usage: *"--log-driver json-file --log-opt max-size=1M --log-opt max-file=3"*.

|===

[[configuring-cluster-variables]]
=== Configuring Cluster Variables

To assign environment variables during the Ansible install that apply more
globally to your OpenShift cluster overall, indicate the desired variables in
the *_/etc/ansible/hosts_* file on separate, single lines within the *[OSEv3:vars]*
section. For example:

====
----
[OSEv3:vars]

openshift_master_identity_providers=[{'name': 'htpasswd_auth', 'login': 'true', 'challenge': 'true', 'kind': 'HTPasswdPasswordIdentityProvider', 'filename': '/etc/origin/master/htpasswd'}]

{'fraction_non_alphanumeric': 0.08214016578749057, 'fraction_numerical': 0.004452969788312667, 'mean_word_length': 5.6596715328467155, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3215787', 'n_tokens_mistral': 3980, 'n_tokens_neox': 3733, 'n_words': 1653}