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

toc::[]

== Overview
ifdef::openshift-origin[]
OpenShift
link:../../architecture/infrastructure_components/kubernetes_infrastructure.html[infrastructure
components] can be installed across multiple hosts. The following sections
outline the system requirements and instructions for preparing your environment
and hosts before installing OpenShift.
endif::[]

ifdef::openshift-enterprise[]
OpenShift
link:../../architecture/infrastructure_components/kubernetes_infrastructure.html[infrastructure
components] can be installed across multiple hosts. The following sections
outline the system requirements and instructions for preparing your environment
and hosts before installing OpenShift.
endif::[]

== System Requirements

ifdef::openshift-enterprise[]
You must have an active OpenShift Enterprise subscription on your Red Hat
account to proceed. If you do not, contact your sales representative for more
information.
endif::[]

The system requirements vary per host type:

[cols="1,7"]
|===
|link:../../architecture/infrastructure_components/kubernetes_infrastructure.html#master[Masters]
a|- Physical or virtual system
ifdef::openshift-origin[]
- Base OS: Fedora 21, CentOS 7.1, or RHEL 7.1 with "Minimal" installation option
endif::[]
ifdef::openshift-enterprise[]
- Base OS: Red Hat Enterprise Linux (RHEL) 7.1  with "Minimal" installation
option
endif::[]
- 2 vCPU
- Minimum 8 GB RAM
- Minimum 30 GB hard disk space

|link:../../architecture/infrastructure_components/kubernetes_infrastructure.html#node[Nodes]
a| - Physical or virtual system, or an instance running on a public IaaS
ifdef::openshift-origin[]
- Base OS: Fedora 21, CentOS 7.1, or RHEL 7.1 with "Minimal" installation option
endif::[]
ifdef::openshift-enterprise[]
- Base OS: Red Hat Enterprise Linux (RHEL) 7.1 with "Minimal" installation
option
endif::[]
- Docker 1.6 or later
- 1 vCPU
- Minimum 8 GB RAM
- Minimum 15 GB hard disk space
|===

[[security-warning]]
*Security Warning*

OpenShift runs
link:../../architecture/core_concepts/containers_and_images.html#containers[Docker
containers] on your hosts, and in some cases, such as build operations and the
registry service, it does so using privileged containers. Furthermore, those
containers access your host's Docker daemon and perform `docker build` and
`docker push` operations. As such, you should be aware of the inherent security
risks associated with performing `docker run` operations on arbitrary images as
they effectively have root access.

For more information, see these articles:

- http://opensource.com/business/14/7/docker-security-selinux
- https://docs.docker.com/articles/security/

To address these risks, OpenShift uses
link:../../architecture/additional_concepts/authorization.html#security-context-constraints[security
context constraints] that control the actions that pods can perform and what it
has the ability to access.

== Environment Requirements
*DNS*

A wildcard for a DNS zone must ultimately resolve to the IP address of the
OpenShift link:../../architecture/core_concepts/routes.html#routers[router].

For example, create a wildcard DNS entry for *cloudapps*, or something similar,
that has a low TTL and points to the public IP address of the host where the
router will be deployed:

----
*.cloudapps.example.com. 300 IN  A 192.168.133.2
----

In almost all cases, when referencing VMs you must use host names, and the host
names that you use must match the output of the `hostname -f` command on each
node.

*Networking*

A shared network must exist between the master and node hosts.

*Git*

You must have either Internet access and a GitHub account, or read and write access to an internal, HTTP-based Git server.

== Host Preparation
Before installing OpenShift, you must first prepare each host per the following.

ifdef::openshift-origin[]
[NOTE]
====
If you are using https://www.vagrantup.com[Vagrant] to run OpenShift Origin, you
do not need to go through the following sections. These changes are only
necessary when you are setting up the host yourself. If you are using Vagrant,
see the
https://github.com/openshift/origin/blob/master/CONTRIBUTING.adoc#develop-on-virtual-machine-using-vagrant[Contributing
Guide], then you can skip directly to trying out the
link:../../getting_started/administrators.html#try-it-out[sample applications].
====
endif::[]

ifdef::openshift-enterprise[]

*Installing Red Hat Enterprise Linux 7*

A base installation of Red Hat Enterprise Linux (RHEL) 7.1 is required for
master or node hosts. See the
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Installation_Guide/index.html[Red
Hat Enterprise Linux 7.1 Installation Guide] for more information.

