== About

This module helps install http://openshift.github.io[OpenShift Origin]
Platform As A Service.  Through the declaration of the `openshift_origin`
class, you can configure the OpenShift Origin Broker, Node and support services
including ActiveMQ, MongoDB, named and OS settings including firewall,
services, and ntp.

=== Authors

* Jamey Owens
* Ben Klang
* Ben Langfeld
* Krishna Raman
* N. Harrison Ripps

== Requirements

* Puppet >= 3
* Facter >= 1.6.17

== Installation

The module can be installed directly via the `puppet` utility from PuppetForge:

----
puppet module install openshift/openshift_origin
----

Additionally, the module can be obtained from the
https://github.com/openshift/puppet-openshift_origin[github repository].

1. Download the https://github.com/openshift/puppet-openshift_origin/archive/master.zip[Zip file from github]
1. Upload the Zip file to your Puppet Master.
1. Unzip the file.  This will create a new directory called puppet-openshift_origin-{commit hash}
1. Rename this directory to just `openshift_origin` and place it in your
     http://docs.puppetlabs.com/learning/modules1.html#modules[modulepath].

== Configuration

There is one class (`openshift_origin`) that needs to be declared on all nodes managing
any component of OpenShift Origin. These nodes are configured using the parameters of
this class.

=== Using Parameterized Classes

http://docs.puppetlabs.com/guides/parameterized_classes.html[Using Parameterized Classes]

.Example: Single host (broker+console+node) which uses the Avahi MDNS and htpasswd Auth plugin:
----
class { 'openshift_origin' :
  domain                        => 'example.com',
  node_unmanaged_users          => ['root'],
  development_mode              => true,
  conf_node_external_eth_dev    => 'eth0',
  install_method                => 'yum',
  register_host_with_nameserver => true,
  broker_auth_plugin            => 'htpasswd',
  broker_dns_plugin             => 'avahi',
}
----

.Example: Single host (broker+console+node) which uses the **Kerberos** Auth plugin and GSS-TSIG.
----
class { 'openshift_origin' :
  domain                        => 'example.com',
  node_unmanaged_users          => ['root'],
  development_mode              => true,
  conf_node_external_eth_dev    => 'eth0',
  install_method                => 'yum',
  register_host_with_nameserver => true,
  broker_auth_plugin            => 'remote-user',
  broker_dns_plugin             => 'nsupdate',
  bind_krb_principal            => $hostname,
  bind_krb_keytab               => '/etc/dns.keytab'
  broker_krb_keytab             => '/etc/http.keytab',
  broker_krb_auth_realms        => 'EXAMPLE.COM',
  broker_krb_service_name       => $hostname,
}
----

Please note:

* The Broker needs to be enrolled in the KDC as a host, `host/node_fqdn` as well as a service, `HTTP/node_fqdn`
* Keytab should be generated, is located on the Broker machine, and Apache should be able to access it (`chown apache <kerberos_keytab>`)
* Like the example config below:
** set `broker_auth_plugin` to `'kerberos'`
** set `broker_krb_keytab` and `bind_krb_keytab` to the absolute file location of the keytab
** set `broker_krb_auth_realms` to the kerberos realm that the Broker host is enrolled with
** set `broker_krb_service_name` to the FQDN of the enrolled kerberos service, e.g. `$hostname`
* After setup, to test:
** authentication: `kinit <user>` then `curl -Ik --negotiate -u : <node_fqdn>`
** GSS-TSIG (should return `nil`):
+
----
$ cd /var/www/openshift/broker
$ bundle --local
$ rails console
$ d = OpenShift::DnsService.instance
$ d.register_application "appname", "namespace", "node_fqdn"
=> nil
----
** For any errors, on the Broker, check `/var/log/openshift/broker/httpd/error_log`.

=== Parameters

==== roles

Choose from the following roles to be configured on this node.

* broker     - Installs the broker and console.
* node       - Installs the node and cartridges.
* msgserver  - Installs ActiveMQ message broker.
* datastore  - Installs MongoDB (not sharded/replicated)
* nameserver - Installs a BIND dns server configured with a TSIG key for updates.

Default: ['broker','node','msgserver','datastore','nameserver']

==== install_method
Choose from the following ways to provide packages:

1. none - install sources are already set up when the script executes (default)
1. yum - set up yum repos manually
  * repos_base
  * os_repo
  * os_updates_repo
  * jboss_repo_base
  * jenkins_repo_base
  * optional_repo

Default: yum

==== repos_base
Base path to repository for OpenShift Origin

* Nightlies:
** Fedora: https://mirror.openshift.com/pub/origin-server/nightly/fedora-19
** RHEL:   https://mirror.openshift.com/pub/origin-server/nightly/rhel-6
* Release-2:
** Fedora: https://mirror.openshift.com/pub/origin-server/release/2/fedora-19
** RHEL:   https://mirror.openshift.com/pub/origin-server/release/2/rhel-6

Default: Fedora-19 Nightlies

=== architecture
CPU Architecture to use for the definition OpenShift Origin yum repositories
Defaults: $::architecture (from facter)

* RHEL:
** x86_64
* CentOS:
** x86_64

==== override_install_repo
Repository path override. Uses dependencies from repos_base but uses 
override_install_repo path for OpenShift RPMs. Used when doing local builds.

Default: none

==== os_repo
The URL for a Fedora 19/RHEL 6 yum repository used with the "yum" install method.
Should end in x86_64/os/.

Default: no change

==== os_updates
The URL for a Fedora 19/RHEL 6 yum updates repository used with the "yum" install method.
Should end in x86_64/.

Default: no change

==== jboss_repo_base
The URL for a JBoss repositories used with the "yum" install method.
Does not install repository if not specified.

==== jenkins_repo_base
The URL for a Jenkins repositories used with the "yum" install method.
Does not install repository if not specified.

==== optional_repo
The URL for a EPEL or optional repositories used with the "yum" install method.
Does not install repository if not specified.

==== domain
The network domain under which apps and hosts will be placed.

Default: example.com

==== broker_hostname
==== node_hostname
==== nameserver_hostname
==== msgserver_hostname
==== datastore_hostname
Default: the root plus the domain, e.g. broker.example.com - except
nameserver=ns1.example.com 

These supply the FQDN of the hosts containing these components. Used
for configuring the host's name at install, and also for configuring
the broker application to reach the services needed.

NOTE: if installing a nameserver, the script will create
DNS entries for the hostnames of the other components being 
installed on this host as well. If you are using a nameserver set
up separately, you are responsible for all necessary DNS entries.

==== nameserver_ip_addr
Default: IP of a name server instance or current IP if installing on this 
node. This is used by every node to configure its primary name server.

Default: the current IP (at install)  

==== bind_key
When the nameserver is remote, use this to specify the HMAC-MD5 key
for updates. This is the "Key:" field from the .private key file
generated by dnssec-keygen. This field is required on all nodes. 

==== bind_krb_keytab
When the nameserver is remote, Kerberos keytab together with principal
can be used instead of the HMAC-MD5 key for updates.

==== bind_krb_principal
When the nameserver is remote, this Kerberos principal together with
Kerberos keytab can be used instead of the HMAC-MD5 key for updates.

==== conf_nameserver_upstream_dns
List of upstream DNS servers to use when installing a nameserver on this node.

Default: ['8.8.8.8']

==== broker_ip_addr
This is used for the node to record its broker. Also is the default
for the nameserver IP if none is given.

Default: the current IP (at install)

==== node_ip_addr
This is used for the node to give a public IP, if different from the
one on its NIC.

Default: the current IP (at install)

==== configure_ntp
Enabling this configures NTP.  It is important that the time be 
synchronized across hosts because MCollective messages have a TTL 
of 60 seconds and may be dropped if the clocks are too far out 
of synch.  However, NTP is not necessary if the clock will be kept 
in synch by some other means.

