Merge branch '4.13'
diff --git a/source/_global.rst b/source/_global.rst
index 87044f6..8804b08 100644
--- a/source/_global.rst
+++ b/source/_global.rst
@@ -25,19 +25,19 @@
.. Latest version systemvm template name
-.. |sysvm64-version| replace:: 4.11.3
-.. |sysvm64-name-xen| replace:: systemvm-xenserver-4.11.3
-.. |sysvm64-name-kvm| replace:: systemvm-kvm-4.11.3
-.. |sysvm64-name-vmware| replace:: systemvm-vmware-4.11.3
-.. |sysvm64-name-hyperv| replace:: systemvm-hyperv-4.11.3
-.. |sysvm64-name-ovm| replace:: systemvm-ovm-4.11.3
+.. |sysvm64-version| replace:: 4.14.0
+.. |sysvm64-name-xen| replace:: systemvm-xenserver-4.14.0
+.. |sysvm64-name-kvm| replace:: systemvm-kvm-4.14.0
+.. |sysvm64-name-vmware| replace:: systemvm-vmware-4.14.0
+.. |sysvm64-name-hyperv| replace:: systemvm-hyperv-4.14.0
+.. |sysvm64-name-ovm| replace:: systemvm-ovm-4.14.0
.. Latest version systemvm template URL
-.. |sysvm64-url-xen| replace:: http://download.cloudstack.org/systemvm/4.11/systemvmtemplate-4.11.3-xen.vhd.bz2
-.. |sysvm64-url-kvm| replace:: http://download.cloudstack.org/systemvm/4.11/systemvmtemplate-4.11.3-kvm.qcow2.bz2
-.. |sysvm64-url-vmware| replace:: http://download.cloudstack.org/systemvm/4.11/systemvmtemplate-4.11.3-vmware.ova
-.. |sysvm64-url-hyperv| replace:: http://download.cloudstack.org/systemvm/4.11/systemvmtemplate-4.11.3-hyperv.vhd.zip
-.. |sysvm64-url-ovm| replace:: http://download.cloudstack.org/systemvm/4.11/systemvmtemplate-4.11.3-ovm.raw.bz2
+.. |sysvm64-url-xen| replace:: http://download.cloudstack.org/systemvm/4.14/systemvmtemplate-4.14.0-xen.vhd.bz2
+.. |sysvm64-url-kvm| replace:: http://download.cloudstack.org/systemvm/4.14/systemvmtemplate-4.14.0-kvm.qcow2.bz2
+.. |sysvm64-url-vmware| replace:: http://download.cloudstack.org/systemvm/4.14/systemvmtemplate-4.14.0-vmware.ova
+.. |sysvm64-url-hyperv| replace:: http://download.cloudstack.org/systemvm/4.14/systemvmtemplate-4.14.0-hyperv.vhd.zip
+.. |sysvm64-url-ovm| replace:: http://download.cloudstack.org/systemvm/4.14/systemvmtemplate-4.14.0-ovm.raw.bz2
.. Version specific: 4.5 systemvm template URL
.. |acs45-sysvm64-url-xen| replace:: http://download.cloudstack.org/systemvm/4.5/systemvm64template-4.5-xen.vhd.bz2
diff --git a/source/_static/images/B&R-BackupSchedule.jpg b/source/_static/images/B&R-BackupSchedule.jpg
new file mode 100644
index 0000000..931283c
--- /dev/null
+++ b/source/_static/images/B&R-BackupSchedule.jpg
Binary files differ
diff --git a/source/_static/images/B&R-BackupScheduleEntry.jpg b/source/_static/images/B&R-BackupScheduleEntry.jpg
new file mode 100644
index 0000000..b4b44ba
--- /dev/null
+++ b/source/_static/images/B&R-BackupScheduleEntry.jpg
Binary files differ
diff --git a/source/_static/images/B&R-assignOffering.jpg b/source/_static/images/B&R-assignOffering.jpg
new file mode 100644
index 0000000..9493847
--- /dev/null
+++ b/source/_static/images/B&R-assignOffering.jpg
Binary files differ
diff --git a/source/_static/images/B&R-backup_offering.jpg b/source/_static/images/B&R-backup_offering.jpg
new file mode 100644
index 0000000..8001a7c
--- /dev/null
+++ b/source/_static/images/B&R-backup_offering.jpg
Binary files differ
diff --git a/source/_static/images/B&R-backup_offering_policy.jpg b/source/_static/images/B&R-backup_offering_policy.jpg
new file mode 100644
index 0000000..f0b76c0
--- /dev/null
+++ b/source/_static/images/B&R-backup_offering_policy.jpg
Binary files differ
diff --git a/source/_static/images/B&R-createBackup.jpg b/source/_static/images/B&R-createBackup.jpg
new file mode 100644
index 0000000..756f99d
--- /dev/null
+++ b/source/_static/images/B&R-createBackup.jpg
Binary files differ
diff --git a/source/_static/images/BnR-CreateDummyTag.jpg b/source/_static/images/BnR-CreateDummyTag.jpg
new file mode 100644
index 0000000..98dd44b
--- /dev/null
+++ b/source/_static/images/BnR-CreateDummyTag.jpg
Binary files differ
diff --git a/source/_static/images/BnR-DummyTagCategory.jpg b/source/_static/images/BnR-DummyTagCategory.jpg
new file mode 100644
index 0000000..658ab6b
--- /dev/null
+++ b/source/_static/images/BnR-DummyTagCategory.jpg
Binary files differ
diff --git a/source/_static/images/BnR-VMsandTags.jpg b/source/_static/images/BnR-VMsandTags.jpg
new file mode 100644
index 0000000..aa9fc95
--- /dev/null
+++ b/source/_static/images/BnR-VMsandTags.jpg
Binary files differ
diff --git a/source/_static/images/BnR-backupschedule.jpg b/source/_static/images/BnR-backupschedule.jpg
new file mode 100644
index 0000000..af7259d
--- /dev/null
+++ b/source/_static/images/BnR-backupschedule.jpg
Binary files differ
diff --git a/source/_static/images/cks-add-version-form.png b/source/_static/images/cks-add-version-form.png
new file mode 100644
index 0000000..317a0aa
--- /dev/null
+++ b/source/_static/images/cks-add-version-form.png
Binary files differ
diff --git a/source/_static/images/cks-cluster-access-tab.png b/source/_static/images/cks-cluster-access-tab.png
new file mode 100644
index 0000000..6e3bc33
--- /dev/null
+++ b/source/_static/images/cks-cluster-access-tab.png
Binary files differ
diff --git a/source/_static/images/cks-cluster-dashboard.png b/source/_static/images/cks-cluster-dashboard.png
new file mode 100644
index 0000000..26eab7e
--- /dev/null
+++ b/source/_static/images/cks-cluster-dashboard.png
Binary files differ
diff --git a/source/_static/images/cks-cluster-details-tab.png b/source/_static/images/cks-cluster-details-tab.png
new file mode 100644
index 0000000..be41217
--- /dev/null
+++ b/source/_static/images/cks-cluster-details-tab.png
Binary files differ
diff --git a/source/_static/images/cks-clusters.png b/source/_static/images/cks-clusters.png
new file mode 100644
index 0000000..5b07051
--- /dev/null
+++ b/source/_static/images/cks-clusters.png
Binary files differ
diff --git a/source/_static/images/cks-create-cluster-form.png b/source/_static/images/cks-create-cluster-form.png
new file mode 100644
index 0000000..6e4ad4a
--- /dev/null
+++ b/source/_static/images/cks-create-cluster-form.png
Binary files differ
diff --git a/source/_static/images/cks-delete-action.png b/source/_static/images/cks-delete-action.png
new file mode 100644
index 0000000..ce2b0aa
--- /dev/null
+++ b/source/_static/images/cks-delete-action.png
Binary files differ
diff --git a/source/_static/images/cks-kube-config-action.png b/source/_static/images/cks-kube-config-action.png
new file mode 100644
index 0000000..b06adc3
--- /dev/null
+++ b/source/_static/images/cks-kube-config-action.png
Binary files differ
diff --git a/source/_static/images/cks-scale-action.png b/source/_static/images/cks-scale-action.png
new file mode 100644
index 0000000..c060695
--- /dev/null
+++ b/source/_static/images/cks-scale-action.png
Binary files differ
diff --git a/source/_static/images/cks-scale-cluster-form.png b/source/_static/images/cks-scale-cluster-form.png
new file mode 100644
index 0000000..0ea9655
--- /dev/null
+++ b/source/_static/images/cks-scale-cluster-form.png
Binary files differ
diff --git a/source/_static/images/cks-start-action.png b/source/_static/images/cks-start-action.png
new file mode 100644
index 0000000..913f566
--- /dev/null
+++ b/source/_static/images/cks-start-action.png
Binary files differ
diff --git a/source/_static/images/cks-stop-action.png b/source/_static/images/cks-stop-action.png
new file mode 100644
index 0000000..69d3163
--- /dev/null
+++ b/source/_static/images/cks-stop-action.png
Binary files differ
diff --git a/source/_static/images/cks-upgrade-action.png b/source/_static/images/cks-upgrade-action.png
new file mode 100644
index 0000000..1a1e82a
--- /dev/null
+++ b/source/_static/images/cks-upgrade-action.png
Binary files differ
diff --git a/source/_static/images/cks-upgrade-cluster-form.png b/source/_static/images/cks-upgrade-cluster-form.png
new file mode 100644
index 0000000..6ee97dc
--- /dev/null
+++ b/source/_static/images/cks-upgrade-cluster-form.png
Binary files differ
diff --git a/source/_static/images/cks-versions.png b/source/_static/images/cks-versions.png
new file mode 100644
index 0000000..d219e16
--- /dev/null
+++ b/source/_static/images/cks-versions.png
Binary files differ
diff --git a/source/_static/images/kvm-rolling-maintenance.png b/source/_static/images/kvm-rolling-maintenance.png
new file mode 100644
index 0000000..ce05eb2
--- /dev/null
+++ b/source/_static/images/kvm-rolling-maintenance.png
Binary files differ
diff --git a/source/_static/images/volume-from-snap.PNG b/source/_static/images/volume-from-snap.PNG
new file mode 100644
index 0000000..5eb9a5e
--- /dev/null
+++ b/source/_static/images/volume-from-snap.PNG
Binary files differ
diff --git a/source/adminguide/accounts.rst b/source/adminguide/accounts.rst
index 9d52d30..2a3f2c7 100644
--- a/source/adminguide/accounts.rst
+++ b/source/adminguide/accounts.rst
@@ -43,9 +43,8 @@
subdomains. For example, a service provider with several resellers could
create a domain for each reseller.
-For each account created, the Cloud installation creates three different
-types of user accounts: root administrator, domain administrator, and
-user.
+Beside the Root Administrator type of account (available in the root domain only), two different types
+of accounts can be created for each domain: Domain Administrator and User.
Users
@@ -284,7 +283,12 @@
keeping the users in the domain up to date with their group membership
in LDAP.
-.. Note:: A caveat with this is that ApacheDS does not yet support the virtual 'memberOf' attribute needed to check if a user moved to another account. Microsoft AD and OpenLDAP as well as OpenDJ do support this. It is a planned feature for ApacheDS that can be tracked in https://issues.apache.org/jira/browse/DIRSERVER-1844.
+.. Note:: A caveat with this is that ApacheDS does not yet support the
+ virtual 'memberOf' attribute needed to check if a user moved
+ to another account. Microsoft AD and OpenLDAP as well as
+ OpenDJ do support this. It is a planned feature for ApacheDS
+ that can be tracked in
+ https://issues.apache.org/jira/browse/DIRSERVER-1844.
There are now three ways to link LDAP users to CloudStack users. These
three ways where developed as extensions on top of each other.
@@ -308,10 +312,10 @@
#. The authentication result from LAP is honoured.
-#. **autoimport**. A domain is configured to import any user if it does
- not yet exist in that domain. For these users a account by the same
- name as the user is created on the fly and the user is created in
- that account.
+#. **autoimport**. A domain is configured to import any user if it
+ does not yet exist in that domain. For these users, an account in the
+ same name as the user is automatically created and the user is created
+ in that account.
#. If the domain is configured to be used with LDAP,
@@ -360,20 +364,65 @@
#. If no CloudStack user exists it is created in the
appropriate account.
-
#. If a CloudStack user exists but is not in the appropriate
account its credentials will be moved.
-
To set up LDAP authentication in CloudStack, call the CloudStack API
command ``addLdapConfiguration`` and provide Hostname or IP address
and listening port of the LDAP server. Optionally a domain id can be
given for the domain for which this LDAP connection is valid. You could
-configure multiple servers as well. These are expected to be
+configure multiple servers as well, for the same domain. These are expected to be
replicas. If one fails, the next one is used.
-The following global configurations should also be configured (the
-default values are for openldap)
+.. code:: bash
+
+ cloudmonkey add ldapconfiguration hostname=localhost\
+ port=389\
+ domainid=12345678-90ab-cdef-fedc-ba0987654321
+
+This is all that is required to enable the manual importing of LDAP users, the
+LisLdapUsers API can be used to query for users to import.
+
+For the auto import method, a CloudStack Domain needs to be linked to
+LDAP. For instance
+
+.. code:: bash
+
+ cloudmonkey link domaintoldap domainid=12345678-90ab-cdef-fedc-ba0987654321\
+ accounttype=2\
+ ldapdomain="ou=people,dc=cloudstack,dc=apache,dc=org"\
+ type=OU
+
+When you want to use auto sync, no domain is linked to ldap but one or
+more accounts. Within a CloudStack domain one needs to link accounts
+to LDAP groups. The linkage of the domain is implicit and nit needed
+to be applied through the API call described above.
+
+.. code:: bash
+
+ #!/bin/bash
+ [ -z "$LDAP1PASSWORD" -o -z "$LDAP2PASSWORD" ] && exit 1
+ ROOTDOMAIN=`cloudmonkey -d json list domains name=ROOT filter=id | jq .domain[0].id`
+
+ # mapping domain and account(s) from ldap server 1
+ MAPPEDDOMAIN1=`cloudmonkey -d json create domain name=mappedDomain1 parentdomainid=$ROOTDOMAIN | jq .domain.id`
+ cloudmonkey -d json add ldapconfiguration hostname=10.1.2.5 port=389 domainid=$MAPPEDDOMAIN1
+ cloudmonkey -d json update configuration domainid=$MAPPEDDOMAIN1 name="ldap.basedn" value="dc=cloudstack,dc=apache,dc=org"
+ cloudmonkey -d json update configuration domainid=$MAPPEDDOMAIN1 name='ldap.bind.principal' value='cn=admin,dc=cloudstack,dc=apache,dc=org'
+ cloudmonkey -d json update configuration domainid=$MAPPEDDOMAIN1 name='ldap.bind.password' value=$LDAP1PASSWORD
+ cloudmonkey -d json update configuration domainid=$MAPPEDDOMAIN1 name='ldap.search.group.principle' value='cn=AcsAccessGroup,dc=cloudstack,dc=apache,dc=org'
+ cloudmonkey -d json update configuration domainid=$MAPPEDDOMAIN1 name='ldap.user.memberof.attribute' value='memberOf'
+
+ cloudmonkey -d json ldap createaccount account='seniors' accounttype=2 domainid=$MAPPEDDOMAIN1 username=guru
+ cloudmonkey -d json link accounttoldap account='seniors' accounttype=2 domainid=$MAPPEDDOMAIN1 ldapdomain='cn=AcsSeniorAdmins,ou=AcsGroups,dc=cloudstack,dc=apache,dc=org' type=GROUP
+ cloudmonkey -d json ldap createaccount account='juniors' accounttype=0 domainid=$MAPPEDDOMAIN1 username=bystander
+ cloudmonkey -d json link accounttoldap account='juniors' accounttype=0 domainid=$MAPPEDDOMAIN1 ldapdomain='cn=AcsJuniorAdmins,ou=AcsGroups,dc=cloudstack,dc=apache,dc=org' type=GROUP
+
+
+
+In addition to those shown in the example script above, the following
+configuration items can be configured (the default values are for
+openldap)
- ``ldap.basedn``: Sets the basedn for LDAP. Ex: **OU=APAC,DC=company,DC=com**
@@ -431,14 +480,14 @@
:align: center
-You could also use api commands: ``listLdapUsers``, ``ldapCreateAccount`` and
-``importLdapUsers``.
+You could also use api commands:
+``listLdapUsers``, to list users in LDAP that could or would be imported in CloudStack
+``ldapCreateAccount``, to manually create a user in a specific account
+``importLdapUsers``, to batch import users from LDAP
Once LDAP is enabled, the users will not be allowed to changed password
directly in CloudStack.
-
-
.. |button to dedicate a zone, pod,cluster, or host| image:: /_static/images/dedicate-resource-button.png
Using a SAML 2.0 Identity Provider for User Authentication
diff --git a/source/adminguide/backup_and_recovery.rst b/source/adminguide/backup_and_recovery.rst
new file mode 100644
index 0000000..a85a2a1
--- /dev/null
+++ b/source/adminguide/backup_and_recovery.rst
@@ -0,0 +1,189 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information#
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+About Backup And Recovery
+--------------------------
+
+CloudStack version 4.14 introduces a new Backup and Recovery (B&R) framework that
+provides CloudStack with users the ability to back up their guest VMs for recovery
+purposes via 3rd party backup solutions. The framework abstracts the API commands
+required for common backup and recovery
+operations, from the vendor specific commmands needed to perform those actions and provides
+a plugin model to enable any solution which provides backup and recovery 'like'
+features to be integrated.
+
+The following providers are currently supported:
+
+- VMware with Veeam Backup and Recovery
+
+See the Veeam Backup and Recovery plugin documentation for plugin specific information.
+:ref:`Veeam Backup and Recovery Plugin`
+
+Backup and Recovery Concepts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Backup and recovery has been designed to support two modes:
+
+- ‘SLA’ based backups
+
+- Adhoc and user scheduled backups
+
+'SLA' based backups are ones where the Cloud provider (ie the root admin) controls the time, and frequency of a backup scheme.
+A user signs up for a 'Gold' offering, which might give them a RPO of 12 hours and the last 14 backups kept; however the user would not be
+allowed to perform additional backups nor set the exact time that these backups took place. The user might be charged
+a fix rate for these backups regardless of the size of the backups.
+
+To use an SLA based backup policy the user adds their VMs to the offering/policy. The job then runs at its predetermined times and 'includes' the
+VM when it runs. A user can remove the VM from the offering/policy and it will no longer be included in the job when it runs.
+
+Adhoc and user scheduled backups follow the same idea as volume snapshots, however they leverage the backup solution
+rather than secondary storage. These could likely be billed on backup storage consumed or protected capacity (the full virtual
+size of the VM(s) being backed up.
+
+Adhoc and user scheduled backups are created and managed in the same fashion as volume snapshots are.
+
+
+Configuring Backup and Recovery
+--------------------------------
+
+The cloud administrator can use global configuration variables to
+control the behavior of B&R feature. To set these variables, go through
+the Global Settings area of the CloudStack UI.
+
+.. cssclass:: table-striped table-bordered table-hover
+
+================================= ========================
+Configuration Description
+================================= ========================
+backup.framework.enabled Setting to enable or disable the feature. Default: false.
+backup.framework.provider.plugin The backup provider (plugin) name. For example: 'dummy' and 'veeam'. This is a zone specific setting. Default: dummy.
+backup.framework.sync.interval Background sync task internal in seconds that performs metrics/usage stats collection, backup reconciliation and backup scheduling. Default: 300.
+================================= ========================
+
+Plugin specific settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each backup and recovery plugin is likely to have settings specific to that plugin. Refer to the CloudStack documentation
+for your plugin for details on how to configure those settings.
+
+
+Backup Offerings
+------------------
+
+Admins can import an external provider's backup offerings using UI or API for a
+particular zone, as well as manage a backup offering's lifecyle. Admins can also
+specify if a backup offering allows user-defined backup schedules and ad-hoc
+backups. Users can list and consume the imported backup offerings, only root admins can import or
+delete offerings.
+
+Supported APIs:
+~~~~~~~~~~~~~~~~
+
+- **listBackupProviders**: lists available backup provider plugins
+- **listBackupProviderOfferings**: lists external backup policy/offering from a provider
+- **importBackupProviderOfferings**: allows importing of an external backup policy/offering to CloudStack as a backup offering
+- **listBackupOfferings**: lists CloudStack's backup offerings (searching via keyword, and pagination supported)
+- **deleteBackupOffering**: deletes a backup offering by its ID
+
+Importing Backup Offerings
+-----------------------------
+
+See plugin specific documentation to create 'Backup provider offerings'
+
+To import a backup provider offering;
+
+#. (As root) navigate to Service Offerings, click on the 'select offering' dropdown box and select 'Backup Offerings'
+#. Click on Import Backup Offering
+#. Enter your user-friendly name and description and select the applicable zone. The External ID will then be populated with the
+ template jobs which CloudStack retrieves from the connected provider.
+
+ |B&R-backup_offering_policy.jpg| |B&R-backup_offering.jpg|
+
+Creating VM Backups
+---------------------
+
+SLA/Policy Based backups
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With the backup and recovery feature enabled for a zone, users simply add and
+remove a VM from a backup offering.
+
+|B&R-assignOffering.jpg|
+
+Adhoc and Scheduled Backups
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For backup offerings that allow ad-hoc user backups and user-defined backup
+schedules, user will be allowed to define a backup schedule for a VM that is
+assigned to a backup offering using UI and API. A VM with backup will not be
+allowed to add/remove volumes similar to VM snapshots.
+
+To trigger an adhoc backup of a VM, navigate to the instance and click on the 'Create Backup'
+icon.
+
+|B&R-createBackup.jpg|
+
+To setup a recurring backup schedule, navigate to the instance and click on the 'Backup Schedule'
+icon.
+
+|B&R-BackupSchedule.jpg|
+
+Then set the time and frequency of the backups, click 'Configure' and then 'Close'
+
+|B&R-BackupScheduleEntry.jpg|
+
+Restoring VM Backups
+---------------------
+
+Users will need to stop a VM to restore to any existing VM backup, restoration
+of an expunged VM will not restore nics and recovery any network which may/may
+not exist. User may however restore a specific volume from a VM backup and attach
+that volume to a specified VM.
+
+Supported APIs:
+~~~~~~~~~~~~~~~~
+
+- **assignVirtualMachineToBackupOffering**: adds a VM to a backup offering.
+- **removeVirtualMachineFromBackupOffering**: removes a VM from a backup offering, if forced `true` parameter is passed this may also
+ remove any and all the backups of a VM associated with a backup offering.
+- **createBackupSchedule**: creates a backup schedule for a VM.
+- **updateBackupSchedule**: updates backup schedule.
+- **listBackupSchedule**: returns backup schedule of a VM if defined.
+- **deleteBackupSchedule**: deletes backup schedule of a VM.
+- **createBackup**: creates an adhoc backup for a VM.
+- **deleteVMBackup**: deletes a VM backup (not support for per restore point for Veeam).
+- **listBackups**: lists backups.
+- **restoreBackup**: restore a previous VM backup in-place of a stopped or destroyed VM.
+- **restoreVolumeFromBackup**: restore and attach a backed-up volume (of a VM backup) to a specified VM.
+
+
+.. |B&R-assignOffering.jpg| image:: /_static/images/B&R-assignOffering.jpg
+ :alt: Assigning an SLA/Policy to a VM.
+ :width: 400 px
+.. |B&R-backup_offering_policy.jpg| image:: /_static/images/B&R-backup_offering_policy.jpg
+ :alt: Importing an SLA/Policy offering.
+ :width: 300 px
+.. |B&R-backup_offering.jpg| image:: /_static/images/B&R-backup_offering.jpg
+ :alt: Importing a template backup offering.
+ :width: 300 px
+.. |B&R-createBackup.jpg| image:: /_static/images/B&R-createBackup.jpg
+ :alt: Triggering an adhoc backup for a VM.
+ :width: 400 px
+.. |B&R-BackupSchedule.jpg| image:: /_static/images/B&R-BackupSchedule.jpg
+ :alt: Creating a backup schedule for a VM.
+ :width: 400 px
+.. |B&R-BackupScheduleEntry.jpg| image:: /_static/images/B&R-BackupScheduleEntry.jpg
+ :alt: Creating a backup schedule for a VM.
+ :width: 400px
diff --git a/source/adminguide/hosts.rst b/source/adminguide/hosts.rst
index 9693f55..9262379 100644
--- a/source/adminguide/hosts.rst
+++ b/source/adminguide/hosts.rst
@@ -845,3 +845,129 @@
.. _`hooks`: https://libvirt.org/hooks.html
.. _`qemu`: https://libvirt.org/hooks.html#qemu
.. _`arguments`: https://libvirt.org/hooks.html#arguments
+
+
+KVM Rolling Maintenance
+-----------------------
+
+Overview
+~~~~~~~~
+
+CloudStack provides a flexible framework for automating the upgrade or patch process of KVM hosts within a zone, pod or cluster by executing custom scripts. These scripts are executed in the context of a stage. Each stage defines only one custom script to be executed.
+
+There are four stages in the KVM rolling maintenance process:
+
+#. Pre-Flight stage: Pre-flight script (``PreFlight`` or ``PreFlight.sh`` or ``PreFlight.py``) runs on hosts before commencing the rolling maintenance. If pre-flight check scripts return an error from any host, then rolling maintenance will be cancelled with no actions taken, and an error returned. If there are no pre-flight scripts defined, then no checks will be done from the hosts.
+
+#. Pre-Maintenace stage: Pre-maintenance script ((``PreMaintenance`` or ``PreMaintenance.sh`` or ``PreMaintenance.py``)) runs before a specific host is put into maintenance. If no pre-maintenance script is defined, then no pre-maintenance actions will be taken, and the management server will move straight to putting the host in maintenance followed by requesting that the agent runs the maintenance script.
+
+#. Maintenance stage: Maintenance script ((``Maintenance`` or ``Maintenance.sh`` or ``Maintenance.py``)) runs after a host has been put into maintenance. If no maintenance script is defined, or if the pre-flight or pre-maintenance scripts determine that no maintenance is required, then the host will not be put into maintenance, and the completion of the pre-maintenance scripts will signal the end of all maintenance tasks and the KVM agent will hand the host back to the management server. Once the maintenance scripts have signalled that it has completed, the host agent will signal to the management server that the maintenance tasks have completed, and therefore the host is ready to exit maintenance mode and any 'information' which was collected (such as processing times) will be returned to the management server.
+
+#. Post-Maintenance stage: Post-maintenance script ((``PostMaintenance`` or ``PostMaintenance.sh`` or ``PostMaintenance.py``)) is expected to perform validation after the host exits maintenance. These scripts will help to detect any problem during the maintenance process, including reboots or restarts within scripts.
+
+.. note::
+ Pre-flight and pre-maintenance scripts’ execution can determine if the maintenance stage is not required for a host. The special exit code = 70 on a pre-flight or pre-maintenance script will let CloudStack know that the maintenance stage is not required for a host.
+
+Administrators must define only one script per stage. In case a stage does not contain a script, it is skipped, continuing with the next stage. Administrators are responsible for defining and copying scripts into the hosts
+
+.. note::
+ The administrator will be responsible for the maintenance and copying of the scripts across all KVM hosts.
+
+On all the KVM hosts to undergo rolling maintenance, there are two types of script execution approaches:
+
+- Systemd service executor: This approach uses a systemd service to invoke a script execution. Once a script finishes its execution, it will write content to a file, which the agent reads and sends back the result to the management server.
+
+- Agent executor: The CloudStack agent invokes a script execution within the JVM. In case the agent is stopped or restarted, the management server will assume the stage was completed when the agent reconnects. This approach does not keep the state in a file.
+
+Configuration
+~~~~~~~~~~~~~
+
+The rolling maintenance process can be configured through the following global settings in the management server:
+
+- ``kvm.rolling.maintenance.stage.timeout``: Defines the timeout (in seconds) for rolling maintenance stage update from hosts to the management servers. The default value is 1800. This timeout is observed per stage.
+
+- ``kvm.rolling.maintenance.ping.interval``: Defines the ping interval (in seconds) between management server and hosts performing stages during rolling maintenance. The management server checks for updates from the hosts every ‘ping interval’ seconds. The default value is 10.
+
+- ``kvm.rolling.maintenance.wait.maintenance.timeout``: Defines the timeout (in seconds) to wait for a host preparing to enter maintenance mode as part of a rolling maintenance process. The default value is 1800.
+
+On each KVM host, the administrator must indicate the directory in which the scripts have been defined, be editing the ``agent.properties`` file, adding the property:
+
+- ``rolling.maintenance.hooks.dir=<SCRIPTS_DIR>``
+
+Optionally, the administrator can decide to disable the systemd executor for the rolling maintenance scripts on each host (enabled by default), allowing the agent to invoke the scripts through the agent execution. This can be done by editing the ``agent.properties`` file, adding the property:
+
+- ``rolling.maintenance.service.executor.disabled=true``
+
+Usage
+~~~~~
+
+An administrator can invoke a rolling maintenance process by the ``startRollingMaintenance`` API or through the UI, by selecting one or more zones, pods, clusters or hosts.
+
+The ``startRollingMaintenance`` API accepts the following parameters:
+
+- ``hostids``, ``clusterids``, ``podids`` and ``zoneids`` are mutually exclusive, and only one of them must be passed. Each of the mentioned parameters expects a comma-separated list of ids of the entity that it defines.
+
+- ``forced``: optional boolean parameter, false by default. When enabled, does not stop iterating through hosts in case of any error in the rolling maintenance process.
+
+- ``timeout``: optional parameter, defines a timeout in seconds for a stage to be completed in a host. This parameter takes precedence over the timeout defined in the global setting ``kvm.rolling.maintenance.stage.timeout``.
+
+.. note::
+ The timeout (defined by the API parameter or by the global setting) must be greater or equal than the ping interval defined by the global setting ‘kvm.rolling.maintenance.ping.interval’. In case the timeout is lower than the ping interval, the API does not start any maintenance actions and fails fast with a descriptive message.
+
+- ``payload``: optional string parameter, adds extra arguments to be passed to the scripts on each stage. The string set as parameter is used to invoke each of the scripts involved in the rolling maintenance process for each stage, by appending the payload at the end of the script invocation.
+
+.. note::
+ The payload parameter is appended at the end of each stage script execution. This allows the administrator to define scripts that can accept parameters and pass them through the payload parameter to each stage execution. For example: defining the payload parameter to “param1=val1 param2=val2” will pass both parameter to each stage execution, similar to execute: ‘./script param1=val1 param2=val2’.
+
+
+In the UI, the administrator must select one or multiple zones, pods, clusters or hosts and click the button: |kvm-rolling-maintenance.png|
+
+.. note::
+ Keep in mind that the rolling maintenance job results are not shown in the UI. To see the job output, one must use API/CLI (i.e. CloudMonkey).
+
+.. |kvm-rolling-maintenance.png| image:: /_static/images/kvm-rolling-maintenance.png
+
+Process
+~~~~~~~
+
+Before attempting any maintenance actions, pre-flight and capacity checks are performed on every host:
+
+#. The management server performs capacity checks to ensure that every host in the specified scope can be set into maintenance. These checks include host tags, affinity groups and compute checks
+
+#. The pre-flight scripts are executed on each host. If any of these scripts fail, then no action is performed unless the ‘force’ parameter is enabled.
+
+The pre-flight script may signal that no maintenance is needed on the host. In that case, the host is skipped from the rolling maintenance hosts iteration.
+
+Once pre-flight checks pass, then the management server iterates through each host in the selected scope and sends a command to execute each of the rest of the stages in order. The hosts in the selected scope are grouped by clusters, therefore all the hosts in a cluster are processed before processing the hosts of a different cluster.
+
+The management server iterates through hosts in each cluster on the selected scope and for each of the hosts does the following:
+
+- Disables the cluster (if it has not been disabled previously)
+- The existence of the maintenance script on the host is checked (this check is performed only for the maintenance script, not for the rest of the stages)
+
+ - If the host does not contain a maintenance script, then the host is skipped and the iteration continues with the next host in the cluster.
+
+- Execute pre-maintenance script (if any) before entering maintenance mode.
+
+ - The pre-maintenance script may signal that no maintenance is needed on the host. In that case, the host is skipped and the iteration continues with the next host in the cluster.
+
+ - In case the pre-maintenance script fails and the ‘forced’ parameter is not set, then the rolling maintenance process fails and an error is reported. If the ‘forced’ parameter is set, the host is skipped and the iteration continues with the next host in the cluster
+
+- Capacity checks are recalculated, to verify that the host can enter maintenance mode.
+
+ .. note::
+ Before recalculating the capacity, the capacity is updated, similar to performing a listCapacity API execution, setting the ‘fetchLatest’ parameter to true
+
+- The host is instructed to enter the maintenance mode. If the host doesn't enter the maintenance mode after ‘kvm.rolling.maintenance.wait.maintenance.timeout’ seconds an exception is thrown and the API will stop executing, but the host may eventually reach the maintenance mode as this is out of the control of the rolling maintenance API/code.
+
+- Execute maintenance script (if any) while the host is in maintenance.
+
+ - In case the maintenance script fails and the ‘forced’ parameter is not set, the rolling maintenance process fails, maintenance mode is cancelled and an error is reported. If the ‘forced’ parameter is set, the host is skipped and the iteration continues with the next host in the cluster
+
+- Cancel maintenance mode
+
+- Execute post maintenance script (if any) after cancelling maintenance mode.
+
+ - In case the post-maintenance script fails and the ‘forced’ parameter is not set, then the rolling maintenance process fails and an error is reported. If the ‘forced’ parameter is set, the host is skipped and the iteration continues with the next host in the cluster
+
+- Enable the cluster that has been disabled, after all the hosts in the cluster have been processed, or in case an error has occurred.
diff --git a/source/adminguide/index.rst b/source/adminguide/index.rst
index 15ed4d0..b4865bb 100644
--- a/source/adminguide/index.rst
+++ b/source/adminguide/index.rst
@@ -81,8 +81,8 @@
virtual_machines
-Working with Templates
-----------------------
+Working with Templates & ISOs
+------------------------------
.. toctree::
:maxdepth: 4
diff --git a/source/adminguide/networking/isolation_in_advanced_zone_with_vlan.rst b/source/adminguide/networking/isolation_in_advanced_zone_with_vlan.rst
index 33fda6f..745facc 100644
--- a/source/adminguide/networking/isolation_in_advanced_zone_with_vlan.rst
+++ b/source/adminguide/networking/isolation_in_advanced_zone_with_vlan.rst
@@ -40,9 +40,9 @@
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Of the three types of Private VLAN (promiscuous, community and isolated),
-CloudStack supports **one promiscuous** PVLAN and **one isolated** PVLAN **per
-primary VLAN**. Ergo, community PVLANs are not currently supported.
-PVLANs are only currently supported on shared networks.
+CloudStack supports **one promiscuous** PVLAN, **one isolated** PVLAN and **multiple community** PVLANs **per
+primary VLAN**.
+PVLANs are currently supported on shared and layer 2 networks.
The PVLAN concept is supported on KVM (when using OVS), XenServer (when using OVS), and VMware hypervisors
.. note::
@@ -50,6 +50,9 @@
CloudStack managed to simulate PVLAN on OVS for XenServer and KVM by
modifying the flow table.
+ .. note::
+ Community PVLANs are only currently supported on VMware hypervisors.
+
Prerequisites
~~~~~~~~~~~~~
@@ -77,23 +80,34 @@
- Before you use PVLAN on XenServer and KVM, enable Open vSwitch (OVS).
-Creating a PVLAN-Enabled Shared Network
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Creating a PVLAN-Enabled Network
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-For a general description of how to create a shared netowrk see `"configuring a shared guest network" <#configuring-a-shared-guest-network>`_.
+PVLAN-enabled networks can be either shared or layer 2 networks.
-On top of the parameters required to create a *normal* shared network, the following
+For a general description of how to create a shared network see `"configuring a shared guest network" <#configuring-a-shared-guest-network>`_.
+
+On top of the parameters required to create a *normal* shared or layer 2 network, the following
parameters must be set:
- **VLAN ID**: The unique ID of the primary VLAN that you want to use.
-- **Secondary Isolated VLAN ID**:
+- **Secondary Isolated VLAN ID**: The PVLAN ID to use within the primary VLAN.
- - For a **promiscuous** PVLAN, set this to the same VLAN ID as the primary VLAN
- that the promiscuous PVLAN will be inside.
- - For an **isolated** PVLAN, set this to the PVLAN ID which you wish to use
- inside the primary VLAN.
+- **PVLAN Type**: The PVLAN type corresponding to the PVLAN ID to use within the primary VLAN.
+Creating a PVLAN-enabled network can be done in multiple ways depending on the PVLAN type:
+
+ - For a **promiscuous** PVLAN:
+ - Set the secondary VLAN ID to the same VLAN ID as the primary VLAN that the promiscuous PVLAN will be inside (available only via API, not UI), or
+ - Set the PVLAN type to "Promiscuous" and do not set the secondary VLAN ID.
+
+ - For an **isolated** PVLAN:
+ - Set the secondary VLAN ID to the PVLAN ID which you wish to use inside the primary VLAN (available only via API, not UI), or
+ - Set the PVLAN type to "Isolated" and set the secondary VLAN ID to the PVLAN ID which you wish to use inside the primary VLAN.
+
+ - For a **community** PVLAN:
+ - Set the PVLAN type to "Community" and set the secondary VLAN ID to the PVLAN ID which you wish to use inside the primary VLAN.
.. |pvlans.png| image:: /_static/images/pvlans.png
:alt: Diagram of PVLAN communications
diff --git a/source/adminguide/storage.rst b/source/adminguide/storage.rst
index 44f5fcb..987dd5f 100644
--- a/source/adminguide/storage.rst
+++ b/source/adminguide/storage.rst
@@ -230,6 +230,15 @@
volume. This optimization allows the CloudStack to provision the volume
nearest to the guest that will use it when the first attachment is made.
+When creating a new volume from an existing ROOT volume snapshot,
+it is required to explicitly define a Disk offering (UI will offer only Disk
+offerings whose disk size is equal or bigger than the size of the snapshot).
+
+|volume-from-snap.PNG|
+
+When creating a new volume from an existing DATA volume snapshot, the disk offering
+associated with the snapshots (inherited from the original volume) is assigned
+to the new volume.
Using Local Storage for Data Volumes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -657,7 +666,6 @@
A completed snapshot is copied from primary storage to secondary
storage, where it is stored until deleted or purged by newer snapshot.
-
How to Snapshot a Volume
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -671,6 +679,21 @@
#. Click the Snapshot button. |SnapshotButton.png|
+KVM volume Snapshot specifics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In recent CloudStack versions, by default, creating a volume snapshot for a running VM is disabled
+due to a possible volume corruption in certain cases. To enable creating a volume snapshots while the VM
+is running, the global setting 'kvm.snapshot.enabled' must be set to 'True'.
+
+The volume snapshot creation has changed in recent versions:
+
+Under the hood, first, a full VM snapshot is taken - this means that during the taking of
+the VM snapshot the VM will be in the "Paused" state (while RAM memory is being written to the
+QCOW2 file), which means that VM will be unavailable from the network point of view.
+When the VM snapshot is created, VM is unpaused/resumed, the single volume snapshot is exported
+to the Secondary Storage, and then the VM snapshots is removed from the VM.
+
Automatic Snapshot Creation and Retention
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -802,3 +825,5 @@
:alt: Detach Disk Button.
.. |Migrateinstance.png| image:: /_static/images/migrate-instance.png
:alt: button to migrate a volume.
+.. |volume-from-snap.PNG| image:: /_static/images/volume-from-snap.PNG
+ :alt: Offering is needed when creating a volume from the ROOT volume snapshot.
diff --git a/source/adminguide/systemvm.rst b/source/adminguide/systemvm.rst
index 4c3da98..43eaeb3 100644
--- a/source/adminguide/systemvm.rst
+++ b/source/adminguide/systemvm.rst
@@ -88,6 +88,51 @@
#. Restart the Management Server.
+Accessing System VMs
+--------------------
+
+It may sometimes be necessary to access System VMs for diagnostics of certain
+issues, for example if you are experiencing SSVM (Secondary Storage VM)
+connection issues. Use the steps below in order to connect to the SSH console
+of a running System VM.
+
+Accessing System VMs over the network requires the use of private keys and
+connecting to System VMs SSH Daemon on port 3922. XenServer/KVM Hypervisors
+store this key at /root/.ssh/id_rsa.cloud on each CloudStack agent. To access
+System VMs running on ESXi, the key is stored on the management server at
+/var/lib/cloudstack/management/.ssh/id_rsa.
+
+
+#. Find the details of the System VM
+
+ #. Log in with admin privileges to the CloudStack UI.
+
+ #. Click Infrastructure, then System VMs, and then click the name of a
+ running VM.
+
+ #. Take a note of the 'Host', 'Private IP Address' and 'Link Local IP
+ Address' of the System VM you wish to access.
+
+#. XenServer/KVM Hypervisors
+
+ #. Connect to the Host of which the System VM is running.
+
+ #. SSH to the 'Link Local IP Address' of the System VM from the Host on
+ which the VM is running.
+
+ Format: ssh -i <path-to-private-key> <link-local-ip> -p 3922
+
+ Example: root@kvm01:~# ssh -i /root/.ssh/id_rsa.cloud 169.254.3.93 -p 3922
+
+#. ESXi Hypervisors
+
+ #. Connect to your CloudStack Management Server.
+
+ #. ESXi users should SSH to the private IP address of the System VM.
+
+ Format: ssh -i <path-to-private-key> <vm-private-ip> -p 3922
+
+ Example: root@management:~# ssh -i /var/lib/cloudstack/management/.ssh/id_rsa 172.16.0.250 -p 3922
Multiple System VM Support for VMware
-------------------------------------
@@ -147,7 +192,7 @@
By default, the console viewing functionality uses plaintext HTTP. In
any production environment, the console proxy connection should be
-encrypted via SSL at the mininum.
+encrypted via SSL at the minimum.
A CloudStack administrator has 2 ways to secure the console proxy
communication with SSL:
@@ -196,7 +241,7 @@
openssl req -new -key yourprivate.key -out yourcertificate.csr
- #. Head to the website of your favorite trusted Certificate
+ #. Head to the website of your favourite trusted Certificate
Authority, purchase an SSL certificate, and submit the CSR. You
should receive a valid certificate in return
@@ -259,11 +304,11 @@
- Unable to build keystore for CPVMCertificate due to CertificateException
- Cold not find and construct a valid SSL certificate
-that means that still some of the Root/intermediate/server certificates or the key is not in a good format, or incorrectly encoded or multiply Root CA/Intemediate CA present in database by mistake.
+that means that still some of the Root/intermediate/server certificates or the key is not in a good format, or incorrectly encoded or multiply Root CA/Intermediate CA present in database by mistake.
Other way to renew Certificates (Root,Intermediates,Server certificates and key) - although not recommended
unless you fill comfortable - is to directly edit the database,
-while still respect the main requirement that the private key is PKCS8 encoded, while Root CA, Intemediate and Server certificates
+while still respect the main requirement that the private key is PKCS8 encoded, while Root CA, Intermediate and Server certificates
are still in default PEM format (no URL encoding needed here).
After editing the database, please restart management server, and destroy SSVM and CPVM after that,
so the new SSVM and CPVM with new certificates are created.
@@ -366,7 +411,7 @@
Various services running on the CloudStack virtual routers can be
monitored by using a Service Monitoring tool. The tool ensures that
services are successfully running until CloudStack deliberately disables
-them. If a service goes down, the tool automatically restarts the
+them. If a service goes down, the tool automatically attempts to restart
service, and if that does not help bringing up the service, an alert as
well as an event is generated indicating the failure. A new global
parameter, ``network.router.enableservicemonitoring``, has been
@@ -385,17 +430,17 @@
.. note::
Only those services with daemons are monitored. The services that are
failed due to errors in the service/daemon configuration file cannot
- be restarted by the Monitoring tool. VPC networks are not supported.
+ be restarted by the Monitoring tool. VPC Networks are supported (as of CloudStack 4.14)
The following services are monitored in a VR:
-- DNS
+- DNS (dnsmasq)
-- HA Proxy
+- HAProxy (haproxy)
-- SSH
+- SSH (sshd)
-- Apache Web Server
+- Apache Web Server (apache2)
The following networks are supported:
@@ -403,11 +448,217 @@
- Shared Networks in both Advanced and Basic zone
- .. note:: VPC networks are not supported
+- VPC (as of CloudStack 4.14)
This feature is supported on the following hypervisors: XenServer,
VMware, and KVM.
+Log file /var/log/routerServiceMonitor.log contains the actions undertaken/attempted
+by the service monitoring script (i.e. trying to restart a stopped service).
+
+As of CloudStack 4.14, the interval at which the service monitoring script runs
+is no more hardcoded to 3 minutes, but is instead controlled via
+global setting router.health.checks.basic.interval.
+
+
+Health checks for Virtual Router
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to monitoring services as of 4.14 CloudStack adds a framework
+for more extensive health checks. The health checks are split into two
+categories - basic and advanced. The two categories have their own admin
+definable intervals. The split is made this way as the advanced health checks
+are considerably more expensive. The health checks will be available on-demand
+via API as well as scheduled.
+
+The following tests are covered: · Basic connectivity from the management server
+to the virtual router
+
+- Basic connectivity to virtual router its interfaces' gateways
+
+- Free disk space on virtual router's disk
+
+- CPU and memory usage
+
+- Basic VR Sanity checks:
+
+ #. Ssh/dnsmasq/haproxy/httpd service running
+
+- Advanced VR Sanity checks:
+
+ #. DHCP/DNS configuration matches mgmt server DB
+
+ #. IPtables rules match management server records
+
+ #. HAproxy config matches mgmt server DB records
+
+ #. VR Version against current version
+
+
+This happens in the following steps:
+
+1. Management server periodically pushes data to each running virtual router
+including schedule intervals, tests to skip, some configuration for LB, VMs,
+Gateways, etc.
+
+2. Basic and advanced tests as scheduled as per the intervals in the data sent
+by Management server. Each run of checks populates it’s results and saves it
+within the router at ‘/root/basic_monitor_results.json’ and
+'/root/advance_monitor_results.json’. Each run of checks also keeps
+track of the start time, end time, and duration of test run for better
+understanding.
+
+3. Each test is also available on demand via ' getRouterHealthCheckResults'
+API added with the patch. The API can be executed from CLI and UI. Performing
+fresh checks is expensive and will cause management server doing the following:
+
+ a. Refresh the data from Management server records on the router for
+ verification (repeat of step 1),
+
+ b. Run all the checks of both basic and advanced type,
+
+ c. Fetch the result of the health check from router to be sent back in response.
+
+4. The patch also supports custom health checks with custom systemVM templates.
+This is achieved as follows:
+
+ a. Each executable script placed in '/root/health_scripts/' is considered an
+ independent health check and is executed on each scheduled or on demand health check run.
+
+ b. The health check script can be in any language but executable (use 'chmod a+x')
+ within '/root/health_checks/' directory. The placed script must do the following:
+
+ #. Accept a command line parameter for check type (basic or advanced) - this
+ parameter is sent by the internal cron job in the VR (/etc/cron.d/process)
+
+ #. Proceed and perform checks as per the check type - basic or advanced
+
+ #. In order to be recognized as a health check and displayed in the list of health
+ checks results, it must print some message to STDOUT which is passed back as message
+ to management server - if the script doesn’t return anything on its STDOUT, it
+ will not be registered as a health check/displayed in the list of the health check results
+
+ #. exit with status of 0 if check was successful and exit with status of 1 if
+ check has failed
+
+ .. code:: bash
+
+ #!/bin/bash if [$1 == ‘advanced’] { do advance checks and print any message to STDOUT }
+ else if [$1 == ‘basic’] { do basic checks and print any message to STDOUT } exit(0) if pass or exit(1) if failure
+
+ #. i.e. if the script is intended to be i.e. a basic check, it must checks
+ for the presence of the 'basic' as the first parameter sent to it, and execute the
+ wanted commands and print some output to STDOUT; otherwise if it receives 'advanced'
+ as the first parameter, it should not execute any commands/logic nor print anything to STDOUT
+
+5. There are 9 health check scripts written in default systemvm template in '/root/health_checks/'
+folder. These indicate the health checks described in executive summary.
+
+6. The management server will connect periodically to each virtual router to confirm that the
+checks are running as scheduled, and retrieve the results of those checks. Any failing checks
+present in ``router.health.checks.failures.to.restart.vr`` will cause the VR to be recreated.
+On each check management server will persist only the last executed check results in its database.
+
+7. UI parses the returned health check results and shows the router 'Health Check'
+column in 'Failed'/'Passed' if there are health check failures of any type.
+
+Following global configs have been added for configuring health checks:
+
+ - ``router.health.checks.enabled`` - If true, router health checks are allowed
+ to be executed and read. If false, all scheduled checks and API calls for on
+ demand checks are disabled. Default is true.
+
+ - ``router.health.checks.basic.interval`` - Interval in minutes at which basic
+ router health checks are performed. If set to 0, no tests are scheduled. Default
+ is 3 mins as per the pre 4.14 monitor services.
+
+ - ``router.health.checks.advanced.interval`` - Interval in minutes at which
+ advanced router health checks are performed. If set to 0, no tests are scheduled.
+ Default value is 10 minutes.
+
+ - ``router.health.checks.config.refresh.interval`` - Interval in minutes at which
+ router health checks config - such as scheduling intervals, excluded checks, etc
+ is updated on virtual routers by the management server. This value should be
+ sufficiently high (like 2x) from the router.health.checks.basic.interval and
+ router.health.checks.advanced.interval so that there is time between new results
+ generation for passed data. Default is 10 mins.
+
+ - ``router.health.checks.results.fetch.interval`` - Interval in minutes at which
+ router health checks results are fetched by management server. On each result fetch,
+ management server evaluates need to recreate VR as per configuration of
+ 'router.health.checks.failures.to.recreate.vr'. This value should be sufficiently
+ high (like 2x) from the 'router.health.checks.basic.interval' and
+ 'router.health.checks.advanced.interval' so that there is time between new
+ results generation and fetch.
+
+ - ``router.health.checks.failures.to.recreate.vr`` - Health checks failures defined
+ by this config are the checks that should cause router recreation. If empty the
+ recreate is not attempted for any health check failure. Possible values are comma
+ separated script names from systemvm’s /root/health_scripts/ (namely - cpu_usage_check.py,
+ dhcp_check.py, disk_space_check.py, dns_check.py, gateways_check.py, haproxy_check.py,
+ iptables_check.py, memory_usage_check.py, router_version_check.py), connectivity.test
+ or services (namely - loadbalancing.service, webserver.service, dhcp.service)
+
+ - ``router.health.checks.to.exclude`` - Health checks that should be excluded when
+ executing scheduled checks on the router. This can be a comma separated list of
+ script names placed in the '/root/health_checks/' folder. Currently the following
+ scripts are placed in default systemvm template - cpu_usage_check.py,
+ disk_space_check.py, gateways_check.py, iptables_check.py, router_version_check.py,
+ dhcp_check.py, dns_check.py, haproxy_check.py, memory_usage_check.py.
+
+ - ``router.health.checks.free.disk.space.threshold`` - Free disk space threshold
+ (in MB) on VR below which the check is considered a failure. Default is 100MB.
+
+ - ``router.health.checks.max.cpu.usage.threshold`` - Max CPU Usage threshold as
+ % above which check is considered a failure.
+
+ - ``router.health.checks.max.memory.usage.threshold`` - Max Memory Usage threshold
+ as % above which check is considered a failure.
+
+The scripts for following health checks are provided in '/root/health_checks/'. These
+are not exhaustive and can be modified for covering other scenarios not covered.
+Details of individual checks:
+
+1. Basic checks:
+
+ a. Services check (ssh, dnsmasq, httpd, haproxy)– this check is still done as
+ per existing monitorServices.py script and any services not running are attempted
+ to be restarted.
+
+ b. Disk space check against a threshold – python's ' statvfs' module is used to
+ retrieve statistics and compare with the configured threshold given by
+ management server.
+
+ c. CPU usage check against a threshold – we use 'top' utility to retrieve idle
+ CPU and compare that with the configured max CPU usage threshold given by management
+ server.
+
+ d. Memory usage check against a threshold – we use 'free' utility to get the
+ used memory and compare that with the configured max memory usage threshold.
+
+ e. Router template and scripts version check – is done by comparing the contents
+ of the '/etc/cloudstack-release' and '/var/cache/cloud/cloud-scripts-signature'
+ with the data given by management server.
+
+ f. Connectivity to the gateways from router – this is done by analysing the success
+ or failure of ping to the gateway IPs given by management server.
+
+2. Advanced checks:
+
+ a. DNS config match against MS – this is checked by comparing entries of '/etc/hosts'
+ on the VR and VM records passed by management server.
+
+ b. DHCP config match against MS – this is checked by comparing entries of
+ '/etc/dhcphosts.txt' on the VR with the VM entries passed by management server.
+
+ c. HA Proxy config match against MS (internal LB and public LB) - this is checked
+ by verifying the max connections, and entries for each load balancing rule in the
+ '/etc/haproxy/haproxy.cfg' file. We do not check for stickiness properties yet.
+
+ d. Port forwarding match against MS in iptables. - this is checked by verifying
+ IPs and ports in the 'iptables-save' command output against an expected list of
+ entries from management server.
+
Enhanced Upgrade for Virtual Routers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -589,7 +840,3 @@
Non-Alphanumeric characters (metacharacters) are not allowed for this parameter
except for the “-“ and the “.”. Any metacharacter supplied will immediately result
in an immediate termination of the command and report back to the operator that an illegal character was passed
-
-
-
-
diff --git a/source/adminguide/templates.rst b/source/adminguide/templates.rst
index 6c43dba..deb6159 100644
--- a/source/adminguide/templates.rst
+++ b/source/adminguide/templates.rst
@@ -13,6 +13,8 @@
specific language governing permissions and limitations
under the License.
+Working With Templates
+=======================
A template is a reusable configuration for virtual machines. When users
launch VMs, they can choose from a list of templates in CloudStack.
@@ -383,6 +385,156 @@
to run. However, new VMs cannot be created based on the deleted
template.
+Working with ISOs
+===================
+
+CloudStack supports ISOs and their attachment to guest VMs. An ISO is a
+read-only file that has an ISO/CD-ROM style file system. Users can
+upload their own ISOs and mount them on their guest VMs.
+
+ISOs are uploaded based on a URL. HTTP is the supported protocol. Once
+the ISO is available via HTTP specify an upload URL such as
+http://my.web.server/filename.iso.
+
+ISOs may be public or private, like templates.ISOs are not
+hypervisor-specific. That is, a guest on vSphere can mount the exact
+same image that a guest on KVM can mount.
+
+ISO images may be stored in the system and made available with a privacy
+level similar to templates. ISO images are classified as either bootable
+or not bootable. A bootable ISO image is one that contains an OS image.
+CloudStack allows a user to boot a guest VM off of an ISO image. Users
+can also attach ISO images to guest VMs. For example, this enables
+installing PV drivers into Windows. ISO images are not
+hypervisor-specific.
+
+
+Adding an ISO
+---------------
+
+To make additional operating system or other software available for use
+with guest VMs, you can add an ISO. The ISO is typically thought of as
+an operating system image, but you can also add ISOs for other types of
+software, such as desktop applications that you want to be installed as
+part of a template.
+
+#. Log in to the CloudStack UI as an administrator or end user.
+
+#. In the left navigation bar, click Templates.
+
+#. In Select View, choose ISOs.
+
+#. Click Add ISO.
+
+#. In the Add ISO screen, provide the following:
+
+ - **Name**: Short name for the ISO image. For example, CentOS 6.2
+ 64-bit.
+
+ - **Description**: Display test for the ISO image. For example,
+ CentOS 6.2 64-bit.
+
+ - **URL**: The URL that hosts the ISO image. The Management Server
+ must be able to access this location via HTTP. If needed you can
+ place the ISO image directly on the Management Server
+
+ - **Zone**: Choose the zone where you want the ISO to be available,
+ or All Zones to make it available throughout CloudStack.
+
+ - **Bootable**: Whether or not a guest could boot off this ISO
+ image. For example, a CentOS ISO is bootable, a Microsoft Office
+ ISO is not bootable.
+
+ - **OS Type**: This helps CloudStack and the hypervisor perform
+ certain operations and make assumptions that improve the
+ performance of the guest. Select one of the following.
+
+ - If the operating system of your desired ISO image is listed,
+ choose it.
+
+ - If the OS Type of the ISO is not listed or if the ISO is not
+ bootable, choose Other.
+
+ - (XenServer only) If you want to boot from this ISO in PV mode,
+ choose Other PV (32-bit) or Other PV (64-bit)
+
+ - (KVM only) If you choose an OS that is PV-enabled, the VMs
+ created from this ISO will have a SCSI (virtio) root disk. If
+ the OS is not PV-enabled, the VMs will have an IDE root disk.
+ The PV-enabled types are:
+
+ - Fedora 13
+
+ - Fedora 12
+
+ - Fedora 11
+
+ - Fedora 10
+
+ - Fedora 9
+
+ - Other PV
+
+ - Debian GNU/Linux
+
+ - CentOS 5.3
+
+ - CentOS 5.4
+
+ - CentOS 5.5
+
+ - Red Hat Enterprise Linux 5.3
+
+ - Red Hat Enterprise Linux 5.4
+
+ - Red Hat Enterprise Linux 5.5
+
+ - Red Hat Enterprise Linux 6
+
+
+ .. note::
+ It is not recommended to choose an older version of the OS than
+ the version in the image. For example, choosing CentOS 5.4 to
+ support a CentOS 6.2 image will usually not work. In these
+ cases, choose Other.
+
+ - **Extractable**: Choose Yes if the ISO should be available for
+ extraction.
+
+ - **Public**: Choose Yes if this ISO should be available to other
+ users.
+
+ - **Featured**: Choose Yes if you would like this ISO to be more
+ prominent for users to select. The ISO will appear in the Featured
+ ISOs list. Only an administrator can make an ISO Featured.
+
+#. Click OK.
+
+ The Management Server will download the ISO. Depending on the size of
+ the ISO, this may take a long time. The ISO status column will
+ display Ready once it has been successfully downloaded into secondary
+ storage. Clicking Refresh updates the download percentage.
+
+#. **Important**: Wait for the ISO to finish downloading. If you move on
+ to the next task and try to use the ISO right away, it will appear to
+ fail. The entire ISO must be available before CloudStack can work
+ with it.
+
+
+Attaching an ISO to a VM
+-------------------------
+
+#. In the left navigation, click Instances.
+
+#. Choose the virtual machine you want to work with.
+
+#. Click the Attach ISO button. |iso.png|
+
+#. In the Attach ISO dialog box, select the desired ISO.
+
+#. Click OK.
+
+
.. |sysmanager.png| image:: /_static/images/sysmanager.png
:alt: System Image Manager
diff --git a/source/adminguide/veeam_plugin.rst b/source/adminguide/veeam_plugin.rst
new file mode 100644
index 0000000..14424fb
--- /dev/null
+++ b/source/adminguide/veeam_plugin.rst
@@ -0,0 +1,152 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information#
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+.. _Veeam Backup and Recovery Plugin:
+
+Veeam Backup and Recovery Plugin
+=================================
+
+About the Veeam Backup and Recovery Plugin
+-------------------------------------------
+
+There are a couple of important concepts to understand before working with the Veeam plugin.
+
+#. Backup Provider Offerings for the Veeam B&R plugin are template backup jobs.
+
+#. Veeams API does not allow for the creation of backup jobs. Therefore, a backup job must be created which will act
+ as a template for all 'backups' which are based on it. You will need to create backup job templates for each of the
+ Backup Offerings which you will be presenting to your users, be they a default template for ad-hoc/scheduled backups or
+ 'SLA' specific templates (ie Gold offering). Refer to the general B&R for information regrading the B&R
+ job types.
+
+#. The backup job templates will be zone specific as they will contain the backup destination, and this will be different
+ in each zone (unless you have extreamly fat links between zones).
+
+#. Veeam backup jobs are not allowed to be empty (i.e. they must backup something); therefore a dummy tag which
+ is not assigned to any VM must be created via vCenter. The initial backup target of the backup job templates is
+ then 'any VM with the dummy tag assigned' i.e. no VMs
+
+#. Veeam's API is not complete and therefore a mix of API commands and powershell commands (via SSH) are employed.
+
+#. Veeam cannot explicitly reduce the number of backups that are kept, nor can it remove individual *partial* backups and 'coalesce' the
+ remaining image(s)
+
+
+Installing Veeam Backup and Recovery for use with CloudStack
+-------------------------------------------------------------
+
+The B&R Veeam plugin has been tested against Veeam Backup and Recovery 9.5 update 4b (Enterprise version). The
+enterprise edition is required for the Enterprise Manager API. The final tested version of Veeam was on a
+Windows Server 2019 (with desktop), although much of the development work was done against a Windows Server 2016 OS (with
+desktop).
+
+The following steps give a minimal installation, they do not cover Veeam integrations with backup, storage or
+virtualisation hardware. A number of the steps below may already have been carried out if you are already using Veeam Backup
+and Replication, however please read the steps below carefully to ensure that your installation meet all requirements for
+compatibility with the B&R Veeam plug-in.
+
+
+#. Install Backup and Replication 9.5 Manager - inc console - default settings
+#. Install Enterprise manager
+#. Install an SSH server on the 'Veeam Backup and Replication Manager' server. Windows Server 2019 has 'OpenSSH Server' as a
+ builtin optional feature which is compatible.
+#. Powershell 5.1 is the default version on Windows Server 2019
+
+Once these components are installed, then Veeam services can be configured. Please see the VM documentation for details,
+but at a high level you need to have done the following;
+
+#. License the Enterprise Manager & Backup and Replication servers (this can be done purely through the Enterprise Manager)
+#. Connect Enterprise Manager to Veeam backup server(s)
+#. Connect Enterprise Manager to vCenter server
+#. Add your 'vSphere' infrastructure to 'Managed Servers' in the Veeam Backup & Replication Console
+#. Setup your 'Backup Repositories' in the Veeam Backup & Replication Console. Remember that you will likely want a different
+ target in each zone.
+
+Creating Template jobs
+----------------------
+
+#. As noted above, a dummy VM tag is required in order to create template jobs which don't contain any VMs. This is done via vCenter
+ by navigating to the 'Tags and Custom Attributes' section, and first creating a category (if you dont already have a suitable one).
+
+ |BnR-DummyTagCategory.jpg|
+
+#. Then, create a dummy tag in that category. Be sure to make it clear that it is not to be used anywhere.
+
+ |BnR-CreateDummyTag.jpg|
+
+#. Now create the template job in Veeam Backup and Replication Manager. using the New Backup Job (Virtual Machine) wizard.
+
+ #. Give the job a name that describes what the job does ie *template_job_zone1_default* or *template_daily_job-14_kept*
+ (the end user will not see this name).
+ #. In the Virtual Machines section of the wizard, click 'Add' and select the 'VMs and Tags' filter (top right of the
+ 'Add Objects' dialog box). And then select your dummy tag and click on Add.
+
+ |BnR-VMsandTags.jpg|
+
+ #. In the Storage section is the correct Backup repository for the zone and number of restore points. (note there are a number
+ of other advanaced options which can be set, these are transparent to CloudStack. CloudStack will clone this job 'as-is' including
+ all advanced settings. However changing these settings will only effect NEW jobs created from the template, existing jobs will be
+ unchanged.
+
+ #. The same is true for the Guest Processing section.
+
+ #. In the Schedule section you, if you are creating an 'SLA' based backup template, you would set the job to run automatically and
+ select 'Periodically every' 24hrs and then in the 'Schedule' dialog set the hours in which the job is allowed to run. This allows
+ Veeam to choose the best time to run the backup within a given window. If you are creating a template for adhoc/scheduled backups,
+ do not tick 'Run the job automatically' as CloudStack will trigger jobs as and when required.
+
+ |BnR-backupschedule.jpg|
+
+ #. Finally, save the job.
+
+
+Connecting CloudStack to Veeam
+-------------------------------
+
+Once Veeam is configured with SSH enabled and at least one template job, we can connect CloudStack to your Veeam server.
+
+To do this, you simply update the global settings listed below:
+
+Plug-in specific settings:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(all settings can be global or per-zone)
+
+.. cssclass:: table-striped table-bordered table-hover
+
+==================================== ========================
+Configuration Description
+==================================== ========================
+backup.plugin.veeam.url Veeam B&R server URL. Default: http://<VEEAM_SERVER_IP>:9398/api/
+backup.plugin.veeam.username Veeam B&R server username. Default: administrator
+backup.plugin.veeam.password Veeam B&R server password. Default:
+backup.plugin.veeam.validate.ssl Whether to validate Veeam B&R server (SSL/TLS) connection while making API requests. Default: false
+backup.plugin.veeam.request.timeout Veeam B&R API request timeout in seconds. Default: 300
+==================================== ========================
+
+
+.. |BnR-DummyTagCategory.jpg| image:: /_static/images/BnR-DummyTagCategory.jpg
+ :alt: Create Tag Category.
+ :width: 300 px
+.. |BnR-CreateDummyTag.jpg| image:: /_static/images/BnR-CreateDummyTag.jpg
+ :alt: Create Dummy Tag.
+ :width: 300 px
+.. |BnR-VMsandTags.jpg| image:: /_static/images/BnR-VMsandTags.jpg
+ :alt: Select Dummy Tag.
+ :width: 300 px
+.. |BnR-backupschedule.jpg| image:: /_static/images/BnR-backupschedule.jpg
+ :alt: Set recurring SLA schedule.
+ :width: 600 px
+
diff --git a/source/adminguide/virtual_machines.rst b/source/adminguide/virtual_machines.rst
index 15bed54..8af8bb6 100644
--- a/source/adminguide/virtual_machines.rst
+++ b/source/adminguide/virtual_machines.rst
@@ -13,9 +13,8 @@
specific language governing permissions and limitations
under the License.
-
About Working with Virtual Machines
------------------------------------
+===================================
CloudStack provides administrators with complete control over the
lifecycle of all guest VMs executing in the cloud. CloudStack provides
@@ -68,96 +67,46 @@
through the CloudStack UI or API.
-Best Practices for Virtual Machines
------------------------------------
-For VMs to work as expected and provide excellent service, follow these
-guidelines.
+.. note::
+ **Monitor VMs for Max Capacity**
+ The CloudStack administrator should monitor the total number of VM
+ instances in each cluster, and disable allocation to the cluster if the
+ total is approaching the maximum that the hypervisor can handle. Be sure
+ to leave a safety margin to allow for the possibility of one or more
+ hosts failing, which would increase the VM load on the other hosts as
+ the VMs are automatically redeployed. Consult the documentation for your
+ chosen hypervisor to find the maximum permitted number of VMs per host,
+ then use CloudStack global configuration settings to set this as the
+ default limit. Monitor the VM activity in each cluster at all times.
+ Keep the total number of VMs below a safe level that allows for the
+ occasional host failure. For example, if there are N hosts in the
+ cluster, and you want to allow for one host in the cluster to be down at
+ any given time, the total number of VM instances you can permit in the
+ cluster is at most (N-1) \* (per-host-limit). Once a cluster reaches
+ this number of VMs, use the CloudStack UI to disable allocation of more
+ VMs to the cluster.
-Monitor VMs for Max Capacity
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The CloudStack administrator should monitor the total number of VM
-instances in each cluster, and disable allocation to the cluster if the
-total is approaching the maximum that the hypervisor can handle. Be sure
-to leave a safety margin to allow for the possibility of one or more
-hosts failing, which would increase the VM load on the other hosts as
-the VMs are automatically redeployed. Consult the documentation for your
-chosen hypervisor to find the maximum permitted number of VMs per host,
-then use CloudStack global configuration settings to set this as the
-default limit. Monitor the VM activity in each cluster at all times.
-Keep the total number of VMs below a safe level that allows for the
-occasional host failure. For example, if there are N hosts in the
-cluster, and you want to allow for one host in the cluster to be down at
-any given time, the total number of VM instances you can permit in the
-cluster is at most (N-1) \* (per-host-limit). Once a cluster reaches
-this number of VMs, use the CloudStack UI to disable allocation of more
-VMs to the cluster.
-
-
-Install Required Tools and Drivers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Be sure the following are installed on each VM:
-
-- For XenServer, install PV drivers and Xen tools on each VM. This will
- enable live migration and clean guest shutdown. Xen tools are
- required in order for dynamic CPU and RAM scaling to work.
-
-- For vSphere, install VMware Tools on each VM. This will enable
- console view to work properly. VMware Tools are required in order for
- dynamic CPU and RAM scaling to work.
-
-To be sure that Xen tools or VMware Tools is installed, use one of the
-following techniques:
-
-- Create each VM from a template that already has the tools installed;
- or,
-
-- When registering a new template, the administrator or user can
- indicate whether tools are installed on the template. This can be
- done through the UI or using the updateTemplate API; or,
-
-- If a user deploys a virtual machine with a template that does not
- have Xen tools or VMware Tools, and later installs the tools on the
- VM, then the user can inform CloudStack using the
- updateVirtualMachine API. After installing the tools and updating the
- virtual machine, stop and start the VM.
VM Lifecycle
-------------
+============
Virtual machines can be in the following states:
-|basic-deployment.png|
+- Created
+- Running
+- Stopped
+- Destroyed
+- Expunged
-Once a virtual machine is destroyed, it cannot be recovered. All the
-resources used by the virtual machine will be reclaimed by the system.
-This includes the virtual machine’s IP address.
+With the intermediate states of
-A stop will attempt to gracefully shut down the operating system, which
-typically involves terminating all the running applications. If the
-operation system cannot be stopped, it will be forcefully terminated.
-This has the same effect as pulling the power cord to a physical
-machine.
-
-A reboot is a stop followed by a start.
-
-CloudStack preserves the state of the virtual machine hard disk until
-the machine is destroyed.
-
-A running virtual machine may fail because of hardware or network
-issues. A failed virtual machine is in the down state.
-
-The system places the virtual machine into the down state if it does not
-receive the heartbeat from the hypervisor for three minutes.
-
-The user can manually restart the virtual machine from the down state.
-
-The system will start the virtual machine from the down state
-automatically if the virtual machine is marked as HA-enabled.
+- Creating
+- Starting
+- Stopping
+- Expunging
Creating VMs
@@ -205,7 +154,9 @@
To create a VM from an ISO:
.. note::
- (XenServer) Windows VMs running on XenServer require PV drivers,
+ **XenServer**
+
+ Windows VMs running on XenServer require PV drivers,
which may be provided in the template or added after the VM is
created. The PV drivers are necessary for essential management
functions such as mounting additional volumes and ISO images,
@@ -224,6 +175,37 @@
#. Click Submit and your VM will be created and started.
+
+Install Required Tools and Drivers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Be sure the following are installed on each VM:
+
+- For XenServer, install PV drivers and Xen tools on each VM. This will
+ enable live migration and clean guest shutdown. Xen tools are
+ required in order for dynamic CPU and RAM scaling to work.
+
+- For vSphere, install VMware Tools on each VM. This will enable
+ console view to work properly. VMware Tools are required in order for
+ dynamic CPU and RAM scaling to work.
+
+To be sure that Xen tools or VMware Tools is installed, use one of the
+following techniques:
+
+- Create each VM from a template that already has the tools installed;
+ or,
+
+- When registering a new template, the administrator or user can
+ indicate whether tools are installed on the template. This can be
+ done through the UI or using the updateTemplate API; or,
+
+- If a user deploys a virtual machine with a template that does not
+ have Xen tools or VMware Tools, and later installs the tools on the
+ VM, then the user can inform CloudStack using the
+ updateVirtualMachine API. After installing the tools and updating the
+ virtual machine, stop and start the VM.
+
+
Accessing VMs
-------------
@@ -265,296 +247,53 @@
needed. In the CloudStack UI, click Instances, select the VM, and use
the Stop, Start, Reboot, and Destroy buttons.
+A stop will attempt to gracefully shut down the operating system, via
+an ACPI 'stop' command which is similar to pressing the soft power switch
+on a physical server. If the operating system cannot be stopped, it will
+be forcefully terminated. This has the same effect as pulling out the power
+cord from a physical machine.
+
+A reboot should not be considered as a stop followed by a start. In CloudStack,
+a start command reconfigures the virtual machine to the stored parameters in
+CloudStack's database. The reboot process does not do this.
+
When starting a VM, admin users have the option to specify a pod, cluster, or host.
-Assigning VMs to Hosts
-----------------------
-
-At any point in time, each virtual machine instance is running on a
-single host. How does CloudStack determine which host to place a VM on?
-There are several ways:
-
-- Automatic default host allocation. CloudStack can automatically pick
- the most appropriate host to run each virtual machine.
-
-- Instance type preferences. CloudStack administrators can specify that
- certain hosts should have a preference for particular types of guest
- instances. For example, an administrator could state that a host
- should have a preference to run Windows guests. The default host
- allocator will attempt to place guests of that OS type on such hosts
- first. If no such host is available, the allocator will place the
- instance wherever there is sufficient physical capacity.
-
-- Vertical and horizontal allocation. Vertical allocation consumes all
- the resources of a given host before allocating any guests on a
- second host. This reduces power consumption in the cloud. Horizontal
- allocation places a guest on each host in a round-robin fashion. This
- may yield better performance to the guests in some cases.
-
-- Admin users preferences. Administrators have the option to specify a
- pod, cluster, or host to run the VM in. CloudStack will then select
- a host within the given infrastructure.
-
-- End user preferences. Users can not control exactly which host will
- run a given VM instance, but they can specify a zone for the VM.
- CloudStack is then restricted to allocating the VM only to one of the
- hosts in that zone.
-
-- Host tags. The administrator can assign tags to hosts. These tags can
- be used to specify which host a VM should use. The CloudStack
- administrator decides whether to define host tags, then create a
- service offering using those tags and offer it to the user.
-
-- Affinity groups. By defining affinity groups and assigning VMs to
- them, the user or administrator can influence (but not dictate) which
- VMs should run on separate hosts. This feature is to let users
- specify that certain VMs won't be on the same host.
-
-- CloudStack also provides a pluggable interface for adding new
- allocators. These custom allocators can provide any policy the
- administrator desires.
-
-
-Affinity Groups
-~~~~~~~~~~~~~~~
-
-By defining affinity groups and assigning VMs to them, the user or
-administrator can influence (but not dictate) which VMs should run on
-separate hosts. This feature is to let users specify that VMs with the
-same “host anti-affinity” type won’t be on the same host. This serves to
-increase fault tolerance. If a host fails, another VM offering the same
-service (for example, hosting the user's website) is still up and
-running on another host.
-
-The scope of an affinity group is per user account.
-
-
-Creating a New Affinity Group
-'''''''''''''''''''''''''''''
-
-To add an affinity group:
-
-#. Log in to the CloudStack UI as an administrator or user.
-
-#. In the left navigation bar, click Affinity Groups.
-
-#. Click Add affinity group. In the dialog box, fill in the following
- fields:
-
- - Name. Give the group a name.
-
- - Description. Any desired text to tell more about the purpose of
- the group.
-
- - Type. The only supported type shipped with CloudStack is Host
- Anti-Affinity. This indicates that the VMs in this group should
- avoid being placed on the same host with each other. If you see
- other types in this list, it means that your installation of
- CloudStack has been extended with customized affinity group
- plugins.
-
-
-Assign a New VM to an Affinity Group
-''''''''''''''''''''''''''''''''''''
-
-To assign a new VM to an affinity group:
-
-- Create the VM as usual, as described in `“Creating
- VMs” <virtual_machines.html#creating-vms>`_. In the Add Instance
- wizard, there is a new Affinity tab where you can select the
- affinity group.
-
-
-Change Affinity Group for an Existing VM
-''''''''''''''''''''''''''''''''''''''''
-
-To assign an existing VM to an affinity group:
-
-#. Log in to the CloudStack UI as an administrator or user.
-
-#. In the left navigation bar, click Instances.
-
-#. Click the name of the VM you want to work with.
-
-#. Stop the VM by clicking the Stop button.
-
-#. Click the Change Affinity button. |change-affinity-button.png|
-
-
-View Members of an Affinity Group
-'''''''''''''''''''''''''''''''''
-
-To see which VMs are currently assigned to a particular affinity group:
-
-#. In the left navigation bar, click Affinity Groups.
-
-#. Click the name of the group you are interested in.
-
-#. Click View Instances. The members of the group are listed.
-
- From here, you can click the name of any VM in the list to access all
- its details and controls.
-
-
-Delete an Affinity Group
-''''''''''''''''''''''''
-
-To delete an affinity group:
-
-#. In the left navigation bar, click Affinity Groups.
-
-#. Click the name of the group you are interested in.
-
-#. Click Delete.
-
- Any VM that is a member of the affinity group will be disassociated
- from the group. The former group members will continue to run
- normally on the current hosts, but if the VM is restarted, it will no
- longer follow the host allocation rules from its former affinity
- group.
-
-
-Virtual Machine Snapshots
+Deleting VMs
-------------------------
-(Supported on VMware, XenServer and KVM (NFS only))
+Users can delete their own virtual machines. A running virtual machine
+will be abruptly stopped before it is deleted. Administrators can delete
+any virtual machines.
-In addition to the existing CloudStack ability to snapshot individual VM
-volumes, you can take a VM snapshot to preserve all the VM's data
-volumes as well as (optionally) its CPU/memory state. This is useful for
-quick restore of a VM. For example, you can snapshot a VM, then make
-changes such as software upgrades. If anything goes wrong, simply
-restore the VM to its previous state using the previously saved VM
-snapshot.
+To delete a virtual machine:
-The snapshot is created using the hypervisor's native snapshot facility.
-The VM snapshot includes not only the data volumes, but optionally also
-whether the VM is running or turned off (CPU state) and the memory
-contents. The snapshot is stored in CloudStack's primary storage.
+#. Log in to the CloudStack UI as a user or admin.
-VM snapshots can have a parent/child relationship. Each successive
-snapshot of the same VM is the child of the snapshot that came before
-it. Each time you take an additional snapshot of the same VM, it saves
-only the differences between the current state of the VM and the state
-stored in the most recent previous snapshot. The previous snapshot
-becomes a parent, and the new snapshot is its child. It is possible to
-create a long chain of these parent/child snapshots, which amount to a
-"redo" record leading from the current state of the VM back to the
-original.
+#. In the left navigation, click Instances.
-After VM snapshots are created, they can be tagged with a key/value pair,
-like many other resources in CloudStack.
+#. Choose the VM that you want to delete.
-KVM supports VM snapshots when using NFS shared storage. If raw block storage
-is used (i.e. Ceph), then VM snapshots are not possible, since there is no possibility
-to write RAM memory content anywhere.
+#. Click the Destroy Instance button. |Destroyinstance.png|
-If you need more information about VM snapshots on VMware, check out the
-VMware documentation and the VMware Knowledge Base, especially
-`Understanding virtual machine snapshots
-<http://kb.vmware.com/selfservice/microsites/search.do?cmd=displayKC&externalId=1015180>`_.
+#. Optionally both expunging and the deletion of any attached volumes can be enabled.
+When a virtual machine is **destroyed**, it can no longer be seen by the end user,
+however, it can be seen (and recovered) by a root admin. In this state it still
+consumes logical resources. Global settings control the maximum time from a VM
+being destroyed, to the physical disks being removed. When the VM and its rooot disk
+have been deleted, the VM is said to have been expunged.
-Limitations on VM Snapshots
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Once a virtual machine is **expunged**, it cannot be recovered. All the
+resources used by the virtual machine will be reclaimed by the system,
+This includes the virtual machine’s IP address.
-- If a VM has some stored snapshots, you can't attach new volume to the
- VM or delete any existing volumes. If you change the volumes on the
- VM, it would become impossible to restore the VM snapshot which was
- created with the previous volume structure. If you want to attach a
- volume to such a VM, first delete its snapshots.
-
-- VM snapshots which include both data volumes and memory can't be kept
- if you change the VM's service offering. Any existing VM snapshots of
- this type will be discarded.
-
-- You can't make a VM snapshot at the same time as you are taking a
- volume snapshot.
-
-- You should use only CloudStack to create VM snapshots on hosts
- managed by CloudStack. Any snapshots that you make directly on the
- hypervisor will not be tracked in CloudStack.
-
-
-Configuring VM Snapshots
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-The cloud administrator can use global configuration variables to
-control the behavior of VM snapshots. To set these variables, go through
-the Global Settings area of the CloudStack UI.
-
-.. cssclass:: table-striped table-bordered table-hover
-
-====================== ========================
-Configuration Description Type
-====================== ========================
-vmsnapshots.max The maximum number of VM snapshots that can be saved for any given virtual machine in the cloud. The total possible number of VM snapshots in the cloud is (number of VMs) \* vmsnapshots.max. If the number of snapshots for any VM ever hits the maximum, the older ones are removed by the snapshot expunge job
-vmsnapshot.create.wait Number of seconds to wait for a snapshot job to succeed before declaring failure and issuing an error.
-====================== ========================
-
-
-Using VM Snapshots
-~~~~~~~~~~~~~~~~~~
-
-To create a VM snapshot using the CloudStack UI:
-
-#. Log in to the CloudStack UI as a user or administrator.
-
-#. Click Instances.
-
-#. Click the name of the VM you want to snapshot.
-
-#. Click the Take VM Snapshot button. |VMSnapshotButton.png|
-
- .. note::
- If a snapshot is already in progress, then clicking this button
- will have no effect.
-
-#. Provide a name and description. These will be displayed in the VM
- Snapshots list.
-
-#. (For running VMs only) If you want to include the VM's memory in the
- snapshot, click the Memory checkbox. This saves the CPU and memory
- state of the virtual machine. If you don't check this box, then only
- the current state of the VM disk is saved. Checking this box makes
- the snapshot take longer.
-
-#. Quiesce VM: check this box if you want to quiesce the file system on
- the VM before taking the snapshot. Not supported on XenServer when
- used with CloudStack-provided primary storage.
-
- When this option is used with CloudStack-provided primary storage,
- the quiesce operation is performed by the underlying hypervisor
- (VMware is supported). When used with another primary storage
- vendor's plugin, the quiesce operation is provided according to the
- vendor's implementation.
-
-#. Click OK.
-
-To delete a snapshot or restore a VM to the state saved in a particular
-snapshot:
-
-#. Navigate to the VM as described in the earlier steps.
-
-#. Click View VM Snapshots.
-
-#. In the list of snapshots, click the name of the snapshot you want to
- work with.
-
-#. Depending on what you want to do:
-
- To delete the snapshot, click the Delete button. |delete-button.png|
-
- To revert to the snapshot, click the Revert button. |revert-vm.png|
-
-.. note::
- VM snapshots are deleted automatically when a VM is destroyed. You don't
- have to manually delete the snapshots in this case.
-
+Managing Virtual Machines
+=========================
Changing the VM Name, OS, or Group
-----------------------------------
+-------------------------------------
After a VM is created, you can modify the display name, operating
system, and the group it belongs to.
@@ -584,7 +323,7 @@
Appending a Display Name to the Guest VM’s Internal Name
---------------------------------------------------------
+----------------------------------------------------------
Every guest VM has an internal name. The host uses the internal name to
identify the guest VMs. CloudStack gives you an option to provide a
@@ -619,7 +358,7 @@
Changing the Service Offering for a VM
---------------------------------------
+----------------------------------------
To upgrade or downgrade the level of compute resources available to a
virtual machine, you can change the VM's compute offering.
@@ -824,177 +563,156 @@
where i in [0,..,N] and N = number of volumes of the virtual machine
-Deleting VMs
-------------
-Users can delete their own virtual machines. A running virtual machine
-will be abruptly stopped before it is deleted. Administrators can delete
-any virtual machines.
+Assigning VMs to Hosts
+----------------------
-To delete a virtual machine:
+At any point in time, each virtual machine instance is running on a
+single host. How does CloudStack determine which host to place a VM on?
+There are several ways:
-#. Log in to the CloudStack UI as a user or admin.
+- Automatic default host allocation. CloudStack can automatically pick
+ the most appropriate host to run each virtual machine.
-#. In the left navigation, click Instances.
+- Instance type preferences. CloudStack administrators can specify that
+ certain hosts should have a preference for particular types of guest
+ instances. For example, an administrator could state that a host
+ should have a preference to run Windows guests. The default host
+ allocator will attempt to place guests of that OS type on such hosts
+ first. If no such host is available, the allocator will place the
+ instance wherever there is sufficient physical capacity.
-#. Choose the VM that you want to delete.
+- Vertical and horizontal allocation. Vertical allocation consumes all
+ the resources of a given host before allocating any guests on a
+ second host. This reduces power consumption in the cloud. Horizontal
+ allocation places a guest on each host in a round-robin fashion. This
+ may yield better performance to the guests in some cases.
-#. Click the Destroy Instance button. |Destroyinstance.png|
+- Admin users preferences. Administrators have the option to specify a
+ pod, cluster, or host to run the VM in. CloudStack will then select
+ a host within the given infrastructure.
-#. Optionally both expunging and the deletion of any attached volumes can be enabled.
+- End user preferences. Users can not control exactly which host will
+ run a given VM instance, but they can specify a zone for the VM.
+ CloudStack is then restricted to allocating the VM only to one of the
+ hosts in that zone.
+
+- Host tags. The administrator can assign tags to hosts. These tags can
+ be used to specify which host a VM should use. The CloudStack
+ administrator decides whether to define host tags, then create a
+ service offering using those tags and offer it to the user.
+
+- Affinity groups. By defining affinity groups and assigning VMs to
+ them, the user or administrator can influence (but not dictate) which
+ VMs should run on separate hosts. This feature is to let users
+ specify that certain VMs won't be on the same host.
+
+- CloudStack also provides a pluggable interface for adding new
+ allocators. These custom allocators can provide any policy the
+ administrator desires.
-Working with ISOs
------------------
+Affinity Groups
+~~~~~~~~~~~~~~~
-CloudStack supports ISOs and their attachment to guest VMs. An ISO is a
-read-only file that has an ISO/CD-ROM style file system. Users can
-upload their own ISOs and mount them on their guest VMs.
+By defining affinity groups and assigning VMs to them, the user or
+administrator can influence (but not dictate) which VMs should run on
+separate hosts. This feature is to let users specify that VMs with the
+same “host anti-affinity” type won’t be on the same host. This serves to
+increase fault tolerance. If a host fails, another VM offering the same
+service (for example, hosting the user's website) is still up and
+running on another host.
-ISOs are uploaded based on a URL. HTTP is the supported protocol. Once
-the ISO is available via HTTP specify an upload URL such as
-http://my.web.server/filename.iso.
-
-ISOs may be public or private, like templates.ISOs are not
-hypervisor-specific. That is, a guest on vSphere can mount the exact
-same image that a guest on KVM can mount.
-
-ISO images may be stored in the system and made available with a privacy
-level similar to templates. ISO images are classified as either bootable
-or not bootable. A bootable ISO image is one that contains an OS image.
-CloudStack allows a user to boot a guest VM off of an ISO image. Users
-can also attach ISO images to guest VMs. For example, this enables
-installing PV drivers into Windows. ISO images are not
-hypervisor-specific.
+The scope of an affinity group is per user account.
-Adding an ISO
-~~~~~~~~~~~~~
+Creating a New Affinity Group
+'''''''''''''''''''''''''''''
-To make additional operating system or other software available for use
-with guest VMs, you can add an ISO. The ISO is typically thought of as
-an operating system image, but you can also add ISOs for other types of
-software, such as desktop applications that you want to be installed as
-part of a template.
+To add an affinity group:
-#. Log in to the CloudStack UI as an administrator or end user.
+#. Log in to the CloudStack UI as an administrator or user.
-#. In the left navigation bar, click Templates.
+#. In the left navigation bar, click Affinity Groups.
-#. In Select View, choose ISOs.
+#. Click Add affinity group. In the dialog box, fill in the following
+ fields:
-#. Click Add ISO.
+ - Name. Give the group a name.
-#. In the Add ISO screen, provide the following:
+ - Description. Any desired text to tell more about the purpose of
+ the group.
- - **Name**: Short name for the ISO image. For example, CentOS 6.2
- 64-bit.
-
- - **Description**: Display test for the ISO image. For example,
- CentOS 6.2 64-bit.
-
- - **URL**: The URL that hosts the ISO image. The Management Server
- must be able to access this location via HTTP. If needed you can
- place the ISO image directly on the Management Server
-
- - **Zone**: Choose the zone where you want the ISO to be available,
- or All Zones to make it available throughout CloudStack.
-
- - **Bootable**: Whether or not a guest could boot off this ISO
- image. For example, a CentOS ISO is bootable, a Microsoft Office
- ISO is not bootable.
-
- - **OS Type**: This helps CloudStack and the hypervisor perform
- certain operations and make assumptions that improve the
- performance of the guest. Select one of the following.
-
- - If the operating system of your desired ISO image is listed,
- choose it.
-
- - If the OS Type of the ISO is not listed or if the ISO is not
- bootable, choose Other.
-
- - (XenServer only) If you want to boot from this ISO in PV mode,
- choose Other PV (32-bit) or Other PV (64-bit)
-
- - (KVM only) If you choose an OS that is PV-enabled, the VMs
- created from this ISO will have a SCSI (virtio) root disk. If
- the OS is not PV-enabled, the VMs will have an IDE root disk.
- The PV-enabled types are:
-
- - Fedora 13
-
- - Fedora 12
-
- - Fedora 11
-
- - Fedora 10
-
- - Fedora 9
-
- - Other PV
-
- - Debian GNU/Linux
-
- - CentOS 5.3
-
- - CentOS 5.4
-
- - CentOS 5.5
-
- - Red Hat Enterprise Linux 5.3
-
- - Red Hat Enterprise Linux 5.4
-
- - Red Hat Enterprise Linux 5.5
-
- - Red Hat Enterprise Linux 6
-
- .. note::
- It is not recommended to choose an older version of the OS than
- the version in the image. For example, choosing CentOS 5.4 to
- support a CentOS 6.2 image will usually not work. In these
- cases, choose Other.
-
- - **Extractable**: Choose Yes if the ISO should be available for
- extraction.
-
- - **Public**: Choose Yes if this ISO should be available to other
- users.
-
- - **Featured**: Choose Yes if you would like this ISO to be more
- prominent for users to select. The ISO will appear in the Featured
- ISOs list. Only an administrator can make an ISO Featured.
-
-#. Click OK.
-
- The Management Server will download the ISO. Depending on the size of
- the ISO, this may take a long time. The ISO status column will
- display Ready once it has been successfully downloaded into secondary
- storage. Clicking Refresh updates the download percentage.
-
-#. **Important**: Wait for the ISO to finish downloading. If you move on
- to the next task and try to use the ISO right away, it will appear to
- fail. The entire ISO must be available before CloudStack can work
- with it.
+ - Type. The only supported type shipped with CloudStack is Host
+ Anti-Affinity. This indicates that the VMs in this group should
+ avoid being placed on the same host with each other. If you see
+ other types in this list, it means that your installation of
+ CloudStack has been extended with customized affinity group
+ plugins.
-Attaching an ISO to a VM
-~~~~~~~~~~~~~~~~~~~~~~~~
+Assign a New VM to an Affinity Group
+''''''''''''''''''''''''''''''''''''
-#. In the left navigation, click Instances.
+To assign a new VM to an affinity group:
-#. Choose the virtual machine you want to work with.
+- Create the VM as usual, as described in `“Creating
+ VMs” <virtual_machines.html#creating-vms>`_. In the Add Instance
+ wizard, there is a new Affinity tab where you can select the
+ affinity group.
-#. Click the Attach ISO button. |iso.png|
-#. In the Attach ISO dialog box, select the desired ISO.
+Change Affinity Group for an Existing VM
+''''''''''''''''''''''''''''''''''''''''
-#. Click OK.
+To assign an existing VM to an affinity group:
+
+#. Log in to the CloudStack UI as an administrator or user.
+
+#. In the left navigation bar, click Instances.
+
+#. Click the name of the VM you want to work with.
+
+#. Stop the VM by clicking the Stop button.
+
+#. Click the Change Affinity button. |change-affinity-button.png|
+
+
+View Members of an Affinity Group
+'''''''''''''''''''''''''''''''''
+
+To see which VMs are currently assigned to a particular affinity group:
+
+#. In the left navigation bar, click Affinity Groups.
+
+#. Click the name of the group you are interested in.
+
+#. Click View Instances. The members of the group are listed.
+
+ From here, you can click the name of any VM in the list to access all
+ its details and controls.
+
+
+Delete an Affinity Group
+''''''''''''''''''''''''
+
+To delete an affinity group:
+
+#. In the left navigation bar, click Affinity Groups.
+
+#. Click the name of the group you are interested in.
+
+#. Click Delete.
+
+ Any VM that is a member of the affinity group will be disassociated
+ from the group. The former group members will continue to run
+ normally on the current hosts, but if the VM is restarted, it will no
+ longer follow the host allocation rules from its former affinity
+ group.
Changing a VM's Base Image
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
Every VM is created from a base image, which is a template or ISO which
has been created and stored in CloudStack. Both cloud administrators and
@@ -1026,8 +744,183 @@
already in use by the VM.
+Advanced VM Instance Settings
+-----------------------------
+
+Each user VM has a set of "details" associated with it (as visible via listVirtualMachine API call) - those "details" are shown on the "Settings" tab of the VM in the GUI (words "setting(s)" and "detail(s)" are here used interchangeably).
+
+The Settings tab is always present/visible, but settings can be changed only when the VM is in a Stopped state.
+Some VM details/settings can be hidden via "user.vm.blacklisted.details" global setting (you can find below the list of those hidden by default).
+
+When adding a new setting or modifying the existing ones, setting names are shown/offered in a drop-down list, as well as their possible values (with the exception of boolean or numerical values).
+
+Read-only details/settings that are hidden by default:
+
+- rootdisksize
+- cpuOvercommitRatio
+- memoryOvercommitRatio
+- Message.ReservedCapacityFreed.Flag
+
+An example list of settings as well as their possible values are shown on the images below:
+
+|vm-settings-dropdown-list.PNG|
+(VMware hypervisor)
+
+|vm-settings-values-dropdown-list.PNG|
+(VMware disk controllers)
+
+|vm-settings-values1-dropdown-list.PNG|
+(VMware NIC models)
+
+|vm-settings-values-dropdown-KVM-list.PNG|
+(KVM disk controllers)
+
+
+Virtual Machine Snapshots
+=========================
+
+(Supported on VMware, XenServer and KVM (NFS only))
+
+In addition to the existing CloudStack ability to snapshot individual VM
+volumes, you can take a VM snapshot to preserve all the VM's data
+volumes as well as (optionally) its CPU/memory state. This is useful for
+quick restore of a VM. For example, you can snapshot a VM, then make
+changes such as software upgrades. If anything goes wrong, simply
+restore the VM to its previous state using the previously saved VM
+snapshot.
+
+The snapshot is created using the hypervisor's native snapshot facility.
+The VM snapshot includes not only the data volumes, but optionally also
+whether the VM is running or turned off (CPU state) and the memory
+contents. The snapshot is stored in CloudStack's primary storage.
+
+VM snapshots can have a parent/child relationship. Each successive
+snapshot of the same VM is the child of the snapshot that came before
+it. Each time you take an additional snapshot of the same VM, it saves
+only the differences between the current state of the VM and the state
+stored in the most recent previous snapshot. The previous snapshot
+becomes a parent, and the new snapshot is its child. It is possible to
+create a long chain of these parent/child snapshots, which amount to a
+"redo" record leading from the current state of the VM back to the
+original.
+
+After VM snapshots are created, they can be tagged with a key/value pair,
+like many other resources in CloudStack.
+
+KVM supports VM snapshots when using NFS shared storage. If raw block storage
+is used (i.e. Ceph), then VM snapshots are not possible, since there is no possibility
+to write RAM memory content anywhere.
+
+If you need more information about VM snapshots on VMware, check out the
+VMware documentation and the VMware Knowledge Base, especially
+`Understanding virtual machine snapshots
+<http://kb.vmware.com/selfservice/microsites/search.do?cmd=displayKC&externalId=1015180>`_.
+
+
+Limitations on VM Snapshots
+---------------------------
+
+- If a VM has some stored snapshots, you can't attach new volume to the
+ VM or delete any existing volumes. If you change the volumes on the
+ VM, it would become impossible to restore the VM snapshot which was
+ created with the previous volume structure. If you want to attach a
+ volume to such a VM, first delete its snapshots.
+
+- VM snapshots which include both data volumes and memory can't be kept
+ if you change the VM's service offering. Any existing VM snapshots of
+ this type will be discarded.
+
+- You can't make a VM snapshot at the same time as you are taking a
+ volume snapshot.
+
+- You should use only CloudStack to create VM snapshots on hosts
+ managed by CloudStack. Any snapshots that you make directly on the
+ hypervisor will not be tracked in CloudStack.
+
+
+Configuring VM Snapshots
+------------------------
+
+The cloud administrator can use global configuration variables to
+control the behavior of VM snapshots. To set these variables, go through
+the Global Settings area of the CloudStack UI.
+
+.. cssclass:: table-striped table-bordered table-hover
+
+====================== ========================
+Configuration Description Type
+====================== ========================
+vmsnapshots.max The maximum number of VM snapshots that can be saved for any given virtual machine in the cloud. The total possible number of VM snapshots in the cloud is (number of VMs) \* vmsnapshots.max. If the number of snapshots for any VM ever hits the maximum, the older ones are removed by the snapshot expunge job
+vmsnapshot.create.wait Number of seconds to wait for a snapshot job to succeed before declaring failure and issuing an error.
+====================== ========================
+
+
+Using VM Snapshots
+------------------
+
+To create a VM snapshot using the CloudStack UI:
+
+#. Log in to the CloudStack UI as a user or administrator.
+
+#. Click Instances.
+
+#. Click the name of the VM you want to snapshot.
+
+#. Click the Take VM Snapshot button. |VMSnapshotButton.png|
+
+ .. note::
+ If a snapshot is already in progress, then clicking this button
+ will have no effect.
+
+#. Provide a name and description. These will be displayed in the VM
+ Snapshots list.
+
+#. (For running VMs only) If you want to include the VM's memory in the
+ snapshot, click the Memory checkbox. This saves the CPU and memory
+ state of the virtual machine. If you don't check this box, then only
+ the current state of the VM disk is saved. Checking this box makes
+ the snapshot take longer.
+
+#. Quiesce VM: check this box if you want to quiesce the file system on
+ the VM before taking the snapshot. Not supported on XenServer when
+ used with CloudStack-provided primary storage.
+
+ When this option is used with CloudStack-provided primary storage,
+ the quiesce operation is performed by the underlying hypervisor
+ (VMware is supported). When used with another primary storage
+ vendor's plugin, the quiesce operation is provided according to the
+ vendor's implementation.
+
+#. Click OK.
+
+To delete a snapshot or restore a VM to the state saved in a particular
+snapshot:
+
+#. Navigate to the VM as described in the earlier steps.
+
+#. Click View VM Snapshots.
+
+#. In the list of snapshots, click the name of the snapshot you want to
+ work with.
+
+#. Depending on what you want to do:
+
+ To delete the snapshot, click the Delete button. |delete-button.png|
+
+ To revert to the snapshot, click the Revert button. |revert-vm.png|
+
+.. note::
+ VM snapshots are deleted automatically when a VM is destroyed. You don't
+ have to manually delete the snapshots in this case.
+
+
+Virtual Machine Backups (Backup and Recovery Feature)
+=====================================================
+
+.. include:: backup_and_recovery.rst
+
Using SSH Keys for Authentication
----------------------------------
+=================================
In addition to the username and password authentication, CloudStack
supports using SSH keys to log in to the cloud infrastructure for
@@ -1040,7 +933,7 @@
Creating an Instance Template that Supports SSH Keys
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------------
Create an instance template that supports SSH Keys.
@@ -1078,7 +971,7 @@
Creating the SSH Keypair
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
You must make a call to the createSSHKeyPair api method. You can either
use the CloudStack Python API library or the curl commands to make the
@@ -1137,7 +1030,7 @@
Creating an Instance
-~~~~~~~~~~~~~~~~~~~~
+--------------------
After you save the SSH keypair file, you must create an instance by
using the template that you created at `Section 5.2.1, “ Creating an
@@ -1161,7 +1054,7 @@
Logging In Using the SSH Keypair
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
To test your SSH key generation is successful, check whether you can log
in to the cloud setup.
@@ -1177,7 +1070,7 @@
Resetting SSH Keys
-~~~~~~~~~~~~~~~~~~
+------------------
With the API command resetSSHKeyForVirtualMachine, a user can set or
reset the SSH keypair assigned to a virtual machine. A lost or
@@ -1189,7 +1082,7 @@
Assigning GPU/vGPU to Guest VMs
--------------------------------
+===============================
CloudStack can deploy guest VMs with Graphics Processing Unit (GPU) or Virtual
Graphics Processing Unit (vGPU) capabilities on XenServer hosts. At the time of
@@ -1243,7 +1136,7 @@
in case of GRID cards, and capacity of the cards.
Prerequisites and System Requirements
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
Before proceeding, ensure that you have these prerequisites:
@@ -1292,7 +1185,7 @@
- Notification thresholds for GPU resource is not supported.
Supported GPU Devices
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
.. cssclass:: table-striped table-bordered table-hover
@@ -1312,7 +1205,7 @@
=========== ========================
GPU/vGPU Assignment Workflow
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
CloudStack follows the below sequence of operations to provide GPU/vGPU support for VMs:
@@ -1345,43 +1238,9 @@
GPU resources are released automatically when you stop a VM. Once the destroy VM is successful, CloudStack will make a resource call to the host to get the remaining GPU capacity in the card and update the database accordingly.
-
-
-VM Instance Settings
-~~~~~~~~~~~~~~~~~~~~
-
-Each user VM has a set of "details" associated with it (as visible via listVirtualMachine API call) - those "details" are shown on the "Settings" tab of the VM in the GUI (words "setting(s)" and "detail(s)" are here used interchangeably).
-
-The Settings tab is always present/visible, but settings can be changed only when the VM is in a Stopped state.
-Some VM details/settings can be hidden via "user.vm.blacklisted.details" global setting (you can find below the list of those hidden by default).
-
-When adding a new setting or modifying the existing ones, setting names are shown/offered in a drop-down list, as well as their possible values (with the exception of boolean or numerical values).
-
-Read-only details/settings that are hidden by default:
-
-- rootdisksize
-- cpuOvercommitRatio
-- memoryOvercommitRatio
-- Message.ReservedCapacityFreed.Flag
-
-An example list of settings as well as their possible values are shown on the images below:
-
-|vm-settings-dropdown-list.PNG|
-(VMware hypervisor)
-
-|vm-settings-values-dropdown-list.PNG|
-(VMware disk controllers)
-
-|vm-settings-values1-dropdown-list.PNG|
-(VMware NIC models)
-
-|vm-settings-values-dropdown-KVM-list.PNG|
-(KVM disk controllers)
-
-
-
-.. |basic-deployment.png| image:: /_static/images/basic-deployment.png
- :alt: Basic two-machine CloudStack deployment
+
+.. |vm-lifecycle.png| image:: /_static/images/vm-lifecycle.png
+ :alt: Virtual Machine State Model
.. |VMSnapshotButton.png| image:: /_static/images/VMSnapshotButton.png
:alt: button to restart a VPC
.. |delete-button.png| image:: /_static/images/delete-button.png
diff --git a/source/conf.py b/source/conf.py
index e2ebe14..9733e62 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -20,13 +20,13 @@
# -- Project information -----------------------------------------------------
project = 'Apache CloudStack'
-copyright = '2018, Apache Foundation'
+copyright = '2012-2020, Apache Foundation'
author = 'Apache CloudStack Project'
# The short X.Y version
-version = '4.13'
+version = '4.14'
# The full version, including alpha/beta/rc tags
-release = '4.13.1.0'
+release = '4.14.0.0'
rst_epilog = """
.. include:: /_global.rst
diff --git a/source/installguide/hypervisor/vsphere.rst b/source/installguide/hypervisor/vsphere.rst
index 91a4819..8286f69 100644
--- a/source/installguide/hypervisor/vsphere.rst
+++ b/source/installguide/hypervisor/vsphere.rst
@@ -654,7 +654,7 @@
After the zone is created, if you want to create an additional cluster
along with Nexus 1000v virtual switch in the existing zone, use the Add
Cluster option. For information on creating a cluster, see
-`"Add Cluster: vSphere" <configuration.html#add-cluster-vsphere>`_.
+:ref:`adding-a-cluster`.
In both these cases, you must specify the following parameters to
configure Nexus virtual switch:
@@ -865,8 +865,7 @@
Alternatively, at the cluster level, you can create an additional
cluster with VDS enabled in the existing zone. Use the Add Cluster
-option. For information as given in `“Add Cluster: vSphere”
-<configuration.html#add-cluster-vsphere>`_.
+option. For information as given in :ref:`adding-a-cluster`.
In both these cases, you must specify the following parameters to
configure VDS:
@@ -963,7 +962,7 @@
Use vCenter to create a vCenter cluster and add your desired hosts to
the cluster. You will later add the entire cluster to CloudStack. (see
-`“Add Cluster: vSphere” <configuration.html#add-cluster-vsphere>`_).
+:ref:`adding-a-cluster`).
Applying Hotfixes to a VMware vSphere Host
diff --git a/source/installguide/management-server/_pkg_repo.rst b/source/installguide/management-server/_pkg_repo.rst
index 9061134..453ca4d 100644
--- a/source/installguide/management-server/_pkg_repo.rst
+++ b/source/installguide/management-server/_pkg_repo.rst
@@ -65,8 +65,8 @@
~~~~~~~~~~~~~~~~~~~~~~
You can add a DEB package repository to your apt sources with the
-following commands. Please note that only packages for Ubuntu 14.04 LTS
-(Trusty) and Ubuntu 16.04 (Xenial) are being built at this time. DISCLAIMER: Ubuntu 12.04 (Precise) is no longer supported.
+following commands. Please note that only packages for Ubuntu 16.04 (Xenial)
+and Ubuntu 18.04 (Bionic) are being built at this time. Ubuntu 14.04 (Trusty) is no longer supported.
Use your preferred editor and open (or create)
``/etc/apt/sources.list.d/cloudstack.list``. Add the community provided
diff --git a/source/installguide/overview/_requirements.rst b/source/installguide/overview/_requirements.rst
index 1531462..173e329 100644
--- a/source/installguide/overview/_requirements.rst
+++ b/source/installguide/overview/_requirements.rst
@@ -29,7 +29,7 @@
- Operating system:
- - Preferred: CentOS/RHEL 7.2+, CentOS/RHEL 6.8+ or Ubuntu 14.04(.2) or higher
+ - Preferred: CentOS/RHEL 7.2+ or Ubuntu 16.04(.2) or higher
- 64-bit x86 CPU (more cores results in better performance)
diff --git a/source/plugins/cloudstack-kubernetes-service.rst b/source/plugins/cloudstack-kubernetes-service.rst
new file mode 100644
index 0000000..0c61de9
--- /dev/null
+++ b/source/plugins/cloudstack-kubernetes-service.rst
@@ -0,0 +1,372 @@
+.. Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with this work
+ for additional information# regarding copyright ownership. The ASF licenses this
+ file to you under the Apache License, Version 2.0 (the "License"); you may not
+ use this file except in compliance with the License. You may obtain a copy of
+ the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by
+ applicable law or agreed to in writing, software distributed under the License
+ is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the specific language
+ governing permissions and limitations under the License.
+
+
+CloudStack Kubernetes Service
+==============================
+
+The Kubernetes Service plugin adds Kubernetes integration to CloudStack. The plugin is disabled by default and an admin can enable it using a Global Setting. It enables users to run containerized services using Kubernetes clusters.
+
+Kubernetes Service plugin uses a CoreOS based template for node VMs for the Kubernetes cluster. CoreOS has been used as it provides docker installation and networking rules needed for Kubernetes by default. In future, different guest OSes might be used. For installation of Kubernetes binaries on cluster nodes, a binaries ISO is used for each Kubernetes version to be made available via CloudStack. This allows faster, offline installation of Kubernetes binaries and docker images along with support for adding multiple versions of Kubernetes for upgrades and running different clusters.
+
+For deployment and setup of Kubernetes on cluster nodes, the plugin uses the Kubernetes tool, 'kubeadm'. kubeadm is the command-line tool for easily provisioning a secure Kubernetes cluster on top of physical or cloud servers or virtual machines. Under the hood, master node(s) of the cluster starts a Kubernetes cluster using kubeadm init command with a custom token, and worker nodes join this Kubernetes cluster using kubeadm join command with the same token. More about kubeadm here: https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm/. Weave Net CNI provider plugin is used for cluster networking. More about Weave Net provide plugin here: https://www.weave.works/docs/net/latest/kubernetes/kube-addon/.
+
+To access the Kubernetes dashboard securely, the plugin provides access to kubeconfig file data which uses the Kubernetes tool kubectl to run a local proxy and thereby access the dashboard. More about kubectl here: https://kubernetes.io/docs/reference/kubectl/overview/
+
+The service allows creation of Kubernetes clusters using the UI or API. Both UI and API provide the ability to list, delete, scale upgrade, stop and start these clusters.
+
+Enabling the Kubernetes Service
+--------------------------------
+
+The Kubernetes Service plugin is disabled by default. To enable it, go to Global Settings and set the following global configuration to true:
+
+.. parsed-literal::
+
+ cloud.kubernetes.service.enabled
+
+Restart the Management Server to enable the set configuration values.
+
+.. parsed-literal::
+
+ # service cloudstack-management restart
+
+ # service cloudstack-usage restart
+
+Once the Kubernetes service is running the new APIs will become accessible and the UI will start show a Kubernetes Service tab.
+
+Kubernetes Supported Versions
+------------------------------
+
+The Kubernetes service provides the functionality to manage multiple supported Kubernetes versions. Management can be via both UI and API. A supported version corresponds to a specific Kubernetes version for which an ISO has been uploaded. Pre-built, community ISOs for different Kubernetes versions are available at:
+
+- http://download.cloudstack.org/cks/
+- http://packages.shapeblue.com/cks/
+
+A script is provided (see below) to add other Kubernetes versions. Once an ISO is created for a Kubernetes version it can be added in the service and other CRUD operations can be performed using both the UI and API. Using a pre-packaged ISO containing required binaries and docker images allows faster provisioning on the node virtual machines of a Kubernetes cluster. Complete offline provisioning of the Kubernetes cluster is not supported at present as the kubeadm init command needs active Internet access.
+
+A script named create-kubernetes-binaries-iso.sh has been provided in the cloudstack-common package for creating a new setup ISO with the desired version of Kubernetes binaries and corresponding docker images.
+
+Usage:
+
+.. parsed-literal::
+
+ # ./create-kubernetes-binaries-iso.sh OUTPUT_PATH KUBERNETES_VERSION CNI_VERSION CRICTL_VERSION WEAVENET_NETWORK_YAML_CONFIG DASHBOARD_YAML_CONFIG
+
+Eg:
+
+.. parsed-literal::
+
+ # ./create-binaries-iso.sh ./ 1.12.5 0.7.1 1.12.0 "https://cloud.weave.works/k8s/net?k8s-version=1.12.5" https://raw.githubusercontent.com/kubernetes/dashboard/v2.0.0-beta1/aio/deploy/recommended.yaml
+
+Working with Kubernetes supported version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Adding supported Kubernetes version
+####################################
+
+Once the ISO has been built for a desired Kubernetes version, it can be added by the admin in the service for cluster deployment using both the UI and API. The UI provides the following form to add new supported version:
+
+|cks-add-version-form.png|
+
+addKubernetesSupportedVersion API can be used by an admin to add a new supported version for the service. It takes following input parameters:
+
+- **name** (the name of the Kubernetes supported version) · semanticversion (the semantic version of the Kubernetes release in MAJOR.MINOR.PATCH format. More about semantic versioning here: https://semver.org/ Required)
+- **zoneid** (the ID of the zone in which Kubernetes supported version will be available)
+- **url** (the URL of the binaries ISO for Kubernetes supported version)
+- **checksum** (the checksum value of the binaries ISO)
+- **mincpunumber** (the minimum number of CPUs to be set with the Kubernetes supported version)
+- **minmemory** (the minimum RAM size in MB to be set with the Kubernetes supported version)
+
+For example:
+
+.. parsed-literal::
+ > add kubernetessupportedversion name=v1.13.2 semanticversion=1.13.2 url=http://172.20.0.1/files/setup-1.13.2.iso zoneid=34d23dd5-5ced-4e8b-9b0a-835a0b8ae2a6 mincpunumber=2 minmemory=2048
+ {
+ "kubernetessupportedversion": {
+ "id": "6668e999-fe6c-4a91-88d8-d10bcf280d02",
+ "isoid": "78d45e9b-a482-46f4-8cbc-cf7964564b85",
+ "isoname": "v1.13.2-Kubernetes-Binaries-ISO",
+ "isostate": "Active",
+ "semanticversion": "1.13.2",
+ "name": "v1.13.2",
+ "supportsha": false,
+ "zoneid": "34d23dd5-5ced-4e8b-9b0a-835a0b8ae2a6",
+ "zonename": "KVM-advzone1"
+ "mincpunumber": 2
+ "minmemory": 2048
+ }
+ }
+
+The minimum Kubernetes version that can be added in the service is 1.11. At present, v1.17 and above might not work due to their incompatibility with weave-net plugin.
+
+Listing supported Kubernetes versions
+######################################
+
+listKubernetesSupportedVersion API can be used to list existing supported versions. id parameter can be passed as input to list details of a single supported version.
+
+|cks-versions.png|
+
+Updating supported Kubernetes version
+######################################
+
+updateKubernetesSupportedVersion API can be used by admins to update an existing supported version to set their state enabled or disabled. Supported versions with disabled state cannot be used for deploying Kubernetes clusters. It takes following input parameters,
+
+- **id** (the ID of the Kubernetes supported version)
+- **state** (the state of the Kubernetes supported version)
+
+Deleting supported Kubernetes version
+######################################
+
+deleteKubernetesSupportedVersion API has been provided for admins to delete an existing supported version if it is not used by any Kubernetes cluster in the service. id parameter of the API can be used to pass Kubernetes version to be deleted.
+
+.. note::
+ addKubernetesSupportedVersion, updatedKubernetesSupportedVersion and deleteKubernetesSupportedVersion APIs are available to admin only
+
+Kubernetes clusters
+--------------------
+
+The Kubernetes service provides the functionality of running and managing Kubernetes clusters. Highly available, scalable Kubernetes clusters can be created to run containerized deployments without having to set up Kubernetes on each container node manually. The service will automatically provision the desired number of virtual machines as per cluster size using the binaries from the given Kubernetes version. Additionally, the service provides the functionality to upgrade and scale clusters. Running clusters can be upgraded to a newer minor or patch Kubernetes version at a time. Running clusters can also be scaled for the number of worker nodes up and down and for the service offering used by each node.
+
+This provides functionality to create Kubernetes clusters for Shared, Isolated and VPC networks in CloudStack, but such networks must be accessible to the CloudStack management server for provisioning virtual machines on the cluster. Template and default network offering must be set Global Settings for the service to create Kubernetes clusters.
+
+The following Global Settings value must be set to the name of Template to be used for deploying node virtual machines for the respective hypervisor while creating a Kubernetes cluster:
+
+- **cloud.kubernetes.cluster.template.name.hyperv** (Name of the template to be used for creating Kubernetes cluster nodes on HyperV)
+- **cloud.kubernetes.cluster.template.name.kvm** (Name of the template to be used for creating Kubernetes cluster nodes on KVM)
+- **cloud.kubernetes.cluster.template.name.vmware** (Name of the template to be used for creating Kubernetes cluster nodes on VMware)
+- **cloud.kubernetes.cluster.template.name.xenserver** (Name of the template to be used for creating Kubernetes cluster nodes on Xenserver)
+
+CoreOS templates for CloudStack can be found here, http://dl.openvm.eu/cloudstack/coreos/x86_64/
+
+The following Global Setting value must be set to the name of Network Offering to be used for creating a new network when no network has been selected while creating a Kubernetes cluster:
+
+.. parsed-literal::
+
+ cloud.kubernetes.cluster.network.offering
+
+A new network offering named DefaultNetworkOfferingforKubernetesService has been added since 4.14.0
+
+.. note::
+ - Multi-master, HA cluster can be created for Kubernetes version 1.16 and above only.
+ - While creating multi-master, HA cluster over a shared network, an external load-balancer must be manually setup. This load-balancer should have port-forwarding rules for SSH, Kubernetes API server access. Service assumes SSH access to cluster nodes is available from port 2222 to (2222 + cluster node count -1). Similarly, for API access 6443 must be forwarded to master nodes. Over the CloudStack isolated network these rules are automatically provisioned.
+
+Managing Kubernetes clusters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For Kubernetes cluster management, the service provides create, stop, start, scale, upgrade and delete APIs and similar features in the UI.
+
+Creating a new Kubernetes cluster
+##################################
+
+New Kubernetes clusters can be create using API or from UI. User will be provided with a Add Kubernetes Cluster form as shown below,
+
+|cks-create-cluster-form.png|
+
+createKubernetesCluster API can be used to create new Kubernetes cluster. It takes following parameters as input,
+
+- **name** (name for the Kubernetes cluster; Required)
+- **description** (description for the Kubernetes cluster; Required)
+- **zoneid** (availability zone in which Kubernetes cluster to be launched; Required)
+- **kubernetesversionid** (Kubernetes version with which cluster to be launched; Required)
+- **serviceofferingid** (the ID of the service offering for the virtual machines in the cluster; Required)
+- **account** (an optional account for the virtual machine. Must be used with domainId)
+- **domainid** (an optional domainId for the virtual machine. If the account parameter is used, domainId must also be used)
+- **projectid** (Deploy cluster for the project)
+- **networkid** (Network in which Kubernetes cluster is to be launched)
+- **keypair** (name of the ssh key pair used to login to the virtual machines)
+- **masternodes** (number of Kubernetes cluster master nodes, default is 1) externalloadbalanceripaddress (external load balancer IP address while using shared network with Kubernetes HA cluster)
+- **size** (number of Kubernetes cluster worker nodes; Required)
+- **noderootdisksize** (root disk size of root disk for each node)
+- **dockerregistryusername** (username for the docker image private registry; Experimental)
+- **dockerregistrypassword** (password for the docker image private registry; Experimental)
+- **dockerregistryurl** (URL for the docker image private registry; Experimental)
+- **dockerregistryemail** (email of the docker image private registry user; Experimental)
+
+For example:
+
+.. parsed-literal::
+ > create kubernetescluster name=Test description=Test-Cluster zoneid=34d23dd5-5ced-4e8b-9b0a-835a0b8ae2a6 size=1 noderootdisksize=10 serviceofferingid=a4f280a1-9122-40a8-8f0c-3adb91060f2a kubernetesversionid=6668e999-fe6c-4a91-88d8-d10bcf280d02
+ {
+ "kubernetescluster": {
+ "associatednetworkname": "Test-network",
+ "cpunumber": "4",
+ "description": "Test-Cluster",
+ "endpoint": "https://172.20.20.12:6443/",
+ "id": "74e3cc02-bbf7-438f-bfb0-9c193e90c1fb",
+ "kubernetesversionid": "6668e999-fe6c-4a91-88d8-d10bcf280d02",
+ "kubernetesversionname": "v1.13.2",
+ "masternodes": 1,
+ "memory": "4096",
+ "name": "Test",
+ "networkid": "148af2cb-4b94-42a2-b701-3b6aa884cbb0",
+ "serviceofferingid": "a4f280a1-9122-40a8-8f0c-3adb91060f2a",
+ "serviceofferingname": "CKS Instance",
+ "size": 1,
+ "state": "Running",
+ "templateid": "17607ed6-1756-4ed7-b0f4-dbab5feff5b2",
+ "virtualmachineids": [
+ "da2cb67e-e852-4ecd-b16f-a8f16eb2c962",
+ "4179864a-88ad-4d6d-890c-c9b73c53589b"
+ ],
+ "zoneid": "34d23dd5-5ced-4e8b-9b0a-835a0b8ae2a6",
+ "zonename": "KVM-advzone1"
+ }
+ }
+
+On successful creation, the new cluster will be automatically started and will show up in Running state. If creation of the new cluster fails it can be in following states:
+- Alert – When node virtual machines were successfully provisioned, and cluster API server is accessible but further provisioning steps could not be completed.
+- Error – When the service has unable to provision node virtual machines for the cluster or cluster API server is not accessible.
+
+.. note::
+ - For CoreOS, a minimum of 2 cores of CPU and 2GB of RAM is needed for deployment. Therefore, the serviceofferingid parameter of createKuberntesCluster API must be provided with the ID of such compute offerings that conform to these requirements.
+ - Private docker registry related parameters of createKubentesCluster API (dockerregistryusername, dockerregistryusername, dockerregistryurl, dockerregistryemail) provides experimental functionality. To use them during cluster deployment value for global setting, cloud.kubernetes.cluster.experimental.features.enabled, must be set as true by admin beforehand.
+
+Listing Kubernetes clusters
+############################
+
+listKubernetesCluster API can be used to list existing Kubernetes clusters. id parameter can be passed as input to list details of a single supported version.
+
+|cks-clusters.png|
+
+Stopping Kubernetes cluster
+############################
+
+A running Kubernetes cluster can be stopped using both the API and |cks-stop-action.png| action icon from UI. action icon is shown for a running cluster in the UI.
+
+stopKubernetesCluster can be used to stop a running cluster. It takes id of the cluster as the input parameter.
+
+Starting a stopped Kubernetes cluster
+######################################
+
+A stopped Kubernetes cluster can be started using both API and the |cks-start-action.png| action icon from UI. action icon is shown for a stopped cluster in the UI.
+
+startKubernetesCluster can be used to start a stopped cluster. It takes id of the cluster as the input parameter.
+
+When the service fails to start a stopped cluster, the cluster will show in Alert state else it will show in Running state.
+
+Scaling Kubernetes cluster
+###########################
+
+A running or stopped Kubernetes cluster can be scaled using both API and UI. |cks-scale-action.png| action icon is shown for a running cluster in the UI which opens the form shown below,
+
+|cks-scale-cluster-form.png|
+
+scaleKubernetesCluster API can be used to scale a running (or stopped cluster) for a desired cluster size and service offering. It takes following parameters as input,
+
+- **id** (the ID of the Kubernetes cluster to be scaled; Required)
+- **serviceofferingid** (the ID of the new service offering for the virtual machines in the cluster)
+- **size** (number of Kubernetes cluster worker nodes)
+
+Only running Kubernetes clusters can be scaled for size. When the service fails to scale the cluster, the cluster will show in Alert state else if the scaling is successfull cluster will show up in Running state.
+
+Note: Only upscaling is supported while scaling clusters for service offering.
+
+Upgrading Kubernetes cluster
+#############################
+
+A running Kubernetes cluster can be upgraded using both API and UI. |cks-upgrade-action.png| action icon is shown for a running cluster in the UI which opens the form shown below,
+
+|cks-upgrade-cluster-form.png|
+
+upgradeKubernetesCluster API can be used to upgrade a running cluster. It takes following parameters as input:
+
+- **id** (the ID of the Kubernetes cluster to be upgraded; Required)
+- **kubernetesversionid** (Kubernetes version with which cluster to be launched; Required)
+
+When the service fails to upgrade the cluster, the cluster will show in Alert state. If the upgrade has been successful cluster will show in Running state.
+
+.. note:: Kubernetes can be upgraded from one MINOR version to the next MINOR version, or between PATCH versions of the same MINOR. That is, you cannot skip MINOR versions when you upgrade. For example, you can upgrade from 1.y to 1.y+1, but not from 1.y to 1.y+2. Therefore, service can upgrade running clusters in the similar manner only.
+
+Deleting Kubernetes cluster
+############################
+
+Both UI and API can be used to delete a created Kubernetes cluster. |cks-delete-action.png| action icon will be available in UI to delete a cluster.
+
+deleteKubernetesCluster can be used to delete a cluster. It takes id of the cluster as the input parameter.
+
+The Kubernetes service runs a background state scanner process which regularly checks for cluster health. For clusters in Alert state, this background process verifies their state and moves them to Running state if all node virtual machines for the cluster are running and API server for the cluster is accessible.
+
+Working with Kubernetes cluster
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+|cks-cluster-details-tab.png|
+
+Once a Kubernetes cluster is created successfully and it is running state, it can be accessed using kubectl tool using cluster’s kubeconfig file. The web dashboard can be accessed by running local proxy using kubectl. Deployments in the cluster can be done using kubectl or web dashboard. More about deployment in Kubernetes here: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/
+
+Accessing Kubernetes cluster
+#############################
+
+Instructions for accessing a running cluster will be shown in Access tab in the UI.
+
+The service provides functionality to access kubeconfig file for a running Kubernetes cluster. This can be done using the UI or API. Action icon is shown in cluster detail UI to download kubeconfig file. UI will show download links for kubectl tool for different OS based on the cluster version.
+
+getKubernetesClusterConfig API can be used to retrieve kubeconfig file data for a cluster. It takes id of the cluster as the input parameter.
+
+Kubernetes cluster web dashboard
+#################################
+
+The service while creating a cluster automatically deploys dashboard for the cluster. More details about Kubernetes dashboard here: https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/
+
+Instructions for accessing the dashboard for a running cluster will be shown in the Access tab in the UI. Essentially, the user needs to run a local proxy first using kubectl and kubecofig file for the cluster to access the dashboard. For secure login, the service doesn’t enable kubeconfig based login for the dashboard. Token-based access is enabled and kubectl can be used to access service account secret token.
+
+|cks-cluster-access-tab.png|
+
+The following command can be used, while passing the correct path to kubeconfig file, to run proxy:
+
+.. parsed-literal::
+
+ # kubectl --kubeconfig /custom/path/kube.config proxy
+
+Once the proxy is running user can open the following URL in the browser to open the dashboard,
+
+.. parsed-literal::
+
+ http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/
+
+|cks-cluster-dashboard.png|
+
+Token for dashboard login can be retrieved using following command
+
+.. parsed-literal::
+
+ # kubectl --kubeconfig /custom/path/kube.config describe secret $(kubectl --kubeconfig /custom/path/kube.config get secrets -n kubernetes-dashboard | grep kubernetes-dashboard-token | awk '{print $1}') -n kubernetes-dashboard
+
+
+.. |cks-add-version-form.png| image:: /_static/images/cks-add-version-form.png
+ :alt: Add Kubernetes Supported Version form.
+.. |cks-cluster-access-tab.png| image:: /_static/images/cks-cluster-access-tab.png
+ :alt: Kubernetes cluster access tab.
+.. |cks-cluster-dashboard.png| image:: /_static/images/cks-cluster-dashboard.png
+ :alt: Kubernetes cluster dashboard.
+.. |cks-cluster-details-tab.png| image:: /_static/images/cks-cluster-details-tab.png
+ :alt: Kubernetes details tab.
+.. |cks-clusters.png| image:: /_static/images/cks-clusters.png
+ :alt: Kubernetes clusters list.
+.. |cks-create-cluster-form.png| image:: /_static/images/cks-create-cluster-form.png
+ :alt: Create Kubernetes Cluster form.
+.. |cks-delete-action.png| image:: /_static/images/cks-delete-action.png
+ :alt: Delete action icon.
+.. |cks-kube-config-action.png| image:: /_static/images/cks-kube-config-action.png
+ :alt: Download kube-config action icon.
+.. |cks-scale-action.png| image:: /_static/images/cks-scale-action.png
+ :alt: Scale action icon.
+.. |cks-scale-cluster-form.png| image:: /_static/images/cks-scale-cluster-form.png
+ :alt: Scale Kubernetes Cluster form.
+.. |cks-start-action.png| image:: /_static/images/cks-start-action.png
+ :alt: Start action icon.
+.. |cks-stop-action.png| image:: /_static/images/cks-stop-action.png
+ :alt: Stop action icon.
+.. |cks-upgrade-action.png| image:: /_static/images/cks-upgrade-action.png
+ :alt: Upgrade action icon.
+.. |cks-upgrade-cluster-form.png| image:: /_static/images/cks-upgrade-cluster-form.png
+ :alt: Upgrade Kubernetes Cluster form.
+.. |cks-versions.png| image:: /_static/images/cks-versions.png
+ :alt: Supported Kubernetes versions list.
diff --git a/source/plugins/index.rst b/source/plugins/index.rst
index 167e3d2..fe95333 100644
--- a/source/plugins/index.rst
+++ b/source/plugins/index.rst
@@ -37,4 +37,5 @@
ovs-plugin
ipv6
quota
+ cloudstack-kubernetes-service
diff --git a/source/releasenotes/compat.rst b/source/releasenotes/compat.rst
index b88ec12..8aa2b08 100644
--- a/source/releasenotes/compat.rst
+++ b/source/releasenotes/compat.rst
@@ -20,20 +20,17 @@
-------------------------------------------
This section lists the operating systems that are supported for running
-CloudStack Management Server. Note that specific versions of the
-operating systems are tested, so compatibility with CentOS 6.3 may not
-indicate compatibility with CentOS 6.2, 6.1 and so on.
+CloudStack Management Server.
-- RHEL versions 6.3, 6.5, 6.6 and 7.0
-- CentOS versions 6.8, 7
+- RHEL versions 7.x
+- CentOS versions 7.x
- Ubuntu 16.04 LTS, 18.04 LTS
Software Requirements
~~~~~~~~~~~~~~~~~~~~~
-- Java JRE 1.8
-- MySQL 5.6, 5.7 (RHEL 7)
-- MySQL 5.1 (RHEL 6.x)
+- Java JRE 11
+- MySQL 5.5, 5.6, 5.7
Supported Hypervisor Versions
-----------------------------
@@ -41,16 +38,16 @@
CloudStack supports three hypervisor families, XenServer with XAPI, KVM,
and VMware with vSphere.
-- CentOS 6.2+, 7.0+ with KVM
-- Ubuntu 14.04LTS, 16.04LTS, 18.04LTS with KVM
-- Red Hat Enterprise Linux 6.2 with KVM
-- XenServer versions 6.1, 6.2 SP1, 6.5, 7.0, 7.1, 7.2 with latest hotfixes, XCP-ng 7.4, 7.6
+- CentOS 7.x with KVM
+- Ubuntu 16.04 LTS, 18.04 LTS with KVM
+- Red Hat Enterprise Linux 7.x with KVM
+- XenServer versions 7.0, 7.1, 7.2, 7.4, 7.5 with latest hotfixes, XCP-ng 7.4, 7.6
.. note:: It is now required to enable HA on the XenServer pool in order to recover from a pool-master failure. Please refer to the `XenServer documentation <http://docs.vmd.citrix.com/XenServer/6.5.0/1.0/en_gb/>`_.
-- VMware versions 5.0, 5.1, 5.5, 6.0, 6.5 and 6.7
+- VMware versions 6.0, 6.5 and 6.7 (tested up to 6.7 U3)
- .. note:: There is a known issue in 6.7u1 (https://kb.vmware.com/s/article/67315) which blocks some CloudStack cloning operations. The use of linked clones is known to be effected.
+ .. note:: There is a known issue in 6.7 U1 (https://kb.vmware.com/s/article/67315) which blocks some CloudStack cloning operations. The use of linked clones is known to be effected.
- LXC Host Containers on RHEL 7
- Windows Server 2012 R2 (with Hyper-V Role enabled)
@@ -59,10 +56,6 @@
- Bare metal hosts are supported, which have no hypervisor. These hosts
can run the following operating systems:
- - RHEL or CentOS, v6.2 or 6.3
-
- .. note:: Use libvirt version 0.9.10 for CentOS 6.3
-
- Fedora 17
- Ubuntu 12.04
@@ -97,18 +90,20 @@
Notice Of Management OSes and Hypervisors to be Deprecated
----------------------------------------------------------
-The following hypervisors will no longer be supported in the next release
+The following hypervisors are no longer be supported in this release
- XenServer 6.2
- XenServer 6.5
- vSphere 5.0
- vSphere 5.1
- vSphere 5.5
-- CentOS (KVM) 6.x
+- CentOS/RHEL (KVM) 6.x
+- Ubuntu 14.04
-The following Management Server Operating Systems will no longer be supported in the next release
+The following Management Server Operating Systems are no longer supported in this release
- CentOS 6.x
+- Ubuntu 14.04
Please see `CloudStack Wiki <https://cwiki.apache.org/confluence/display/CLOUDSTACK/Hypervisor+and+Management+Server+OS+EOL+Dates>`_
diff --git a/source/upgrading/index.rst b/source/upgrading/index.rst
index 3fefce9..7bb6c28 100644
--- a/source/upgrading/index.rst
+++ b/source/upgrading/index.rst
@@ -36,7 +36,7 @@
.. toctree::
:maxdepth: 1
-
+
upgrade/upgrade-4.13
upgrade/upgrade-4.12
upgrade/upgrade-4.11
diff --git a/source/upgrading/upgrade/_java_8_ubuntu.rst b/source/upgrading/upgrade/_java_version.rst
similarity index 61%
rename from source/upgrading/upgrade/_java_8_ubuntu.rst
rename to source/upgrading/upgrade/_java_version.rst
index 1e0a57d..5604747 100644
--- a/source/upgrading/upgrade/_java_8_ubuntu.rst
+++ b/source/upgrading/upgrade/_java_version.rst
@@ -15,17 +15,24 @@
.. sub-section included in upgrade notes.
-Java 8 JRE on Ubuntu
---------------------
+Java Version Requirement
+------------------------
-CloudStack |version| requires installation of Java 8 JRE from an external PPA
-such as openjdk-r for Ubuntu distributions where the openjdk-8 packages are not
-available from the main repositories such as on Ubuntu 14.04. The PPA can be
-added before installation/upgrade:
+CloudStack |version| requires installation of Java 11 JRE for management server
+and the KVM agent. On installing or upgrading cloudstack-management and/or
+cloudstack-agent packages, please configure Java 11 as the default java
+version using:
+
+ .. parsed-literal::
+
+ $ sudo alternatives --config java
+
+Note: For Ubuntu distributions where the openjdk-11 packages are not available
+from the main repositories, the JRE can be installed from an external PPA such
+as openjdk-r. The PPA can be added before installation/upgrade:
.. parsed-literal::
$ sudo add-apt-repository ppa:openjdk-r/ppa
$ sudo apt-get update
-Users can also choose to install Java 8 distribution from Oracle, or `Xulu-8 <http://repos.azulsystems.com/>`_ OpenJDK distribution from Azul.
diff --git a/source/upgrading/upgrade/_sysvm_templates.rst b/source/upgrading/upgrade/_sysvm_templates.rst
index 36793d4..6503568 100644
--- a/source/upgrading/upgrade/_sysvm_templates.rst
+++ b/source/upgrading/upgrade/_sysvm_templates.rst
@@ -48,9 +48,7 @@
| | |
| | Format: VHD |
| | |
- | | OS Type: Debian GNU/Linux 7.0 (64-bit) (or the |
- | | highest Debian release number available in the |
- | | dropdown) |
+ | | OS Type: Other Linux (64-bit) |
| | |
| | Extractable: no |
| | |
@@ -100,7 +98,7 @@
| | |
| | Format: OVA |
| | |
- | | OS Type: Other Linux 64-bit |
+ | | OS Type: Other Linux (64-bit) |
| | |
| | Extractable: no |
| | |
diff --git a/source/upgrading/upgrade/_timezone.rst b/source/upgrading/upgrade/_timezone.rst
new file mode 100644
index 0000000..1c00863
--- /dev/null
+++ b/source/upgrading/upgrade/_timezone.rst
@@ -0,0 +1,32 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information#
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+.. sub-section included in upgrade notes.
+
+Time zone requirements
+######################
+
+As of CloudStack 4.14, you must explicitly configure time zone either in the MySQL server or JDBC driver (db.properties).
+In previous CloudStack versions, UTC time zone was assumed by default (all event's have UTC time stamps), so
+the same UTC time zone should now be explicitly configured.
+
+You can do this by editing the /etc/cloudstack/management/db.properties file and adding "serverTimezone=UTC"
+to the "db.cloud.url.params=" and "db.usage.url.params=" lines. Example lines, from a clean 4.14 installation, are given below:
+
+.. parsed-literal::
+
+ db.cloud.url.params=prepStmtCacheSize=517&cachePrepStmts=true&sessionVariables=sql_mode='STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION'&serverTimezone=UTC
+ db.usage.url.params=serverTimezone=UTC
+
diff --git a/source/upgrading/upgrade/upgrade-4.10.rst b/source/upgrading/upgrade/upgrade-4.10.rst
index 04906d3..a0070cd 100644
--- a/source/upgrading/upgrade/upgrade-4.10.rst
+++ b/source/upgrading/upgrade/upgrade-4.10.rst
@@ -59,6 +59,8 @@
.. include:: _sysvm_templates.rst
+.. include:: _java_version.rst
+
Packages repository
-------------------
@@ -102,25 +104,9 @@
.. parsed-literal::
- $ mysqldump -u root -p cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
+ $ mysqldump -u root -p -R cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
$ mysqldump -u root -p cloud_usage > cloud_usage-backup_`date '+%Y-%m-%d'`.sql
-#. **(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:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e "select id,name,path from cloud.storage_pool where pool_type='Filesystem'"
-
- If local storage paths are found to have a trailing forward slash,
- remove it:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';
-
.. _ubuntu410:
.. _apt-repo410:
@@ -128,6 +114,8 @@
Management Server
-----------------
+.. include:: _timezone.rst
+
Ubuntu
######
@@ -145,7 +133,6 @@
servers, and any hosts that have the KVM agent. (No changes should
be necessary for hosts that are running VMware or Xen.)
-.. include:: _java_8_ubuntu.rst
Start by opening ``/etc/apt/sources.list.d/cloudstack.list`` on
any systems that have CloudStack packages installed.
@@ -162,6 +149,8 @@
deb http://download.cloudstack.org/ubuntu precise |version|
+Please note that CloudStack |version| doesn't support Ubuntu 12.04/Precise and it's recommended to upgrade to Ubuntu 18.04
+
Setup the public key for the above repository:
.. parsed-literal::
@@ -232,6 +221,8 @@
http://download.cloudstack.org/centos/$releasever/|version|/
+Please note that CloudStack |version| doesn't support CentOS 6 and it's recommended to upgrade to CentOS 7.
+
Setup the GPG public key if you wish to enable ``gpgcheck=1``:
.. parsed-literal::
@@ -414,7 +405,6 @@
.. parsed-literal::
$ sudo service cloudstack-agent stop
- $ sudo killall jsvc
$ sudo service cloudstack-agent start
diff --git a/source/upgrading/upgrade/upgrade-4.11.rst b/source/upgrading/upgrade/upgrade-4.11.rst
index cfbe00b..e12f682 100644
--- a/source/upgrading/upgrade/upgrade-4.11.rst
+++ b/source/upgrading/upgrade/upgrade-4.11.rst
@@ -50,20 +50,14 @@
.. include:: _customisation_warnings.rst
.. warning::
- If you have not registered the 4.11.3 System VM templates for your hypervisors,
- you will need to register them prior to performing the upgrade of the CloudStack
- packages. This includes those currently running a **clean** install of CloudStack 4.11.3 (i.e. you
- did not upgrade from another version to reach 4.11.3) - you will still need to
- explicitly register the 4.11.3 System VM template(s), but you will not need
- to restart the existing system VMs.
-
- If you are running an instance of CloudStack 4.11.3
- that was upgraded from a the previous versions,
- you will already have explicitly registered the 4.11.3 System VM template(s) and
- need not to do it again.
+ If you are not already using the |sysvm64-version| System VM template you will need to
+ upgrade your System VM template prior to performing the upgrade of the
+ CloudStack packages.
.. include:: _sysvm_templates.rst
+.. include:: _java_version.rst
+
Packages repository
-------------------
@@ -106,25 +100,9 @@
.. parsed-literal::
- $ mysqldump -u root -p cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
+ $ mysqldump -u root -p -R cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
$ mysqldump -u root -p cloud_usage > cloud_usage-backup_`date '+%Y-%m-%d'`.sql
-#. **(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:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e "select id,name,path from cloud.storage_pool where pool_type='Filesystem'"
-
- If local storage paths are found to have a trailing forward slash,
- remove it:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';
-
.. _ubuntu411:
.. _apt-repo411:
@@ -132,6 +110,8 @@
Management Server
-----------------
+.. include:: _timezone.rst
+
Ubuntu
######
@@ -329,7 +309,6 @@
.. parsed-literal::
$ sudo service cloudstack-agent stop
- $ sudo killall jsvc
$ sudo service cloudstack-agent start
diff --git a/source/upgrading/upgrade/upgrade-4.12.rst b/source/upgrading/upgrade/upgrade-4.12.rst
index c0dfacb..e66b42f 100644
--- a/source/upgrading/upgrade/upgrade-4.12.rst
+++ b/source/upgrading/upgrade/upgrade-4.12.rst
@@ -54,6 +54,8 @@
.. include:: _sysvm_templates.rst
+.. include:: _java_version.rst
+
Packages repository
-------------------
@@ -96,25 +98,9 @@
.. parsed-literal::
- $ mysqldump -u root -p cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
+ $ mysqldump -u root -p -R cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
$ mysqldump -u root -p cloud_usage > cloud_usage-backup_`date '+%Y-%m-%d'`.sql
-#. **(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:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e "select id,name,path from cloud.storage_pool where pool_type='Filesystem'"
-
- If local storage paths are found to have a trailing forward slash,
- remove it:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';
-
.. _ubuntu412:
.. _apt-repo412:
@@ -122,11 +108,13 @@
Management Server
-----------------
+.. include:: _timezone.rst
+
Ubuntu
######
If you are using Ubuntu, follow this procedure to upgrade your packages. If
-not, skip to step :ref:`rhel411`.
+not, skip to step :ref:`rhel412`.
.. note::
**Community Packages:** This section assumes you're using the community
@@ -147,13 +135,13 @@
.. parsed-literal::
- deb http://download.cloudstack.org/ubuntu precise 4.12
+ deb http://download.cloudstack.org/ubuntu bionic 4.12
We'll change it to point to the new package repository:
.. parsed-literal::
- deb http://download.cloudstack.org/ubuntu precise |version|
+ deb http://download.cloudstack.org/ubuntu bionic |version|
Setup the public key for the above repository:
@@ -214,7 +202,7 @@
[apache-cloudstack]
name=Apache CloudStack
- baseurl=http://download.cloudstack.org/centos/6/4.12/
+ baseurl=http://download.cloudstack.org/centos/7/4.12/
enabled=1
gpgcheck=0
@@ -285,7 +273,7 @@
required only for clouds using KVM as hosts and only on the KVM
hosts.
-#. Configure the :ref:`APT repo <apt-repo411>` as detailed above.
+#. Configure the :ref:`APT repo <apt-repo412>` as detailed above.
#. Stop the running agent.
@@ -311,7 +299,7 @@
For KVM hosts, upgrade the ``cloudstack-agent`` package
-#. Configure the :ref:`rpm-repo411` as detailed above.
+#. Configure the :ref:`rpm-repo412` as detailed above.
.. parsed-literal::
@@ -322,7 +310,6 @@
.. parsed-literal::
$ sudo service cloudstack-agent stop
- $ sudo killall jsvc
$ sudo service cloudstack-agent start
diff --git a/source/upgrading/upgrade/upgrade-4.13.rst b/source/upgrading/upgrade/upgrade-4.13.rst
index 5563c8f..a85b833 100644
--- a/source/upgrading/upgrade/upgrade-4.13.rst
+++ b/source/upgrading/upgrade/upgrade-4.13.rst
@@ -18,6 +18,7 @@
Upgrade Instruction from |version_to_upgrade|
=============================================
+
This section will show you how to upgrade from CloudStack |version_to_upgrade| to latest
CloudStack |release|.
@@ -35,8 +36,11 @@
----------------------------
#. Check any customisations and integrations
+#. Upload the |sysvm64-version| System VM template if not already using it.
+#. Confirm Java 11 is the default Java version
#. Stop all running management servers
#. Backup CloudStack database (MySQL)
+#. Add "serverTimezone=UTC" to your "db.properties"
#. Upgrade 1st CloudStack management server
#. Update hypervisors specific dependencies
#. Restart 1st management server
@@ -47,9 +51,13 @@
.. include:: _customisation_warnings.rst
.. warning::
- CloudStack |release| uses the same systemVM templates as |version_to_upgrade|,
- so there is no need for a new systemVM template.
+ If you are not already using the |sysvm64-version| System VM template you will need to
+ upgrade your System VM template prior to performing the upgrade of the
+ CloudStack packages.
+.. include:: _sysvm_templates.rst
+
+.. include:: _java_version.rst
Packages repository
-------------------
@@ -63,7 +71,7 @@
the |release| source, or check the Apache CloudStack downloads page at
http://cloudstack.apache.org/downloads.html
for package repositories supplied by community members. You will need
-them for :ref:`ubuntu413` or :ref:`rhel413` and :ref:`kvm413` hosts upgrade.
+them for :ref:`ubuntu413` or :ref:`kvm413` hosts upgrade.
Instructions for creating packages from the CloudStack source are in the
`CloudStack Installation Guide`_.
@@ -93,25 +101,9 @@
.. parsed-literal::
- $ mysqldump -u root -p cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
+ $ mysqldump -u root -p -R cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
$ mysqldump -u root -p cloud_usage > cloud_usage-backup_`date '+%Y-%m-%d'`.sql
-#. **(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:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e "select id,name,path from cloud.storage_pool where pool_type='Filesystem'"
-
- If local storage paths are found to have a trailing forward slash,
- remove it:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';
-
.. _ubuntu413:
.. _apt-repo413:
@@ -119,6 +111,8 @@
Management Server
-----------------
+.. include:: _timezone.rst
+
Ubuntu
######
@@ -135,17 +129,20 @@
servers, and any hosts that have the KVM agent (no changes should
be necessary for hosts that are running VMware or Xen.)
-
-
-Make sure that your ``/etc/apt/sources.list.d/cloudstack.list`` file on
-any systems that have CloudStack packages installed points to version 4.13
+Edit your ``/etc/apt/sources.list.d/cloudstack.list`` file on
+any systems that have CloudStack packages installed to points to version |version|
This file should have one line, which contains:
.. parsed-literal::
- deb http://download.cloudstack.org/ubuntu precise 4.13
+ deb http://download.cloudstack.org/ubuntu bionic |version|
+Setup the public key for the above repository:
+
+.. parsed-literal::
+
+ wget -qO - http://download.cloudstack.org/release.asc | sudo apt-key add -
#. Now update your apt package list:
@@ -168,7 +165,7 @@
.. _rhel413:
-.. _fpo413:
+.. _rpm-repo413:
CentOS/RHEL
##############
@@ -186,8 +183,8 @@
management servers, and any hosts that have the KVM agent (no changes
should be necessary for hosts that are running VMware or Xen.)
-Confirm your ``/etc/yum.repos.d/cloudstack.repo`` file on
-any systems that have CloudStack packages installed points to version 4.13.
+Change your ``/etc/yum.repos.d/cloudstack.repo`` file on
+any systems that have CloudStack packages installed to points to version |version|.
This file should have content similar to the following:
@@ -195,7 +192,7 @@
[apache-cloudstack]
name=Apache CloudStack
- baseurl=http://download.cloudstack.org/centos/7/4.13/
+ baseurl=http://download.cloudstack.org/centos/$releasever/|version|/
enabled=1
gpgcheck=0
@@ -234,8 +231,8 @@
###################
.. warning::
- For VMware hypervisor CloudStack management server packages must be
- build using "noredist". Refer to :ref:`building-noredist`.
+ For VMware hypervisor, CloudStack management server packages must be
+ built using "noredist". Refer to :ref:`building-noredist`.
No additional steps are requried for the VMware Hypervisor for this upgrade.
@@ -291,7 +288,6 @@
.. parsed-literal::
$ sudo service cloudstack-agent stop
- $ sudo killall jsvc
$ sudo service cloudstack-agent start
@@ -309,3 +305,8 @@
.. parsed-literal::
$ sudo service cloudstack-usage start
+
+System-VMs and Virtual-Routers
+------------------------------
+
+.. include:: _sysvm_restart.rst
diff --git a/source/upgrading/upgrade/upgrade-4.2.rst b/source/upgrading/upgrade/upgrade-4.2.rst
index cd782cc..596245f 100644
--- a/source/upgrading/upgrade/upgrade-4.2.rst
+++ b/source/upgrading/upgrade/upgrade-4.2.rst
@@ -56,6 +56,8 @@
.. include:: _sysvm_templates.rst
+.. include:: _java_version.rst
+
Database Preparation
--------------------
@@ -86,23 +88,6 @@
$ mysqldump -u root -p cloud_usage > cloud_usage-backup_`date '+%Y-%m-%d'`.sql
-#. **(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:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e "select id,name,path from cloud.storage_pool where pool_type='Filesystem'"
-
- If local storage paths are found to have a trailing forward slash,
- remove it:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';
-
-
.. _ubuntu42:
Management Server Ubuntu
@@ -111,6 +96,8 @@
If you are using Ubuntu, follow this procedure to upgrade your packages. If
not, skip to step :ref:`rhel42`.
+.. include:: _timezone.rst
+
.. note::
**Community Packages:** This section assumes you're using the community
supplied packages for CloudStack. If you've created your own packages and
@@ -123,7 +110,6 @@
.. _apt-repo42:
-.. include:: _java_8_ubuntu.rst
CloudStack apt repository
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -180,6 +166,8 @@
If you are using CentOS or RHEL, follow this procedure to upgrade your
packages. If not, skip to hypervisors section :ref:`upg_hyp_42`.
+.. include:: _timezone.rst
+
.. note::
**Community Packages:** This section assumes you're using the community
supplied packages for CloudStack. If you've created your own packages and
@@ -397,7 +385,6 @@
.. parsed-literal::
$ sudo service cloudstack-agent stop
- $ sudo killall jsvc
$ sudo service cloudstack-agent start
diff --git a/source/upgrading/upgrade/upgrade-4.3.rst b/source/upgrading/upgrade/upgrade-4.3.rst
index 491cc19..4c7e79a 100644
--- a/source/upgrading/upgrade/upgrade-4.3.rst
+++ b/source/upgrading/upgrade/upgrade-4.3.rst
@@ -60,6 +60,8 @@
.. include:: _sysvm_templates.rst
+.. include:: _java_version.rst
+
Database Preparation
--------------------
@@ -89,22 +91,6 @@
$ mysqldump -u root -p cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
$ mysqldump -u root -p cloud_usage > cloud_usage-backup_`date '+%Y-%m-%d'`.sql
-#. **(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:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e "select id,name,path from cloud.storage_pool where pool_type='Filesystem'"
-
- If local storage paths are found to have a trailing forward slash,
- remove it:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';
-
.. _ubuntu43:
@@ -114,6 +100,8 @@
If you are using Ubuntu, follow this procedure to upgrade your packages. If
not, skip to step :ref:`rhel43`.
+.. include:: _timezone.rst
+
.. note::
**Community Packages:** This section assumes you're using the community
supplied packages for CloudStack. If you've created your own packages and
@@ -127,7 +115,6 @@
.. _apt-repo43:
-.. include:: _java_8_ubuntu.rst
CloudStack apt repository
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -184,6 +171,8 @@
If you are using CentOS or RHEL, follow this procedure to upgrade your
packages. If not, skip to hypervisors section :ref:`upg_hyp_43`.
+.. include:: _timezone.rst
+
.. note::
**Community Packages:** This section assumes you're using the community
supplied packages for CloudStack. If you've created your own packages and
@@ -402,7 +391,6 @@
.. parsed-literal::
$ sudo service cloudstack-agent stop
- $ sudo killall jsvc
$ sudo service cloudstack-agent start
diff --git a/source/upgrading/upgrade/upgrade-4.4.rst b/source/upgrading/upgrade/upgrade-4.4.rst
index 67f1223..0be2e86 100644
--- a/source/upgrading/upgrade/upgrade-4.4.rst
+++ b/source/upgrading/upgrade/upgrade-4.4.rst
@@ -60,6 +60,8 @@
.. include:: _sysvm_templates.rst
+.. include:: _java_version.rst
+
Database Preparation
--------------------
@@ -89,22 +91,6 @@
$ mysqldump -u root -p cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
$ mysqldump -u root -p cloud_usage > cloud_usage-backup_`date '+%Y-%m-%d'`.sql
-#. **(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:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e "select id,name,path from cloud.storage_pool where pool_type='Filesystem'"
-
- If local storage paths are found to have a trailing forward slash,
- remove it:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';
-
.. _ubuntu44:
@@ -114,6 +100,8 @@
If you are using Ubuntu, follow this procedure to upgrade your packages. If
not, skip to step :ref:`rhel44`.
+.. include:: _timezone.rst
+
.. note::
**Community Packages:** This section assumes you're using the community
supplied packages for CloudStack. If you've created your own packages and
@@ -127,7 +115,6 @@
.. _apt-repo44:
-.. include:: _java_8_ubuntu.rst
CloudStack apt repository
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -184,6 +171,8 @@
If you are using CentOS or RHEL, follow this procedure to upgrade your
packages. If not, skip to hypervisors section :ref:`upg_hyp_44`.
+.. include:: _timezone.rst
+
.. note::
**Community Packages:** This section assumes you're using the community
supplied packages for CloudStack. If you've created your own packages and
@@ -404,7 +393,6 @@
.. parsed-literal::
$ sudo service cloudstack-agent stop
- $ sudo killall jsvc
$ sudo service cloudstack-agent start
diff --git a/source/upgrading/upgrade/upgrade-4.5.rst b/source/upgrading/upgrade/upgrade-4.5.rst
index 7e7d5b4..da6102b 100644
--- a/source/upgrading/upgrade/upgrade-4.5.rst
+++ b/source/upgrading/upgrade/upgrade-4.5.rst
@@ -53,6 +53,8 @@
.. include:: _sysvm_templates.rst
+.. include:: _java_version.rst
+
Packages repository
-------------------
@@ -98,22 +100,6 @@
$ mysqldump -u root -p cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
$ mysqldump -u root -p cloud_usage > cloud_usage-backup_`date '+%Y-%m-%d'`.sql
-#. **(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:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e "select id,name,path from cloud.storage_pool where pool_type='Filesystem'"
-
- If local storage paths are found to have a trailing forward slash,
- remove it:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';
-
.. _ubuntu45:
@@ -123,6 +109,8 @@
If you are using Ubuntu, follow this procedure to upgrade your packages. If
not, skip to step :ref:`rhel45`.
+.. include:: _timezone.rst
+
.. note::
**Community Packages:** This section assumes you're using the community
supplied packages for CloudStack. If you've created your own packages and
@@ -136,7 +124,6 @@
.. _apt-repo45:
-.. include:: _java_8_ubuntu.rst
CloudStack apt repository
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -196,6 +183,8 @@
If you are using CentOS or RHEL, follow this procedure to upgrade your
packages. If not, skip to hypervisors section :ref:`upg_hyp_45`.
+.. include:: _timezone.rst
+
.. note::
**Community Packages:** This section assumes you're using the community
supplied packages for CloudStack. If you've created your own packages and
@@ -415,7 +404,6 @@
.. parsed-literal::
$ sudo service cloudstack-agent stop
- $ sudo killall jsvc
$ sudo service cloudstack-agent start
diff --git a/source/upgrading/upgrade/upgrade-4.6.rst b/source/upgrading/upgrade/upgrade-4.6.rst
index e308b04..eca297b 100644
--- a/source/upgrading/upgrade/upgrade-4.6.rst
+++ b/source/upgrading/upgrade/upgrade-4.6.rst
@@ -59,6 +59,8 @@
.. include:: _sysvm_templates.rst
+.. include:: _java_version.rst
+
Database Preparation
--------------------
@@ -87,22 +89,6 @@
$ mysqldump -u root -p cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
$ mysqldump -u root -p cloud_usage > cloud_usage-backup_`date '+%Y-%m-%d'`.sql
-#. **(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:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e "select id,name,path from cloud.storage_pool where pool_type='Filesystem'"
-
- If local storage paths are found to have a trailing forward slash,
- remove it:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';
-
.. _ubuntu46:
@@ -112,6 +98,8 @@
If you are using Ubuntu, follow this procedure to upgrade your packages. If
not, skip to step :ref:`rhel46`.
+.. include:: _timezone.rst
+
.. note::
**Community Packages:** This section assumes you're using the community
supplied packages for CloudStack. If you've created your own packages and
@@ -125,7 +113,6 @@
.. _apt-repo46:
-.. include:: _java_8_ubuntu.rst
CloudStack apt repository
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -182,6 +169,8 @@
If you are using CentOS or RHEL, follow this procedure to upgrade your
packages. If not, skip to hypervisors section :ref:`upg_hyp_46`.
+.. include:: _timezone.rst
+
.. note::
**Community Packages:** This section assumes you're using the community
supplied packages for CloudStack. If you've created your own packages and
@@ -401,7 +390,6 @@
.. parsed-literal::
$ sudo service cloudstack-agent stop
- $ sudo killall jsvc
$ sudo service cloudstack-agent start
diff --git a/source/upgrading/upgrade/upgrade-4.7.rst b/source/upgrading/upgrade/upgrade-4.7.rst
index 0833c6d..6cec9d8 100644
--- a/source/upgrading/upgrade/upgrade-4.7.rst
+++ b/source/upgrading/upgrade/upgrade-4.7.rst
@@ -58,6 +58,8 @@
.. include:: _sysvm_templates.rst
+.. include:: _java_version.rst
+
Database Preparation
--------------------
@@ -86,22 +88,6 @@
$ mysqldump -u root -p cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
$ mysqldump -u root -p cloud_usage > cloud_usage-backup_`date '+%Y-%m-%d'`.sql
-#. **(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:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e "select id,name,path from cloud.storage_pool where pool_type='Filesystem'"
-
- If local storage paths are found to have a trailing forward slash,
- remove it:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';
-
.. _ubuntu47:
@@ -111,6 +97,8 @@
If you are using Ubuntu, follow this procedure to upgrade your packages. If
not, skip to step :ref:`rhel47`.
+.. include:: _timezone.rst
+
.. note::
**Community Packages:** This section assumes you're using the community
supplied packages for CloudStack. If you've created your own packages and
@@ -124,7 +112,6 @@
.. _apt-repo47:
-.. include:: _java_8_ubuntu.rst
CloudStack apt repository
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -181,6 +168,8 @@
If you are using CentOS or RHEL, follow this procedure to upgrade your
packages. If not, skip to hypervisors section :ref:`upg_hyp_47`.
+.. include:: _timezone.rst
+
.. note::
**Community Packages:** This section assumes you're using the community
supplied packages for CloudStack. If you've created your own packages and
@@ -398,7 +387,6 @@
.. parsed-literal::
$ sudo service cloudstack-agent stop
- $ sudo killall jsvc
$ sudo service cloudstack-agent start
diff --git a/source/upgrading/upgrade/upgrade-4.8.rst b/source/upgrading/upgrade/upgrade-4.8.rst
index 6cdc837..64e05c4 100644
--- a/source/upgrading/upgrade/upgrade-4.8.rst
+++ b/source/upgrading/upgrade/upgrade-4.8.rst
@@ -41,6 +41,8 @@
.. include:: _sysvm_templates.rst
+.. include:: _java_version.rst
+
Packages repository
-------------------
@@ -87,22 +89,6 @@
$ mysqldump -u root -p cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
$ mysqldump -u root -p cloud_usage > cloud_usage-backup_`date '+%Y-%m-%d'`.sql
-#. **(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:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e "select id,name,path from cloud.storage_pool where pool_type='Filesystem'"
-
- If local storage paths are found to have a trailing forward slash,
- remove it:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';
-
.. _ubuntu48:
@@ -112,6 +98,8 @@
If you are using Ubuntu, follow this procedure to upgrade your packages. If
not, skip to step :ref:`rhel48`.
+.. include:: _timezone.rst
+
.. note::
**Community Packages:** This section assumes you're using the community
supplied packages for CloudStack. If you've created your own packages and
@@ -125,7 +113,6 @@
.. _apt-repo48:
-.. include:: _java_8_ubuntu.rst
CloudStack apt repository
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -182,6 +169,8 @@
If you are using CentOS or RHEL, follow this procedure to upgrade your
packages. If not, skip to hypervisors section :ref:`upg_hyp_48`.
+.. include:: _timezone.rst
+
.. note::
**Community Packages:** This section assumes you're using the community
supplied packages for CloudStack. If you've created your own packages and
@@ -401,7 +390,6 @@
.. parsed-literal::
$ sudo service cloudstack-agent stop
- $ sudo killall jsvc
$ sudo service cloudstack-agent start
diff --git a/source/upgrading/upgrade/upgrade-4.9.rst b/source/upgrading/upgrade/upgrade-4.9.rst
index ee21786..13ae88f 100644
--- a/source/upgrading/upgrade/upgrade-4.9.rst
+++ b/source/upgrading/upgrade/upgrade-4.9.rst
@@ -56,6 +56,8 @@
.. include:: _sysvm_templates.rst
+.. include:: _java_version.rst
+
Packages repository
-------------------
@@ -99,25 +101,9 @@
.. parsed-literal::
- $ mysqldump -u root -p cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
+ $ mysqldump -u root -p -R cloud > cloud-backup_`date '+%Y-%m-%d'`.sql
$ mysqldump -u root -p cloud_usage > cloud_usage-backup_`date '+%Y-%m-%d'`.sql
-#. **(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:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e "select id,name,path from cloud.storage_pool where pool_type='Filesystem'"
-
- If local storage paths are found to have a trailing forward slash,
- remove it:
-
- .. parsed-literal::
-
- $ mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';
-
.. _ubuntu49:
.. _apt-repo49:
@@ -125,6 +111,8 @@
Management Server
-----------------
+.. include:: _timezone.rst
+
Ubuntu
######
@@ -141,7 +129,6 @@
servers, and any hosts that have the KVM agent. (No changes should
be necessary for hosts that are running VMware or Xen.)
-.. include:: _java_8_ubuntu.rst
Start by opening ``/etc/apt/sources.list.d/cloudstack.list`` on
any systems that have CloudStack packages installed.
@@ -412,7 +399,6 @@
.. parsed-literal::
$ sudo service cloudstack-agent stop
- $ sudo killall jsvc
$ sudo service cloudstack-agent start
diff --git a/source/upgrading/upgrade/upgrade_notes.rst b/source/upgrading/upgrade/upgrade_notes.rst
index 713c5b1..cd53754 100644
--- a/source/upgrading/upgrade/upgrade_notes.rst
+++ b/source/upgrading/upgrade/upgrade_notes.rst
@@ -18,15 +18,28 @@
=====================
-Java version upgraded to Java 1.8
+Java version upgraded to Java 11
---------------------------------
-As of Apache CloudStack 4.10, Java version required is 1.8 for the
+As of Apache CloudStack 4.14, Java version required is 11 for the
management-server, cloudstack-usage, KVM agent and system-VMs.
-.. include:: _java_8_ubuntu.rst
+.. include:: _java_version.rst
+UI Deprecation Notice
+---------------------
+
+The current jQuery-based CloudStack UI will be `deprecated
+<http://markmail.org/message/vxnskmwhfaagnm4r/>`_ in the next Apache CloudStack
+major release and removed in the subsequent future releases.
+
+`Primate <https://github.com/apache/cloudstack-primate/>`_ will ship as the
+modern UI for future Apache CloudStack releases. Users are encouraged to `test
+<https://github.com/apache/cloudstack-primate/wiki/Migrating-to-Primate/>`_
+Primate, report bugs and give feedback to the `dev community
+<http://cloudstack.apache.org/mailing-lists.html>`_ with this release of Apache
+CloudStack.
Migrating to dynamic roles feature
----------------------------------
@@ -95,12 +108,3 @@
db.cloud.driver=jdbc:mysql
db.usage.driver=jdbc:mysql
-
-
-Other Notes
------------
-
-If you are experiencing CloudStack UI issues, please consider upgrading your
-tomcat instance to version 6.0.43 (tested version, but earlier versions prior
-to 6.0.37 might work as well), to address the tomcat response issues caused by
-latency between the browser/client and CloudStack Management server.