*Registering the Hosts*

Each host must be registered using Red Hat Subscription Manager (RHSM) and have
an active OpenShift Enterprise subscription attached to access the required
packages.

. On each host, register with RHSM:
+
----
# subscription-manager register --username=<user_name> --password=<password>
----

. List the available subscriptions:
+
----
# subscription-manager list --available
----

. In the output for the previous command, find the pool ID for an OpenShift
Enterprise subscription and attach it:
+
----
# subscription-manager attach --pool=<pool_id>
----

. Disable all repositories and enable only the required ones:
+
----
# subscription-manager repos --disable="*"
# subscription-manager repos \
    --enable="rhel-7-server-rpms" \
    --enable="rhel-7-server-extras-rpms" \
    --enable="rhel-7-server-optional-rpms" \
    --enable="rhel-7-server-ose-3.0-rpms"
----
endif::[]

*Managing Base Packages*

. Remove *NetworkManager*:
+
----
# yum remove NetworkManager*
----

. Install the following packages:
+
----
# yum install wget git net-tools bind-utils iptables-services bridge-utils
----

. Update the system to the latest packages:
+
----
# yum update
----

*Installing Docker*

Docker version 1.6 or later
ifdef::openshift-enterprise[]
from the *rhel-7-server-ose-3.0-rpms* repository
endif::[]
must be installed and running on master and node hosts before installing
OpenShift.

. Install Docker:
+
----
# yum install docker
----

. Edit the *_/etc/sysconfig/docker_* file and add `--insecure-registry
172.30.0.0/16` to the `*OPTIONS*` parameter. For example:
+
----
OPTIONS=--selinux-enabled --insecure-registry 172.30.0.0/16
----
+
The `--insecure-registry` option instructs the Docker daemon to trust any Docker
registry on the *172.30.0.0/16* subnet, rather than requiring a certificate.

[NOTE]
====
After installing OpenShift, you can choose to
link:docker_registry.html#securing-the-registry[secure the integrated Docker
registry], which involves adjusting the `--insecure-registry` option
accordingly.
====

*Configuring Docker Storage*

Docker's default loopback storage mechanism is not supported for production use
and is only appropriate for proof of concept environments. For production
environments, you must create a thin-pool logical volume and re-configure docker
to use that volume.

You can use the *docker-storage-setup* script to create a thin-pool device and
configure Docker's storage driver after installing Docker but before you start
using it. The script reads configuration options from the
*_/etc/sysconfig/docker-storage-setup_* file.

. Configure *docker-storage-setup* for your environment. There are three options
available based on your storage configuration:

.. Create a thin-pool volume from the remaining free space in the volume group
where your root file system resides; this requires no configuration:
+
----
# docker-storage-setup
----

.. Use an existing volume group, in this example *docker-vg*, to create a
thin-pool:
+
----
# cat <<EOF > /etc/sysconfig/docker-storage-setup
VG=docker-vg
SETUP_LVM_THIN_POOL=yes
EOF
# docker-storage-setup
----

.. Use an unpartitioned block device to create a new volume group and thinpool.
In this example, the `/dev/vdc` device is used to create the *docker-vg* volume
group:
+
----
# cat <<EOF > /etc/sysconfig/docker-storage-setup
DEVS=/dev/vdc
VG=docker-vg
SETUP_LVM_THIN_POOL=yes
EOF
# docker-storage-setup
----

. Verify your configuration. You should have *dm.thinpooldev* value in the
*_/etc/sysconfig/docker-storage_* file and a *docker-pool* device:
+
====
----
# lvs
LV                  VG        Attr       LSize  Pool Origin Data%  Meta% Move Log Cpy%Sync Convert
docker-pool         docker-vg twi-a-tz-- 48.95g             0.00   0.44

# cat /etc/sysconfig/docker-storage
DOCKER_STORAGE_OPTIONS=--storage-opt dm.fs=xfs --storage-opt
dm.thinpooldev=/dev/mapper/docker--vg-docker--pool
----
====

. Re-initialize Docker.
+
[WARNING]
====
This will destroy any docker containers or images currently on the host.
====
+
----
# systemctl stop docker
# rm -rf /var/lib/docker/*
# systemctl restart docker
----

== Host Access for Ansible-based Installations

ifdef::openshift-origin[]
If you plan to use the link:advanced_install.html[advanced installation] method,
Ansible requires a user that has access to all hosts.
endif::[]
ifdef::openshift-enterprise[]
Ansible, which is used to run OpenShift Enterprise installations, requires a
user that has access to all hosts.
endif::[]
For running the Ansible-based installer as a non-root user, passwordless *sudo*
rights must also be configured on each destination host.

For example, you can generate an SSH key on the host where you will invoke the
installation process:

----
# ssh-keygen
----

Do *not* use a password.

An easy way to distribute your SSH keys is by using a `bash` loop:

----
# for host in master.example.com \
    node1.example.com \
    node2.example.com; \
    do ssh-copy-id -i ~/.ssh/id_rsa.pub $host; \
    done
----

Modify the host names in the above command according to your configuration.

== What's Next?

ifdef::openshift-enterprise[]
Now that your environment and hosts are properly set up, you can install
OpenShift Enterprise using the
link:quick_install.html#installing-openshift[quick installation] or
link:advanced_install.html#installing-ansible[advanced installation] method.
endif::[]

ifdef::openshift-origin[]
If you came here from link:../../getting_started/administrators.html[Getting
Started for Administrators], you can now continue there by choosing an
link:../../getting_started/administrators.html#installation-methods[installation
method]. Alternatively, you can install OpenShift using the
link:advanced_install.html#installing-ansible[advanced installation] method.
endif::[]
<commit_msg>Initial info adds re docker storage.<commit_after>= Prerequisites
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap!:

toc::[]

== Overview
ifdef::openshift-origin[]
OpenShift
link:../../architecture/infrastructure_components/kubernetes_infrastructure.html[infrastructure
components] can be installed across multiple hosts. The following sections
outline the system requirements and instructions for preparing your environment
and hosts before installing OpenShift.
endif::[]

ifdef::openshift-enterprise[]
OpenShift
link:../../architecture/infrastructure_components/kubernetes_infrastructure.html[infrastructure
components] can be installed across multiple hosts. The following sections
outline the system requirements and instructions for preparing your environment
and hosts before installing OpenShift.
endif::[]

== System Requirements

ifdef::openshift-enterprise[]
You must have an active OpenShift Enterprise subscription on your Red Hat
account to proceed. If you do not, contact your sales representative for more
information.
endif::[]

The system requirements vary per host type:

[cols="1,7"]
|===
|link:../../architecture/infrastructure_components/kubernetes_infrastructure.html#master[Masters]
a|- Physical or virtual system
ifdef::openshift-origin[]
- Base OS: Fedora 21, CentOS 7.1, or RHEL 7.1 with "Minimal" installation option
endif::[]
ifdef::openshift-enterprise[]
- Base OS: Red Hat Enterprise Linux (RHEL) 7.1  with "Minimal" installation
option
endif::[]
- 2 vCPU
- Minimum 8 GB RAM
- Minimum 30 GB hard disk space

|link:../../architecture/infrastructure_components/kubernetes_infrastructure.html#node[Nodes]
a| - Physical or virtual system, or an instance running on a public IaaS
ifdef::openshift-origin[]
- Base OS: Fedora 21, CentOS 7.1, or RHEL 7.1 with "Minimal" installation option
endif::[]
ifdef::openshift-enterprise[]
- Base OS: Red Hat Enterprise Linux (RHEL) 7.1 with "Minimal" installation
option
endif::[]
- Docker 1.6 or later
- 1 vCPU
- Minimum 8 GB RAM
- Minimum 15 GB hard disk space
- An additional minimum 15 GB unallocated space to be configured using
*docker-storage-setup*; see link:#configuring-docker-storage[Configuring
Docker Storage] below.
|===

[[security-warning]]
*Security Warning*

OpenShift runs
link:../../architecture/core_concepts/containers_and_images.html#containers[Docker
containers] on your hosts, and in some cases, such as build operations and the
registry service, it does so using privileged containers. Furthermore, those
containers access your host's Docker daemon and perform `docker build` and
`docker push` operations. As such, you should be aware of the inherent security
risks associated with performing `docker run` operations on arbitrary images as
they effectively have root access.

For more information, see these articles:

- http://opensource.com/business/14/7/docker-security-selinux
- https://docs.docker.com/articles/security/