Default: true

NOTE: Passwords used to secure various services. You are advised to specify
only alphanumeric values in this script as others may cause syntax
errors depending on context. If non-alphanumeric values are required,
update them separately after installation.

==== ntp_servers
If configure_ntp is set to true (default), ntp_servers allows users to
specify an array of NTP servers used for clock synchronization.

Default: ['time.apple.com iburst', 'pool.ntp.org iburst', 'clock.redhat.com iburst']

NOTE: Use iburst after every ntp server definition to speed up the
initial synchronization.

==== msgserver_admin_password
This is the admin password for the ActiveMQ admin console, which is
not needed by OpenShift but might be useful in troubleshooting.

Default: scrambled

==== mcollective_user
==== mcollective_password
This is the user and password shared between broker and node for
communicating over the mcollective topic channels in ActiveMQ. Must
be the same on all broker and node hosts.

Default: mcollective/marionette

==== mongodb_admin_user
==== mongodb_admin_password
These are the username and password of the administrative user that
will be created in the MongoDB datastore. These credentials are not
used by in this script or by OpenShift, but an administrative user
must be added to MongoDB in order for it to enforce authentication.
Note: The administrative user will not be created if
CONF_NO_DATASTORE_AUTH_FOR_LOCALHOST is enabled.

Default: admin/mongopass

==== mongodb_broker_user
==== mongodb_broker_password
These are the username and password of the normal user that will be
created for the broker to connect to the MongoDB datastore. The
broker application's MongoDB plugin is also configured with these
values.

Default: openshift/mongopass
  
==== mongodb_name
This is the name of the database in MongoDB in which the broker will
store data.

Default: openshift_broker

==== openshift_user1
==== openshift_password1
This user and password are entered in the /etc/openshift/htpasswd
file as a demo/test user. You will likely want to remove it after
installation (or just use a different auth method).

Default: demo/changeme

==== conf_broker_auth_salt
==== conf_broker_auth_public_key
==== conf_broker_auth_private_key
==== conf_broker_auth_key_password
Salt, public and private keys used when generating secure authentication 
tokens for Application to Broker communication. Requests like scale up/down 
and jenkins builds use these authentication tokens. This value must be the 
same on all broker nodes.

Default:  Self signed keys are generated. Will not work with multi-broker 
          setup.
  
==== conf_broker_session_secret
==== conf_console_session_secret
Session secrets used to encode cookies used by console and broker. This 
value must be the same on all broker nodes.
  
==== conf_valid_gear_sizes
List of all gear sizes this will be used in this OpenShift installation.

Default: ['small']

==== conf_default_gear_size
Default gear size if one is not specified.

Default: ['small']

==== conf_default_gear_capabilities
List of all gear sizes that newly created users will be able to create.

Default: ['small']

==== broker_dns_plugin

DNS plugin used by the broker to register application DNS entries.
Options:

* nsupdate - nsupdate based plugin. Supports TSIG and GSS-TSIG based 
             authentication. Uses bind_key for TSIG and bind_krb_keytab, 
             bind_krb_principal for GSS_TSIG auth.
* avahi    - sets up a MDNS based DNS resolution. Works only for 
             all-in-one installations.

==== broker_auth_plugin
Authentication setup for users of the OpenShift service.
Options:

* mongo       - Stores username and password in mongo.
* kerberos    - Kerberos based authentication. Uses 
                broker_krb_service_name, broker_krb_auth_realms,
                broker_krb_keytab values.
* htpasswd    - Stores username/password in a htaccess file.
* ldap        - LDAP based authentication. Uses broker_ldap_uri.

Default: htpasswd

==== broker_krb_service_name
The KrbServiceName value for mod_auth_kerb configuration

==== broker_krb_auth_realms
The KrbAuthRealms value for mod_auth_kerb configuration

