You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by ch...@apache.org on 2013/11/20 11:07:45 UTC
git commit: Adding back 4.0.x to 4.2.1 upgrade instructions
Updated Branches:
refs/heads/4.2 3b6310140 -> 3e35c0de0
Adding back 4.0.x to 4.2.1 upgrade instructions
Project: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/commit/3e35c0de
Tree: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/tree/3e35c0de
Diff: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/diff/3e35c0de
Branch: refs/heads/4.2
Commit: 3e35c0de05b5db43fb0f43c7cfc3c2c7a92488ba
Parents: 3b63101
Author: Chip Childers <ch...@gmail.com>
Authored: Wed Nov 20 11:07:26 2013 +0100
Committer: Chip Childers <ch...@gmail.com>
Committed: Wed Nov 20 11:07:26 2013 +0100
----------------------------------------------------------------------
release-notes/en-US/Release_Notes.xml | 175 +++++++++++++++++++++++++++++
1 file changed, 175 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/3e35c0de/release-notes/en-US/Release_Notes.xml
----------------------------------------------------------------------
diff --git a/release-notes/en-US/Release_Notes.xml b/release-notes/en-US/Release_Notes.xml
index 46db2e0..3c58b12 100644
--- a/release-notes/en-US/Release_Notes.xml
+++ b/release-notes/en-US/Release_Notes.xml
@@ -874,6 +874,181 @@ Done restarting router(s).
</listitem>
</orderedlist>
</section>
+ <section id="upgrade-from-4.0-to-4.2.1">
+ <title>Upgrade from 4.0.x to 4.2.1</title>
+ <para>This section will guide you from &PRODUCT; 4.0.x versions to &PRODUCT; 4.2.1.</para>
+ <para>Any steps that are hypervisor-specific will be called out with a note.</para>
+ <warning><title>Package Structure Changes</title>
+ <para>The package structure for &PRODUCT; has changed significantly since the 4.0.x releases. If you've compiled your own packages, you'll notice that the package names and the number of packages has changed. This is <emphasis>not</emphasis> a bug.</para>
+ <para>However, this <emphasis>does</emphasis> mean that the procedure is not as simple as an <command>apt-get upgrade</command> or <command>yum update</command>, so please follow this section carefully.</para>
+ </warning>
+ <para>We recommend reading through this section once or twice before beginning your upgrade procedure, and working through it on a test system before working on a production system.</para>
+ <orderedlist>
+ <listitem>
+ <para>Most users of &PRODUCT; manage the installation and upgrades of &PRODUCT; with one of Linux's predominant package systems, RPM or APT. This guide assumes you'll be using RPM and Yum (for Red Hat Enterprise Linux or CentOS), or APT and Debian packages (for Ubuntu).</para>
+ <para>Create RPM or Debian packages (as appropriate) and a repository from the 4.1.0 source, or check the Apache CloudStack downloads page at <ulink url="http://cloudstack.apache.org/downloads.html">http://cloudstack.apache.org/downloads.html</ulink> for package repositories supplied by community members. You will need them for step <xref linkend="upgrade-deb-packages" /> or step <xref linkend="upgrade-rpm-packages" />.</para>
+ <para>Instructions for creating packages from the &PRODUCT; source are in the <ulink url="http://cloudstack.apache.org/docs/en-US/index.html">Installation Guide</ulink>.</para>
+ </listitem>
+ <listitem>
+ <para>Stop your management server or servers. Run this on all management server hosts:</para>
+ <programlisting><prompt>#</prompt> service cloud-management stop</programlisting>
+ </listitem>
+ <listitem>
+ <para>If you are running a usage server or usage servers, stop those as well:</para>
+ <programlisting><prompt>#</prompt> service cloud-usage stop</programlisting>
+ </listitem>
+ <listitem>
+ <para>Make a backup of your MySQL database. If you run into any issues or need to roll back the upgrade, this will assist in debugging or restoring your existing environment. You'll be prompted for your password.</para>
+ <programlisting><prompt>#</prompt> mysqldump -u root -p cloud > cloudstack-backup.sql</programlisting>
+ </listitem>
+ <listitem>
+ <para>Whether you're upgrading a Red Hat/CentOS based system or Ubuntu based system, you're going to need to stop the CloudStack management server before proceeding.</para>
+ <programlisting language="Bash"><prompt>#</prompt> service cloud-management stop</programlisting>
+ </listitem>
+ <listitem>
+ <para>If you have made changes to <filename>/etc/cloud/management/components.xml</filename>, you'll need to carry these over manually to the new file, <filename>/etc/cloudstack/management/componentContext.xml</filename>. This is not done automatically. (If you're unsure, we recommend making a backup of the original <filename>components.xml</filename> to be on the safe side.</para>
+ </listitem>
+ <listitem>
+ <para>After upgrading to 4.2.1, API clients are expected to send plain text passwords for login and user creation, instead of MD5 hash. Incase, api client changes are not acceptable, following changes are to be made for backward compatibility:</para>
+ <para>Modify componentsContext.xml, and make PlainTextUserAuthenticator as the default authenticator (1st entry in the userAuthenticators adapter list is default)</para>
+ <programlisting language="XML">
+<!-- Security adapters -->
+<bean id="userAuthenticators" class="com.cloud.utils.component.AdapterList">
+ <property name="Adapters">
+ <list>
+ <ref bean="PlainTextUserAuthenticator"/>
+ <ref bean="MD5UserAuthenticator"/>
+ <ref bean="LDAPUserAuthenticator"/>
+ </list>
+ </property>
+</bean>
+ </programlisting>
+ <para>PlainTextUserAuthenticator works the same way MD5UserAuthenticator worked prior to 4.2.1.</para>
+ </listitem>
+ <listitem id="upgrade-deb-packages">
+ <para>If you are using Ubuntu, follow this procedure to upgrade your packages. If not, skip to step <xref linkend="upgrade-rpm-packages" />.</para>
+ <note><title>Community Packages</title>
+ <para>This section assumes you're using the community supplied packages for &PRODUCT;. If you've created your own packages and APT repository, substitute your own URL for the ones used in these examples.</para>
+ </note>
+ <orderedlist id="debsteps">
+ <listitem>
+ <para>The first order of business will be to change the sources list for each system with &PRODUCT; packages. This means all management servers, and any hosts that have the KVM agent. (No changes should be necessary for hosts that are running VMware or Xen.)</para>
+ <para>Start by opening <filename>/etc/apt/sources.list.d/cloudstack.list</filename> on any systems that have &PRODUCT; packages installed.</para>
+ <para>This file should have one line, which contains:</para>
+ <programlisting language="Bash">deb http://cloudstack.apt-get.eu/ubuntu precise 4.0</programlisting>
+ <para>We'll change it to point to the new package repository:</para>
+ <programlisting language="Bash">deb http://cloudstack.apt-get.eu/ubuntu precise 4.1</programlisting>
+ <para>If you're using your own package repository, change this line to read as appropriate for your 4.1.0 repository.</para>
+ </listitem>
+ <listitem>
+ <para>Now update your apt package list:</para>
+ <programlisting language="Bash">$ sudo apt-get update</programlisting>
+ </listitem>
+ <listitem id="deb-master">
+ <para>Now that you have the repository configured, it's time to install the <filename>cloudstack-management</filename> package. This will pull in any other dependencies you need.</para>
+ <programlisting language="Bash">$ sudo apt-get install cloudstack-management</programlisting>
+ </listitem>
+ <listitem id="kvm-agent-deb">
+ <para>You will need to manually install the <filename>cloudstack-agent</filename> package:</para>
+ <programlisting language="Bash">$ sudo apt-get install cloudstack-agent</programlisting>
+ <para>During the installation of <filename>cloudstack-agent</filename>, APT will copy your <filename>agent.properties</filename>, <filename>log4j-cloud.xml</filename>, and <filename>environment.properties</filename> from <filename>/etc/cloud/agent</filename> to <filename>/etc/cloudstack/agent</filename>.</para>
+ <para>When prompted whether you wish to keep your configuration, say Yes.</para>
+ </listitem>
+ <listitem>
+ <para>Verify that the file <filename>/etc/cloudstack/agent/environment.properties</filename> has a line that reads:</para>
+ <programlisting language="Bash">paths.script=/usr/share/cloudstack-common</programlisting>
+ <para>If not, add the line.</para>
+ </listitem>
+ <listitem>
+ <para>Restart the agent:</para>
+ <programlisting language="Bash">
+ service cloud-agent stop
+ killall jsvc
+ service cloudstack-agent start
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>During the upgrade, <filename>log4j-cloud.xml</filename> was simply copied over, so the logs will continue to be added to <filename>/var/log/cloud/agent/agent.log</filename>. There's nothing <emphasis>wrong</emphasis> with this, but if you prefer to be consistent, you can change this by copying over the sample configuration file:</para>
+ <programlisting language="Bash">
+ cd /etc/cloudstack/agent
+ mv log4j-cloud.xml.dpkg-dist log4j-cloud.xml
+ service cloudstack-agent restart
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>Once the agent is running, you can uninstall the old cloud-* packages from your system:</para>
+ <programlisting language="Bash">sudo dpkg --purge cloud-agent</programlisting>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem id="upgrade-rpm-packages">
+ <para>If you are using CentOS or RHEL, follow this procedure to upgrade your packages. If not, skip to step <xref linkend="restart-system-vms" />.</para>
+ <note><title>Community Packages</title>
+ <para>This section assumes you're using the community supplied packages for &PRODUCT;. If you've created your own packages and yum repository, substitute your own URL for the ones used in these examples.</para>
+ </note>
+ <orderedlist id="rpmsteps">
+ <listitem>
+ <para>The first order of business will be to change the yum repository for each system with &PRODUCT; packages. This means all management servers, and any hosts that have the KVM agent. (No changes should be necessary for hosts that are running VMware or Xen.)</para>
+ <para>Start by opening <filename>/etc/yum.repos.d/cloudstack.repo</filename> on any systems that have &PRODUCT; packages installed.</para>
+ <para>This file should have content similar to the following:</para>
+ <programlisting language="Bash">
+ [apache-cloudstack]
+ name=Apache CloudStack
+ baseurl=http://cloudstack.apt-get.eu/rhel/4.2/
+ enabled=1
+ gpgcheck=0
+ </programlisting>
+ <para>If you are using the community provided package repository, change the baseurl to http://cloudstack.apt-get.eu/rhel/4.1/</para>
+ <para>If you're using your own package repository, change this line to read as appropriate for your 4.2.1 repository.</para>
+ </listitem>
+ <listitem id="rpm-master">
+ <para>Now that you have the repository configured, it's time to install the <filename>cloudstack-management</filename> package by upgrading the older <filename>cloud-client</filename> package.</para>
+ <programlisting language="Bash">$ sudo yum upgrade cloud-client</programlisting>
+ </listitem>
+ <listitem id="kvm-agent-rpm">
+ <para>For KVM hosts, you will need to upgrade the <filename>cloud-agent</filename> package, similarly installing the new version as <filename>cloudstack-agent</filename>.</para>
+ <programlisting language="Bash">$ sudo yum upgrade cloud-agent</programlisting>
+ <para>During the installation of <filename>cloudstack-agent</filename>, the RPM will copy your <filename>agent.properties</filename>, <filename>log4j-cloud.xml</filename>, and <filename>environment.properties</filename> from <filename>/etc/cloud/agent</filename> to <filename>/etc/cloudstack/agent</filename>.</para>
+ </listitem>
+ <listitem>
+ <para>Verify that the file <filename>/etc/cloudstack/agent/environment.properties</filename> has a line that reads:</para>
+ <programlisting language="Bash">paths.script=/usr/share/cloudstack-common</programlisting>
+ <para>If not, add the line.</para>
+ </listitem>
+ <listitem>
+ <para>Restart the agent:</para>
+ <programlisting language="Bash">
+ service cloud-agent stop
+ killall jsvc
+ service cloudstack-agent start
+ </programlisting>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem id="restart-system-vms">
+ <para>Once you've upgraded the packages on your management servers, you'll need to restart the system VMs. Make sure port 8096 is open in your local host firewall to do this.</para>
+ <para>There is a script that will do this for you, all you need to do is run the script and supply the IP address for your MySQL instance and your MySQL credentials:</para>
+ <programlisting language="Bash"><prompt>#</prompt> nohup cloudstack-sysvmadm -d <replaceable>IP address</replaceable> -u cloud -p -a > sysvm.log 2>&1 &</programlisting>
+ <para>You can monitor the log for progress. The process of restarting the system VMs can take an hour or more.</para>
+ <programlisting language="Bash"><prompt>#</prompt> tail -f sysvm.log</programlisting>
+ <para>The output to <filename>sysvm.log</filename> will look something like this:</para>
+ <programlisting language="Bash">
+ Stopping and starting 1 secondary storage vm(s)...
+ Done stopping and starting secondary storage vm(s)
+ Stopping and starting 1 console proxy vm(s)...
+ Done stopping and starting console proxy vm(s).
+ Stopping and starting 4 running routing vm(s)...
+ Done restarting router(s).
+ </programlisting>
+ </listitem>
+ <listitem>
+ <note><title>For Xen Hosts: Copy vhd-utils</title>
+ <para>This step is only for CloudStack installs that are using Xen hosts.</para>
+ </note>
+ <para>Copy the file <filename>vhd-utils</filename> to <filename>/usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver</filename>.</para>
+ </listitem>
+ </orderedlist>
+ </section>
<section id="upgrade-from-3.0.x-to-4.2.1">
<title>Upgrade from 3.0.x to 4.2.1</title>
<para>This section will guide you from Citrix CloudStack 3.0.x to Apache CloudStack 4.2.1.