To address these risks, OpenShift uses
link:../../architecture/additional_concepts/authorization.html#security-context-constraints[security
context constraints] that control the actions that pods can perform and what it
has the ability to access.

== Environment Requirements
*DNS*

A wildcard for a DNS zone must ultimately resolve to the IP address of the
OpenShift link:../../architecture/core_concepts/routes.html#routers[router].

For example, create a wildcard DNS entry for *cloudapps*, or something similar,
that has a low TTL and points to the public IP address of the host where the
router will be deployed:

----
*.cloudapps.example.com. 300 IN  A 192.168.133.2
----

In almost all cases, when referencing VMs you must use host names, and the host
names that you use must match the output of the `hostname -f` command on each
node.

*Networking*

A shared network must exist between the master and node hosts.

*Git*

You must have either Internet access and a GitHub account, or read and write
access to an internal, HTTP-based Git server.

== Host Preparation
Before installing OpenShift, you must first prepare each host per the following.

ifdef::openshift-origin[]
[NOTE]
====
If you are using https://www.vagrantup.com[Vagrant] to run OpenShift Origin, you
do not need to go through the following sections. These changes are only
necessary when you are setting up the host yourself. If you are using Vagrant,
see the
https://github.com/openshift/origin/blob/master/CONTRIBUTING.adoc#develop-on-virtual-machine-using-vagrant[Contributing
Guide], then you can skip directly to trying out the
link:../../getting_started/administrators.html#try-it-out[sample applications].
====
endif::[]

ifdef::openshift-enterprise[]

*Installing Red Hat Enterprise Linux 7*

A base installation of Red Hat Enterprise Linux (RHEL) 7.1 is required for
master or node hosts. See the
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Installation_Guide/index.html[Red
Hat Enterprise Linux 7.1 Installation Guide] for more information.

*Registering the Hosts*

Each host must be registered using Red Hat Subscription Manager (RHSM) and have
an active OpenShift Enterprise subscription attached to access the required
packages.

. On each host, register with RHSM:
+
----
# subscription-manager register --username=<user_name> --password=<password>
----

. List the available subscriptions:
+
----
# subscription-manager list --available
----

. In the output for the previous command, find the pool ID for an OpenShift
Enterprise subscription and attach it:
+
----
# subscription-manager attach --pool=<pool_id>
----

. Disable all repositories and enable only the required ones:
+
----
# subscription-manager repos --disable="*"
# subscription-manager repos \
    --enable="rhel-7-server-rpms" \
    --enable="rhel-7-server-extras-rpms" \
    --enable="rhel-7-server-optional-rpms" \
    --enable="rhel-7-server-ose-3.0-rpms"
----
endif::[]

*Managing Base Packages*

. Remove *NetworkManager*:
+
----
# yum remove NetworkManager*
----

. Install the following packages:
+
----
# yum install wget git net-tools bind-utils iptables-services bridge-utils
----

. Update the system to the latest packages:
+
----
# yum update
----

*Installing Docker*

Docker version 1.6 or later
ifdef::openshift-enterprise[]
from the *rhel-7-server-ose-3.0-rpms* repository
endif::[]
must be installed and running on master and node hosts before installing
OpenShift.

. Install Docker:
+
----
# yum install docker
----

. Edit the *_/etc/sysconfig/docker_* file and add `--insecure-registry
172.30.0.0/16` to the `*OPTIONS*` parameter. For example:
+
----
OPTIONS=--selinux-enabled --insecure-registry 172.30.0.0/16
----
+
The `--insecure-registry` option instructs the Docker daemon to trust any Docker
registry on the *172.30.0.0/16* subnet, rather than requiring a certificate.

[NOTE]
====
After installing OpenShift, you can choose to
link:docker_registry.html#securing-the-registry[secure the integrated Docker
registry], which involves adjusting the `--insecure-registry` option
accordingly.
====

[[configuring-docker-storage]]
*Configuring Docker Storage*

Docker's default loopback storage mechanism is not supported for production use
and is only appropriate for proof of concept environments. For production
environments, you must create a thin-pool logical volume and re-configure Docker
to use that volume.

You can use the *docker-storage-setup* script to create a thin-pool device and
configure Docker's storage driver after installing Docker but before you start
using it. The script reads configuration options from the
*_/etc/sysconfig/docker-storage-setup_* file. Allocate at least 15 GB of space
for this purpose no matter which option you choose.