==== broker_krb_keytab
The Krb5KeyTab value of mod_auth_kerb is not configurable -- the keytab
is expected in /var/www/openshift/broker/httpd/conf.d/http.keytab

==== broker_ldap_uri
URI to the LDAP server (e.g. ldap://ldap.example.com:389/ou=People,dc=my-domain,dc=com).
Set <code>broker_auth_plugin</code> to <code>ldap</code> to enable
this feature.

==== node_container_plugin
Specify the container type to use on the node.
Options:

  * selinux - This is the default OpenShift Origin container type.

==== node_frontend_plugins
Specify one or more plugins to use register HTTP and web-socket connections 
for applications.
Options:

* apache-mod-rewrite  - Mod-Rewrite based plugin for HTTP and HTTPS 
    requests. Well suited for installations with a lot of 
    creates/deletes/scale actions.
* apache-vhost        - VHost based plugin for HTTP and HTTPS. Suited for 
    installations with less app create/delete activity. Easier to 
    customize.  If apache-mod-rewrite is also selected, apache-vhost will be
    ignored
* nodejs-websocket    - Web-socket proxy listening on ports 8000/8444
* haproxy-sni-proxy   - TLS proxy using SNI routing on ports 2303 through 2308
    requires /usr/sbin/haproxy15 (haproxy-1.5-dev19 or later).

Default: ['apache-mod-rewrite','nodejs-websocket']
  
==== node_unmanaged_users
List of user names who have UIDs in the range of OpenShift gears but must be 
excluded from OpenShift gear setups.

Default: []

==== conf_node_external_eth_dev
External facing network device. Used for routing and traffic control setup.

Default: eth0

==== conf_node_supplementary_posix_groups
Name of supplementary UNIX group to add a gear to.

==== development_mode
Set development mode and extra logging. 

Default: false

==== install_login_shell
Install a Getty shell which displays DNS, IP and login information. Used for 
all-in-one VM installation.

==== register_host_with_nameserver
Setup DNS entries for this host in a locally installed bind DNS instance.

Default: false

==== install_cartridges
List of cartridges to be installed on the node. Options:

* 10gen-mms-agent
* cron
* diy
* haproxy
* mongodb
* nodejs
* perl
* php
* phpmyadmin
* postgresql
* python
* ruby
* jenkins
* jenkins-client
* mariadb         (will install mysql on RHEL)
* jbossews
* jbossas
* jbosseap

Default: ['10gen-mms-agent','cron','diy','haproxy','mongodb',
          'nodejs','perl','php','phpmyadmin','postgresql',
          'python','ruby','jenkins','jenkins-client','mariadb']

== Manual Tasks

This script attempts to automate as many tasks as it reasonably can.
Unfortunately, it is constrained to setting up only a single host at a
time. In an assumed multi-host setup, you will need to do the 
following after the script has completed.

1. Set up DNS entries for hosts.
+
If you installed BIND with the script, then any other components
installed with the script on the same host received DNS entries.
Other hosts must all be defined manually, including at least your
node hosts. oo-register-dns may prove useful for this.

2. Copy public rsync key to enable moving gears.
+
The broker rsync public key needs to go on nodes, but there is no
good way to script that generically. Nodes should not have
password-less access to brokers to copy the .pub key, so this must
be performed manually on each node host:
+
----
# scp root@broker:/etc/openshift/rsync_id_rsa.pub /root/.ssh/
(above step will ask for the root password of the broker machine)
# cat /root/.ssh/rsync_id_rsa.pub >> /root/.ssh/authorized_keys
# rm /root/.ssh/rsync_id_rsa.pub
----
+
If you skip this, each gear move will require typing root passwords
for each of the node hosts involved.

3. Copy ssh host keys between the node hosts.
+
All node hosts should identify as the same host, so that when gears
are moved between hosts, ssh and git don't give developers spurious
warnings about the host keys changing. So, copy /etc/ssh/ssh_* from
one node host to all the rest (or, if using the same image for all
hosts, just keep the keys from the image).
