Merge remote-tracking branch 'origin/4.14'
diff --git a/source/adminguide/hosts.rst b/source/adminguide/hosts.rst
index 9262379..34bf4e4 100644
--- a/source/adminguide/hosts.rst
+++ b/source/adminguide/hosts.rst
@@ -593,6 +593,13 @@
out-of-band management driver in CloudStack that uses ``ipmitool`` for performing
IPMI 2.0 management operations.
+CloudStack also supports Redfish protocol for out-of-band management; Redfish provides an
+HTTP REST API to control servers and has been widely adopted on newer machines.
+The commands supported by CloudStack's Redfish out-of-band driver are the same supported by
+the IPMITOOL driver.
+
+Note: so far CloudStack officially supports Redfish protocol for Dell and Supermicro machines.
+
Following are some global settings that control various aspects of this feature.
.. cssclass:: table-striped table-bordered table-hover
@@ -605,6 +612,8 @@
outofbandmanagement.ipmitool.path /usr/bin/ipmitool The out of band management ipmitool path used by the IpmiTool driver
outofbandmanagement.ipmitool.retries 1 The out of band management IpmiTool driver retries option -R
outofbandmanagement.sync.poolsize 50 The out of band management background sync thread pool size 50
+redfish.ignore.ssl true Default value is false, ensuring that the client requests validate the certificate when using SSL. If set to true the redfish client will ignore SSL certificate validation when sending requests to a Redfish server.
+redfish.use.https true Use HTTPS/SSL for all connections.
======================================= ============================= ====================================================================================================
A change in ``outofbandmanagement.sync.poolsize`` settings requires restarting of
diff --git a/source/adminguide/templates.rst b/source/adminguide/templates.rst
index deb6159..1936bfe 100644
--- a/source/adminguide/templates.rst
+++ b/source/adminguide/templates.rst
@@ -302,20 +302,23 @@
Note that uploading multi-disk templates is also supported.
-Sharing templates with other accounts/projects
+Sharing templates and ISOs with other accounts/projects
----------------------------------------------
-When adding a template, the owner can choose to make template public or to keep it private. Once the template is created, the owner can choose to share this template so that other accounts/projects can also use the template.
+When adding a template/ISO, the owner can choose to make template/ISO public or to keep it private. Once the template/ISO is created, the owner can choose to share this template/ISO so that other accounts/projects can also use the template/ISO.
-Currently, the template owner can share his template with:
- - other accounts inside his own domain (i.e. can't share the template with other accounts in the subdomain of his domain or any other domains)
+Currently, the owner can share his template/ISO with:
+ - other accounts inside his own domain (i.e. can't share the template/ISO with other accounts in the subdomain of his domain or any other domains)
- projects where he belongs to (i.e. projects where he is the owner/creator or other projects where he has been joined)
-Template permissions can be changed via updateTemplatePermissions API call or via GUI. It is supported to add, remove or reset (remove all) template permissions.
+Template/ISO permissions can be changed via updateTemplatePermissions/updateIsoPermissions API call or via GUI. It is supported to add, remove or reset (remove all) template/ISO permissions.
-When adding or removing permissions to/from a template, it is required to specify account/project name which is being added/removed from the template permissions.
+When adding or removing permissions to/from a template/ISO, it is required to specify account/project name which is being added/removed from the template/ISO permissions.
-Global setting "allow.user.view.all.domain.accounts" has a default value of "false". This makes sure that when a regular user (of a "User" role) wants to share a template via GUI, he will not be shown the list of all accounts in his domain and he will need to know the name of the destination account with which he is sharing the template. This makes sense in public clouds where each account of a single domain is a different tenant/customer and privacy is imperative. In this case, the user will be presented with an input field to enter the account name, as on the images below:
+Global setting "allow.user.view.all.domain.accounts" has a default value of "false". This makes sure that when a regular user (of a "User" role) wants to share a template/ISO via GUI, he will not be shown the list of all accounts in his domain and he will need to know the name of the destination account with which he is sharing the template/ISO. This makes sense in public clouds where each account of a single domain is a different tenant/customer and privacy is imperative. In this case, the user will be presented with an input field to enter the account name, as on the images below:
+
+.. warning::
+ The images displayed below refer to template permissions, but the same applies for ISO permissions.
|template-permissions-update-manually-1.PNG|
diff --git a/source/adminguide/virtual_machines.rst b/source/adminguide/virtual_machines.rst
index d6c2c3a..fd1bd1a 100644
--- a/source/adminguide/virtual_machines.rst
+++ b/source/adminguide/virtual_machines.rst
@@ -913,6 +913,11 @@
VM snapshots are deleted automatically when a VM is destroyed. You don't
have to manually delete the snapshots in this case.
+Unmanaging Virtual Machines
+===========================
+
+.. include:: virtual_machines/unmanage_vms.rst
+
Importing Virtual Machines
===========================
diff --git a/source/adminguide/virtual_machines/VM_Ingestion.rst b/source/adminguide/virtual_machines/VM_Ingestion.rst
index 54bf18b..a1eda3e 100644
--- a/source/adminguide/virtual_machines/VM_Ingestion.rst
+++ b/source/adminguide/virtual_machines/VM_Ingestion.rst
@@ -13,22 +13,6 @@
specific language governing permissions and limitations
under the License.
-About Importing VMs
---------------------
-
-Unmanaged Virtual Machines
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-As of ACS 4.14, CloudStack has the concept of **unmanaged** virtual machines. These are virtual machines that are on CloudStack
-managed hosts, but that are not in CloudStack's database and therefore CloudStack cannot control (manage) then in any way. Previously,
-such VMs could exist, but CloudStack did not 'see' them (their existence *would* be reported in logs as unrecognised VMs).
-
-From ACS 4.14 onwards, CloudStack is able to list these VMs via the listUnmanagedInstances API command and then import (also known as ingest)
-those unmanaged VMs via the importUnmanagedInstance API so that they become CloudStack managed guest instances
-
-.. note:: This is currently only available for **vSphere** clusters.
-
-
Use Cases and General Usage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -123,12 +107,14 @@
- **projectid**
- **templateid**
- **serviceofferingid**
- - **diskofferingid** (UUID of disk offering for root disk)
- **nicnetworklist** (Map for NIC ID and corresponding Network UUID)
- **nicipaddresslist** (Map for NIC ID and corresponding IP address)
- **datadiskofferinglist** (Map for data disk ID and corresponding disk offering UUID)
- **details** (Map for VM details)
- **migrateallowed** (VM and its volumes are allowed to migrate to different host/storage pool when offering tags conflict with host/storage pool)
+ - **forced** (If true, a VM is imported despite some of its NIC's MAC addresses being already present)
+
+.. note:: The `forced` parameter is false by default and prevents importing a VM which has a NIC containing a MAC address that has been previously assigned by CloudStack. If it is set to true, the NICs with MAC addresses which already exist in the CloudStack database have the existing MAC addresses reassigned to its NICs.
**Response**:
diff --git a/source/adminguide/virtual_machines/unmanage_vms.rst b/source/adminguide/virtual_machines/unmanage_vms.rst
new file mode 100644
index 0000000..9cf2c36
--- /dev/null
+++ b/source/adminguide/virtual_machines/unmanage_vms.rst
@@ -0,0 +1,82 @@
+About Unmanaged Virtual Machines
+--------------------------------
+
+As of ACS 4.14, CloudStack has the concept of **unmanaged** virtual machines. These are virtual machines that are on CloudStack
+managed hosts, but that are not in CloudStack's database and therefore CloudStack cannot control (manage) then in any way. Previously,
+such VMs could exist, but CloudStack did not 'see' them (their existence *would* be reported in logs as unrecognised VMs).
+
+From ACS 4.14 onwards, CloudStack is able to list these VMs via the listUnmanagedInstances API command and then import (also known as ingest)
+those unmanaged VMs via the importUnmanagedInstance API so that they become CloudStack managed guest instances
+
+From ACS 4.15 onwards, administrators are able to unmanage guest virtual machines.
+
+.. note:: This is currently only available for **vSphere** clusters.
+
+Unmanaging Virtual Machines via API
+-----------------------------------
+
+Administrators are able to unmanage guest virtual machines from CloudStack. Once unmanaged, CloudStack can no longer monitor, control or administer the provisioning and orchestration related operations on a virtual machine.
+
+To unmanage a guest virtual machine, an administrator must invoke the unmanageVirtualMachine API passing the ID of the virtual machine to unmanage. The API has the following preconditions:
+
+- The virtual machine must not be destroyed
+- The virtual machine state must be 'Running’ or ‘Stopped’
+- The virtual machine must be a VMware virtual machine
+
+The API execution will perform the following pre-checks, failing if they are not met:
+
+- There are no volume snapshots associated with any of the virtual machine volumes
+- There is no ISO attached to the virtual machine
+
+.. note:: This is currently only available for **vSphere** clusters.
+
+
+Preserving unmanaged virtual machine NICs
+-----------------------------------------
+
+The zone setting: unmanage.vm.preserve.nics can be used to preserve virtual machine NICs and its MAC addresses after unmanaging them. If set to true, the virtual machine NICs (and their MAC addresses) are preserved when unmanaging it. Otherwise, NICs are removed and MAC addresses can be reassigned.
+
+
+Unmanaging virtual machine actions
+----------------------------------
+
+- Clean up virtual machine NICs and deallocate network resources used such as IP addresses and DHCP entries on virtual routers.
+
+ - If ‘unmanage.vm.preserve.nics’ = ‘false’ then the NICs are deallocated and removed from CloudStack
+
+ - If ‘unmanage.vm.preserve.nics’ = ‘true’ then the NICs remain allocated and are not removed from the database. The NIC’s MAC addresses remain preserved and therefore cannot be assigned to any new NIC.
+
+- Clean up virtual machine volumes in the CloudStack database
+
+- Clean up virtual machine snapshots in the CloudStack database (if any)
+- Revoke host access to any managed volumes attached to the VM (applicable to managed storage only)
+
+- Clean up the virtual machine from the following:
+
+ - Remove the virtual machine from security groups (if any)
+
+ - Remove the virtual machine from instance groups (if any)
+
+ - Remove firewall rules for the virtual machine (if any)
+
+ - Remove port forwarding rules for the virtual machine (if any)
+
+ - Remove load balancing rules for the virtual machine (if any)
+
+ - Disable static NAT (if the virtual machine is assigned to it)
+
+ - Remove the virtual machine from affinity groups (if any)
+
+- Remove VM details from the CloudStack database
+
+- Decrement the account resources count for volumes and virtual machines
+
+- Generate usage events:
+
+ - For volumes destroyed, with type: ‘VOLUME.DELETE’
+
+ - For virtual machine snapshots destroyed (if any), with type: ‘VMSNAPSHOT.DELETE’ and 'VMSNAPSHOT.OFF_PRIMARY'
+
+ - For virtual machine NICs destroyed: with type: ‘NETWORK.OFFERING.REMOVE’
+
+ - For the virtual machine being unmanaged: stopped and destroyed usage events (similar to the generated usage events when expunging a virtual machine), with types: ‘VM.STOP’ and ‘VM.DESTROY', unless the VM has been already stopped before being unmanaged and in this case only ‘VM.DESTROY' is generated.
diff --git a/source/installguide/primate.rst b/source/installguide/primate.rst
index bb01464..d7bcbe4 100644
--- a/source/installguide/primate.rst
+++ b/source/installguide/primate.rst
@@ -13,8 +13,6 @@
specific language governing permissions and limitations
under the License.
-:ref:`primate-install-guide`
-
Primate Guide
=============
@@ -29,16 +27,8 @@
:alt: alternate text
:align: left
-With Apache CloudStack 4.14, a technical preview of Primate is proposed that
-users can evaluate. The technical preview release is not an officially voted
-release by the Apache CloudStack project but offers a snapshot build of Primate
-for users for testing and evaluation. The official Primate GA is expected with
-the next CloudStack release where the legacy UI will be deprecated, and the
-legacy UI will be removed in an eventual major CloudStack release.
-
-.. parsed-literal::
-
- NOTE: Primate tech-preview is not suitable to run in production environments.
+Primate GA was released with CloudStack 4.15, where the legacy UI is deprecated,
+and will be removed in an eventual major CloudStack release.
`User participation in the community mailing lists
<http://cloudstack.apache.org/mailing-lists.html>`_ is encouraged. Users may
@@ -48,29 +38,30 @@
~~~~~~~~~~~~
Primate uses API auto-discovery to discover APIs allowed for a logged-in user
-and creates navigation and views based on that.
+and creates navigation and views based on that, and requires the following:
-- Apache CloudStack 4.13.1.0 or later
-- API auto-discovery (listApis enabled)
-- All modern browsers that are `ES5-compliant <https://github.com/vuejs/vue#browser-compatibility>`_
+- Apache CloudStack 4.15 or later
+- API discovery (listApis) enabled
+- Modern browsers that are `ES5-compliant <https://github.com/vuejs/vue#browser-compatibility>`_
-In theory Primate can work with any older version of CloudStack.
-However, several Primate list views require API pagination support, some of which are
-available starting Apache CloudStack 4.13.1.0.
+In theory Primate can work with any older version of CloudStack that supports
+API discovery. However, several Primate list views require API pagination support,
+some of which are available starting Apache CloudStack 4.15 as well as several other
+API improvements which may not be available prior to Apache CloudStack 4.15.
Installation on CentOS
~~~~~~~~~~~~~~~~~~~~~~
-Users running management server (4.13 or above) on CentOS can setup the
-following Primate tech-preview repository:
+Users running management server (4.15 or above) on CentOS can setup the
+following Primate repository:
.. parsed-literal::
rpm --import https://download.cloudstack.org/primate/release.asc
- cat << EOF > /etc/yum.repos.d/cloudstack-primate-tech-preview.repo
- [cloudstack-primate-tech-preview]
+ cat << EOF > /etc/yum.repos.d/cloudstack-primate.repo
+ [cloudstack-primate]
name=cloudstack
- baseurl=https://download.cloudstack.org/primate/testing/preview/centos/
+ baseurl=https://download.cloudstack.org/primate/centos/
enabled=1
gpgcheck=1
gpgkey=https://download.cloudstack.org/primate/release.asc
@@ -89,12 +80,12 @@
Installation on Ubuntu
~~~~~~~~~~~~~~~~~~~~~~
-Users running CloudStack management server (4.13 or above) on Ubuntu can setup the following Primate tech-preview repository:
+Users running CloudStack management server (4.15 or above) on Ubuntu can setup the following Primate repository:
.. parsed-literal::
apt-key adv --keyserver keys.gnupg.net --recv-keys BDF0E176584DF93F
- echo deb https://download.cloudstack.org/primate/testing/preview/debian / > /etc/apt/sources.list.d/cloudstack-primate-tech-preview.list
+ echo deb https://download.cloudstack.org/primate/debian / > /etc/apt/sources.list.d/cloudstack-primate.list
Next, install Primate:
@@ -114,19 +105,19 @@
downloaded and extracted to the management server webapp directory or hosted
with a custom webserver.
-Users can download the builds from https://download.cloudstack.org/primate/testing/preview/archive/
+Users can download the builds from https://download.cloudstack.org/primate/archive/
Using Docker
~~~~~~~~~~~~
-Users can use docker builds of the tech preview from https://hub.docker.com/r/apache/cloudstack-primate
+Users can use docker builds of Primate from https://hub.docker.com/r/apache/cloudstack-primate
For example:
.. parsed-literal::
- docker pull apache/cloudstack-primate:tech-preview
- docker run -ti --rm -p 8080:80 -v $(pwd)/nginx:/etc/nginx/conf.d:ro apache/cloudstack-primate:tech-preview
+ docker pull apache/cloudstack-primate:latest
+ docker run -ti --rm -p 8080:80 -v $(pwd)/nginx:/etc/nginx/conf.d:ro apache/cloudstack-primate:latest
Example nginx config:
@@ -146,18 +137,103 @@
}
}
+Basic Customization in CloudStack Primate
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Users can now customize the CloudStack's user interface by means of a configuration file at /usr/share/cloudstack-management/webapp/primate/config.json which can be used to modify the theme, logos, etc. to align to one's requirement.
+
+To change the logo, login banner, error page icon, etc. the following details can be edited in config.json:
+
+.. parsed-literal::
+
+ "logo": "assets/logo.svg",
+ "banner": "assets/banner.svg",
+ "error": {
+ "404": "assets/404.png",
+ "403": "assets/403.png",
+ "500": "assets/500.png"
+ }
+
+where,
+
+- logo: changes the logo top-left side image.
+- banner: changes the login banner image.
+- error.404: changes the image of error Page not found.
+- error.403: changes the image of error Forbidden.
+- error.500: changes the image of error Internal Server Error.
+
+Customization of themes is also possible, such as, modifying banner width, general color, etc. This can be done by editing the "theme" section of the config.json file:
+
+.. parsed-literal::
+
+ "theme": {
+ "@primary-color": "#1890ff",
+ "@link-color": "#1890ff",
+ "@processing-color": "#1890ff",
+ "@success-color": "#52c41a",
+ "@warning-color": "#faad14",
+ "@error-color": "#f5222d",
+ "@font-size-base": "14px",
+ "@heading-color": "rgba(0, 0, 0, 0.85)",
+ "@text-color": "rgba(0, 0, 0, 0.65)",
+ "@text-color-secondary": "rgba(0, 0, 0, 0.45)",
+ "@disabled-color": "rgba(0, 0, 0, 0.25)",
+ "@border-color-base": "#d9d9d9",
+ "@border-radius-base": "4px",
+ "@box-shadow-base": "0 2px 8px rgba(0, 0, 0, 0.15)",
+ "@logo-width": "256px",
+ "@logo-height": "64px",
+ "@banner-width": "700px",
+ "@banner-height": "110px",
+ "@error-width": "256px",
+ "@error-height": "256px"
+ }
+
+where,
+
+- @primary-color: changes the major background color of the page (background button, icon hover, etc).
+- @success-color: changes success state color.
+- @processing-color: changes processing state color. Exp: progress status.
+- @warning-color: changes warning state color.
+- @error-color: changes error state color.
+- @heading-color: changes table header color.
+- @text-color: change in major text color.
+- @text-color-secondary: change of secondary text color (breadcrumb icon).
+- @disabled-color: disable state color (disabled button, switch, etc).
+- @border-color-base: change in major border color.
+- @logo-width: change the width of the logo top-left side.
+- @logo-height: change the height of the logo top-left side.
+- @banner-width: changes the width of the login banner.
+- @banner-height: changes the height of the login banner.
+- @error-width: changes the width of the error image.
+- @error-height: changes the height of the error image.
+
+Some assorted primary theme colours:
+
+- Blue: #1890FF
+- Red: #F5222D
+- Yellow: #FAAD14
+- Cyan: #13C2C2
+- Green: #52C41A
+- Purple: #722ED1
+
+Advanced Customisation
+~~~~~~~~~~~~~~~~~~~~~~
+
+Primate advanced customisation is possible only by changing JavaScript based config
+files which define rules for sections, names, icons, actions and components and by
+building primate from source available on the `cloudstack-primate
+<https://github.com/apache/cloudstack-primate>`_
+repository. Advanced customisation may require some experience in JavaScript and VueJS,
+a development and customisation guide is available `here
+<https://github.com/apache/cloudstack-primate/blob/master/docs/development.md>`_.
+
Known Issues and Missing Features
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- Support for network service providers
-- Support for S3 based secondary storage
-- Full support for all Quota plugin views
-- Group actions for events, alerts and instances
-- Metrics view cell-colouring
-- Authorisation management for SAML users
-- Filter by feature for searching
-- Guest network LB support for SSL certificate
-- Not all translations are fully migrated from legacy UI to Primate.
-- Feature and enhancements added in 4.14 except CloudStack Kubernetes Service and Backup and Recovery
+- Deployment of a basic zone is not supported. However, existing basic zones will continue to be supported as well as all the actions and views of various resources within the existing basic zone.
+- Support for S3 based secondary storage.
+- NFS secondary staging storage list/resource view and add/update actions.
+- SSL certificate for Guest network LB rule.
+- Regions.
-Please also refer to open issues on https://github.com/apache/cloudstack-primate/issues
+Primate open issues are listed on https://github.com/apache/cloudstack-primate/issues
diff --git a/source/plugins/cloudstack-kubernetes-service.rst b/source/plugins/cloudstack-kubernetes-service.rst
index 0c61de9..ade34ac 100644
--- a/source/plugins/cloudstack-kubernetes-service.rst
+++ b/source/plugins/cloudstack-kubernetes-service.rst
@@ -144,7 +144,7 @@
- **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/
+Using a CoreOS template is required - you can find CoreOS templates for CloudStack 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:
diff --git a/source/releasenotes/about.rst b/source/releasenotes/about.rst
index 45c88c2..56359a9 100644
--- a/source/releasenotes/about.rst
+++ b/source/releasenotes/about.rst
@@ -61,6 +61,20 @@
For CentOS users using the security groups feature on KVM it is needed to install the epel-release and python36-libvirt packages.
+Workaround for adding newer KVM hosts
+=====================================
+
+Newer GNU/Linux distributions with latest OpenSSH package disables some older
+SSH algorithms and ciphers and newer algorithms are not supported by trilead-ssh
+library used by CloudStack to SSH into KVM hosts during the host-add operation.
+Until the dependency library can support that users can use the following
+workaround in their KVM host's /etc/ssh/sshd_config and restart ssh server
+before adding the KVM host in CloudStack:
+
+ PubkeyAcceptedKeyTypes=+ssh-dss
+ HostKeyAlgorithms=+ssh-dss
+ KexAlgorithms=+diffie-hellman-group1-sha1
+
New User Interface & Depreciation notice of existing UI
=======================================================
@@ -70,10 +84,10 @@
However, with the 4.14 release, the Apache Cloudstack community will stop taking feature requests
for new functionality in the existing UI. All new functionality will be developed against the new UI.
-
-The next LTS release (likely to be version 4.15) of Apache Cloudstack will ship with the production
-release of the new UI. It will also be the last version of CloudStack to ship with the old UI. This
-release will also have the final deprecation notice for the old UI.
+The next LTS release (likely to be version 4.15) of Apache Cloudstack will ship
+with the production release of the new UI. It will also be the last version of
+CloudStack to ship with the old UI. This release will also have the final
+deprecation notice for the old UI.
In the following release (likely to be 4.16), the old UI will be deprecated.