[NOTE]
====
See the https://access.redhat.com/articles/1492923["Managing Storage with Docker
Formatted Containers on Red Hat Enterprise Linux and Red Hat Enterprise Linux
Atomic Host"] Knowledgebase article for more details about
*docker-storage-setup* and basic instructions on storage management in Red Hat
Enterprise Linux 7.
====

. Configure *docker-storage-setup* for your environment. There are three methods
available based on your storage configuration:
[[docker-storage-a]]
.. [[docker-storage-a]]Create a thin-pool volume from the remaining free space in the volume group
where your root file system resides by running the *docker-storage-setup*
command with no arguments; this requires no configuration.
+
[IMPORTANT]
====
This method will fail if you do not have unpartitioned space available. Ensure
before running that the amount of unpartitioned space available is actually
enough to meet link:#system-requirements[your requirements].
====
+
----
# docker-storage-setup
----
+
If this method does not work as expected for you, see the
link:#docker-storage-c[third method below], which may require adding a new
volume to your host.
+
.. [[docker-storage-b]]Use an existing volume group, in this example *docker-vg*, to create a
thin-pool:
+
----
# cat <<EOF > /etc/sysconfig/docker-storage-setup
VG=docker-vg
SETUP_LVM_THIN_POOL=yes
EOF

# docker-storage-setup
----
.. [[docker-storage-c]]Use an unpartitioned block device to create a new volume
group and thinpool. In this example, the `/dev/vdc` device is used to create the
*docker-vg* volume group:
+
----
# cat <<EOF > /etc/sysconfig/docker-storage-setup
DEVS=/dev/vdc
VG=docker-vg
SETUP_LVM_THIN_POOL=yes
EOF

# docker-storage-setup
----

. Verify your configuration. You should have *dm.thinpooldev* value in the
*_/etc/sysconfig/docker-storage_* file and a *docker-pool* device:
+
====
----
# lvs
LV                  VG        Attr       LSize  Pool Origin Data%  Meta% Move Log Cpy%Sync Convert
docker-pool         docker-vg twi-a-tz-- 48.95g             0.00   0.44

# cat /etc/sysconfig/docker-storage
DOCKER_STORAGE_OPTIONS=--storage-opt dm.fs=xfs --storage-opt
dm.thinpooldev=/dev/mapper/docker--vg-docker--pool
----
====

. Re-initialize Docker.
+
[WARNING]
====
This will destroy any Docker containers or images currently on the host.
====
+
----
# systemctl stop docker
# rm -rf /var/lib/docker/*
# systemctl restart docker
----

== Host Access for Ansible-based Installations

ifdef::openshift-origin[]
If you plan to use the link:advanced_install.html[advanced installation] method,
Ansible requires a user that has access to all hosts.
endif::[]
ifdef::openshift-enterprise[]
Ansible, which is used to run OpenShift Enterprise installations, requires a
user that has access to all hosts.
endif::[]
For running the Ansible-based installer as a non-root user, passwordless *sudo*
rights must also be configured on each destination host.

For example, you can generate an SSH key on the host where you will invoke the
installation process:

----
# ssh-keygen
----

Do *not* use a password.

An easy way to distribute your SSH keys is by using a `bash` loop:

----
# for host in master.example.com \
    node1.example.com \
    node2.example.com; \
    do ssh-copy-id -i ~/.ssh/id_rsa.pub $host; \
    done
----

Modify the host names in the above command according to your configuration.

== What's Next?

ifdef::openshift-enterprise[]
Now that your environment and hosts are properly set up, you can install
OpenShift Enterprise using the
link:quick_install.html#installing-openshift[quick installation] or
link:advanced_install.html#installing-ansible[advanced installation] method.
endif::[]

ifdef::openshift-origin[]
If you came here from link:../../getting_started/administrators.html[Getting
Started for Administrators], you can now continue there by choosing an
link:../../getting_started/administrators.html#installation-methods[installation
method]. Alternatively, you can install OpenShift using the
link:advanced_install.html#installing-ansible[advanced installation] method.
endif::[]

{'fraction_non_alphanumeric': 0.10269187986651836, 'fraction_numerical': 0.009432703003337041, 'mean_word_length': 4.298444130127298, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 13, 'https://': 9, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 8, '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': '3417115', 'n_tokens_mistral': 6747, 'n_tokens_neox': 6268, 'n_words': 2479}