This document provides users step-by-step instructions for deploying OpenShift Origin (OSO) v3.0 using OpenStack [http://wiki.openstack.org/wiki/Heat Heat]. Heat is the main project in the OpenStack Orchestration program. It implements an orchestration engine to launch multiple composite cloud applications based on templates in the form of text files that can be treated like code. The current OSO Heat template supports deploying one Broker instance and one Node instance. The base OpenStack deployment was accomplished using [http://docwiki.cisco.com/wiki/Openstack:Havana-Openstack-Installer Cisco's OpenStack Installer (COI) Havana release]. However, the Heat deployment should work with any OpenStack distribution that uses [http://status.openstack.org/release/ Icehouse-2] or later and Neutron [http://developer.rackspace.com/blog/neutron-networking-vlan-provider-networks.html VLAN Provider Networking]. Therefore, if you are using COI to manage your OpenStack deployment, you must use either the full_ha or compressed_ha scenario. This is because both scenarios use Neutron VLAN Provider Networking. Please file a [http://bugs.launchpad.net/openstack-cisco feature request] if you require support for a different Neutron networking model.

+

This document provides users step-by-step instructions for deploying OpenShift Origin (OSO) v3.0 using OpenStack [http://wiki.openstack.org/wiki/Heat Heat]. Heat is the main project in the OpenStack Orchestration program. It implements an orchestration engine to launch multiple composite cloud applications based on templates in the form of text files that can be treated like code. The current OSO Heat template supports deploying one Broker instance and one Node instance. The base OpenStack deployment was accomplished using [http://docwiki.cisco.com/wiki/Openstack:Havana-Openstack-Installer Cisco's OpenStack Installer (COI) Havana release]. However, the Heat deployment should work with any OpenStack distribution that uses [http://github.com/openstack/heat/releases/tag/2014.1.b1 Icehouse-1] and Neutron [http://developer.rackspace.com/blog/neutron-networking-vlan-provider-networks.html VLAN Provider Networking]. Therefore, if you are using COI to manage your OpenStack deployment, you must use either the full_ha or compressed_ha scenario. This is because both scenarios use Neutron VLAN Provider Networking. Please file a [http://bugs.launchpad.net/openstack-cisco feature request] if you require support for a different Neutron networking model.

Nova uses metadata to manage the hostname of instances. By default the hostname of instances will be the name of the instance in the Nova boot command, followed by a period and the domain. The domain is either [https://github.com/openstack/nova/blob/stable/havana/etc/nova/nova.conf.sample#L1229-L123 novalocal] or [https://github.com/openstack/neutron/blob/stable/havana/etc/dhcp_agent.ini#L56-L57 openstacklocal] by default, depending on the method used for accessing metadata. This domain '''MUST''' match the domain used within your OpenShift deployment. The example below sets the domain to example.com in /etc/nova/nova.conf:

+

+

<pre>vi /etc/nova/nova.conf

+

dhcp_domain=example.com</pre>

+

+

Restart the Nova API service:

+

<pre>service nova-api restart</pre>

+

+

The example below sets the domain to example.com in /etc/neutron/dhcp_agent.ini

+

<pre>vi /etc/neutron/dhcp_agent.ini

+

dhcp_domain=example.com</pre>

+

+

Restart the Neutron DHCP Agent:

+

<pre>service neutron-dhcp-agent restart</pre>

== Heat Deployment ==

== Heat Deployment ==

-

Since the Icehouse release (2014.1.b2 or later) of Heat is required for the OSO template, Heat must be installed from source. At the time of this writing, the latest version of [http://docwiki.cisco.com/wiki/Openstack:Havana-Openstack-Installer COI] is Havana. If you have a current Heat installation prior to 2014.1.b2, uninstall all Heat packages:

+

Since the [http://github.com/openstack/heat/releases/tag/2014.1.b1 Icehouse-1 release] of Heat is required for the OSO template, Heat must be installed from source. At the time of this writing, the latest version of [http://docwiki.cisco.com/wiki/Openstack:Havana-Openstack-Installer COI] is Havana. If you have an existing Heat installation prior to 2014.1.b2, uninstall all Heat packages:

If you are planning to deploy OpenStack using COI or you have just uninstalled the Heat packages from an existing COI deployment, remove Heat from the list of services that are managed by COI:

If you are planning to deploy OpenStack using COI or you have just uninstalled the Heat packages from an existing COI deployment, remove Heat from the list of services that are managed by COI:

Line 99:

Line 116:

<pre>cp -R ~/heat/etc/heat/* /etc/heat/.</pre>

<pre>cp -R ~/heat/etc/heat/* /etc/heat/.</pre>

-

Edit the /etc/heat/heat.conf file to include the following. Replace <CONTROLLER_IP> with the IP address of the Controller. Replace <CONTROLLER_VIP> with the VIP address of the Controller Cluster. '''Note:''' The example configuration below is based on the [http://docwiki.cisco.com/wiki/Openstack:Havana-Openstack-Installer COI] full_ha scenario. If you are not using the full_ha deployment scenario, use <CONTROLLER_IP> instead of <CONTROLLER_VIP> and follow the inline notes:

+

Edit the /etc/heat/heat.conf file to include the following. Replace <CONTROLLER_IP> with the IP address of the Controller. Replace <CONTROLLER_VIP> with the VIP address of the Controller Cluster. '''Note:''' The example configuration below is based on the [http://docwiki.cisco.com/wiki/Openstack:Havana-Openstack-Installer COI] full_ha scenario. If you are not using the full_ha or compressed_ha scenario, use <CONTROLLER_IP> instead of <CONTROLLER_VIP> and follow the inline notes:

<pre>[DEFAULT]

<pre>[DEFAULT]

heat_metadata_server_url=http://<CONTROLLER_VIP>:8000

heat_metadata_server_url=http://<CONTROLLER_VIP>:8000

Line 157:

Line 174:

At this point, you should have a functioning OpenStack deployment that includes Heat (2014.1.b2 or later) and that your OpenShift Broker and Node images have been successfully uploaded to Glance. Now simply issue the ''heat stack-create'' command to deploy your OpenShift Origin environment:

At this point, you should have a functioning OpenStack deployment that includes Heat (2014.1.b2 or later) and that your OpenShift Broker and Node images have been successfully uploaded to Glance. Now simply issue the ''heat stack-create'' command to deploy your OpenShift Origin environment:

Here is an overview of the parameters contained within the ''heat stack-create'' command:

Here is an overview of the parameters contained within the ''heat stack-create'' command:

-

* <STACK_NAME>: The name of the Heat stack.

+

* <STACK_NAME>: A unique name for the OpenShift Heat stack.

* <HEAT_TEMPLATE_FILE_PATH>: The file path to the Heat OpenShift.template. If you are following these directions, the path should be: /root/heat-templates/openshift-origin/F19/OpenShift.template.

* <HEAT_TEMPLATE_FILE_PATH>: The file path to the Heat OpenShift.template. If you are following these directions, the path should be: /root/heat-templates/openshift-origin/F19/OpenShift.template.

* <KEY_NAME>: The name of the Nova key-pair created earlier in this document. (i.e. admin-key)

* <KEY_NAME>: The name of the Nova key-pair created earlier in this document. (i.e. admin-key)

* <DOMAIN_NAME>: The domain name that will be used by your OpenShift deployment. Defaults to example.com

* <DOMAIN_NAME>: The domain name that will be used by your OpenShift deployment. Defaults to example.com

-

* <UPSTREAM_DNS>: The IP address(es) of the upstream DNS serves used by your Broker instance for name resolution (outside of <DOMAIN_NAME>).

+

* <UPSTREAM_DNS>: The IP address(es) of the upstream DNS serves used by your Broker instance for name resolution (outside of <DOMAIN_NAME>). Defaults to Google DNS (8.8.8.8).

* <UPSTREAM_NTP>: IP address of the upstream NTP server. Defaults to 'clock.redhat.com iburst'. Note: iburst must be included in your NTP server entry and therefore a ' ' is required for this parameter.

* <UPSTREAM_NTP>: IP address of the upstream NTP server. Defaults to 'clock.redhat.com iburst'. Note: iburst must be included in your NTP server entry and therefore a ' ' is required for this parameter.

* <NEUTRON_NET_ID>: The ID of the Neutron network that will be used to spawn Broker and Node instances on. You can obtain the Neutron Net ID from the ''neutron net-list'' command.

* <NEUTRON_NET_ID>: The ID of the Neutron network that will be used to spawn Broker and Node instances on. You can obtain the Neutron Net ID from the ''neutron net-list'' command.

* <NEUTRON_SUBNET_ID>: The ID of the Neutron subnet that will be used to spawn Broker and Node instances on. You can obtain the Neutron Subnet ID from the ''neutron subnet-list'' command.

* <NEUTRON_SUBNET_ID>: The ID of the Neutron subnet that will be used to spawn Broker and Node instances on. You can obtain the Neutron Subnet ID from the ''neutron subnet-list'' command.

-

* <BROKER_NAME>: The name that will be appended to <DOMAIN_NAME> and used as the hostname of the Broker instance.

+

* <BROKER_NAME>: The name that will be appended to <DOMAIN_NAME> and used as the hostname of the Broker instance. Defaults to openshift.brokerinstance.novalocal.

-

* <NODE_NAME>: The name that will be appended to <DOMAIN_NAME> and used as the hostname of the Node instance.

+

* <NODE_NAME>: The name that will be appended to <DOMAIN_NAME> and used as the hostname of the Node instance. Defaults to openshift.nodeinstance.novalocal.

+

* <USERNAME>: The username of the admin account for managing the OpenShift environment. Defaults to openshift.

+

* <PASSWORD>: The password of the admin account for managing the OpenShift environment. Defaults to password.

+

* Remove PuppetModuleURL=https://github.com/danehans/puppet-openshift_origin.git;PuppetModuleBranch=systemd_vim_fixes from the command above when upstream pull requests are merged.

Here is an example of the ''heat stack-create'' command with the required parameters supplied:

Here is an example of the ''heat stack-create'' command with the required parameters supplied:

You should then be able to SSH into your Broker instance. Keep in mind that you need to specify the SSH private key that was used to create the Nova key-pair. ec2-user is the default user name. You can change the default user name in heat.conf (instance_user=ec2-user).

You should then be able to SSH into your Broker instance. Keep in mind that you need to specify the SSH private key that was used to create the Nova key-pair. ec2-user is the default user name. You can change the default user name in heat.conf (instance_user=ec2-user).

Line 287:

Line 312:

Note: The last line in the log should be ''Provision done: 2014-03-07 18:47:09.791809''

Note: The last line in the log should be ''Provision done: 2014-03-07 18:47:09.791809''

-

The broker is now successfully deployed by Heat. You can repeat these verification steps for the Node instance if you would like. Otherwise, wait 10-15 minutes for Heat to complete the rest of the stack deployment and issue the ''heat stack-list'' or ''heat stack show <STACK_NAME>'' commands to verify the successful completion of the stack:

+

The broker is now successfully deployed by Heat. You can repeat these verification steps for the Node instance if you would like. Otherwise, wait 10-15 minutes for Heat to complete the rest of the stack deployment and issue the ''heat stack-list'' or ''heat stack-show <STACK_NAME>'' commands to verify the successful completion of the stack:

If not, do not proceed with this section and follow the [http://docwiki.cisco.com/wiki/OpenShift_Origin_Heat_Deployment_Guide#Deployment_Verification Deployment Verification for troubleshooting assistance. Otherwise, follow the [http://docwiki.cisco.com/wiki/OpenShift_Origin_Automated_Deployment_Guide#Deploy_Your_First_Application Deploy Your First Application Section] of the OpenShift Automated Deployment Guide.

+

If not, do not proceed with this section and follow the [http://docwiki.cisco.com/wiki/OpenShift_Origin_Heat_Deployment_Guide#Deployment_Verification Deployment Verification] for troubleshooting assistance. Otherwise, follow the [http://docwiki.cisco.com/wiki/OpenShift_Origin_Automated_Deployment_Guide#Deploy_Your_First_Application Deploy Your First Application Section] of the OpenShift Automated Deployment Guide.

Background

This document provides users step-by-step instructions for deploying OpenShift Origin (OSO) v3.0 using OpenStack Heat. Heat is the main project in the OpenStack Orchestration program. It implements an orchestration engine to launch multiple composite cloud applications based on templates in the form of text files that can be treated like code. The current OSO Heat template supports deploying one Broker instance and one Node instance. The base OpenStack deployment was accomplished using Cisco's OpenStack Installer (COI) Havana release. However, the Heat deployment should work with any OpenStack distribution that uses Icehouse-1 and Neutron VLAN Provider Networking. Therefore, if you are using COI to manage your OpenStack deployment, you must use either the full_ha or compressed_ha scenario. This is because both scenarios use Neutron VLAN Provider Networking. Please file a feature request if you require support for a different Neutron networking model.

Prepare the Images

Images must be created for the Broker and Node instance. The images will be used to deploy running Broker and Node instances using the OpenStack Image Service (Glance), Compute Service (Nova) and Orchestration Service (Heat).

Log into a host that contains the following:

OpenStack client packages (i.e. python-novaclient)

Network connectivity to OpenStack API endpoints

OpenStack credential file. (i.e. openrc). Here is a reference to the contents of an authentication file.

Follow the instructions in the SSH Key Injection Section of the Cisco Havana HA Manual Deployment Guide to create a Nova key-pair.

If Neutron networks have yet to be created, create your first tenant network now. Keep in mind this example uses Neutron Provider VLAN Networks which is the only supported networking model for the OSO Heat template. In our example, we use the admin tenant. Create additional networks as needed. Note: The --tenant_id flag is not specified in the following commands because we previously sourced our credential file.

Create your first tenant subnet and associate it to the network you created in the previous step. The example below uses .10-.250 for Instance IP addresses. Modify the allocation-pool and dns_nameservers based on your deployment needs. Create additional networks as needed.

Configure the OpenStack DHCP Domain

Nova uses metadata to manage the hostname of instances. By default the hostname of instances will be the name of the instance in the Nova boot command, followed by a period and the domain. The domain is either novalocal or openstacklocal by default, depending on the method used for accessing metadata. This domain MUST match the domain used within your OpenShift deployment. The example below sets the domain to example.com in /etc/nova/nova.conf:

vi /etc/nova/nova.conf
dhcp_domain=example.com

Restart the Nova API service:

service nova-api restart

The example below sets the domain to example.com in /etc/neutron/dhcp_agent.ini

vi /etc/neutron/dhcp_agent.ini
dhcp_domain=example.com

Restart the Neutron DHCP Agent:

service neutron-dhcp-agent restart

Heat Deployment

Since the Icehouse-1 release of Heat is required for the OSO template, Heat must be installed from source. At the time of this writing, the latest version of COI is Havana. If you have an existing Heat installation prior to 2014.1.b2, uninstall all Heat packages:

Edit the /etc/heat/heat.conf file to include the following. Replace <CONTROLLER_IP> with the IP address of the Controller. Replace <CONTROLLER_VIP> with the VIP address of the Controller Cluster. Note: The example configuration below is based on the COI full_ha scenario. If you are not using the full_ha or compressed_ha scenario, use <CONTROLLER_IP> instead of <CONTROLLER_VIP> and follow the inline notes:

OpenShift Deployment

At this point, you should have a functioning OpenStack deployment that includes Heat (2014.1.b2 or later) and that your OpenShift Broker and Node images have been successfully uploaded to Glance. Now simply issue the heat stack-create command to deploy your OpenShift Origin environment:

You should then be able to SSH into your Broker instance. Keep in mind that you need to specify the SSH private key that was used to create the Nova key-pair. ec2-user is the default user name. You can change the default user name in heat.conf (instance_user=ec2-user).

ssh -i ~/.ssh/id_rsa ec2-user@<BROKER_IP>
sudo -i

You can view the installation log at /var/log/configure_openshift.log

tail -f /var/log/configure_openshift.log

Note:' You can safely ignore the following warning messages that may appear during your Puppet run:Warning: Config file /etc/puppet/hiera.yaml not found, using Hiera defaults
Warning: Augeas[network-scripts](provider=augeas): Loading failed for one or more files, see debug for /augeas//error output

The puppet run should complete with the following message:

Notice: Finished catalog run in xxx seconds

You can also view the Heat provisioning log.

less /var/log/heat-provision.log

Note: The last line in the log should be Provision done: 2014-03-07 18:47:09.791809

The broker is now successfully deployed by Heat. You can repeat these verification steps for the Node instance if you would like. Otherwise, wait 10-15 minutes for Heat to complete the rest of the stack deployment and issue the heat stack-list or heat stack-show <STACK_NAME> commands to verify the successful completion of the stack: