Merge branch '4.13' of https://github.com/apache/cloudstack-documentation

Author: PaulAngus

.gitignore

@@ -1,2 +1,3 @@
 build/
-.vscode
+.vscode
+source/_build/

source/_imagesource/pvlans.drawio

@@ -0,0 +1 @@
+<mxfile host="Chrome" modified="2019-10-09T13:28:47.165Z" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36" version="12.1.0" etag="FKAbdMejNJbJpPzL8ecu" type="device" pages="1"><diagram id="cEOUKJeksBoM-9QyOMCy" name="Page-1">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</diagram></mxfile>

source/_static/images/pvlans.png

@@ -14,72 +14,16 @@
    under the License.
    
 
-Isolation in Advanced Zone Using Private VLAN
----------------------------------------------
-
-Isolation of guest traffic in shared networks can be achieved by using
-Private VLANs (PVLAN). PVLANs provide Layer 2 isolation between ports
-within the same VLAN. In a PVLAN-enabled shared network, a user VM
-cannot reach other user VM though they can reach the DHCP server and
-gateway, this would in turn allow users to control traffic within a
-network and help them deploy multiple applications without communication
-between application as well as prevent communication with other users'
-VMs.
-
--  Isolate VMs in a shared networks by using Private VLANs.
-
--  Supported on KVM, XenServer, and VMware hypervisors
-
--  PVLAN-enabled shared network can be a part of multiple networks of a
-   guest VM.
-
-
-About Private VLAN
-~~~~~~~~~~~~~~~~~~
-
-In an Ethernet switch, a VLAN is a broadcast domain where hosts can
-establish direct communication with each another at Layer 2. Private
-VLAN is designed as an extension of VLAN standard to add further
-segmentation of the logical broadcast domain. A regular VLAN is a single
-broadcast domain, whereas a private VLAN partitions a larger VLAN
-broadcast domain into smaller sub-domains. A sub-domain is represented
-by a pair of VLANs: a Primary VLAN and a Secondary VLAN. The original
-VLAN that is being divided into smaller groups is called Primary, which
-implies that all VLAN pairs in a private VLAN share the same Primary
-VLAN. All the secondary VLANs exist only inside the Primary. Each
-Secondary VLAN has a specific VLAN ID associated to it, which
-differentiates one sub-domain from another.
-
-Three types of ports exist in a private VLAN domain, which essentially
-determine the behaviour of the participating hosts. Each ports will have
-its own unique set of rules, which regulate a connected host's ability
-to communicate with other connected host within the same private VLAN
-domain. Configure each host that is part of a PVLAN pair can be by using
-one of these three port designation:
-
--  **Promiscuous**: A promiscuous port can communicate with all the
-   interfaces, including the community and isolated host ports that
-   belong to the secondary VLANs. In Promiscuous mode, hosts are
-   connected to promiscuous ports and are able to communicate directly
-   with resources on both primary and secondary VLAN. Routers, DHCP
-   servers, and other trusted devices are typically attached to
-   promiscuous ports.
-
--  **Isolated VLANs**: The ports within an isolated VLAN cannot
-   communicate with each other at the layer-2 level. The hosts that are
-   connected to Isolated ports can directly communicate only with the
-   Promiscuous resources. If your customer device needs to have access
-   only to a gateway router, attach it to an isolated port.
-
--  **Community VLANs**: The ports within a community VLAN can
-   communicate with each other and with the promiscuous ports, but they
-   cannot communicate with the ports in other communities at the layer-2
-   level. In a Community mode, direct communication is permitted only
-   with the hosts in the same community and those that are connected to
-   the Primary PVLAN in promiscuous mode. If your customer has two
-   devices that need to be isolated from other customers' devices, but
-   to be able to communicate among themselves, deploy them in community
-   ports.
+Isolation in Advanced Zone Using Private VLANs
+-----------------------------------------------
+
+About PVLANs (Secondary VLANs)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The clasic use-case for PVLANs is a shared backup network, where you wish all users' 
+hosts to be able to communicate with a backup host, but not with each other.
+
+   |pvlans.png|
 
 For further reading:
 
@@ -92,6 +36,19 @@ For further reading:
 -  `Private VLAN (PVLAN) on vNetwork Distributed Switch - Concept
    Overview (1010691) <http://kb.vmware.com>`_
 
+Supported Secondary VLAN types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+The PVLAN concept is supported on KVM (when using OVS), XenServer (when using OVS), and VMware hypervisors
+
+   .. note:: 
+      OVS on XenServer and KVM does not support PVLAN natively. Therefore,
+      CloudStack managed to simulate PVLAN on OVS for XenServer and KVM by
+      modifying the flow table.
 
 Prerequisites
 ~~~~~~~~~~~~~
@@ -119,84 +76,24 @@ Prerequisites
 
 -  Before you use PVLAN on XenServer and KVM, enable Open vSwitch (OVS).
 
