You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by ra...@apache.org on 2013/11/18 04:37:10 UTC
git commit: updated Book info file, Release notes for 4.2.1 release
Updated Branches:
refs/heads/master f9a2a60b8 -> 01d9e3ce3
updated Book info file, Release notes for 4.2.1 release
Project: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/commit/01d9e3ce
Tree: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/tree/01d9e3ce
Diff: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/diff/01d9e3ce
Branch: refs/heads/master
Commit: 01d9e3ce333aa4b2241cdfc7c971af6aff95d279
Parents: f9a2a60
Author: radhikap <ra...@citrix.com>
Authored: Mon Nov 18 09:06:44 2013 +0530
Committer: radhikap <ra...@citrix.com>
Committed: Mon Nov 18 09:06:44 2013 +0530
----------------------------------------------------------------------
.../en-US/Book_Info_Release_Notes_4.xml | 8 +-
release-notes/en-US/Release_Notes.xml | 292 ++++++++++++++++++-
2 files changed, 287 insertions(+), 13 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/01d9e3ce/release-notes/en-US/Book_Info_Release_Notes_4.xml
----------------------------------------------------------------------
diff --git a/release-notes/en-US/Book_Info_Release_Notes_4.xml b/release-notes/en-US/Book_Info_Release_Notes_4.xml
index e1c270f..d4801a1 100644
--- a/release-notes/en-US/Book_Info_Release_Notes_4.xml
+++ b/release-notes/en-US/Book_Info_Release_Notes_4.xml
@@ -19,12 +19,14 @@
under the License.
-->
<bookinfo id="book-release-notes-4.2">
- <title>Version 4.2.0 Release Notes</title>
+ <title>Version 4.2.1 Release Notes</title>
+ <subtitle>Revised November 18, 2013 9:00 am IST</subtitle>
<productname>Apache &PRODUCT;</productname>
- <productnumber/>
+ <productnumber>4.2.1</productnumber>
+ <edition>1</edition>
<pubsnumber/>
<abstract>
- <para>Release notes for the Apache &PRODUCT; 4.2.0 release.</para>
+ <para>Release notes for the Apache &PRODUCT; 4.2.1 release.</para>
</abstract>
<corpauthor>
<inlinemediaobject>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/01d9e3ce/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 7b28e9f..46db2e0 100644
--- a/release-notes/en-US/Release_Notes.xml
+++ b/release-notes/en-US/Release_Notes.xml
@@ -300,7 +300,7 @@ under the License.
issue number.</para>
<para>For the list of issues fixed, see <ulink
url="https://issues.apache.org/jira/issues/?filter=12325707">Issues Fixed in
- 4.2</ulink>.</para>
+ 4.2.1</ulink>.</para>
</section>
<section id="known-issues-4.2.1">
<title>Known Issues in 4.2.1</title>
@@ -317,13 +317,285 @@ under the License.
made while CloudStack was in the Apache Incubator.</para>
<para>If you run into any issues during upgrades, please feel free to ask questions on
users@cloudstack.apache.org or dev@cloudstack.apache.org.</para>
- <note>
- <title>Overprovisioning cautions</title>
- <para>If the &PRODUCT; instance you are upgrading is leveraging overprovisioning you need to
- read and understand <xref linkend="cpu-ram-overcommit"/>. The overprovisioning factors are
- now cluster specific and should you be overprovisioned, your new system VMs may not start
- up. </para>
- </note>
+ <section id="upgrade-from-4.2-to-4.2.1">
+ <title>Upgrade from 4.2.0 to 4.2.1</title>
+ <para>This section will guide you from &PRODUCT; 4.2 to &PRODUCT; 4.2.1.</para>
+ <para>Any steps that are hypervisor-specific will be called out with a note.</para>
+ <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>
+ </listitem>
+ <listitem>
+ <para>Create RPM or Debian packages (as appropriate) and a repository from the 4.2.1
+ 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-4.2.1"/> or step <xref
+ linkend="upgrade-rpm-packages-4.2.1"/>.</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 cloudstack-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 cloudstack-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>(KVM Only) If primary storage of type local storage is in use, the path for this
+ storage needs to be verified to ensure it passes new validation. Check local storage by
+ querying the cloud.storage_pool table: </para>
+ <programlisting><prompt>#</prompt>mysql -u cloud -p -e "select id,name,path from cloud.storage_pool where pool_type='Filesystem'"</programlisting>
+ <para>If local storage paths are found to have a trailing forward slash, remove it:
+ <programlisting><prompt>#</prompt>mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';</programlisting>
+ </para>
+ </listitem>
+ <listitem id="upgrade-deb-packages-4.2.1">
+ <para>If you are using Ubuntu, follow this procedure to upgrade your packages. If not,
+ skip to step <xref linkend="upgrade-rpm-packages-4.2.1"/>.</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-4.2.1" numeration="loweralpha">
+ <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.2</programlisting>
+ <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>
+ <para>Now update your apt package list:</para>
+ <programlisting language="Bash">$ sudo apt-get update</programlisting>
+ </listitem>
+ <listitem id="deb-master-4.2.1">
+ <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-4.2.1">
+ <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 cloudstack-agent stop
+killall jsvc
+service cloudstack-agent start
+ </programlisting>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem>
+ <para>(VMware only) Additional steps are required for each VMware cluster. These steps
+ will not affect running guests in the cloud. These steps are required only for clouds
+ using VMware clusters:</para>
+ <orderedlist numeration="loweralpha">
+ <listitem>
+ <para>Stop the Management Server:</para>
+ <programlisting>service cloudstack-management stop</programlisting>
+ </listitem>
+ <listitem>
+ <para>Generate the encrypted equivalent of your vCenter password:</para>
+ <programlisting>java -classpath /usr/share/cloudstack-common/lib/jasypt-1.9.0.jar org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI encrypt.sh input="_your_vCenter_password_" password="`cat /etc/cloudstack/management/key`" verbose=false</programlisting>
+ <para>Store the output from this step, we need to add this in cluster_details table
+ and vmware_data_center tables in place of the plain text password</para>
+ </listitem>
+ <listitem>
+ <para>Find the ID of the row of cluster_details table that you have to update:</para>
+ <programlisting>mysql -u <username> -p<password></programlisting>
+ <programlisting>select * from cloud.cluster_details;</programlisting>
+ </listitem>
+ <listitem>
+ <para>Update the plain text password with the encrypted one</para>
+ <programlisting>update cloud.cluster_details set value = '_ciphertext_from_step_1_' where id = _id_from_step_2_;</programlisting>
+ </listitem>
+ <listitem>
+ <para>Confirm that the table is updated:</para>
+ <programlisting>select * from cloud.cluster_details; </programlisting>
+ </listitem>
+ <listitem>
+ <para>Find the ID of the correct row of vmware_data_center that you want to
+ update</para>
+ <programlisting>select * from cloud.vmware_data_center; </programlisting>
+ </listitem>
+ <listitem>
+ <para>update the plain text password with the encrypted one:</para>
+ <programlisting>update cloud.vmware_data_center set password = '_ciphertext_from_step_1_' where id = _id_from_step_5_; </programlisting>
+ </listitem>
+ <listitem>
+ <para>Confirm that the table is updated:</para>
+ <programlisting>select * from cloud.vmware_data_center; </programlisting>
+ </listitem>
+ <listitem>
+ <para>Start the &PRODUCT; Management server </para>
+ <programlisting>service cloudstack-management start</programlisting>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem>
+ <para>(KVM only) Additional steps are required for each KVM host. These steps will not
+ affect running guests in the cloud. These steps are required only for clouds using KVM
+ as hosts and only on the KVM hosts.</para>
+ <orderedlist numeration="loweralpha">
+ <listitem>
+ <para>Configure the CloudStack yum repository as detailed above.</para>
+ </listitem>
+ <listitem>
+ <para>Stop the running agent.</para>
+ <programlisting># service cloud-agent stop</programlisting>
+ </listitem>
+ <listitem>
+ <para>Update the agent software.</para>
+ <programlisting># yum update cloudstack-agent</programlisting>
+ </listitem>
+ <listitem>
+ <para>Start the agent.</para>
+ <programlisting># service cloudstack-agent start</programlisting>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem id="upgrade-rpm-packages-4.2.1">
+ <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-4.2.1"/>.</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-4.2.1" numeration="loweralpha">
+ <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. </para>
+ <para>(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.0/
+enabled=1
+gpgcheck=0
+ </programlisting>
+ <para>If you are using the community provided package repository, change the base url
+ to http://cloudstack.apt-get.eu/rhel/4.2/</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-4.2.1">
+ <para>Now that you have the repository configured, it's time to install the
+ <filename>cloudstack-management</filename> package by upgrading the older
+ <filename>cloudstack-management</filename> package.</para>
+ <programlisting language="Bash">$ sudo yum upgrade cloudstack-management</programlisting>
+ </listitem>
+ <listitem id="kvm-agent-rpm-4.2.1">
+ <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 cloudstack-agent</programlisting>
+ </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 cloudstack-agent stop
+killall jsvc
+service cloudstack-agent start
+ </programlisting>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem id="restart-mgmt-server-4.2.1">
+ <para>Now it's time to restart the management server</para>
+ <programlisting language="Bash"><prompt>#</prompt> service cloudstack-management start</programlisting>
+ </listitem>
+ <listitem id="restart-system-vms-4.2.1">
+ <para>Once you've upgraded the packages on your management servers, you'll need to restart
+ the system VMs. Ensure that the admin port is set to 8096 by using the
+ "integration.api.port" global parameter. This port is used by the cloud-sysvmadm script
+ at the end of the upgrade procedure. For information about how to set this parameter,
+ see "Setting Global Configuration Parameters" in the Installation Guide. Changing this
+ parameter will require management server restart. Also 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-4.0-to-4.2.1">
<title>Upgrade from 4.1.x to 4.2.1</title>
<para>This section will guide you from &PRODUCT; 4.1.x versions to &PRODUCT; 4.2.1.</para>
@@ -1947,8 +2219,8 @@ service cloudstack-agent start
</orderedlist>
</section>
</chapter>
- <chapter id="api-changes-42.1">
- <title>API Changes from 3.0 to 4.2.1</title>
+ <chapter id="api-changes">
+ <title>API Changes from 4.2 to 4.2.1</title>
<para>Due to the <xref linkend="ucs-enhancements"/>, the following API changes have been
introduced:</para>
<itemizedlist>