-   .. note:: 
-      OVS on XenServer and KVM does not support PVLAN natively. Therefore,
-      CloudStack managed to simulate PVLAN on OVS for XenServer and KVM by
-      modifying the flow table.
-
-
-Creating a PVLAN-Enabled Guest Network
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-#. Log in to the CloudStack UI as administrator.
-
-#. In the left navigation, choose Infrastructure.
-
-#. On Zones, click View More.
-
-#. Click the zone to which you want to add a guest network.
-
-#. Click the Physical Network tab.
-
-#. Click the physical network you want to work with.
-
-#. On the Guest node of the diagram, click Configure.
-
-#. Click the Network tab.
-
-#. Click Add guest network.
-
-   The Add guest network window is displayed.
-
-#. Specify the following:
-
-   -  **Name**: The name of the network. This will be visible to the
-      user.
-
-   -  **Description**: The short description of the network that can be
-      displayed to users.
-
-   -  **VLAN ID**: The unique ID of the VLAN.
-
-   -  **Secondary Isolated VLAN ID**: The unique ID of the Secondary
-      Isolated VLAN.
-
-      For the description on Secondary Isolated VLAN, see
-      `About Private VLAN" <#about-private-vlan>`_.
-
-   -  **Scope**: The available scopes are Domain, Account, Project, and
-      All.
-
-      -  **Domain**: Selecting Domain limits the scope of this guest
-         network to the domain you specify. The network will not be
-         available for other domains. If you select Subdomain Access,
-         the guest network is available to all the sub domains within
-         the selected domain.
-
-      -  **Account**: The account for which the guest network is being
-         created for. You must specify the domain the account belongs
-         to.
 
-      -  **Project**: The project for which the guest network is being
-         created for. You must specify the domain the project belongs
-         to.
+Creating a PVLAN-Enabled Shared Network
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-      -  **All**: The guest network is available for all the domains,
-         account, projects within the selected zone.
+For a general description of how to create a shared netowrk see `"configuring a shared guest network" <#configuring-a-shared-guest-network>`_.
 
-   -  **Network Offering**: If the administrator has configured multiple
-      network offerings, select the one you want to use for this
-      network.
+On top of the parameters required to create a *normal* shared network, the following
+parameters must be set:
 
-   -  **Gateway**: The gateway that the guests should use.
+-  **VLAN ID**: The unique ID of the primary VLAN that you want to use.
 
-   -  **Netmask**: The netmask in use on the subnet the guests will use.
+-  **Secondary Isolated VLAN ID**:
 
-   -  **IP Range**: A range of IP addresses that are accessible from the
-      Internet and are assigned to the guest VMs.
+   - 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.
 
-   -  **Network Domain**: A custom DNS suffix at the level of a network.
-      If you want to assign a special domain name to the guest VM
-      network, specify a DNS suffix.
 
-#. Click OK to confirm.
+.. |pvlans.png| image:: /_static/images/pvlans.png
+   :alt: Diagram of PVLAN communications

source/adminguide/networking/isolation_in_advanced_zone_with_vlan.rst

@@ -0,0 +1,72 @@
+.. 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.
+
+CloudStack Customisations
+--------------------------
+
+There are a number of ways in which administrators can customise CloudStack.  During an
+upgrade, a number of these could be overridden.  Therefore steps should be taken to ensure
+that they can be restored after the upgrade is completed.
+
+
+Guest OS mappings
+##################
+
+A new CloudStack release often brings compatibility with new hypervisors, and therefore 
+new Guest OS mappings. An API is provided to manually add guest OSes and the
+relevant hypervisor mappings, however, there is a high probability that manually 
+added guest OSes and/or mappings would conflict with guest OSes and/or mappings
+added as part of a version upgrade.
+
+It is therefore essential to remove any Guest OS mappings that were manually added 
+in order to ensure a successful upgrade.  If need be, any custom Guest OS mappings 
+still 'missing' after an upgrade can be re-added after the upgrade.
+That means that any custom added rows in the *guest_os*, *guest_os_hypervisor*, 
+*guest_os_details* and *guest_os_category* database tables, should be removed 
+prior to the upgrade, and added later if needed.
+
+.. warning::
+      Manually added guest OS mappings can cause the upgrade process to fail.
+
+
+Customised CSS
+###############
+
+If you have altered the CSS files in order to customise the appearance of the CloudStack UI,
+you should make a backup copy as the installed CSS files are likely to be overwritten during
+any upgrade.
+
+You should inspect a 'diff' of your customised css files and the new versions, and then
+reapply your changes to the new files as the new versions may contain changes to better display existing
+elements or have new entries to support new UI elements.
+
+Plugins
+#######
+
+If you have 3rd party plugins installed, you should backup your plugins directories and the
+plugins.js file.  While the plugins directories *should* remain untouched, the plugins.js
+file is likely to be overwritten.
+
+3rd Party Integrations
+#######################
+
+CloudStack is put through extensive regression testing during a release cycle, however 
+the numerous 3rd party integrations which are available cannot all be tested by the 
+community nor indeed may the community know about many of them. Therefore it is essential
+that you verify that your integrations will continue to work after an upgrade through thorough
+testing and checking with the vendor/supplier of your integrations.
+